Token

token 是一个有名字的值：一种颜色、一种阴影、一个尺寸。组件和产品只用名字，从不直接用值，所以一个值只需在一处修改，所有界面在两种模式下都会跟着变。本页是所有 token 的参考。在 token 之间如何选择的规则，归属于各组 token 所属的基础页面，下面每一节都附有链接。

原则

• 只有一个来源。 tokens.json 里的每个 token 只在那里写一次。foundation.css 由它生成，其他任何地方都不定义 token 的值。
• 名字说明角色，不说明颜色。 写 attention，不写粉色；写 layer-canvas，不写白色。值变了，token 的名字不变；深色模式的值也放在同一个名字下。
• 先用角色 token，再用调色板。 只有在没有合适角色时才用 palette-*；见颜色。
• 一个值用到第三次就变成 token。 只用一次的值可以内联，写成一个墨色阶或一个 oklch() 字面量；用到第三次时，添加一个 token。

token 放在哪里

使用 Tailwind 的应用引入 @botiverse/raft-ui/styles.css。不用 Tailwind 的页面引入 @botiverse/raft-ui/foundation.css，读取自定义属性：var(--layer-canvas)。

foundation.css 如何生成

packages/ui/scripts/build-tokens.mjs 读取 tokens.json，写出 foundation.css。不要手动编辑 foundation.css。

vp run @botiverse/raft-ui#build:tokens          # write src/foundation.css
node packages/ui/scripts/build-tokens.mjs --check   # exit 1 if it is out of date

• 在 tokens.json 里改一个值，运行 build:tokens，然后两个文件一起提交。foundation.css 与 tokens.json 不一致时，测试（foundation.generated.test.ts）会失败。
• token 的路径就是它的属性名：{layer.canvas} 对应 --layer-canvas。$root 表示分组本身：{foreground.$root} 对应 --foreground。引用（"{palette.cyan.800}"）会变成 var(--palette-cyan-800)。
• 这个格式没有表示模式的字段，所以 tokens.json 加了一个扩展 build.botiverse.raft：

生成的文件依次包含：

1. 调色板，在 :where(:root) 上；
2. 浅色模式，在 :where(:root) 和 .light 上；
3. 深色模式，在 .dark 上；
4. 再写一遍深色模式，放在 @media (prefers-color-scheme: dark) 下，针对没有 .light 或 .dark 的根节点，这样在应用设置 class 之前页面的颜色就是对的；
5. 在每个模式中都声明的别名，然后是弃用的名称；
6. 桌面端的值，放在 @media (width >= 48rem) and (pointer: fine) 下（也是 styles.css 中桌面字号用的查询），选择器与它们所替换的值相同。

深色页面里的 .light 元素是一个浅色孤岛，用于预览或传送门（portal）；styles.css 中的 dark: 变体跟随最近的模式 class。见深色模式。

token 命名规则

名字由几个部分组成，所以即使是没见过的名字，你也能看出它是做什么的。

中性角色。 角色是以下四种之一：

• foreground-*：文字和图标；
• layer-*：表面，按叠放顺序排列（外框、侧边栏、画布、卡片、弹出层）；
• line-*：线；
• fill-*：铺在表面里或表面上的填充。

用途说明 token 用在哪里：frame、sidebar、canvas、card、popover、code、hud、on-frame、on-hud、link、field。强度从不带后缀的名字往下到 -muted，文字再往下是 -hint；线则从 -hairline 经 -seam 到 -strong。

颜色角色。 色系是 brand、attention、info、success、warning、danger 或 inactive 之一。槽位说明是哪个色阶：

不透明度。 除了两个遮罩 layer-backdrop 和 layer-backdrop-nested，所有 layer token 都是不透明的。fill-muted 和 fill-strong 是不透明的。fill-subtle、fill-medium、fill-frame-medium 和 sticker-medium 是半透明的：它们是悬停层级，叠在控件或行上面（悬停浮层）。

工具类。 Tailwind 工具类由属性前缀加 token 名构成：bg-layer-card、text-foreground-muted、border-line-strong。阴影另有命名：elevation-float 对应 shadow-float，elevation-sticker 对应 shadow-sticker，focus-ring 对应 shadow-focus。带编号的调色板色阶只有自定义属性，没有工具类；不带编号的 bg-palette-yellow 及同类是例外。

