跳转至

主题 token 架构

{
  "scope": "global",
  "triggers": {
    "tokens": [
      "INV1",
      "INV3",
      "INV4",
      "INV6",
      "INV8",
      "INV9",
      "INV10",
      "INV11",
      "INV12"
    ]
  }
}

该记录定义了组件、主题、文档以及非 CSS 消费方共享的语义 token 词汇表。

目的

主题作者和组件作者应引用同一组稳定的语义名称。修改默认主题、在 JavaScript 中解析 token,或生成消费方文档,都不得创建第二套 token 词汇表。

系统模型

Core token 在 tokens.stylex.ts 中以配对导出形式声明:

  • *Defaults 对象保存默认 CSS 值。
  • *Vars 对象通过 stylex.defineVars 从这些默认值创建,是组件样式所消费的对象。
  • defineTheme 将核心默认值组合成完整的主题 token 类型。
  • tokenVar、tokenVars、resolveThemeToken 和 resolveThemeTokens 将同一词汇表暴露给 canvas、SVG、图表、测试、构建工具以及其他非 StyleX 消费方。

语法高亮和数据可视化 token 属于领域层。它们保持可单独导入,因此不使用这些领域的应用无需加载其实现模块,而 domainTokenDefaults 使它们的名称可用于主题验证和解析。

CLI 主题模板和生成的 token 文档是此词汇表的投影。它们不定义额外的 token。

主题族本地 token 是一个单独的登记映射表。它们可以复用现有 token 值的形状,但不会进入 TokenName、默认值、tokenVar、tokenVars、resolveThemeToken、resolveThemeTokens、生成的可移植文档或 Core 组件源码。一个名称不能同时出现在可移植的 tokens 和 localTokens 中,因为 CSS 和非 CSS 解析届时会产生相互矛盾的胜出者。

边界与不变量

  • INV1 — defineVars 声明是权威声明。 核心 token 名称及其默认值源自 tokens.stylex.ts;投影不引入新名称。
  • INV2 — 默认值与类型化变量同步存在。 每个核心 token 族都有一个 *Defaults 对象和对应的 *Vars 导出。
  • INV3 — Token 名称描述语义角色。 组件消费的是以用途为导向的名称,如文本、表面、间距和动效角色,而不是嵌入主题的原始调色板选择。
  • INV4 — 与模式相关的默认值仍为单个 token。 随颜色模式变化的语义角色使用受支持的 light-dark() 或元组值,而不是创建无关的浅色和深色 token 名称。
  • INV5 — 领域层是显式的。 语法和数据 token 可供主题编写和解析使用,而不会被并入核心组件 token 模块。
  • INV6 — 非 CSS 消费方解析同一依赖图。 JavaScript 辅助函数遵循 token 引用和受支持的颜色表达式,而不是维护第二套已解析值。
  • INV7 — 投影不能悄然漂移。 主题模板清单和生成的 token 文档会随权威族一起变化,否则验证失败。
  • INV8 — 主题本地的名称保持非可移植。 已登记的本地声明仍不进入权威词汇表、类型化辅助函数、生成的可移植文档以及 Core 组件依赖。
  • INV9 — 间距 token 使用 rem。 核心 --spacing-* 默认值是 rem 值(--spacing-N 为 N × 0.25rem;--spacing-4 为 1rem,在默认根字号下即 16px),因此由它们构建的间隙、内边距和外边距会像字号比例那样跟随读者的根字号。一条规则覆盖所有情形:间距步长使用 rem,除非主题将该步长记录为 px 例外。覆盖步长的主题写 rem;间距步长生成器(逐字复制第一方主题的 CLI 主题模板,以及 docsite 游乐场主题编辑器的梯度)输出 rem,并且仅在主题声明了某 px 例外时才复现该例外。作者在自定义主题中写入的值会按原样生效,绝不进行转换。非 CSS 消费方(useTheme().token()、resolveThemeToken()、tokenDefaults)返回带单位的 token 值;需要像素的代码应基于根字号解析该值,而不是解析数字。
  • INV10 — Astryx 的颜色 token 名称遵循一种语法。 该语法仅管辖 Astryx 定义的颜色 token:Core 的 colorDefaults、领域层默认值,以及 Astryx 的第一方主题从该词汇表设置的 token。它不管辖 Astryx 未定义的名称,例如产品或应用自身的 CSS 变量、主题作者的扩展或本地 token(INV8),或其他设计系统的 token。Astryx 定义的每个颜色 token 均采用以下五种形状之一:
    1. --color-<property>-<role>:用于某个绘制属性的颜色。属性为 text、icon、background 或 border。角色可以是强调(primary、secondary、disabled、emphasized)、意图(--color-text-accent)、表面(surface、body、card、popover、muted、inverted)、色相(--color-text-green),或 control,即表单控件的边缘(--color-border-control,INV13)。
    2. --color-<intent>:该意图自身的颜色。意图包括 accent、neutral、info、success、warning 和 error。
    3. 形状 1 或形状 2 的名称加上一个变体后缀:-muted(浅淡形式)、-emphasized(强化形式)、-hover 或 -pressed(交互状态),或 -inverted(用于反色表面)。
    4. --color-on-<fill>:放置在填充上的内容,其中 <fill> 是形状 2 或形状 3 的意图名称、dark 或 light。--color-on-<intent> 是放在该意图自身颜色上的内容;-muted 填充与其对应的 --color-on-<intent>-muted 配对。
    5. --color-<domain>-… 用于 INV5 下的领域层:--color-data-* 和 --color-syntax-*。

