示例项目四：设计 token 组件库

这是一份示例内容，用于演示项目详情页的结构，不代表真实项目、真实成果或真实指标。所有数字字段均留空。

背景与目标#

颜色、圆角与间距散落在组件里时，改一次主题就要全量搜索。示例项目的目标是：设计 token 成为唯一来源，组件只能引用语义变量，不能写裸值。

• token 定义在一处，构建期生成对应的工具类
• 组件里出现十六进制色值时，校验脚本直接报错
• 新增 token 需要同时补充语义说明，避免出现 color-17 这类命名

方案与实现#

token 分两层：基础值与语义层。基础值是调色板，语义层回答「用在哪里」，组件只消费语义层。

从 token 到工具类#

@theme {
  --color-surface: #0d1424;
  --color-border: rgb(255 255 255 / 0.08);
  --radius-card: 16px;
}

对比度校验#

深色主题下最容易出问题的是强调色配白字。示例项目把对比度检查放进构建流程，低于 AA 阈值的组合直接失败，而不是等到评审时才发现。

难点与取舍#

1. 语义层不能太细：每个组件一套变量会退化成换名字的硬编码，示例里按用途分组，不按组件分组。
2. 向后兼容：删除 token 比新增 token 危险，因此先标记废弃，跨一个版本后再移除。
3. 文档成本：token 没有说明就等于没有语义，说明写在定义旁边，不另建文档站。

原则：约束写在构建里，写在文档里的约束通常只有写它的人记得。

结果与复盘#

示例项目不提供任何测量结果，指标字段保持为空。复盘部分是方法上的总结：先把「不允许多写什么」定清楚，再讨论组件能做什么。