# @ch-ui/tokens 中文文档

规范地址：https://npmcn.com/package/%40ch-ui/tokens/

版本：3\.0\.1
npm 元数据更新时间：2025-10-29T22:03:53.660Z
中文译文更新时间：2026-11-09T09:10:08.599Z
软件包许可：Ch Public License

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

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

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

- 包体积（解压后）：413 kB，45 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=20\.0\.0
- 运行依赖：4 个
- 首次发布：2024-09-05T21:02:34.401Z
- 最新版本发布：2025-10-29T22:03:53.414Z
- 近 30 天下载量：6513（2026-10-10 至 2026-11-08，npm 官方下载统计）
- 已发布版本数：24（近 12 个月 0 个）

## 中文简介

一个更可卖的网络的标志系统.

## 安装

```sh
npm install @ch-ui/tokens
```

也可以使用：`pnpm add @ch-ui/tokens`、`yarn add @ch-ui/tokens`、`bun add @ch-ui/tokens`

## README

# `@ch-ui/tokens`

符號套件使CSS自定义属性集,a.k.a. CSS变量,可以放入Tailwind等公用系统或网页组件库的上游(或自动使用).

这个软件包使用原则性方法生成符号,目的是让平台开发者、应用程序开发者和终端用户都更容易维护和应用对应用程序设计系统符号的调整.

## 开始

```shell
pnpm add -D @ch-ui/tokens
```