无角色(role-less)的实用工具名称 --color-border、--color-overlay(及其 -hover 和 -pressed 状态)、--color-shadow、--color-skeleton、--color-track 和 --color-tint-hover 保持原有名称。新名称不添加任何组段(如 status)、不添加其他属性词(如 foreground),也不添加属性后缀(如 -text)。Tailwind 键是此语法之外的投影:键可以在更短或实用工具专用的名称下为 token 设置别名,例如 text-status-<status> 对应 --color-text-<status>,并且它永远不会添加 CSS 变量。

  • INV11 — 语义状态角色是特定于表面的。 每种状态(info、success、warning、error)在三种表面上具有以下角色,按 INV10 命名:

    • --color-<status> 是强状态填充。其上的内容使用 --color-on-<status>,对比度至少为 4.5:1;该内容可以是浅色或深色。
    • --color-<status>-muted 是淡状态填充。其上的内容使用 --color-on-<status>-muted,在填充位于默认表面之上时对比度至少为 4.5:1。
    • --color-text-<status> 是默认页面和卡片表面上的状态文本,与这些表面的对比度至少为 4.5:1。--color-icon-<status> 和 --color-border-<status> 是这些表面上的状态图标和状态边框。每个都默认使用 --color-text-<status>;设置了自身值的 Astryx 主题会将其保持在与相同表面至少 3:1 的对比度。强填充不是状态文本:在页面上,组件使用文本角色。

    Info 与其他状态一样,是一种状态,并且独立于强调色(accent):没有任何 Info 角色默认使用强调色 token。--color-info、--color-info-muted 及其内容角色是新名称;v0.0.8 升级转换仍会将 v0.0.8 之前对 --color-info 和 --color-info-muted 的使用重写为取代它们的紫色调 token,这只会影响从 v0.0.8 之前升级的项目。

    每种状态填充和状态文本颜色都是有彩度的(chromatic):Core 的默认值、第一方主题,或在 architecture:theme-compilation INV17 下推导出的值,都不会将其中任何一种绘制为中性灰、近黑或近白。对比度下限和彩度规则约束 Core 的默认值、Astryx 的第一方主题以及明暗模式下推导出的值;第三方主题设置的值属于该主题自身。组件根据表面选择角色,而不是为所有用途使用同一种颜色。当主题未设置内容或文本角色时,主题生成会推导出该角色(architecture:theme-compilation INV17)。生成的 token 文档会用一行描述每个状态角色:它所服务的表面以及它配对的 token。

    在 forced-colors 模式下,浏览器的系统颜色会取代每个状态角色:填充上的状态文本、图标和内容以 CanvasText 渲染,填充以 Canvas 渲染。因此,状态在该模式下从不依赖颜色。每种状态都会保留其非颜色线索(标签、图标或文本),并且强或淡的状态填充会保留可见的 CanvasText 边框,以便其形状得以保留。

    Tailwind 按绘制属性(paint property)映射每种状态:文本类实用工具(text-、decoration-、placeholder-、caret-<status>)读取状态文本角色,线条类实用工具(border-、divide-、outline-、ring-<status>)读取状态边框角色,填充类实用工具(bg-、accent-、fill-、stroke-<status>、阴影颜色和渐变)则是强填充。Tailwind 还映射 bg-<status>-muted、text-on-<status>、text-on-<status>-muted 和 text-status-<status>,其中 text-status-<status> 作为状态文本角色的别名保留;与每个 Tailwind 键一样,这些键为 token 设置别名,并且不添加 CSS 变量。

  • INV12 — 默认强调色组合满足 4.5:1。 在 Core 的默认值中,--color-on-accent 位于 --color-accent 之上时,在明暗模式下均满足 4.5:1。

  • INV13 — 表单控件的边缘满足 3:1。 --color-border-control 是字段外壳以及复选框或单选框的边缘,也是唯一标示控件位置的线索。在 Core 的默认值中,它相对于默认表面和页面主体在明暗模式下均满足 3:1 对比度,并且每个 Astryx 主题模板都会设置满足该要求的值。从颜色刻度构建的主题会获得生成的 --color-border-control,并保持与其自身表面和主体至少 3:1 的对比度(spec:AST-020 FR1;WCAG 2.2 SC 1.4.11)。其他边框保持自身较浅的角色(--color-border 或 --color-border-emphasized)(DEC-2)。