token 分组

下面每个区块都由 tokens.json 生成，显示浅色和深色两种值。

调色板

角色所指向的原始颜色。直接使用它们的规则见颜色。

文字和图标

foreground 及其各层级，以及外框和 HUD 上的文字颜色。用法和对比度：颜色、字体排印。

表面

用法：颜色。

填充

用法：颜色和悬停浮层。

线

用法和宽度：颜色、形状。

墨色阶

半透明的墨色阶梯，线、次要文字和浮层都由它构成。请用角色 token；只有一次性的淡色铺底才用墨色阶。

颜色角色

每种颜色的含义：颜色的含义。

状态

任务状态和在线状态灯：状态。

贴纸

用法：贴纸。

阴影和焦点环

用法：层级、无障碍。

尺寸

输入框和卡片标题与旁边并排部件共用的文字尺寸。用法：字体排印。

控件尺寸：默认控件的高度、它的图标和点击区域，以及嵌在外框里的控件保持的值：control-embedded-inset，即它到外框外边缘和到相邻控件的距离；control-embedded-size，即输入框里标签或按钮的高度（间距、形状）。

时间线节奏：对话里各行之间的消息档和分段档，以及每行在文字周围保留的行内距（间距）。

在 styles.css 中定义的 token

这些是 styles.css 里的 Tailwind 主题值，不是 tokens.json 中的条目，所以没有生成的表格。

弃用的名称

旧名称作为别名保留到 raft-ui 1.0，放在 tokens.json 的 deprecated 分组里。每个别名都指向应改用的 token，这样旧代码在迁移期间仍能正常工作。

重命名遵循几种模式：

primary-*                  ->  brand-*
accent-*                   ->  attention-*
color-brutal-{color}-{n}   ->  palette-{color}-{n}   (purple -> lavender)
secondary-{n}              ->  palette-stone-{n}
layer-panel                ->  layer-canvas
layer-canvas-muted         ->  layer-sidebar
layer-inset                ->  fill-muted
layer-hud-foreground       ->  foreground-on-hud
foreground-strong          ->  foreground
foreground-icon            ->  foreground-muted
foreground-placeholder     ->  foreground-hint
line                       ->  line-seam
line-muted                 ->  line-hairline
theme-shadow-float/lg/xl   ->  elevation-float       (utility: shadow-float)
theme-shadow-sticker       ->  elevation-sticker     (utility: shadow-sticker)
theme-focus-ring           ->  focus-ring            (utility: shadow-focus)
theme-shadow-xs/sm/md      ->  none: controls cast no shadow, drop the class

Codemod

raft-ui 附带一个 codemod，可以改写 Tailwind 工具类（bg-…、hover:border-…/50）和 CSS 自定义属性（var(--…)）中的旧名称：

node node_modules/@botiverse/raft-ui/codemods/token-names.mjs <dir-or-file>... [--dry]

• 它改写 .ts、.tsx、.js、.jsx、.mjs、.cjs、.css 和 .html 文件，跳过 node_modules、dist 和 build。--dry 列出它会修改的文件。
• 它只重命名引用，不动声明，所以运行两次也是安全的。
• 人工检查结果。原本禁止旧名称的防护（lint 规则、测试、允许列表）现在会禁止新名称；由片段拼出的模式，比如针对 class 名的正则表达式，仍保留旧名称。
• 文档从不使用弃用的名称：页面中出现时，scripts/check-docs.mjs 会报错。

修改 token

• 只在 tokens.json 里添加或修改值，并在同一次改动中重新生成 foundation.css。
• 新 token 的名字要遵循上面的命名规则；如果组件需要，在 styles.css 里加上它的工具类。
• 重命名 token 时，把旧名称保留在 deprecated 分组里并指向新名称，同时把这次重命名加进 codemod。只在大版本中删除别名。
• 文字、表面或淡色的值变化时，在两种模式下重新核对颜色中的对比度保证。
• 在同一个 pull request 里更新这个 token 所属的基础页面（编写指南）。

相关

• 颜色：每个颜色 token 的用途，以及它保证的对比度。
• 字体排印：文字样式和尺寸 token。
• 层级：阴影和焦点环。
• 深色模式：两种模式之间有哪些变化。