Token 契约、主题与状态

状态：七角色＋固定职责 step 的公共颜色消费契约已由用户确认，默认 primary=ink、neutral=gray 也由用户确认。D01-R1 浅深主题物理值由代理依用户授权采用；D01-R2（2026-10-22）依用户决定只把默认 primary-200/300 修订为带轻微彩度的选择面，其余值不变（见 1.1 节）。非颜色资源结构、生成格式和平台 API 仍待实现确定；静态配对计算不代替实际绘制与实现验收，本页验收项均未执行。 更新：2026-10-22（D01-R2 修订） 所属章节：视觉与语义基础

决定依据见决策与讨论记录。

1. 已确认：角色＋色阶两维 Token

2026-10-19 用户确认：颜色 Token 严格采用 Billgo 两维体系，即语义角色＋固定职责色阶。七角色为 primary、neutral、focused、success、warning、failure、general。产品组件消费统一 role-step 标识，不再建立 Primitive / Semantic / Component 三层公共颜色别名；物理色板只用于中心配置。图表类别颜色由数据字典定义，不冒充 UI 状态色。跨平台 Token 标识和语义统一，调用语法可按平台映射。文末历史附录的三层模型是已被替代的历史候选，不再作为当前规范。具体允许色阶遵循 Billgo better-colors/palette-structure.md。此决定不表示色值和实现已验收。

Token 是可追溯设计决定的表达方式，不承担权限、业务状态机、格式化规则或布局算法。颜色由角色和固定职责色阶直接表达用途；组件不得再叠加 background／foreground／hover 或组件颜色别名。非颜色资源不由此自动批准三层架构。

本节集中说明现行颜色契约；以下允许表是对已确认 Billgo palette-structure.md 规则的展开，配对测法见色彩语义与可辨状态。允许表不等于实际色值已经通过对比测试。

FND-C01：七角色允许表与固定职责

本表依据 2026-10-19 读取的 Billgo Standard Design 与 better-colors/palette-structure.md，只展开已确认的角色和色阶；物理值另由本页 1.1 节的 D01 采用表规定。跨平台统一消费 role-step；括号中的前景、表面、悬浮是职责说明，不构成第二层别名。

普通行悬浮用 neutral-300，已选择行悬浮才用 primary-300。自 D01-R2 起默认主题的 primary-200/300 与 neutral-200/300 不再同值，这两条规则在默认主题下可以观测；选择仍须持久标记，不以颜色为唯一线索。强状态按钮只在同状态上下文中成为该独立任务的主操作；与普通 primary 主操作互斥。独立任务的边界沿用 YUDS 决策，不照搬外部“每个视图”解释；D04 已选择不启用批准／拒绝双强调例外。

此表没有指定品牌面或强状态按钮的额外按下色阶。平台适配可保留当前允许表面，叠加不改变色彩语义的原生即时反馈；不得临时造出 primary-400、failure-800 或公共 pressed 别名。若原生反馈改变合成色，须把实际按下结果纳入配对测量。

拒绝条件

不在允许表内的组合、focused 无焦点触发、普通结构染品牌色、状态仅靠颜色表达、给组件增加一套颜色 Token 别名，均应退回角色选择步骤。角色正确但测量不合格时修正中心物理映射，不反转深浅主题色阶编号。

文档夹具 C01

输入为“选中的合同 C-008 同时存在日期错误，键盘进入该行”。预期是选择标记＋primary-200 表面、独立 focused-900 轮廓，以及错误文字／图标；错误不把整个选择底色改成 failure。失败注入为普通未选行 hover 使用 primary-300，按本表拒绝。两者是规范预期，运行未执行。

1.1 D01-R2 浅深主题物理值（TeaCSS 对齐；D01-R2 修订默认选择面）

