# @charcuterie/tokens 中文文档

规范地址：https://npmcn.com/package/%40charcuterie/tokens/

版本：1\.10\.2
npm 元数据更新时间：2026-09-28T17:37:34.737Z
中文译文更新时间：2026-11-09T10:59:13.346Z
软件包许可：MIT

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

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

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

- 包体积（解压后）：1.1 MB，122 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：0 个
- 首次发布：2026-07-31T04:30:54.168Z
- 最新版本发布：2026-09-28T17:37:34.264Z
- 近 30 天下载量：2840（2026-10-10 至 2026-11-08，npm 官方下载统计）
- 已发布版本数：18（近 12 个月 18 个）

## 中文简介

Charcuterie 组件库的设计符号 。 零依赖性,无反应.

## 安装

```sh
npm install @charcuterie/tokens
```

也可以使用：`pnpm add @charcuterie/tokens`、`yarn add @charcuterie/tokens`、`bun add @charcuterie/tokens`

## README

# `@charcuterie/tokens`

设计-接地层. **零依赖性,无反应.**

`castkit/packages/views` 通过佐藤里制作给 ePaper PNG 并需要颜色和 间距值不拉入反应树; `slatecast` 预算为60KB克兹。 两者 这就是为什么这是一个单独的包 从 `@charcuterie/ui`。反应消费者从不看到两个 名称 - 它们导入 `@charcuterie/ui/tokens`。这是建筑图分割,而不是API分割.

## 运行它

节点 24 直接运行 TypeScript, 所以 **不需要安装** 用于使用其中任何一种 脚本 :

```bash
node scripts/checkContrast.ts   # the WCAG 2.2 AA gate — exits non-zero on failure
node scripts/buildTokens.ts     # → dist/{variables,theme,first-paint}.css, dist/tokens.json
node scripts/fetchFonts.ts      # re-download the three shipped faces → fonts/, src/fonts.css
node scripts/buildPreview.ts    # → preview/index.html, the M0 bake-off board
node scripts/buildEpaperPreview.ts  # → preview/epaper-palette.html, the ePaper board
```

这是刻意的,值得保存的:M0烤面包在工作区之前运出 已经存在,一个符号更改应该让一个命令远离重建的棋盘.

`fetchFonts.ts` 是需要网络的例外, 这是这里唯一的脚本 写一个跟踪二进制。 说得很清楚 `fonts/` 在调试之前,因为谷歌 文件名带有内容散列物,覆盖物会让那些老的孤儿在 包永远.

## 字体

三相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相`--font-display`),外衬 (单位:千美元)`--font-sans`)和维克多·莫诺(英语:`--font-mono`),所有SILOFL. 消费者增加一行:

```css
@import "@charcuterie/tokens/fonts.css";
```

从 `theme.css` 进口令牌不应强迫 字体下载。 佐藤店的消费者想独来独往 可以在 `@charcuterie/tokens/fonts/<name>.woff2`。 。 。 .

**单是维克多·莫诺,不是丹克·莫诺.** 这是许可证的限制,而不是 偏好,而压倒它每个应用 是一个得到支持的一行 [决定](https://npmcn.com/package/docs/decisions/2026-07-30-the-shipped-mono-is-victor-mono.md) 已经 片断。 在这支舰队中,领有执照的Dank Mono woff2不得进入任何回购 通过一个只读的绑定器从NAS上架来达到一个应用程序—— [怎么样](https://npmcn.com/package/docs/decisions/2026-08-05-dank-mono-reaches-the-fleet-by-bind-mount.md)。 。 。 .

通过Yarn,从任何地方 在repo:

```bash
yarn workspace @charcuterie/tokens build   # tsc → dist/*.js + .d.ts, then the CSS
yarn workspace @charcuterie/tokens test    # Vitest, including the contrast gate
```

`build` 运行 `prepack`这样 `dist/` 产生而不是承诺.

**两个源工作流程同时直播** 因为 `tsconfig.base.json` 套装 `rewriteRelativeImportExtensions`源导入兄弟姐妹 `./contrast.ts` - 哪个 是让节点运行它而不建设的, 和Tsc重写这些到 `./contrast.js` 打开 离开的路。 没有这种旗帜,这两个工作流程是相互排斥的.

### 对比门现在是一个考验

`src/contrast.test.ts` 完成同样的审计 `scripts/checkContrast.ts` 指纹。 这是 页:1 _仅限_ m1变了 一个真理的来源,被董事会问 剧本,还有CI一样的——一个剧本大门,只是人们记得要运行的.

## 两级

**第1级** 原始斜坡( r)`neutral.50…950`) (中文(简体) ). 某一构成部分永远不得提及某一构成部分。 他们 因此,一个变体作者有 东西来构建第二级.

