# @assure-one/design-system 中文文档

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

版本：1\.50\.0
npm 元数据更新时间：2026-10-21T17:03:35.732Z
中文译文更新时间：2026-11-07T00:34:30.373Z
软件包许可：UNLICENSED

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

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

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

- 包体积（解压后）：7 MB，107 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=22
- 运行依赖：38 个
- peer 依赖：next \>=15，react \>=19，react-dom \>=19，stylelint \>=16
- 首次发布：2026-05-07T09:32:09.906Z
- 最新版本发布：2026-10-21T17:03:35.536Z
- 近 30 天下载量：3635（2026-10-07 至 2026-11-05，npm 官方下载统计）
- 已发布版本数：80（近 12 个月 80 个）

## 中文简介

确定 一个设计系统——为Assure套房的活物,原始物和图案.

## 安装

```sh
npm install @assure-one/design-system
```

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

## README

# 确保一个设计系统

跨出所有Assure产品外观设计的唯一真理来源.

-   **键** ——每个产品所消耗的语义CSS变量(颜色,类型,间隔,运动).
-   **初级** ——可访问 React 组件已建于 Radix + Tailwind 4.
-   **复合材料** – 常见图案 (DataTable, Pageheader, Sidebar, Kanban).

## 文档

-   [**`docs/components.md`**](https://npmcn.com/package/%40assure-one/design-system/docs/components.md) ——组件目录:按需要和类别划分的每个公共组件,其取而代之的取而代之的取而代之的取而代之的取而代之的取而代之. 根据API报告产生;货包中的船舶(`node_modules/@assure-one/design-system/docs/components.md`) (中文(简体) ).
-   [**`docs/for-ai-agents.md`**](https://npmcn.com/package/%40assure-one/design-system/docs/for-ai-agents.md) ——AI代理商和新贡献者的短则手册:永远不要生 HTML, the `Field` 食谱, `className` 对 `classNames`,则 `ds:` 前缀,符号,代码,测试,什么是实验,如何提出一个组件.
-   [**`CHANGELOG.md`**](https://npmcn.com/package/%40assure-one/design-system/CHANGELOG.md) ——逐批出货记录.
-   [**`CONTRIBUTING.md`**](https://npmcn.com/package/%40assure-one/design-system/CONTRIBUTING.md) ——dev循环,放出流量,版本化,陷阱.
-   [**`CLAUDE.md`**](https://npmcn.com/package/%40assure-one/design-system/CLAUDE.md) ——在这项回购中工作的AI助手的变动和约定.
-   [**`docs/integration/css.md`**](https://npmcn.com/package/%40assure-one/design-system/docs/integration/css.md) ——应用程序如何加载我们的 CSS:层序,导入序列,相容性预设,去除 `@source`,运行时间品牌主题.
-   [**`docs/testing.md`**](https://npmcn.com/package/%40assure-one/design-system/docs/testing.md) ——在应用的"杰斯特"测试中制作真实的软件包(`@assure-one/design-system/testing`,实验性).
-   [**`docs/forms.md`**](https://npmcn.com/package/%40assure-one/design-system/docs/forms.md) 建立一种形式: `Field` + 设计-系统控制 + 服务器动作 + zod, 重置和 `required`,每个控件提交,并测试它 `fillField` 编号 : `selectOption` 编号 : `pickDate`。 。 。 .
-   [**`docs/data-tables.md`**](https://npmcn.com/package/%40assure-one/design-system/docs/data-tables.md) ——构建数据表:无头 `useDataTable` 控制器(排序、页码、搜索、选择、列可见度、过滤器——每个可控),服务器 `manual` 模式,以及 URL 状态配方.
-   [**`docs/design-system/icons.md`**](https://npmcn.com/package/%40assure-one/design-system/docs/design-system/icons.md) ——图标目录及其服务器安全条目(`@assure-one/design-system/icons`,实验性):在没有客户端边界的服务器组件中导入图标.
-   [**`docs/adr/010-design-system-provider.md`**](https://npmcn.com/package/%40assure-one/design-system/docs/adr/010-design-system-provider.md) - 任择性 `DesignSystemProvider` (信息、语言、链接适配器) `/next` 条目; 快速启动为 [下级](https://npmcn.com/package/%40assure-one/design-system/#readme-the-provider-and-the-next-entry-experimental)。 。 。 .
-   [**`claude-skills/`**](https://npmcn.com/package/%40assure-one/design-system/claude-skills) 用于消费项目的Claude代码技能.

## 安装

```bash
pnpm add @assure-one/design-system
```

从您的应用程序全局样式表装入设计系统的 CSS, 作为拆分 条目,在一层语句下(您构造中的 Tailwind 4) :

```css
/* src/app/globals.css — the layer statement is the first line of the file */
@layer theme, base, ds, components, utilities;

@import "tailwindcss";

@import "@assure-one/design-system/css/tokens.css";
@import "@assure-one/design-system/css/legacy-aliases.css"; /* optional */
@import "@assure-one/design-system/css/tailwind.css";
@import "@assure-one/design-system/css/shadcn.css"; /* optional */
@import "@assure-one/design-system/css/base.css"; /* optional */
@import "@assure-one/design-system/css/components.css";

@import "./ds-preset.css"; /* your app's preset, optional */
```

然后使用组件 :

```tsx
import { Button } from "@assure-one/design-system";

export default function Page() {
  return <Button variant="primary">Click me</Button>;
}
```

### 分割 CSS 条目

分出项是自1.40起被记录的默认CSS集成. 每个 设计系统类是 `ds:`\- 前缀并编入 `css/components.css` 内部 `@layer ds`,所以你自己的公用事业 总是赢得组件样式和 你的"尾风"从不用扫描我们的包裹.

| 子路径 | 这是什么 |
| --- | --- |
| `./css/tokens.css` | 这个 `--ds-*` 设计符号 : `:root`,颜色方案范围和品牌范围. 无任何组件可用. |
| `./css/legacy-aliases.css` | 读取从今天的代名词到空格名称(`--color-surface: var(--ds-color-surface)`),只要您自己的CSS读取设计系统符号名称. |
| `./css/tailwind.css` | 尾风 `@theme` 桥,所以 `bg-surface/40`, (中文(简体) ), `hover:text-fg-3` 财务报告和审定财务报表 `rounded-control` 编译入 __ 而不是无声无息地生产. |
| `./css/shadcn.css` | App-vobulary大桥: `background`, (中文(简体) ), `foreground`, (中文(简体) ), `primary`, (中文(简体) ), `muted`, (中文(简体) ), `destructive`,半径尺度和其余,每个读出一个 `--app-*` 输入可以覆盖 . |
| `./css/base.css` | 可选文档默认:正文背景、墨水、字体和 `color-scheme`。没有飞行前、没有元素规则和字体导入. |
| `./css/components.css` | 由Tailwind编辑的公用事业部分 `ds` 前缀( e)`ds:flex`, (中文(简体) ), `ds:bg-surface`内部 `@layer ds` 和约束 `--ds-*` 标志. |

导入命令为 `tokens.css` → `legacy-aliases.css` (可选) `tailwind.css` → `shadcn.css` (可选) `base.css` (可选) `components.css`,在你自己之后 `@import "tailwindcss"` 和层下语句 `@layer theme, base, ds, components, utilities;`。 。 。 . [**`docs/integration/css.md`**](https://npmcn.com/package/%40assure-one/design-system/docs/integration/css.md) 拥有完整的 序列,每个应用程序的预置位置,为什么没有 `@source` 我们的包裹 需要,而固定 运行后面的每一个权利要求。 推理活着 内 [ADR-004 (英语)](https://npmcn.com/package/%40assure-one/design-system/docs/adr/004-css-delivery-cascade.md) 财务报告和审定财务报表 [ADR-005 (英语)](https://npmcn.com/package/%40assure-one/design-system/docs/adr/005-app-vocabulary-bridge.md)。 。 。 .

### `styles.css` (折旧)

`@assure-one/design-system/styles.css` - 一张单子上都有 飞行前, 一个谷歌字体 `@import` 以及被冻结的未加固定的后遗症 实值 **自1.40起贬值** (登记) `C-CSS-STYLES`) (中文(简体) ). 还是船,没有改变, 并被以 3.0 键删除; 已建文件以折旧打开 图标。 移动到拆分条目是有意的视觉变化(文档字体) 大小、字体、飞行前: [`docs/integration/css.md`](https://npmcn.com/package/%40assure-one/design-system/docs/integration/css.md) 第6条和 [`docs/migration/1.40.md`](https://npmcn.com/package/%40assure-one/design-system/docs/migration/1.40.md)。 。 。 .

### 运行时品牌主题(实验)

对于只在跑步时间才知道的租户颜色, `@assure-one/design-system/tokens` 出口 `createBrandTheme()`: 经验证的种子成为自定义属性 a 内置品牌范围宣布,准备扩展为 `style` 属性.

```tsx
import { createBrandTheme } from "@assure-one/design-system/tokens";

<div style={{ ...createBrandTheme({ brand: "#2258d8", accent: "#f59e0b" }) }}>…</div>;
```

它是纯洁的,而SSR决定主义的, 夹住一个填充太苍白,不能读对面 和保证WCAG AA的每一个前方。 种子形状是 受D7号决定约束,在该决定开放期间可能改变——见 [`docs/integration/css.md`](https://npmcn.com/package/%40assure-one/design-system/docs/integration/css.md#5-runtime-brand-theming)。 。 。 .

### 品牌艺术

保证文字标记和标记 `Logo` 将船装入包裹内,下方 `public/brand/`由您的应用程序提供,不是进口的,所以复制一次 进入您的公共文件夹 :

```sh
cp -R node_modules/@assure-one/design-system/public/brand public/brand
```

从子路径调用的程序 `setAssetBasePath("/my-base")` 曾经 首先转换文件,而不是移动文件。 A 类 `Logo` 谁 艺术品不装入 回到品牌glyph + 文本锁,所以没有 需要安装可读锁.

### 提供者和 `/next` 条目(实验)

不需要一个提供者:每个组件都使英语字符串,格式 与 `en-US` 和(用于) `LinkButton` 编号 : `Logo`)使一个平地 `<a>` 编号 : `<img>`。 。 。 . 在下一个.js, 渲染 `NextDesignSystemProvider` 获取 `next/link` 路线和 `next/image`: 根导入否 `next/*` 从2.0. `DesignSystemProvider` 是一个可选的,瘦的,客户端的提供者 cSS不能做的——通用字符串,语言,文本方向, 门户容器、链接和图像适配器、共享工具提示默认以及 吐司地区 它没有DOM包装([ADR-010 (英语)](https://npmcn.com/package/%40assure-one/design-system/docs/adr/010-design-system-provider.md)) (中文(简体) ).

```tsx
// app/layout.tsx (Next.js) — the Next adapters are filled in for you
import { NextDesignSystemProvider } from "@assure-one/design-system/next";

export default function RootLayout({ children }) {
  return (
    <html lang="de">
      <body>
        <NextDesignSystemProvider
          locale="de-DE"
          messages={{ select: { clear: "Auswahl löschen" }, combobox: { empty: "Keine Treffer" } }}
        >
          {children}
        </NextDesignSystemProvider>
      </body>
    </html>
  );
}
```

-   **`messages`** 输入目录中的任何子集 `DsMessages`,按构成部分分列 命名空间( n)`select`, (中文(简体) ), `searchInput`, (中文(简体) ), `combobox`, (中文(简体) ), `field`, (中文(简体) ), `fileUpload`; 更多 加入到覆盖物上。 解决总是 _组件道具 > 提供者 > 英语默认_每个键。 英语列表全文为: `src/foundation/messages/en.json`; 参数化消息是函数 (单位:千美元)`combobox.create: (query) => string`) (中文(简体) ).
-   **`locale`** 默认的 BCP 47 标签 `"en-US"` 在服务器上 _财务报告和审定财务报表_ 客户. 通过您的应用程序已经知道服务器侧; 设计系统永远不会 读取 `navigator.language` 在渲染过程中,服务器和客户端HTML都同意.
-   **`linkComponent` 编号 : `imageComponent`** - 什麽 `LinkButton` 财务报告和审定财务报表 `Logo` 提交 通过。 没有它们,部件就变成平地 `<a>` 编号 : `<img>` (全额) 页面导航)。 一个非下一个应用程序通过它的路由器链接; 一个 Next.js 应用程序使用 `NextDesignSystemProvider`。 。 。 . `next` 是一个可选的对等点, 仅由 `/next` 输入.
-   **`portalContainer`**, (中文(简体) ), **`dir`**, (中文(简体) ), **`tooltip`**, (中文(简体) ), **`toasts`** - 记录 道具 道具 道具. `toasts` 举起土司地区 `useToast()`; 如果 您已经使 `ToastProvider`。 。 。 .

## 消费者的 Lint 配置

两艘可共享配置的飞船与包裹(**实验**,W7-18) 所以一个 类似的东西的产品用意 这个寄存器会自燃 每个 规则是 **警告**在代码上通过它,记录计数 把它切下来.

```js
// eslint.config.mjs
import ds from "@assure-one/design-system/eslint-config";
export default [...ds.configs.recommended];

// stylelint.config.mjs  (stylelint is yours — an optional peer dependency here)
export { default } from "@assure-one/design-system/stylelint-config";
```

| 规则 | 报告 |
| --- | --- |
| `ds/no-raw-controls` | 原始内容 `<button>`, (中文(简体) ), `<input>`, (中文(简体) ), `<select>`, (中文(简体) ), `<textarea>` 在存在设计系统控制的情况下 |
| `ds/no-radix-imports` | 一个直接 `@radix-ui/*` 导入而不是包装它的原始 |
| `ds/no-deep-imports` | 超过已公布条目的导入(`dist/…`, (中文(简体) ), `src/…` ——ADR-011号卫星 |
| `ds/no-ds-token-redefinition` | (单位:千美元) `--ds-*` 符号设置在内, 文件外 `presets/` |
| `assure-ds/no-ds-token-redefinition` | 在CSS(stylelint;)中相同; `presets/` 财务报告和审定财务报表 `*.preset.css` 豁免) |
| `assure-ds/no-important-on-ds-selectors` | `!important` 编号 `ds:`编号 :`data-slot` 选择器——通过 `className`编号 :`classNames` 换成 |

提高规则 `"error"` 在你自己的配置 一旦你干净。 收养人数 应用被跟踪为W7-19.

## 开发

```bash
pnpm install
pnpm storybook    # http://localhost:6006
pnpm build        # bundle for publishing
pnpm typecheck
pnpm lint
```

见 [`CONTRIBUTING.md`](https://npmcn.com/package/%40assure-one/design-system/CONTRIBUTING.md) 包括针对一个真正消费的应用软件的延展.

## 建筑

3级符号系统, 作者为 DTCG JSON in [`tokens/src`](https://npmcn.com/package/%40assure-one/design-system/tokens/README.md) 生成到 `src/tokens/` 编辑 `./css/*` 条目(ADR-003):

| 级别 | 示例( 名称空格名称 ) | 读取 |
| --- | --- | --- |
| 参考文献 | `--ds-ref-brand-pro-fg: #6c42f8` | a 字形;生坡道,每品牌一通 |
| 系统(语义) | `--ds-color-action-brand-bg: var(--ds-ref-brand-pro-fg)` | 参考层次; **这是公共合同** |
| 组件 | `--ds-menu-item-hover-bg: var(--ds-color-canvas-sunken)` | 系统级; 只有在一个组件必须能够单独使用的情况下 |

组件消耗 **系统符号**,从不直接引用值。 主题 (彩色计划,每品品牌,运行时品牌来自 `createBrandTheme()`(中文(简体) ) 重映射系统 ~ 引用而不触摸组件代码.

每个符号都有两种已公布的拼写: 取名空间 `--ds-*` 上方名称和 留下的遗产名称`--color-brand`, (中文(简体) ), `--color-pro-fg`, (中文(简体) ), `--color-menu-item-hover-bg`) (中文(简体) ). `css/legacy-aliases.css` 声明 `<legacy>: var(<--ds-* name>)` 因此双方都决心 价值——由 `pnpm tokens:ds-check`。 。 。 .

## 释放

由标签驱动发布到 public npm. 见 [`CONTRIBUTING.md`](https://npmcn.com/package/%40assure-one/design-system/CONTRIBUTING.md#release-flow) ; 以往的释放 [`CHANGELOG.md`](https://npmcn.com/package/%40assure-one/design-system/CHANGELOG.md)。 。 。 .

## 常见问题

### @assure-one/design-system 是什么？

确定 一个设计系统——为Assure套房的活物,原始物和图案\.

### 如何安装 @assure-one/design-system？

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

### @assure-one/design-system 支持 TypeScript 吗？

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

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

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

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

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

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

@assure-one/design-system 使用 UNLICENSED 许可。作者声明为 UNLICENSED，即不授予公开使用许可（与公共领域的 Unlicense 不同）。使用前需获得作者授权。以上为概括，不构成法律意见，请以许可原文为准。

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

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

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

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