那么,使用任意的渲染功能 如果你在使用Vite, 已经存在 [`@ch-ui/vite-plugin-tokens`](https://npmcn.com/package/%40ch-ui/tokens/vite-plugin-tokens) 如果你喜欢.

## 使用 PostCSS

要添加到您的 PostCSS 设置中 :

```ts
import chTokens from '@ch-ui/tokens/postcss';
import myTokenSet from './config';
//...
plugins: [
  // ...
  chTokens((params: string) => myTokenSet),
  // ...
]
//...
```

在您的 PostCSS 中:

```postcss
@layer tokens {
  @tokens myTokens
}
```

别紧张.

如果你喜欢,可以使用 `params` 之后提供 `@tokens`。 。 。 .

如果出现空白画布综合症,则提供“默认符号集”:

```ts
import chTokens from '@ch-ui/tokens/postcss';
import { defaultTokenSet } from '@ch-ui/tokens';
import myTokenSet from './config';
//...
plugins: [
  // ...
  chTokens(
    (params: string) => params === 'myProductionApp'
      ? myTokenSet
      : defaultTokenSet
  ),
  // ...
]
//...
```

## 背景情况

设计系统经常保持一套有意有限的设计标志,例如:

-   在“平板”中排列的具体颜色,
-   字体大小按“平面”或“平面坡道”排列.

这些 _物理状态_ 符是最根本的地层,命名要使用的特定分级(数字)值. 同样的同义词可以在有条件的规则中重新定义,例如支持更广泛的游戏,例如: `rec2020`。 。 。 .

然后,物理符号的基层可以加一层 _语义_ 符号,将有条件规则保护的物理值映射到一个连贯有意义的名称,例如 `--fg-description` (对于“前景颜色:描述”)可以默认地映射到一种物理颜色,也可以在下列情况下映射到另一种颜色: `prefers-color-palette: dark`。 。 。 .

## 物理序列

所有设计标志最终都符合物理价值,在 `@ch-ui/tokens` 由 a 生成 _系列_ 沿连续线输入.

`@ch-ui/tokens` 执行三种系列:

-   _线性_, (中文(简体) ),
-   _指数_,以及
-   _螺旋弧_ 彩色调色板

例如,软件包在一个指数序列中带有默认字体大小:

```ts
const defaultSizes = {
  initial: 1,
  unit: 'rem',
  base: 1.2,
  naming: {
    '2xs': -3,
    xs: -2,
    s: -1,
    base: 0,
    lg: 1,
    xl: 2,
    '2xl': 3,
    '3xl': 4,
    '4xl': 5,
  },
} satisfies ExponentialSeries;
```

这将输出物理符号于 `rem` 输入值 `[-3, -2, -1, 0, 1, 2, 3, 4, 5]` 使用等式 `initial * Math.pow(base, input)`。 。 。 .

## 层

编剧:

-   `renderPhysicalLayer(physicalLayer: PhysicalLayer, semanticValues?: SemanticValues)`
-   `renderSemanticLayer(semanticLayer: SemanticLayer)`

物理和语义配置定义于 _层_ 让你根据 _条件_,这些只是嵌入式 CSS 语句(按规则或选择者)。 此外,层是设置命名空间的地方.

例如,当浏览器支持更广泛的游戏时,包会带有默认的颜色,使用条件来重新定义符:

```ts
export const defaultPhysicalColors = {
  conditions: {
    srgb: [':root'],
    p3: ['@media (color-gamut: p3)', ':root'],
    rec2020: ['@media (color-gamut: rec2020)', ':root'],
  },
  series: {
    neutral: {
      srgb: neutralArc,
      p3: neutralArc,
      rec2020: neutralArc,
    },
    accent: {
      srgb: accentArc,
      p3: accentArc,
      rec2020: accentArc,
    },
  },
  namespace: 'ch-',
} satisfies ColorsPhysicalLayer;
```

请注意: `neutralArc` 财务报告和审定财务报表 `accentArc` 是重复的螺旋弧系列;重复是偶然的,因为您可能想要在不同条件下使用不同的系列。 如何具体适用于颜色,详见 [`@ch-ui/colors`](https://npmcn.com/package/%40ch-ui/tokens/colors)。 。 。 .

## 语义层

使用语义分层,可以定义在不同的条件下将哪些名称映射到不同的物理符号上. 如果物理层将其值描述为 _系列_,语义层将其值描述为 [_语句_](https://en.wikipedia.org/wiki/Sememe) (/ˈsɛmiːms/),将有意义的名称映射到层中每个条件的物理值.

例如,软件包带有默认的语义层,用于在光和暗模式之间应用颜色:

```ts
export const defaultSemanticColors = {
  conditions: {
    light: [':root'],
    dark: ['@media (prefers-color-scheme: dark)', ':root'],
  },
  sememes: {
    'bg-base': {
      light: ['neutral', 975],
      dark: ['neutral', 150],
    },
    'fg-base': {
      light: ['neutral', 0],
      dark: ['neutral', 900],
    },
    // etc
  },
  namespace: 'ch-',
} satisfies SemanticLayer;
```

### 语义表达式

语义层支持表达式,在表达式中,您可以在字面值上指定一些操作,或者引用另一个语义符号,例如:

```ts
export const defaultSemanticColors = {
  // ...
  sememes: {
    'bg-base': {
      // ...
    },
    'fg-base': {
      light: ['neutral', '88f:bg-base'],
      dark: ['neutral', '-88f:bg-base'],
    },
    // ...
  },
  // ...
} satisfies SemanticLayer;
```

有了这个配置, `fg-base`光和暗的值将被计算成一个值,如果每个值都导致 [APCA 内值](https://apcacontrast.com/) ±88 当 `fg-base` 用作反对 `bg-base`。 。 。 .

在提到其他符号时注意,它们不能循环,最终必须达到字面价值.

有效操作取决于语义层配置的系列类型. 目前仅 `f` 财务报告和审定财务报表 `b` 行动得到支持,以及 `f` 财务报告和审定财务报表 `b` 仅适用于颜色序列 a.k.a. `HelicalArcSeries`。 。 。 .

## 面额

编剧: `renderFacet(facet: Facet)`。 。 。 .

为了更好的人文工程,物理和语义层可以合并成一个 _侧_像这样在一起的时候, `@ch-ui/tokens` 将自动推断语义层中提及的任何值应被添加到物理层的输入中。 如果您只使用语义值, 这意味着您不需要定义物理层中的任何值 .

## 打开所有符牌

所有符号都可以使用 `renderTokenSet(tokenSet: TokenSet)`。 。 。 .

A 类 `TokenSet` 这只是一个 `Record<string, Facet>` 包含您想要表达的方方面面.

## 审计

如果你想要更多关于系统为何会渲染物理标志的信息, 您可以对符号( 一次一个面) 进行审计 .

```ts
import { auditFacet } from '@ch-ui/tokens';
const colorsAudit = auditFacet(tokenSet.colors, { condition: 'p3' });
```

## 常见问题

### @ch-ui/tokens 是什么？

一个更可卖的网络的标志系统\.

### 如何安装 @ch-ui/tokens？

在项目目录运行 npm install @ch-ui/tokens，或使用 pnpm add / yarn add / bun add。

### @ch-ui/tokens 支持 TypeScript 吗？

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

### @ch-ui/tokens 支持 ESM 还是 CommonJS？

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

### @ch-ui/tokens 需要什么版本的 Node\.js？

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

### @ch-ui/tokens 可以商用吗？

@ch-ui/tokens 使用 Ch Public License 许可。声明的许可为 Ch Public License，请阅读许可原文确认使用条件。以上为概括，不构成法律意见，请以许可原文为准。

### @ch-ui/tokens 的下载量有多少？

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

### @ch-ui/tokens 还在维护吗？

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