# @apipass/design-system 中文文档

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

版本：8\.3\.0
npm 元数据更新时间：2026-11-05T14:33:45.429Z
中文译文更新时间：2026-11-06T20:44:37.917Z
软件包许可：未声明

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

原始 npm 页面：https://www.npmjs.com/package/%40apipass/design-system
原文对照：https://npmcn.com/package/%40apipass/design-system/?lang=original

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

- 包体积（解压后）：4.9 MB，2263 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：4 个
- peer 依赖：react \>=18\.0\.0，echarts \>=5\.5\.0，react-dom \>=18\.0\.0，@codemirror/view \>=6\.0\.0，@lezer/highlight \>=1\.0\.0，@codemirror/state \>=6\.0\.0，@codemirror/language \>=6\.0\.0，@monaco-editor/react \>=4\.0\.0，@codemirror/lang-json \>=6\.0\.0，react-aria-components \>=1\.10\.0
- 首次发布：2026-03-31T15:01:14.938Z
- 最新版本发布：2026-11-05T14:33:45.231Z
- 近 30 天下载量：2374（2026-10-06 至 2026-11-04，npm 官方下载统计）
- 已发布版本数：97（近 12 个月 97 个）

## 中文简介

APIPass 反应设计系统

## 安装

```sh
npm install @apipass/design-system
```

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

## README

# 简易设计系统(α)