**第二级** 是语义角色,它是唯一可以命名的层次组件 :

| 组 | 作用 |
| --- | --- |
| `surface` | `base`, (中文(简体) ), `raised`, (中文(简体) ), `sunken`, (中文(简体) ), `overlay`, (中文(简体) ), `inverse` |
| `content` | `primary`, (中文(简体) ), `secondary`, (中文(简体) ), `muted`, (中文(简体) ), `disabled`, (中文(简体) ), `onAccent` |
| `border` | `subtle`, (中文(简体) ), `default`, (中文(简体) ), `strong`, (中文(简体) ), `focus` |
| `intent` | `{neutral, accent, success, warning, danger, info}` × `{surface, surfaceHover, border, content, solid, solidHover, onSolid}` |
| `categorical` | `{1 … 10}` • 相同的七个角色 |
| `focus` | `ring`, (中文(简体) ), `ringOffset`,以及 `focusRing.width` 编号 : `.offset` |

`intent` 是一个普通的 rindeck的 `TONE_CLASS` 地图——它目前使用的地图 两者均相同 `VerdictBadge.tsx` 财务报告和审定财务报表 `TowerAlerts.tsx`。 。 。 .

### `intent` 意味着什么; `categorical` 故意没有

每一个成员 `intent` 是一个 **索赔**数字 : `danger` 不是一种颜色,而是关于 如果你按下它,组件打开它会发生什么. `categorical` 这是 颜色的家族 a **用户选择** ——道克特标签,项目,图表系列——其中: 语义上的名字会是一个谎言 设计系统告诉他们。 编号,因为 没什么好说的.

产生而不是手工挑选: `CATEGORICAL_HUES` 表示色角并 `buildCategoricalScheme` 以对比目标解决每个角色 计划。 变体说明其 _字符_ (单位:千美元)`chromaScale`, (中文(简体) ), `contentContrast`永远不会 he.

两道门,不是一道. 每对绝对对 注册在 `contrastAudit.ts` 旁边 意图——此外 **互相攻击**,因为两个指数都可以清楚 4.5: 1 在同一地平面上,并且与每一数字的颜色相同 地板绿色. `getCategoricalDistinctnessFailures` 测量 OKLab 中的每对 最紧 `solid` 机队中的一对是QQ Eok 0.0893,对手是0.0835 Tableau 10实现 为了自己.

`getCategoricalIndex(key)` 表示在 特性。 这是一个倒计时,绝不是压倒性——一个存储的拾取胜.

