跳转至

已批准调色板编写契约

意图

为受维护的主题提供一致、可审查的颜色参考,而无需将该参考纳入运行时主题契约。

主题可以在其拥有的源文件中保留一个已批准调色板。作者和工具可以使用它来选择和审计显式主题颜色。defineTheme() 仍然接收控制渲染输出的显式值;它不会接收、继承、验证、发布或解析调色板数据。

语义 Token 仍然是组件和应用程序的主要接口。调色板是颜色决策和对比度测试的起点,并不声称每个组件上下文都已通过无障碍性。

“已批准”意味着该调色板已由其所属主题有意审查。结构验证并不授予设计批准,也不认证对比度。

术语

  • 一个主题可以拥有一个调色板映射(palette map)。
  • 该映射包含命名的色系(family),例如 neutral、red 或 blue。
  • 一个色系至少包含一个特定模式下的色阶(ramp):浅色(light)、深色(dark),或两者。
  • 一个色阶包含一个或多个由作者定义的数值色标(stop)。色标标签是 0 到 100(含)范围内的有限 JSON 数字;整数和小数标签均有效,等价拼写(如 5 和 5.0)标识同一个色标。不同的调色板可使用不同的色标布局,以满足 UI、图标、插画、数据可视化或品牌工作的需要。
  • 显式主题颜色要么是字面 CSS 颜色,要么是对主题已提交调色板文件中某个确切值的有意引用。在两种情况下,defineTheme() 接收的都是解析后的 CSS 值,而不是调色板元数据。
  • 对齐检查会将一个有意以调色板为支撑的主题颜色,与它被选择自的那个已批准调色板色标进行比较。

编写流程

flowchart TD
  Generator["Optional palette generator<br/>(separate follow-up)"]
  Manual["Hand-authored or imported palette"]
  Choice{{"Choose one starting path"}}
  Candidate["Candidate palette"]
  Review["Human review and approval"]
  Palette["Theme-owned palette file<br/>for example neutralPalettes.ts"]

  Generator --> Choice
  Manual --> Choice
  Choice --> Candidate
  Candidate --> Review
  Review --> Palette

  Palette --> Validate["Palette checker<br/>checks structure only"]
  Validate --> Validation["Structured errors and warnings"]
  Validation --> PaletteCI["Palette validation test"]

  Palette -. "Optional authoring help:<br/>suggest candidate colors" .-> Suggestions["Mapping suggestions"]
  Roles["Semantic roles and existing values"] --> Suggestions
  Suggestions --> ColorReview["Author reviews intent,<br/>appearance, and contrast"]
  ColorReview --> Hex["Approved CSS color<br/>literal or committed palette reference"]

  Hex --> Define["defineTheme({tokens, components})"]
  Define --> Runtime["Runtime theme and CSS"]

  Palette --> Alignment["Alignment test for mappings<br/>that intentionally use the palette"]
  Hex --> Alignment
  Alignment --> ThemeCI["Theme mapping test"]

调色板文件在后续编写和审计中仍然可用。它不会在生成建议后消失。映射建议是可选的,绝不可自动改写主题。作者审查每一个所选颜色,并要么直接存储其 CSS 值,要么从已提交的调色板文件中引用该确切值。因此,更改被引用的值属于有意且可审查的主题更改。

非目标

  • 将调色板添加到 DefineThemeInput 或 DefinedTheme。
  • 更改颜色展开、继承、运行时 CSS 或静态主题构建。
  • 要求每个主题都维护一个调色板。
  • 要求每个主题颜色都匹配调色板色标。
  • 将色标视为语义角色或无障碍性保证。
  • 在此更改中将调色板文件作为运行时包产物发布。
  • 在此更改中生成调色板或映射建议。
  • 为未来的调色板生成器选择算法或生产 API。