用法格玛的 [代码连接](https://github.com/figma/code-connect)。 。 。 .

简易设计系统(SDS)是一个基础设计系统,显示如何在React Codebase同时使用Figma的可变,样式,组件和代码连接,以形成一个响应性网络设计系统的完整图片.

SDS不仅仅是Figma的另一个设计系统. 设计和开发之间仍然存在许多差距,战略部署储存为如何弥补这些差距提供了一些最佳做法。 SDS试图对其在代码中的影响保持诚实,同时也在设计上提供自定义性,超越许多代码第一组件库所典型的简单主题层.

无论您想要使用 SDS 来启动一个新项目, 还是寻找一些共同设计系统最佳做法的例子, 您都会在这个代码库和设计文件内找到工具来引导您正确方向.

## 资源

-   [故事书](https://storybook.apipass.com.br/)
-   [Figma 社区文件](https://www.figma.com/community/file/1380235722331273046/simple-design-system)

## 设置

-   `npm i` 以安装依赖关系
-   `npm run app:dev` 将运行服务器于 [本地主机: 8000](http://localhost:8000/) 产生内容的 [应用程序x](https://npmcn.com/package/%40apipass/design-system/src/App.tsx)
-   `npm run storybook` 开始故事书 [本地主机: 6006](http://localhost:6006/)

### 图像 Auth

-   [创建图像 API 令牌](https://www.figma.com/developers/api#authentication)
    -   添加代码连接范围
    -   如果您想要使用整合, 请添加文件读取、 Dev 资源写入和变量范围 [脚本](https://npmcn.com/package/%40apipass/design-system/scripts/)
    -   [更多关于瞄准镜](https://www.figma.com/developers/api#authentication-scopes)
-   复制 [.env 重命名](https://npmcn.com/package/%40apipass/design-system/.env-rename)
-   重命名为 `.env`,它将被忽略 从git.
    -   设定 `FIGMA_ACCESS_TOKEN=` 作为你的象征 `.env`
    -   设定 `FIGMA_FILE_KEY=` 作为您文件的密钥( 从文件 URL 中获取) `.env`

### 代码连接

SDS完全由Figma的"代码连接"支持. 这包括如何连接的实例 [原始人](https://npmcn.com/package/%40apipass/design-system/src/figma/primitives/),以及 [组成](https://npmcn.com/package/%40apipass/design-system/src/figma/compositions/) 这些原始的 为你的设计系统.

这回波利用 `documentUrlSubstitutions` 内 [figma.config.json (英语)](https://npmcn.com/package/%40apipass/design-system/figma.config.json)。这可以让我们的文档 Figma 文件不可知化,并汇总所有 Figma 文件特定信息,以便于url 互换 。 文件 URL 替换的命名方式也帮助您找到关联组件而不点击链接. 键 `<FIGMA_INPUTS_CHECKBOX_GROUP>` 细分为 `<FIGMA_[PAGE_NAME]_[COMPONENT_NAME]>`。 。 。 .

```json
{
  "documentUrlSubstitutions": {
    "<FIGMA_INPUTS_CHECKBOX_GROUP>": "https://figma.com/design/whatever?node-id=123-456"
  }
}
```

允许我们在代码连接文件中有更多的表达式 URL:

```js
figma.connect(CheckboxGroup, "<FIGMA_INPUTS_CHECKBOX_GROUP>");
```

### 连接此 repo 到重复的 Figma 文件

考虑到上述情况,一个"简易设计系统"(Simple Design System Figma)文件的新克隆人应该保持所有的节点标识. 这些步骤如下:

-   复制 [Figma 社区文件](https://www.figma.com/community/file/1380235722331273046/simple-design-system)
-   克隆这个还原
-   更新 urls 中 [figma.config.json (英语)](https://npmcn.com/package/%40apipass/design-system/figma.config.json) 指向您的 Figma 文件
    -   注:文件密钥(例如:. `J0KLPKXiONDRssXD1AX9Oi`)应该是urls中唯一的变化,除非你正在创建新的组件,去除和再创建.
-   创建和设置您的 [图像 Auth Token](https://npmcn.com/package/%40apipass/design-system/#readme-figma-auth)
-   那时, `npx figma connect publish` 您的新文件应该有代码连接.

## 结构

所有组件和样式都在 [锡克/锡克](https://npmcn.com/package/%40apipass/design-system/src/ui)。在该目录中,代码分为几类.

### [src/ui/组件](https://npmcn.com/package/%40apipass/design-system/src/ui/components/)

APIPASS 添加,不是上游SDS的一部分. 由原始人组装而成,可重复使用的块来解析特定反复出现的UI图案(Card, DataTable, CivirDialog, Form Modal, Pageheader, Sidebar, Widget/WidgetGrid). 与 `compositions`,这些包含真实的app-faceing行为,并意在被直接导入,而不仅仅是被复制为布局示例.

### [rc/ui/组合](https://npmcn.com/package/%40apipass/design-system/src/ui/compositions/)

原始组件的示例安排,以显示您如何使用 SDS 构建一个响应网站 .

### [斜弧/斜角/斜角](https://npmcn.com/package/%40apipass/design-system/src/ui/hooks/)

自定义反应钩定义

### [锡克/锡克/锡克/锡克](https://npmcn.com/package/%40apipass/design-system/src/ui/icons/)

所有图标组件 。 自动生成 [脚本/缩写](https://npmcn.com/package/%40apipass/design-system/scripts/icons)

### [弧度/度/图像](https://npmcn.com/package/%40apipass/design-system/src/ui/images/)

占位符图像 .

### [src/ui/放电](https://npmcn.com/package/%40apipass/design-system/src/ui/layout/)

布局组件 。 与 SDS 的布局至关重要,但在 Figma 中没有类似的组件 .

### [锡克/基干/基干](https://npmcn.com/package/%40apipass/design-system/src/ui/primitives/)

主要组件库. SDS原始体无法再被进一步缩小为子组件.

### [src/ui/供应商](https://npmcn.com/package/%40apipass/design-system/src/ui/providers/)

自定义反应提供者定义

### [斜弧/斜角/斜角](https://npmcn.com/package/%40apipass/design-system/src/ui/utils/)

定制公用事业和公用事业组件

### 代码连接和故事本

所有代码连接 Docs 和故事书故事都遵循同样的分类定义 [斜弧/图形](https://npmcn.com/package/%40apipass/design-system/src/figma) 财务报告和审定财务报表 [曲线/故事](https://npmcn.com/package/%40apipass/design-system/src/stories)。 。 。 .

## 脚本

一些实例集成在 `scripts` 目录。 您可能需要额外的 API 范围 。 在可能的情况下,有一些插件实例可以帮助填补空白.

### [脚本/ 组件- 元数据](https://npmcn.com/package/%40apipass/design-system/scripts/component-metadata)

-   在菲格马JS控制台运行的脚本
-   Bulk 管理文件中所有组件的描述 。 与其制作一个复杂的插件,不如更简单地通过直接从JavaScript控制台运行脚本来做到这一点.
-   复制内容 [脚本/组件-元数据/导出组件JSON.js](https://npmcn.com/package/%40apipass/design-system/scripts/component-metadata/exportComponentJSON.js) 并打开文件在控制台中运行.
    -   将结果粘贴到 [脚本/组件-元数据/组件. json](https://npmcn.com/package/%40apipass/design-system/scripts/component-metadata/components.json)。 。 。 .
-   在那里,你可以更容易地修改描述.
-   一旦您修改了描述, 请复制 JSON 并粘贴在顶端 [脚本/组件-元数据/进口组件JSON.js](https://npmcn.com/package/%40apipass/design-system/scripts/component-metadata/importComponentJSON.js) 作为 `json` 变量.
-   复制导入文件的全部内容,并在控制台中运行,以批量更新整个文件的描述.
-   **这只会更新描述.** 要更新 Dev 资源, 您可以使用 [脚本/非资源](https://npmcn.com/package/%40apipass/design-system/#readme-scriptsdev-resources)。 。 。 .

### [脚本/非资源](https://npmcn.com/package/%40apipass/design-system/scripts/dev-resources)

-   `npm run script:dev-resources` (仅限REST API)
-   设置其中描述的所有组件的 dev 资源 [脚本/资源/资源](https://npmcn.com/package/%40apipass/design-system/scripts/dev-resources/devResources.mjs) 来匹配.
-   在批量交换urls时有用. 要求数 `Dev Resources: Write` 显示您的 REST API 指示符.

### [脚本/缩写](https://npmcn.com/package/%40apipass/design-system/scripts/icons)

-   `npm run script:icons:rest`
-   从文件中获取所有图标,并在 [锡克/锡克/锡克/锡克](https://npmcn.com/package/%40apipass/design-system/src/ui/icons) 目录.
-   还生成 [src/figma/icons/Icons.figma.tsx 互联网档案馆的存檔,存档日期2013-12-02](https://npmcn.com/package/%40apipass/design-system/src/figma/icons/Icons.figma.tsx) 代码连接.

### [脚本/脚本](https://npmcn.com/package/%40apipass/design-system/scripts/tokens)

-   `npm run script:tokens:rest`
-   从 Figma 获取所有变量和样式,并将其转换为 [src/主题.css](https://npmcn.com/package/%40apipass/design-system/src/theme.css)。 。 。 .
-   创建 [脚本/托克/托克](https://npmcn.com/package/%40apipass/design-system/scripts/tokens/tokensCodeSyntaxes.js) 这是您可以在Figma JS控制台运行的脚本,以更新所有变量的 [代码语法](https://www.figma.com/plugin-docs/api/Variable/#codesyntax) 与CSS匹配的重播.
-   包括一些没有变量 REST API 的插件来获取相同数据 .
    -   [安装插件](https://www.figma.com/plugin-docs/plugin-quickstart-guide/) 联合国
    -   运行插件,并将插件输出复制到 [脚本/脚本/样式. json](https://npmcn.com/package/%40apipass/design-system/scripts/tokens/styles.json) 财务报告和审定财务报表 [脚本/指针/指针.json](https://npmcn.com/package/%40apipass/design-system/scripts/tokens/tokens.json)
    -   运行 `npm run script:tokens` (无) `:rest`),它会直接引用JSON文件,而无需请求REST API更新它们

## 常见问题

### @apipass/design-system 是什么？

APIPass 反应设计系统

### 如何安装 @apipass/design-system？

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

### @apipass/design-system 支持 TypeScript 吗？

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

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

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

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

@apipass/design-system 使用 未声明 许可。package\.json 没有声明许可证。没有许可证的代码默认保留全部权利，商用前请联系作者或查看仓库中的 LICENSE 文件。以上为概括，不构成法律意见，请以许可原文为准。

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

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

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

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