# @fireworks-ai/design-system 中文文档

规范地址：https://npmcn.com/package/%40fireworks-ai/design-system/

版本：0\.1\.5
npm 元数据更新时间：2026-09-24T07:16:25.545Z
中文译文更新时间：2026-11-14T20:01:59.312Z
软件包许可：Apache-2\.0

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

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

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

- 包体积（解压后）：343 kB，150 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=24\.0\.0
- 运行依赖：27 个
- peer 依赖：next ^16\.0\.0，react ^19\.0\.0，react-dom ^19\.0\.0，react-hook-form ^7\.62\.0
- 首次发布：2026-08-12T05:57:12.479Z
- 最新版本发布：2026-09-24T07:16:25.356Z
- 近 30 天下载量：12121（2026-10-15 至 2026-11-13，npm 官方下载统计）
- 已发布版本数：7（近 12 个月 7 个）

## 中文简介

Fireworks AI产品共享反应组件和设计符.

## 安装

```sh
npm install @fireworks-ai/design-system
```

也可以使用：`pnpm add @fireworks-ai/design-system`、`yarn add @fireworks-ai/design-system`、`bun add @fireworks-ai/design-system`

## README

# @ fireworks-ai/ 设计系统

Fireworks AI产品共享反应组件和设计符.

组件预览和文件(故事本): [https://storybook.preview.fireworks.ai 互联网档案馆的存檔,存档日期2013-12-02](https://storybook.preview.fireworks.ai/)

```bash
npm i @fireworks-ai/design-system
```

## 所需资源

| 依赖性 | 所需经费 |
| --- | --- |
| `react` 编号 : `react-dom` | `^19.0.0`,对等者,需要 |
| `next` | `^16.0.0`,对等者,需要 |
| `react-hook-form` | `^7.62.0`,对等,可选——仅需用于 `./components/ui/form` |
| `tailwindcss` | `^4.0.0`页:1 |

## 使用量

### 构成部分

从自己的子路径导入每个组件 .

```ts
import { Action } from '@fireworks-ai/design-system/Action';
import { DataTable } from '@fireworks-ai/design-system/DataTable';
```

然后将Tailwind指向编译的组件. 尾风只为它找到的类生成 CSS 扫描时,它永远不会扫描 `node_modules` 因此,跳过这个和每个组件使 无名无姓,没有告诉你原因.

```css
@source "../node_modules/@fireworks-ai/design-system/dist";
```

调整路径,使其决定 `node_modules` 从您的 CSS 文件所在位置。 给大家 子路径列表, 运行 `npm view @fireworks-ai/design-system exports`。 。 。 .

### 主题和 `cn`

**需要尾风 v4 .** 样式表使用 v4 唯一的语法(`@theme`, (中文(简体) ), `@utility`, (中文(简体) ), `@source`, (中文(简体) ), 所以v3不能分析,没有 `tailwind.config.js` 前往符号的路由。 运行 `npx @tailwindcss/upgrade` 如果你仍然在v3上的话.

导入 `theme.css` 之后 `tailwindcss`,然后作为一个整体导入。 这是唯一的样式表 软件包导出,它会拉入四个文件,它们只按此顺序重新发送.

```css
@import 'tailwindcss';
@import '@fireworks-ai/design-system/styles/theme.css';
```

这种导入取代了Tailwind的调色板,类型尺度,和字体重量——它不扩展它们. 它的风格也是赤裸的 `h1`– 说吧 –`h6` 和船舶a `scrollbar` 滚动容器的分类。 随便 滴滴停止编译, 无声:

-   **颜色.** `gray` 运行 `50`– 说吧 –`900` (加上a) `750`其他家庭提供 `50 / 100 / 300 / 500 / 700`,还有 `white`。 。 。 . `slate-500` 和尾风的其余部分 调色板不见了.
-   **类型尺度.** `xs sm base lg 2xl 3xl 4xl 5xl` - 注意没有 `text-xl`每一步都带着 它本身的行高和字母间距,所以大小类已经是一个已完成的类型样式;不要 添加 `leading-*` 或者说 `tracking-*` 在顶上.
-   **字体重量.** 仅 `font-normal`, (中文(简体) ), `font-medium`,以及 `font-semibold` 生存下来. `font-bold` 完全没有结果.

使用 `cn` 从此软件包合并 a `className`而不是建立你自己的 `twMerge`这个 实例配置为软件包 `@utility` 类; 股票一个错误 `text-eyebrow` 颜色,所以 `cn('text-eyebrow', 'text-gray-900')` 安静地放下它.

```ts
import { cn } from '@fireworks-ai/design-system/lib/utils';
```

### 颜色符号

CSS变量持有RGB三重而不是Hex,这让手写CSS选择自己的α: `rgb(var(--gray-900) / 0.4)`。 。 。 .

同样的值也与平原TypeScript常数相通,没有CSS的副作用. 测试保持 两个同步.

```ts
import { colors } from '@fireworks-ai/design-system/tokens/colors';

colors.gray[900]; // '#18181B'
```

只当一个 CSS 变量无法到达时使用常数——图表配置,画布, SVG. 如果 值最终出现在样式表中,取而代之的是工具类.

### 守卫

`check-design-tokens` 捕获绕过调色板和类型尺度的颜色和字体大小: 尾风任意值( U)`bg-[#fff]`, (中文(简体) ), `text-[13px]`以及任何地方的原始价值—— `#6720FF` 内 一个常数, `rgb(24 24 27)` 在CSS中, `fontSize: 12` 以内线样式.

```bash
bun run lint:tokens        # this repo, all packages
```

#### 你犯了错 现在怎么办?

几乎总是固定 到达的标志。 哪个形式取决于值的活度:

```tsx
<div className="bg-gray-900" />                   // markup: a utility class
<div style={{ fontSize: 'var(--text-xs)' }} />    // inline style: the CSS variable
canvasContext.fillStyle = colors.green[500];      // canvas, SVG props: the TS constant
```

到达 `colors` (从) `@fireworks-ai/design-system/tokens/colors`) 只在最后一种情况下—— API 想要一个真实的颜色字符串而无法解析 `var()`。 。 。 .

如果真的值不能成为符号——第三方部件的颜色,复制的艺术品 一些其他产品的UI——在它上面的线上这样说:

```tsx
{/* design-system-exempt: macOS traffic light */}
<span className="bg-[#ff5f57]" />
```

需要说明理由; `design-system-exempt:` 之后什么也没有,这本身就是一个错误。 一个标记 完全覆盖一行——单行时其下一行,单行后其后一行 ——所以两个硬码值需要两个标记. 偏好上面的一行:一个前题会移动一个后端 JSX评论自己的一行,并打破了配对.

#### 在你的回购中设置后卫

安装软件包,然后将 CLI 指向您的源头和配置 :

```json
"lint:tokens": "check-design-tokens ./src --config ./design-tokens.config.mjs"
```

退出代码 0 表示干净, 1 表示至少一个错误, 2 表示命令本身是错误的—— 一个差错 路径或可卸载配置。 警告不会失败.

包里只有船 到处都有 您自己的图表目录和生成的资产 由你来宣布

```js
/** @type {import('@fireworks-ai/design-system/guards').GuardConfig} */
export default {
  pathExemptions: [
    { pattern: /\/(?:analytic|vis)\//, reason: 'Deferred: chart and data-viz colors' },
    { pattern: /\/components\/assets\/icons\.tsx$/, reason: 'Brand artwork, not a theme choice' },
  ],
};
```

`rules` 需要自己的形状相同; 运行 `check-design-tokens --list-rules` 改为 见目前生效的一切。 一个完整的例子存在于 `apps/web/design-tokens.config.mjs`。 。 。 .

## 捐款

### 发展

运行 `dev` 启动监视构建的脚本 。 从回波根, `bun run dev --filter=@fireworks/web...` 运行网络应用和设计系统.

### 大楼

`bun run build` 在本包中,或 `bun run build --filter=@fireworks-ai/design-system` 从 复发相根.

### 添加新组件

> \[大 所有组成部分都需要在 `exports` 报告 `package.json` 档案!

```json
{
  "exports": {
    "./NewComponent": {
      "types": "./dist/NewComponent.d.ts",
      "import": "./dist/NewComponent.js"
    }
  }
}
```

在此包中导入其它带有相对路径的文件 。 自引用子路径导入,例如 `@fireworks-ai/design-system/Action` 生存为 `dist/`,使消费者在 软件包已重新命名 `~/` 化名在此还原之外根本无法解决.

### 从 shadcn/ ui 添加组件

运行 `npx shadcn add <component>`,然后在承诺前固定输出:

1.  **颜色 :** `slate-*` → `gray-*` (单位:千美元)`slate-950` → `gray-900`(中文(简体) )
2.  **半径 :** `rounded-md` → `rounded-8`, (中文(简体) ), `rounded-lg` → `rounded-12`, (中文(简体) ), `rounded-xl` → `rounded-16`
3.  **焦点环 :** `ring-ring` → `ring-purple-500`, (中文(简体) ), `ring-offset-background` → `ring-offset-white`

CLI 配置为内含混凝土颜色(`cssVariables: false`)并跳过 CSS 文件,所以 生成组件是自成一体的——只是调色板错误.

### 释放

运行 [`publish-design-system.yml`](https://npmcn.com/package/.github/workflows/publish-design-system.yml) 手动从 动作标签,使用 `bump` 设置为 `patch`, (中文(简体) ), `minor`,或 `major`。工作流程会使版本发生颠倒 本身,所以不要编辑 `version` 手边。 它首先验证——构建,打字检查,测试,包装干跑,以及检查版本还没有在npm上——然后打开搭载被撞的放出PR `package.json` 财务报告和审定财务报表 `bun.lock`,发布,最后标记它从 `design-system-v<version>`合并运行为绿色的 PR : `main` 仍然指向已公布的版本,下一次发布失败其飞行前检查.

## 常见问题

### @fireworks-ai/design-system 是什么？

Fireworks AI产品共享反应组件和设计符\.

### 如何安装 @fireworks-ai/design-system？

在项目目录运行 npm install @fireworks-ai/design-system，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：next（^16\.0\.0）、react（^19\.0\.0）、react-dom（^19\.0\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。它还提供命令行工具 check-design-tokens，可以用 npx check-design-tokens 直接运行。

### @fireworks-ai/design-system 支持 TypeScript 吗？

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

### @fireworks-ai/design-system 支持 ESM 还是 CommonJS？

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

### @fireworks-ai/design-system 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=24\.0\.0。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @fireworks-ai/design-system 可以商用吗？

@fireworks-ai/design-system 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。

### @fireworks-ai/design-system 的下载量有多少？

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

### @fireworks-ai/design-system 还在维护吗？

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