要求

  • FR1 — 调色板采用是可选的。 受维护的主题可以保留一个主题拥有的调色板文件。没有调色板文件的主题保持其现有的编写、运行时、构建、继承和包行为。采用调色板 MUST NOT 使其成为 defineTheme() 的必填字段。
  • FR2 — 调色板仅是编写时数据。 调色板数据 MUST 位于 DefineThemeInput、DefinedTheme、运行时提供程序、生成的 CSS 以及通用 astryx theme build 输出之外。它可以与其主题放在一起,或从另一个编写来源导入。本契约不要求统一的仓库布局,但每个受维护的调色板 MUST 有明确的所有者。主题拥有的调色板 MUST 保持对该主题私有,除非某个单独的公共 API 明确承担了对其色系和色标键的兼容性义务。
  • FR3 — 声明的色阶使用明确、由作者定义的形状。 调色板映射 MUST 至少包含一个命名的色系。每个色系 MUST 声明一个非空的浅色色阶、一个非空的深色色阶,或两者。不得推断缺失的模式。Gothic 等主题可以只声明深色色阶,而 Stone 等主题可以只维护一个色系。共享色阶 MUST 明确分配给两种模式。每个色阶定义自己的严格递增色标标签和不透明的六位十六进制值。标签 MUST 是 0 到 100 之间的有限 JSON 数字,在数值归一化后唯一且严格递增。端点 0 和 100 是可选的,单色标色阶也有效。本契约 MUST NOT 要求 11、21 或任何其他固定色标数量。生成器可以推荐默认布局,但不能使该布局成为有效性规则。可选的色相(hue)、色度(chroma)、用途(purpose)和描述(description)字段仅为元数据。
  • FR4 — 验证是显式且非修改性的。 调色板检查器 MUST 检查声明数据,而不定义、归一化、生成或返回替换调色板。它 MUST 以稳定的路径和消息报告所有结构性问题。结构错误包括空调色板、空色阶、重复或无效的色标标签(包括非有限值、超出 0..100 的值、5 和 5.0 等非唯一数值,或不严格递增的标签)、格式错误的颜色,以及无效的模式形状。检查器 MUST 验证作者声明的色标布局,而不是要求一个通用色标清单。它 MUST NOT 从 defineTheme()、运行时提供程序或通用主题构建中运行。公共检查器或 CLI 需要其自己已接受的 API 契约。
  • FR5 — 主题选择保持显式。 作者和工具可以使用调色板来建议或选择颜色。主题映射可以以字面形式存储已接受的 CSS 颜色,或有意引用其已提交调色板文件中的确切值。引用 MUST 在运行时输出之前解析为受支持的 CSS 值,并且 MUST NOT 让 defineTheme() 感知调色板色系或色标。重命名或移除被引用的色标 MUST 导致类型检查、验证或主题构建失败。更改被引用的值是有意的主题更改,且 MUST 结合其渲染影响进行审查。
  • FR6 — 验证与对齐是独立的检查。 采用调色板的主题 MUST 测试其调色板没有结构错误。它应当单独测试那些有意从调色板色标中选择的主题映射。对齐测试 MUST NOT 暗示每个直接主题颜色都是违规。Alpha 叠加、品牌色、合成色和特定于对比度的调整可以保持为显式的有意偏差。
  • FR7 — 无障碍性仍是情境化的。 结构有效的调色板或对齐的映射并不能证明前景/背景对、交互状态或组件通过 WCAG。所属主题 MUST 在其打算支持的实际组件情境中测试对比度。
  • FR8 — 生成是独立的能力。 未来的生成器或 CLI 可以创建候选调色板文件或映射建议。该工作 MUST 拥有自己已接受的契约和审查。生成输出在主题作者审查并采用之前始终保持候选状态;仅仅添加调色板 MUST NOT 触发自动最近颜色替换。

处理现有及有意的差异

本契约仅在一个主题选择采用该调色板形态时适用。它不会追溯性地拒绝无关主题或其现有的颜色系统。

验证器将声明的契约与主题实际使用区分开来:

  • 无效的调色板容器、格式错误的颜色、重复或无效的色阶标签、空的色阶,或某个色族两种模式都没有,均属结构性错误。
  • 仅浅色、仅深色、双模式、单色族和多色族调色板都是受支持的形态,而非例外。
  • 调色板之外的颜色不会构成验证器错误,因为验证器不检查主题令牌或组件。
  • 当调色板包含中性色族时,作者应当将其用于近黑、近白及其他无彩色 UI 角色。纯黑和纯白仍然是一般的显式主题值,而不是必需的色族端点。这是编写指南,而非结构性验证规则。
  • 有意的映射差异在所属主题的对齐测试中处理:更新主题、保留并记录显式偏离,或回退调色板更改。

未来的仓库工具在维护中的调色板经过真实模式审计后,可能会添加警告。在没有先将该模式加入契约或记录一个狭窄例外之前,它不得将有意的现有模式转化为硬性失败。

当前状态影响

当前的 main 存储显式主题颜色,并且在规范化主题契约中没有 palette 字段。本提案保留该行为。

在单独的后续工作中,Neutral 是预期的首个采用者。其调色板可以放在一个主题私有的 TypeScript 文件中,而 neutralTheme.ts 显式引用经审查的、解析为 CSS 颜色的值。该采用需要其自身的视觉审查、测试、主题记录和发布处理,而不是从本契约获得隐式批准。

现有的沙盒生成器仍然是有用的设计证据。生产生成器被有意推迟到一个单独的提案,该提案以沙盒及 PR #5800 中的讨论为依据。