用户确认默认 primary 选择 ink、neutral 选择 gray；用户未自定义 primary 时始终回退 ink。代理依据授权采用下表作为 YUDS 高可读设计修订，不修改 TeaCSS 上游。七角色与允许色阶保持；ink、gray 等是中心物理色板身份，不成为公共第三维或额外角色。每主题 32 值，共 64 个不透明 8 位 sRGB HEX，下表是本版本唯一现行的物理值。D01-R2 只替换 primary-200/300 四个槽位：取 @teasim/colors（teakit/colors@7474f74e）violet 色板浅色第 4/5 阶、深色第 3/4 阶，使默认主题下的选择面与中性控件面可辨；其余 60 值与 D01-R1 相同。primary 的 000/800/850/900/950 仍为无彩度 ink。

来源锁定 TeaCSS teacss/teacss-ts@7532869ebfd1efdb64fbeac28cdbbdd275371902（workspace 0.8.5，非 npm 制品核验）：默认 primary=ink、neutral=gray、focused 跟随 neutral、success=jade、warning=amber、failure=red、general=blue。原色板为 OKLCH；本版本输出固定 sRGB，保留无彩度 ink/gray 身份、品牌 hover 方向和原状态色系。必要边界／辅助文字及浅色状态 900 作高可读调整，共 14/64 角色主题槽位（含焦点派生变化）；这是 YUDS 的代理设计选择，不冒称 TeaCSS 原值或用户逐值批准。原 D01 蓝黑表仅保留于历史证据。

1.2 默认与自定义 primary 的契约

• 默认配置是 primary=ink、neutral=gray；focused 默认跟随最终 neutral-900，不因自定义 primary 自动改色。状态角色默认保持 jade/amber/red/blue 的 YUDS 映射。没有覆盖、覆盖删除或覆盖校验失败时，使用完整默认 ink 映射，而非上一份未知值或蓝黑替代。默认 ink 下 primary-200/300 带轻微彩度（violet 淡调）是 D01-R2 默认值的一部分，不构成自定义 primary，也不新增角色。
• 用户可以自定义 primary 的中心色板。YUDS 必须同时记录浅／深两主题的全部允许 primary 步 000 200 300 800 850 900 950，保留每步职责和 000 反色文字规则；不允许逐组件硬编码、遗漏主题／步骤、混用不同版本或新增公共别名。若通过 TeaCSS 实体色板注册，还须满足其完整 12 阶／000 回退机制；YUDS 允许消费子集不冒充 TeaCSS 完整色板。
• 自定义不能只替换 800 一个品牌色。启用前重跑所有受影响配对：品牌普通／hover、选择／选择 hover 文字、链接、标记、状态字／边界／焦点对选中底，以及实际 pressed 合成。任何一项不达本页配对门槛，拒绝整份覆盖并说明失败，不静默修改用户色或降低阈值。接受的配置保存范围依赖真实产品能力，规范不承诺同步／持久化。
• 相同 role-step 跨平台保留名称与职责。主题改变物理值不反转职责编号；原生不强制使用 CSS 语法。更换 primary 不改变 neutral、状态或数据字典，不把 lime 当未配置时的默认值。
• 焦点由站点一次绑定；当前采用 neutral，若明确改绑 primary 或物理色板需作为独立配置记录并重测。TeaCSS 当前不再支持 @focused 列表或 data-css-focused 用户候选选择，不复制旧接口。

配对／焦点构造见色彩语义与可辨状态；静态通过不是视觉、浏览器或原生验收。

来源：D01-R1 的来源、原 D01／TeaCSS／修订逐值对照与算法见 v1 修订说明 ↗；D01-R2 的选择面修订、可辨性记录、现行 198 项配对账本与可重算脚本见 v2 修订说明 ↗、v2 账本 ↗及 v2 脚本 ↗。

2. 新增 Token 前的判断

新增前依次回答：

