# @cytario/design 中文文档

规范地址：https://npmcn.com/package/%40cytario/design/

版本：11\.1\.3
npm 元数据更新时间：2026-10-28T16:34:30.197Z
中文译文更新时间：2026-11-11T07:37:47.546Z
软件包许可：AGPL-3\.0-only

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40cytario/design
原文对照：https://npmcn.com/package/%40cytario/design/?lang=original
项目主页：https://github.com/cytario/cytario-design#readme
源码仓库：https://github.com/cytario/cytario-design

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：5.2 MB，37 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：3 个
- peer 依赖：react \>=18\.0\.0，react-dom \>=18\.0\.0，@tanstack/react-table ^8\.21\.3，react-aria-components ^1\.20\.0
- 首次发布：2026-02-22T08:57:26.850Z
- 最新版本发布：2026-10-28T16:34:29.627Z
- 近 30 天下载量：2778（2026-10-11 至 2026-11-09，npm 官方下载统计）
- 已发布版本数：70（近 12 个月 70 个）

## 中文简介

Cytario 设计系统和品牌门户

## 安装

```sh
npm install @cytario/design
```

也可以使用：`pnpm add @cytario/design`、`yarn add @cytario/design`、`bun add @cytario/design`

## README

# 细胞设计系统

细胞实体身份的单一真相来源——从品牌基础(logos,colors,twitchography)到制作准备的React组件. 建成后成为设计师,开发者和利益攸关方的交互式故事书门户.

## 技术堆栈