本记录不涵盖以下内容:

  • defineTheme 输入形状、生成的色阶或优先级;
  • 局部 token 的名称、含义、登记、所有权、谱系和产出;
  • 挂载、嵌套、颜色模式选择或运行时主题观察;
  • 将规范化主题转换为作用域 CSS 和构建文件;
  • 组件特定的目标、视觉状态或私有派生变量。

这些关注点属于单独的主题架构记录,因此 token 的更改不会静默改变编写、运行时、编译器或组件的约定。

变更耦合

  • 添加、移除或重命名核心 *Defaults 系列时,需同时更新其 *Vars 导出、组合的 TokenName/默认值表面、CLI 模板清单、生成的 token 文档和漂移测试。
  • 添加或更改域 token 会更新该域的默认值和导出的名称类型;聚合域映射仍然是验证桥梁。
  • 重命名或移除已发布的 token 是兼容性决策,而非机械性清理。使用者可能会直接使用其 CSS 自定义属性名称。
  • 更改默认值是视觉行为变更,需要针对具有代表性的明/暗、状态和高对比度表面提供真实浏览器证据。
  • 对 JavaScript 解析的更改会保留受支持引用和颜色表达式的 CSS 级联语义;不支持的表达式保持原样,而不是被猜测。
  • 添加可移植的颜色 token 时,按 INV10 选择其名称;语法无法命名的角色会先更改 INV10。
  • 添加主题局部名称不会更新可移植默认值、名称类型、辅助程序或生成的 token 文档。编写验证会在编译器或辅助程序产生分歧之前,拒绝 tokens 和 localTokens 之间的重复项。

拥有代码

  • packages/core/src/theme/tokens.stylex.ts 拥有核心 token 名称、默认值和 StyleX 变量。
  • packages/core/src/theme/domainTokens/ 和 packages/core/src/theme/syntax/tokens.ts 拥有领域词汇表。语法词汇表包含十九个槽位:十三个 token 颜色、代码背景、三个 diff 行绘制色,以及两个 diff 标记颜色。--color-syntax-added 和 --color-syntax-removed 默认为 --color-success-muted 和 --color-error-muted,强度为 25%(通过 color-mix 与透明混合);--color-syntax-diff-header 在默认语法主题中默认为 --color-background-muted,而在未设置该值的已定义语法主题中默认为 transparent(标题行位于该主题自身的语法背景上,并使用其 punctuation 文本);--color-syntax-added-marker 和 --color-syntax-removed-marker(变更行的行号和字形)在默认语法主题中默认为 --color-text-green 和 --color-text-red;而在未设置它们的已定义语法主题中,它们采用该主题的 --color-syntax-punctuation。在未设置这些值的每个主题中,added 和 removed 行绘制色都保持其默认值。
  • packages/core/src/theme/defineTheme.ts 汇总 token 类型/默认值,用于验证和编写;它不会成为第二个 token 来源。
  • packages/core/src/theme/tokens.ts 拥有服务器安全的引用与解析。
  • packages/core/src/theme/localTokens.ts 强制执行可移植本地映射与已登记本地映射之间的边界;它不会向此词汇表添加本地名称。
  • packages/cli/assets/theme.template.ts 和生成的 token 文档是面向主题作者与使用者的受检投影。

决定规范

AST-006 的决定 1 和决定 5 确立了主题本地名称是附加的主题族契约,而非可移植的 Astryx token。现有的可移植词汇表和辅助架构保持不变。

DEC-1 — 间距随根字体大小变化

决策者: cixzhang、2026-10-12

间距 token 使用 rem。读者如果调大浏览器的根字体大小,会获得成比例增大的间隙和内边距,因此文本不会在保持像素单位的盒子内变得局促;在默认的 16px 根字体下,每一步为 4px × step。defineTheme 没有间距基准单位:它只接受逐 step 的 token 覆盖(architecture:theme-authoring-contract 负责该输入)。两个界面生成间距步进,并且都在 INV9 的同一规则下输出 rem:CLI 的主题模板(原样复制第一方主题的步进)和 docsite playground 的主题编辑器(从基准步进推导出渐变阶梯,并将其导出为 defineTheme 源码)。visual gate 的探针主题特意将 --spacing-4 固定为 px,以证明 token 值能够贯穿流通;它是测试夹具而非生成器,因此保留其固定值。主题作者保持控制权:主题可以将某个步进固定为 px 作为其文档化的例外,且作者编写的值永远不会被重写。该决定所接受的代价:固定宽度的表格列在非常大的根字体下会因更大的内边距而失去空间;将固定的 px 步进作为文档化例外的主题,在这些步进上不随根字体变化;而将间距 token 解析为像素数字的代码会读取出错误的值,且没有任何 codemod 能够发现。