1. 这是可复用的设计决定，还是某次内容排版的偶然值？
2. 已有语义是否准确？仅因颜色看起来相似不能复用错误用途。
3. 颜色用途先映射已确认的七角色和固定职责色阶，不因组件或页面新增独立角色或颜色别名；不能表达的用途登记冲突与建议，未经决定不扩展公共契约。非颜色资源另行评估。
4. 差异属于公共组件还是单个产品？产品特例先留在产品范围，验证重复性后再提升。
5. 是否能给出真实使用例、禁止使用例、维护人和验证方法？没有这些信息时不进入公共主档。

暂时的实验值要带状态、作用域与复核条件。禁止用“特殊蓝2”“新表格灰”“更浅一点”等描述创建永久语义。

3. 每个 Token 的最小记录

• 稳定标识、数据类型、单位或复合结构。
• 中文用途、使用和禁用场景、对应原则。
• 值或引用来源；颜色记录统一 role-step 与中心物理色板映射，不导出第二套公共颜色别名。非颜色引用若存在，须在不同导出中保持同义。
• 适用主题、状态和平台，缺省值及回退规则。
• 对比配对或其他约束，例如此文本色仅可用于哪些表面。
• 所属负责人、版本、决策状态：已确认／拟议／待验证／被替代；资源生命周期（如实验、弃用）及实现测试结果另列，不用它们替代决策确认状态。
• 设计资源与实现映射、验证样例和已知限制。

引用图不得有循环或失效目标。颜色只能引用可解析为颜色的值，时长和长度不能因都写成数字而混用。复合排版值应明确字体、字号、行高、字重各部分的单位及继承关系，不能把无法跨平台解释的字符串当作统一标准。

4. 将主题维度分开

语言与文字方向是内容和布局条件，不建议伪装成一套颜色主题。响应式布局也不能由密度 Token 代替。这些维度需要组合测试，但无需预先生成所有可能组合。

每个发布配置明确：支持哪些组合、哪些组合未验证、哪些不支持及原因。主题回退必须确定并可检查。不能因缺少深色错误前景而静默采用浅色错误值；系统高对比模式下也不能依赖被移除的阴影作为唯一边界。

5. 状态映射与组合

组件首先定义状态契约，再映射视觉：

• 悬浮与按下仅适用于可操作控件；只读值不能因悬浮伪装成可编辑。
• 键盘焦点是独立可见层，不能被选中、错误或危险样式覆盖。
• “已选中”表达持久选择，“按下”表达瞬时交互，不能复用为同一种状态。
• “只读”仍应支持适当的阅读、选择与复制；它不等于禁用。
• 处理中是否允许取消、继续输入或其他操作由行为契约决定，不由灰色外观决定。
• 数据过期、部分结果及权限受限等状态除视觉角色外必须有可理解文本。

组合例：有错误且聚焦的金额字段

错误文本和关联关系保留，字段错误标识仍可见，焦点再以独立边界表达。若两种边界无法共存，应调整表达结构，而不是让某一种状态消失。

组合例：已选择且旧数据的表格行

选择标识和“数据截至…”提示分别保留；后台刷新不改变已选对象身份。是否允许操作由产品决定并说明，不能将整行变灰后留给用户猜测。

6. 修改与发布

修改分三类：值调整、用途变化、标识与结构变化。改一个原始色值可能影响多个语义角色，因此即使接口未变，也要列出影响配对和组件。用途变化或标识删除需要迁移说明，不得仅称为视觉微调。

推荐流程：提案说明用途与证据 → 检查已有角色 → 在真实组件中试用 → 评审主题与状态组合 → 批准并版本化 → 同步资源与实现 → 验证消费者 → 按明确条件弃用旧项。旧名称到新名称的映射保留在迁移说明与历史记录中；公共颜色不新增运行时兼容别名层。非颜色资源若需兼容期，由维护规则单独确定，不得让过期别名永久掩盖迁移失败。

设计文件和实现生成物都需能追到同一规范版本。平台单位转换应由适配层说明；相同语义不意味着 Web、原生界面或文档输出使用相同数值或 API。