| 层 | 技术 |
| --- | --- |
| 文档 | 故事集10, MDX |
| UI 框架 | 反应 19, TypeScript 5.9 |
| 样式 | 尾风 CSS v4, CSS 自定义属性 |
| 无障碍 | 反应 Aria 组件( Adobe) |
| 设计符号 | CSS 自定义属性(`src/styles/theme.css`(中文(简体) ) |
| 测试 | Vitest, React Testing 库, 轴心(addon-a11y) |

## 开始

### 先决条件

-   节点.js 22+

### 安装和运行

```bash
npm install
npm run dev            # start Storybook at http://localhost:6006
```

## 项目结构

```
cytario-design/
  .storybook/          # Storybook configuration (main.ts, preview.ts, theme.ts)
  assets/
    logos/              # SVG and PNG logo variants (full, reduced, black, white, on-purple)
    fonts/              # Montserrat font files
    approvals/          # approved brand materials
  scripts/
    validate-tokens.ts # CI script to verify dark-theme invariant
  src/
    styles/
      theme.css           # single hand-maintained token file — primitives, light/dark semantics, @theme inline
      tailwind.css        # Tailwind v4 entry point (imports theme.css)
    components/
      Button/           # Button.tsx, Button.stories.tsx, Button.test.tsx
      Input/            # Input.tsx, Input.stories.tsx, Input.test.tsx
      Select/           # Select.tsx, Select.stories.tsx, Select.test.tsx
      Table/            # Table.tsx, Table.stories.tsx, Table.test.tsx
    docs/               # MDX documentation pages (Introduction, Foundation, Guidelines)
```

## 设计符号

手持手持的脚趾 `src/styles/theme.css` ——作为真相来源的单一CSS文件:

-   **初级** (单位:千美元)`:root`: 生六氧化物/rg值(`--color-purple-500`(中文(简体) )
-   **语义光** (单位:千美元)`:root`: `var()` 原始人参考`--color-primary: var(--color-purple-500)`(中文(简体) )
-   **语义黑暗** (单位:千美元)`[data-theme="dark"]`: 对每个语义符号的覆盖
-   **`@theme inline`**: 映射到 Tailwind v4 工具名

所有符号 CSS 都住在 `@layer cytario-design` 所以消费者应用的风格可以超越.

### 添加或修改符号

1.  编辑 `src/styles/theme.css` 直接说.
2.  如果添加了新的颜色尺度,则在所有四个部分(原始内容、轻语义、暗语义、, `@theme inline`) (中文(简体) ).
3.  运行 `npm run validate:tokens` 以验证阴暗主题的变异(每个 `:root` 颜色有 `[data-theme="dark"]` ,第2段.

## 构成部分发展

每个组件都遵循相同的文件结构:

```
src/components/ComponentName/
  ComponentName.tsx           # implementation
  ComponentName.stories.tsx   # Storybook stories (CSF3)
  ComponentName.test.tsx      # Vitest + React Testing Library tests
```

### 方针

-   **行为和无障碍**: React Aria 组件提供键盘导航,ARIA属性,并出框进行焦点管理. 组件用细胞结构来包装回放Aria原始人.
-   **样式**: Tailwind CSS v4 通用类,包括由设计符号(例如, `bg-primary`, (中文(简体) ), `text-muted-foreground`, (中文(简体) ), `bg-destructive`) (中文(简体) ). 没有运行时间 CSS-in-JS.
-   **故事**: CSF3 格式为 `args`, (中文(简体) ), `argTypes`,以及 `play` 用于交互测试的函数。 所有故事都会由 a11y addon(轴-核心)自动检查.
-   **测试**: Vitest 有反应测试库. 通过用户视角进行测试——按照角色和标签进行查询,验证行为和无障碍属性. 不要测试反应 阿里娅内部.

### 创建新组件

1.  创建 `src/components/YourComponent/YourComponent.tsx`. 包接相应的回放 Aria 原始, 应用以符号为基础的 Tailwind 类.
2.  创建 `YourComponent.stories.tsx` 默认元, 单个变体故事, 游戏场故事, 以及至少一个 `play` 函数交互测试.
3.  创建 `YourComponent.test.tsx` 覆盖渲染,用户交互,被禁用/误入状态,以及键盘的可访问性.
4.  如果存在枪管文件, 从该文件导出, 或者直接导入 .

## 品牌颜色

细胞分泌品牌主要有两种颜色:

| 颜色 | 十六进制 | 脚本 | 使用量 |
| --- | --- | --- | --- |
| 紫色 | `#5c2483` | `--color-purple-700` 编号 : `--color-brand-primary` | 主要品牌颜色、标题、次要行动 |
| 提尔 | `#35b7b8` | `--color-teal-500` 编号 : `--color-brand-accent` | 色调、主要行动、互动要素 |

两种颜色都有完整的50-900比例尺定义 `src/styles/theme.css` 用于徘徊状态、背景和细微的花纹.

## 可用组件

| 构成部分 | 备选案文 | 原生反应 |
| --- | --- | --- |
| 按钮 | 初级、二级、幽灵、破坏性(sm/md/lg) | `Button` |
| 投入 | 文本、电子邮件、密码、号码;错误+描述状态 | `TextField` |
| 选择 | 单选下拉 | `Select` |
| 图表 | 可排序列、 行选择 | `Table` |

## 脚本

| 命令 | 说明 |
| --- | --- |
| `npm run dev` | 在端口启动 Storybook dev 服务器 6006 |
| `npm run build` | 构建静态故事书网站 `storybook-static/` |
| `npm run validate:tokens` | 验证符号 CSS 中的暗主题变量 |
| `npm run build:css` | 将 Tailwind 样式表构建为 `dist/index.css` |
| `npm run watch:css` | 重建 `dist/index.css` 更改( 继续运行) |
| `npm test` | 运行虚拟测试套件( 监视模式) |
| `npx vitest run` | 运行一次测试( CI 模式) |
| `npm run lint` | 林特 `src/` 带有 ESLint 的 |

## 许可证

这个项目有双重许可证:

-   **开源**数字 : [GNU 阿费罗通用公共许可证 v3.0](https://npmcn.com/package/%40cytario/design/LICENSE) (AGPL-3.0-仅限)
-   **商业**: Slash-m GmbH提供专有许可证,用于AGPL不适合的情况。 联系人 [许可@ slash-m.com](mailto:licensing@slash-m.com) 就条件而言.

"cytario"和"cytario"标志是Slash-m GmbH的商标. 见 [贸易商](https://npmcn.com/package/%40cytario/design/TRADEMARK.md)。 。 。 .

## 常见问题

### @cytario/design 是什么？

Cytario 设计系统和品牌门户

### 如何安装 @cytario/design？

在项目目录运行 npm install @cytario/design，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：react（\>=18\.0\.0）、react-dom（\>=18\.0\.0）、@tanstack/react-table（^8\.21\.3）、react-aria-components（^1\.20\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @cytario/design 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @cytario/design 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @cytario/design 可以商用吗？

@cytario/design 使用 AGPL-3\.0-only 许可。最严格的 Copyleft：除分发外，通过网络向用户提供基于它的服务也需要开源对应源码。闭源 SaaS 使用前务必评估。以上为概括，不构成法律意见，请以许可原文为准。

### @cytario/design 的下载量有多少？

根据 npm 官方下载统计，@cytario/design 在 2026/10/11 – 2026/11/09 这 30 天内被下载 2,778 次，日均约 93 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @cytario/design 还在维护吗？

最新版本 11\.1\.3 发布于 2026/10/29（13 天前）；至今共发布 70 个版本，其中过去 12 个月发布了 70 个；首次发布于 2026/02/22。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。