边界与 `Swatch`数字 : `Swatch` 取颜色 **从世界抵达** (实物) 贴纸,一张相册口音),并且可以保证任何关于它的东西; `categorical` 是一个被整理的集 用户选择 _从_这样它就能保证一切. [决定](https://npmcn.com/package/docs/decisions/2026-08-19-categorical-is-a-curated-palette-not-ungoverned-colour.md)。 。 。 .

### 为什么意图带有 _固态_ 以及一个 _表面_

该计划命名了四个意图角色. 建造标本板 第五个需要 马上. `surface` 这是 **有锡** 处理机队已经用于状态 药丸(`bg-blue-950 text-blue-300`); 主按钮为 a **饱和填充** 拥有自己的 文本颜色。 从另一层推导出来的 恰恰是这个层的猜测 删除,因此两者都说明——和 `onSolid` 因为无论白色还是白色 近黑者在给定的填充量上胜负,真实性因意图的不同而异(在 `layered`白色失败 珊瑚口音和近黑口音在5.4:1时通过.

## 三轴和一轴

`data-scheme` {\\fn黑体\\fs22\\bord1\\shad0\\3ahbe\\4ah00\\fscx67\\fscy66\\2chffffff\\3ch808080}你这混蛋 `data-density` (舒适的qq收缩qq亭) ^ `data-variant` (视觉方向) - 所有三个都是 `<html>` 属性和所有三个 编曲. 一个属性翻转重取主题 **零重递**,因为没有 在 React 中观察变化.

**ePaper不是第四个轴.** 单项出口(`@charcuterie/tokens/epaper`(中文(简体) ) 因为它消除了能力 而不是让他们休息: 没有悬浮, 没有不透明,没有 阴影,没有过渡, 和颜色限制在一个小到可以保持锋利边缘的集合. 建模为 `data-scheme="epaper"` 将意味着 `data-variant` 仍然适用, 它不能做到这一点.

### 六是哪个 _像素_ 可能不是面板能显示的

用来声称其调色板的配置是"面板可以实际渲染出六种颜色" 这是 **虚假**,这就是为什么限制被理解为任意。 光谱 6 面板 将每个像素设置为六分之一; a _区域_ 以像素表示的比喻要多得多,因为 司机dithers——这正是舰队相片路径一直依赖的.

真正的规则是按键 **正在绘制什么** (单位:千美元)[决定](https://npmcn.com/package/docs/decisions/2026-07-31-epaper-restricts-colour-by-what-is-drawn-not-by-the-panel.md):

| 什麽 | 它可能用来什么 | 数到6 |
| --- | --- | --- |
| 图片 | 完全分化的游戏——不是这个简介的生意 | 接近连续 |
| 大面积平地填充 | `inks` **\+ 键 `blends`** | **第 19 条** |
| 边框、 小文本、 图标 | `inks` 仅限 | 6个 |

```ts
import { epaperPanels, spectra6Blends } from "@charcuterie/tokens/epaper"

// a large fill — the panel-side quantizer turns this one flat hex
// into a 50/50 yellow-red checkerboard
const fill = spectra6Blends.yellowRed // #DB8225

// a 1px rule — six inks only, or it becomes a dotted line
const rule = epaperPanels.spectra6.family === "fixedInk"
  ? epaperPanels.spectra6.inks.black
  : undefined
```

15个墨子中有两个是 **没有,而不是现在和错误**数字 : `blackYellow` 财务报告和审定财务报表 `yellowBlue` 完全量化为不同的一对,所以没有六分位值 他们.

`epaperPanels` 被面板键入并受到歧视 `family`。 。 。 . `fixedInk` 带面板 `inks` 编号 : `emittedInks` 编号 : `blends`· ; `continuousTone` 面板 — E 墨水画廊 3 ~ 50,000 颜色 ACEP, **不在舰队里** ——没有携带,因为没有调色板可以 列举,因此没有发明.

`node scripts/buildEpaperPreview.ts` 画整件事,检查板和所有,从 `src/epaper.ts`。承诺董事会是 [`docs/previews/2026-07-31-m6g-epaper-palette.html`](https://npmcn.com/package/docs/previews/2026-07-31-m6g-epaper-palette.html)。 。 。 .

## 从这里开始的第一纸船——复制,永远不要 `<link>` 这个

每个应用程序在其条目HTML中需要一行CSS,在任何程序之前涂上画布 样式表已解析,或用一整页的白色闪光打开了深色应用程序. `dist/first-paint.css` 是这条线,从同一个字头为两个方案生成 `variables.css` 全文如下:

```html
<style>
  html, body { background-color: var(--color-surface-base, #131822); color-scheme: dark; }
</style>
```

**贴上. 别 `<link>` 这个.** 样式表请求是网络回转和跳动 来回旅行是规则的全部工作 连接文件会重新显示它 存在可以防止,同时看起来像 tidier 选项。 已导出 (单位:千美元)`@charcuterie/tokens/first-paint.css`所以,一个建筑可以读它 所以,"这是哪里做的 片段来自"有一个答案.

**这个 `var()` 这是这艘船从一个包而不是维基页面 得到的原因.** 一个 内入 `<style>` 实值 **无层**,并且没有层次的作者 CSS 击败每个 `@layer` 无论 - 尾风 v4 向 `@layer utilities`所以赤裸裸的形态, `background-color: #131822`,不只是画早期: **排行 `bg-surface-base` 打开 `<body>` 永久**,没有 `data-scheme` 翻转可以到达页面背景 。 灯光模式 然后在暗色画布上制作轻卡。 写成 _倒计时_,文字仅适用于 时 `--color-surface-base` 这是没有定义的——规则曾经存在的那一刻.

3个应用软件手抄了赤色的形态,3个应用软件得到bug. [决定记录](https://npmcn.com/package/docs/decisions/2026-07-31-tokens-ships-the-first-paint-snippet.md) 有测量.

`color-scheme` 需要没有 `var()`数字 : `variables.css`是因为 `[data-scheme]` 规则也是没有层次的,所以 它在特异性上获胜 而不是输给这个.

### 在应用程序中打开副本

`buildFirstPaintRule` 仅返回规则——一行,无评论——所以消费者的漂移 测试是一个论断,它把 `var()` 以及六分卫:

```ts
import { buildFirstPaintRule, daylight } from "@charcuterie/tokens"

expect(indexHtml).toContain(
  buildFirstPaintRule(daylight, "dark"),
)
```

这是三个被破的应用程序无法写的大门, 因为每个都只有自己的副本.

## `colour` 在类型脚本中, `--color-*` 在中央支助系统

这种分裂是蓄意的 **绝不能被"固定"**。 。 。 .

使用 TS 标识符 `colour`匹配 `e6Colour` 编号 : `colourMode` 编号 : `getAccentColour` 内 `castkit/packages/views/src/viewStyles.ts`,按照关于匹配现有 术语。 CSS 自定义属性使用 `--color-*` 因为 **尾风v4's `@theme` 仅限 生成 `bg-*` 编号 : `text-*` 编号 : `border-*` 水电费 `--color-` 命名空间**。 。 。 . 把他们改头换面 `--colour-*` 静静地生成一个无功能的样式表 .

## 仅逻辑属性

每个空间价值都作为逻辑属性消耗—— `padding-inline`, (中文(简体) ), `margin-block`, (中文(简体) ), `inset-inline-start`, (中文(简体) ), `border-inline-start`, (中文(简体) ), `text-align: start`永远 `left`编号 :`right`。 。 。 . 在尾风,意思是 `ms-`编号 :`me-`编号 :`ps-`编号 :`pe-`编号 :`start-`编号 :`end-`编号 :`border-s`编号 :`border-e`。 。 。 .

现在不花什么钱,让RTL在不久之后几乎自由,这就是为什么这是一条规则 而不是喜欢. `scripts/previewStyles.ts` 完全是这样写的,是 最终的ESLint规则将被测试.

## 对比是检验,不是指导

`scripts/checkContrast.ts` 将每个内容和意向一对穿过每一个 (变相×计划),并退出低于阈值的非零.

-   **WCAG 2.2是大门** - 4.5:1,案文(1.4.3),3:1,管制界限和重点 指标(1.4.11)。 这是规范性的,也是审计将使用的内容.
-   **与APCA一起报道** 它的模型在黑暗的UI上 感觉的对比要好得多, 但WCAG 3仍然是一份工作草案, 所以在它上指在移动的目标上.

报告有两个类别,但从未加门,每个类别都有明确的理由:

-   `content.disabled`,因为 WCAG 明确豁免不活动控制,并标注它 将强制禁用文本显示已启用.
-   装饰行- `border.subtle`, (中文(简体) ), `border.default`,以及 **意图** 徽章轮廓. 1.4.11 涵盖边界 _需要识别控制_而不是屏幕上的每一行. `border.strong` **实值** 有门,因为那是文本输入、复选框和切换的作用 轨迹自画自画 **绝对** 边框,因为一个丸读 "Homelab"是用它的颜色和别的东西来识别的 (单位:千美元)[决定](https://npmcn.com/package/docs/decisions/2026-08-19-categorical-borders-are-gated-where-intent-borders-are-exempt.md)) (中文(简体) ).

将范围界定错误不是无害的: 3:1的标注装饰产生了65个"失败" 第一跑步,这正是 对比门如何关闭.

审计还声称: **别名漂移**数字 : `content.onAccent` 必须是平等的 `intent.accent.onSolid`,以及 `border.focus` 必须是平等的 `focus.ring`。两个名字换一个 值是一个等待第一个只调取其中之一的bug .

## 添加变体

复制任何文件 `src/variants/`,修改数值,添加到 `src/variants/index.ts`, (中文(简体) ), 然后运行 `node scripts/checkContrast.ts`。如果退出零,请运行 `buildPreview.ts` 看着 临Τ 两个步骤都需要——大门证明是 _可读_,不是说它是 _不错_。 。 。 .

`src/variants.test.ts` 也持有属性 一个新的方向最有可能 断开:光模式不是纯白色, `raised` 财务报告和审定财务报表 `sunken` 实际从 `base`,每一个意图 _和每个绝对指数_ 所有七个角色,每个表是 透明六位数的螺旋 十个绝对的螺旋可以分辨 非零宽度。 更新文件中的名册断言 添加一个;该断言存在,所以无法添加变量 _安静_。 。 。 .

## 在 M3 关闭: 结构命名空间现在也到达了 Tailwind

`theme.css` 地图 `--color-*` 输入 `@theme`,生成 `bg-*` 编号 : `text-*` 编号 : `border-*`。 。 。 . 到M3的时候,它也是 **5个结构命名空间**,所以一个组件写入普通 公用事业和获得我们的价值观:

| 发表 | 读取 | 使用它修正 |
| --- | --- | --- |
| `--text-{xs…2xl}` | `--font-size-*` | `text-sm` - 而我们的密度 |
| `--leading-*` | `--line-height-*` | `leading-normal` |
| `--shadow-{low,medium,high}` | `--elevation-*` | `shadow-low`,了解计划 |
| `--ease-*` | `--easing-*` | `ease-standard` |
| `--spacing` | `space[1]` | `p-3` 是象征值,不是巧合 |

`--radius-*`, (中文(简体) ), `--tracking-*`, (中文(简体) ), `--font-*`,以及 `--font-weight-*` 不需要桥梁: 与 Tailwind 名称空间相撞 `:root` 已经, M1 碰撞审计被锁定 如所欲为. `--duration-*` 财务报告和审定财务报表 `--control-*` 没有尾风命名空间,所以 组件以 `duration-(--duration-fast)` 财务报告和审定财务报表 `h-(--control-height-md)`。 。 。 .

设定由 `THEME_BRIDGES` 并坚持两种方式: `tailwindCollisions.test.ts`数字 : 未公布但被公布的桥也失败了 未经公布但被公布的桥也失败了 每个 故意输入 **重新定义每个消费者的现有用途** - 这就是重点, 这就是为什么它是一个决定 而不是一个调整: [发展成果评估](https://npmcn.com/package/docs/decisions/2026-07-29-theme-css-bridges-tailwind-namespaces.md)。 。 。 .

`packages/docs/src/TokenSpecimen.tsx` 仍然读过 `var()`左边 作为前相; `@charcuterie/ui` 是后边.

## 这里也会产生容器-干燥变体

`theme.css` 发出一个 `@custom-variant` 容器 -- -- 干燥度的每步 **字义** 阈值, 因为容器查询的条件在自定义前解决 属性存在 - `@container (min-inline-size: var(--cq-sm))` 无效 CSS :

```css
@custom-variant cq-sm (@container (min-inline-size: 24rem));
```

这么说吧 `cq-sm:` . `cq-xl:` 是我们的,匹配 `--cq-*`而不是尾风 `@sm:`,哪个 读取 `--container-*` 命名空间,我们刻意移走. [决定](https://npmcn.com/package/docs/decisions/2026-07-29-container-query-variants-are-generated.md)。 。 。 .

## 常见问题

### @charcuterie/tokens 是什么？

Charcuterie 组件库的设计符号 。 零依赖性,无反应\.

### 如何安装 @charcuterie/tokens？

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

### @charcuterie/tokens 支持 TypeScript 吗？

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

### @charcuterie/tokens 支持 ESM 还是 CommonJS？

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

### @charcuterie/tokens 可以商用吗？

@charcuterie/tokens 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @charcuterie/tokens 的下载量有多少？

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

### @charcuterie/tokens 还在维护吗？

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