Design token（设计令牌）

什么是 Design token？

做界面时，我们经常会遇到很多重复出现的设计决定：比如主色调选哪个蓝、按钮圆角是多大、卡片之间空开几像素、弹窗弹出来要花几毫秒。

如果把这些具体数字硬编码写死在每个组件的 CSS 里，以后只要想改个圆角或换个主题色，就得翻遍整个项目的代码挨个修改，不仅费时而且特别容易改漏。

Design token（设计令牌）就是把这些通用的设计决定统一抽出来，给它们起一个固定、清晰的名字。组件本身不写死具体数字，只引用对应的 token。以后换主题，本质上就是把这批 token 背后的具体数值整套替换掉。

在 astryx-vue 中是如何实现的？

astryx-vue 的 token 严格对齐原版 Astryx（原版在 tokens.stylex.ts 和 dataTokens.stylex.ts 中维护），名字和取值都一样。但在前端输出层面，我们并没有把它们做成 StyleX 对象，而是全部编译成了现代标准的 CSS 自定义属性（CSS 变量）。

这样设计的好处很明显：不用引入任何专门的 CSS-in-JS 编译器，只要写原生 CSS，在哪都能直接读到和修改。

1. 统一的前缀规范： 每一条语义化 token 都有统一的 --astryx- 前缀，避免和你项目已有的其他全局变量起冲突。这是我们和原版唯一有意不同的地方：原版的 --spacing-4，在这里叫 --astryx-spacing-4。前缀会一直保留，因为已经有用户的自定义主题在用这些名字。defineTheme() 两种写法都认。
2. 原生双模配色： 颜色相关的 token 采用标准 CSS 的 light-dark() 函数书写，一条变量就同时包含了浅色和深色两套色值，不需要分开发布两份样式表，切换模式时也不需要刷掉整套样式。
3. 层级覆盖规则：
   • 如果 Neutral 主题覆盖了某个变量，优先使用 Neutral 的值。
   • 如果 Neutral 没覆盖，则回退使用原版的默认规范值。
   • 如果在自定义样式中想要微调，只需通过 CSS 层级（@layer astryx.overrides）重新给变量赋值即可。

数值以 packages/themes/neutral/base.css 的声明为准，图表配色以 packages/themes/data.css 为准。文档中的色板与尺寸参考也是直接由这两个文件解析生成的。

Token 分类总览

你可以按照功能分类查看具体的变量名称与视觉效果：

类别文档	变量前缀与说明
颜色	--astryx-color-*：包含文字、表面背景、状态提示色，以及图表用的 --astryx-color-data-*
排版与字体	--astryx-font-*、--astryx-text-*：包含字体族、字号尺寸、字重和行高梯级
动画刻度	--astryx-duration-*、--astryx-ease-*：包含持续时间、缓动曲线与共享关键帧
间距、圆角与阴影	--astryx-spacing-*、--astryx-size-*、--astryx-radius-*、--astryx-shadow-* 等通用尺寸标尺

在组件外部使用

如果你在编写自己的业务组件或页面时，也希望外观完全符合这套设计规范，直接在你的 CSS 里引用这些变量即可：

.my-custom-card {
  /* 背景直接引用主题卡片背景色 */
  background: var(--astryx-color-background-card);
  /* 文字直接引用主题主要文字色 */
  color: var(--astryx-color-text-primary);
  /* 边框圆角直接引用元素通用圆角 */
  border-radius: var(--astryx-radius-element);
  /* 内边距直接引用第 4 档标尺（1rem，默认 16px，跟随根字号） */
  padding: var(--astryx-spacing-4);
}

更多关于 CSS 分层和覆盖层级的规则，请阅读 CSS 变量。