7. 正反例

合适

两种客户主题消费同一 primary 角色的固定职责色阶配对；中心配置改变物理值后分别验证可读性，错误映射 failure，焦点映射 focused。前景、背景是使用位置的说明，不另建公共颜色别名。切换品牌不改变“提交审核”的行为。

不合适

将主操作引用为“蓝600”，再让错误、链接和图表系列也直接引用这个值。客户改成橙色后，页面各处的用途一起改变且无人知道影响。

合适

表格行高由文字、操作区和密度约束共同计算，以最小尺寸而非固定裁切高度处理长内容。

不合适

将“compact = 28”应用到所有控件，并把两行错误文字裁掉以通过截图比较。

8. 验收清单

• 引用可解析、无循环、类型与单位一致，缺失主题映射能被检查发现。
• 每个语义有用途与禁用场景；产品页无未经说明的原始值绕过。
• 正文、控件、焦点、状态与图表均在实际表面上验证，而非只验证原始色板。
• 至少覆盖错误+焦点、选中+焦点、选中+旧数据等真实组合。
• 切换主题和密度不丢输入、焦点、选择对象或必要文本。
• 变更能追踪到受影响组件、资源、版本与迁移步骤。

以上验收项均未执行。本页未选定 Token 工具、交换格式、代码生成链或平台实现。

相关：色彩语义与可辨状态、排版层级与文字可读性、布局、响应式与信息密度。

历史补记：2026-10-19 两维契约确认原文

以下保留 2026-10-19 当日追加的确认原文。现行规则集中在第 1 节，被替代的三层方案见下方历史附录；原文不扩大已确认范围。

YUDS 统一采用 Billgo Standard Design 的 role + step 两维公共颜色消费模型。角色固定为 primary、neutral、focused、success、warning、failure、general。角色和色阶的职责跨平台一致，具体色阶使用限制以 Billgo palette-structure 为对齐依据。物理色板属于配置或生成输入，不形成额外公共 Token 消费层；不得叠加重复的 background、foreground、hover 或组件颜色别名。图表类别颜色由独立的数据语义字典表达。

各平台使用同一 Token ID 与语义，平台代码语法可以不同。此决定针对颜色 Token；其他资源类型、数值、序列化格式和生成工具仍待验证。规范已确认不代表代码实现或对比度测试已通过。

历史附录：v0.2 三层候选（被替代）

以下原文仅供追溯，不是现行颜色消费规范；其中的推荐、例子和消费边界均无现行效力。颜色部分由第 1 节已确认的角色＋色阶两维契约替代；非颜色部分仍属未批准历史候选。

原文快照

Token 是可追溯设计决定的表达方式。它应使团队能更换视觉值而保持用途清楚，避免组件依赖某个恰好合适的色号。Token 不承担权限、业务状态机、格式化规则或布局算法；“error”颜色不能执行校验，“compact”间距不能决定哪些列可以删除。

推荐采用原始、语义、组件三层。层级表达依赖责任，并不要求每个数值机械经过三层，也不规定某一种文件格式或生成工具。

层	回答的问题	候选例子	消费边界
原始 primitive	可用的基础值是什么	中性色阶、尺寸阶梯、时长阶梯、字重值	由基础资源维护；产品页面通常不直接引用
语义 semantic	在什么用途和条件下使用	正文前景、危险操作背景、焦点边界、分组间距	组件及通用页面样式的主要入口
组件 component	某组件是否存在独立且稳定的差异	表格选中行背景、对话框内容间距	只有通用语义无法清楚表达时才引入

示意引用为“按钮主操作背景 → 操作强调背景 → 某主题的原始色值”。箭头表示依赖，实际命名及序列化语法待定。若两个组件只是碰巧使用相同数字，不必合并为同一语义；若两个名称表达同一用途，也不应因页面不同不断复制。