验证

该仅涉及规范的更改会运行仓库知识检查,并且不改变任何包、运行时、构建、主题或公共 API 行为。后续实现必须证明调色板编写仍处于运行时主题契约之外,并且只测试它们显式支持的调色板形态。

决策日志

DEC-1 — 调色板在不强制的前提下引导一致性

参考: spec:AST-018/DEC-1

决策者: rubyycheung, 2026-09-02

主题可以使用调色板来建立一致的颜色表达,但采用和使用仍属可选。语义令牌优先,而有意的直接颜色仍然有效。

已拒绝:要求每个主题或每种颜色都使用调色板。那会把编写指南变成运行时策略,并错误表述合法的叠加层、品牌颜色及对比度特定值。

DEC-2 — 调色板数据保留在运行时主题契约之外

参考: spec:AST-018/DEC-2

决策者: rubyycheung, 2026-09-03

调色板文件是主题自有的编写参考。defineTheme() 不接受、验证、保留、继承或发布它们。这遵循 architecture:theme-authoring-contract:仅用于验证的数据不会进入规范化后的运行时主题。

已拒绝:在 DefineThemeInput 或 DefinedTheme 上添加 palettes 字段。这会增加运行时兼容性成本,却不会构造运行时值。

DEC-3 — 验证只做报告;不定义或规定色阶数量

参考: spec:AST-018/DEC-3

决策者: rubyycheung, 2026-09-03

调色板验证报告结构性错误,但不会像构造了一个新值那样返回未改变的调色板。它验证作者声明的色阶布局,而不是规定 11 或 21 个色阶。主题包测试或被接受的未来 CLI 决定验证结果如何影响 CI。

已拒绝:在 Core 中导出 defineTonalPalettes() 或 validateTonalPalettes()。根据 spec:AST-002/FR17 和 DEC-7,define* 辅助函数必须构造或规范化一个持久受支持的值,而仅用于验证的编写数据不属于 Core 运行时契约。

DEC-4 — 主题映射显式选择经审查的 CSS 值

参考: spec:AST-018/DEC-4

决策者: rubyycheung, 2026-09-03

基于调色板的映射是编写决策。一旦获批,主题可以直接存储选定的 CSS 值,也可以有意地引用其私有的、已提交的调色板文件中的确切值。后者使调色板成为唯一事实来源:更改它将产生可见的、影响主题的源码变更;缺失的引用会失败,而不是回退。两种形式都不会向 defineTheme() 或运行时输出添加调色板语义。

已拒绝:在常规主题构建期间重新运行生成,以及自动进行最近颜色替换。两者都可能在没有对已提交的调色板或主题源码进行经审查编辑的情况下改变渲染出的颜色。

DEC-5 — Neutral 的重新映射是对比测试基线

参考: spec:AST-018/DEC-5

决策者: rubyycheung, 2026-09-02

Neutral 已批准的调色板和显式重新映射为未来的颜色决策和组件对比度测试提供了锚点。批准并不声称每个现有组件、模式或交互状态都已通过无障碍检查。

已拒绝:将完整的组件级一致性作为调色板的前提。调色板是用于发现并修复这些上下文问题的基线。

DEC-6 — 支持的模式是显式的

参考: spec:AST-018/DEC-6

决策者: rubyycheung, 2026-09-03

一个色族声明浅色、深色或两者兼有的色阶。缺失的模式不会被推断。这支持诸如 Gothic 之类的仅深色主题,以及诸如 Stone 之类的单色族主题,而不会假装它们具有不同的模式或清单。

DEC-7 — 调色板生成是后续工作

参考: spec:AST-018/DEC-7

决策者: rubyycheung,2026-09-03

本提案对已采纳的调色板文件进行验证。生产级生成器以及用于创建或映射建议的任何 CLI 命令都需要单独的提案。现有的沙箱原型和 PR #5800 是未来设计的输入,而非本契约中的运行时依赖或已接受的 API。

DEC-8 — 色标布局属于调色板作者

参考: spec:AST-018/DEC-8

决策者: rubyycheung,2026-09-03

该契约接受任何非空的、由作者定义的色标布局,只要其有限的数值标签唯一、严格递增,并且位于 0..100 范围内。未来的 Astryx 生成器可能默认使用 21 个色标以提供更精细的创作选择,但用于图标、插画、可视化或品牌工作的 11 色标、单色标或专用调色板同样有效。输入要求更窄的工具必须在本地声明并验证这些要求,而不是重新定义调色板的有效性。

已拒绝:要求每个调色板都包含两个端点或固定增量(如五)。那会将一个生成器默认值变成对无关创作需求的不必要限制。

开放问题

无。

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