已拒绝:在 type 为 rem 时保留间距为 px(文本会生长进固定盒子);转换自定义主题中作者编写的 px(这是主题自身的决定)。

DEC-2 — 表单控件拥有自己的边框角色

决策者: cixzhang、2026-11-13

“新 control-border 角色”——所有者决定,2026-11-13 (Cindy)

字段的边缘往往是判断其位置的唯一线索,因此表单控件采用自己的边框角色 --color-border-control,并保持在 3:1(INV13)。字段外壳、复选框和单选按钮框使用该角色。卡片、分隔线以及所有其他表面保留自己更浅的边缘(--color-border 或 --color-border-emphasized),因此在 Core 的默认值和主题模板中,只有控件会变暗。基于颜色标尺构建的主题会获得生成的控件边缘,该边缘相对于其表面和主体保持在 3:1。

已拒绝:将 --color-border-emphasized 提高到 3:1,因为大约二十个其他表面会随之变暗。 已拒绝:将字段指向 --color-border-gray,因为它在某些主题中无法达到 3:1,并且会让字段与徽章主题绑定。

验证

不变式 证据 失败信号
INV1, INV2, INV7 scripts/check-theme-template.test.mjs 以及 token-doc 生成检查 存在一个 token 家族,但没有对应的面向作者的清单或生成的文档
INV5 领域 token 导出和主题生成测试 领域名称从验证中消失,或需要导入未使用的领域实现
INV6 packages/core/src/theme/tokens.test.ts JavaScript 解析与默认值、模式选择、引用或受支持的颜色表达式不一致
INV8 defineTheme.test.ts、模板检查以及 token-doc 生成 本地名称进入可移植的辅助函数/文档,或可能与可移植声明冲突
INV9 tokens.test.ts (核心默认值)、SpacingRootFontSize.a11y.chromium.spec.ts (真实 Chromium 根字体大小)、每个覆盖主题对应的 *Theme.spacing.test.ts、check-cli-theme-bundle.test.mjs (打包副本与各包逐字节相等)、theme-concentricity.test.ts (以 rem 为单位读取的演示场梯度) 某个以 px 为单位的间距步进,没有任何主题将其记录为例外:既不是核心默认值,也不是主题覆盖、打包副本或生成的梯度步进
INV10 tokens.test.ts 仅对 Astryx 自身的 colorDefaults 和 domainTokenDefaults 执行名称检查 Astryx 定义的某个颜色 token 不符合五种形态中的任何一种
INV11 scripts/check-muted-status-contrast.test.mjs (解析全局及 Banner 浅色表面角色对)、scripts/check-badge-contrast.test.mjs (解析 Core Badge 默认值及主题覆盖)、scripts/check-status-text-contrast.test.mjs (解析每个强填充上的 --color-on-<status>,并将 --color-text-<status>、--color-icon-<status> 和 --color-border-<status> 与表面和卡片 token 对照检查,同时验证每个状态填充和文本颜色在每个第一方主题中都是彩色的)、neutralTheme.test.ts (固定已评审的角色值和配对)、tailwind-theme.test.ts (固定状态工具类,包括已发布的基础工具类)、Badge、StatusDot 和 Banner 测试中的 forced-colors 断言,以及主题别名生成测试 状态角色缺失、错配、呈灰色、被路由到错误的公共工具类,或在浅色或深色模式下低于其对比度阈值;状态填充在 forced-colors 模式下丢失边框;或已发布的状态填充或工具类在无记录原因的情况下改变取值
INV12 packages/core/src/theme/contrast.test.ts "默认强调色对在浅色/深色主题中达到 4.5:1" (当前取值:浅色 #0064E0、深色 #0171E3、标签 #FFFFFF) 在浅色或深色模式下,--color-accent 上的默认 --color-on-accent 低于 4.5:1
INV13 packages/core/src/theme/contrast.test.ts 针对 Core 的默认值、每个主题模板以及一个色阶主题,在浅色和深色模式下将 --color-border-control 与表面和页面主体进行对比解析 在任一模式下,针对上述任何一项,--color-border-control 与表面或页面主体的对比度低于 3:1,或者某个色阶主题未发出 --color-border-control
已发布 token 的兼容性 类型检查以及具有代表性的包/源码构建 某个已发布的 CSS 变量或类型化 token 名称在没有明确迁移决策的情况下消失
视觉默认值 在浅色、深色、状态和高对比度场景中的真实 Chromium 示例 变更后的默认值会产生不可读或语义不一致的输出

本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 as/astryx