创作期色调调色板生成系统规范¶
意图¶
主题作者需要一种可重复的方式,来制作完整的色调调色板候选方案。 生成属于创作性工作:它产生颜色,供人们检查、调整 并接受。被接受的结果保存为私有的、主题所有的调色板数据。 普通主题构建不会重新运行生成器。
调色板生成实验室(Palette Generator Lab)会比较候选配方、完整族系、模式、 锚点以及现有主题,然后让作者复制候选 JSON。 有版本号的 OKLCH 配方是受支持的生成的可视化基础。后续的当前权威 ——仅在被修订并接受情况下的 AST-018——拥有已接受调色板数据的形态与生命周期, 以及任何一等调色板/主题集成。
Astryx CLI 主题创作工作流暴露了纯粹的
generateTonalPalette() 创作 API 和
astryx theme palette generate 命令。两者使用同一个有版本号的引擎。
二者都不会隐式地重写主题。
新创作界面推荐调色板工作流,并且不会将旧版颜色标尺辅助工具
呈现为“选择一种强调色就像一次孤立编辑或一个已批准的调色板”。
Playground 移除了其 Create from accent 入口,同时保留显式的令牌编辑。
DefineThemeInput.color、ThemeAdaptationValue.color 和
expandColorScale() 是旧版创作界面。它们保持 stable,直到
一个“以替换为先”的补丁交付下文所述的完整现代化路线;
该补丁会将它们移至 deprecated。在整个弃用窗口期内,
它们现有的运行时行为保持受支持且在字节级别等价。弃用是
静态的、源码层面的:声明、创作验证和文档
标明替代方案,不附带任何兼容性标志、运行时分支、
渲染应用警告或新增可执行的 production 包字节。
静态 TypeScript 声明元数据不属于可执行的运行时行为。
非目标¶
- 为未来的“一等调色板”选择公共 API、已接受的数据形态、语义角色引用模型、 编译器集成或运行时投影。后续的当前权威——仅在被修订并接受情况下的 AST-018——拥有这些选择。
- 在单独识别的清理项被批准进入次要版本之前,
移除
DefineThemeInput.color、ThemeAdaptationValue.color或expandColorScale()。 - 仅出于弃用目的,添加运行时兼容性设置、运行时警告、可执行的 production 分支或可执行的 production 包字节。
- 要求手写或导入的数据必须带有生成的调色板或来源信息。
- 将调色板色标视为设计批准或可访问性保证。
所有权¶
| 所有者 | 契约 |
|---|---|
| AST-008 | 候选生成、新创作推荐,以及三个旧版颜色标尺弃用生命周期。 |
| Ruby | 在所需比较证据之后的可视化配方及推荐。 |
| 后续当前调色板权威 | 已接受的调色板形态、稳定语义角色引用、验证,以及任何一等创作或编译集成。 |
theme:<name> |
已接受的精确调色板值、映射与偏差、所需状态、兼容性以及渲染证据。 |
| 当前主题架构 | 生产环境下的 defineTheme 规范化与编译,包括弃用窗口期内的字节等价旧版行为。 |
| CLI 创作面 | 生成命令、纯 API、候选序列化、回执、安全写入、迁移工具以及创作诊断。 |
创作生命周期¶
| 阶段 | 所需结果 |
|---|---|
| 创建 | 生成、手写或导入一个完整的候选调色板。 |
| 审查 | 检查完整的族系、模式、诊断、比较以及渲染上下文;可自由调整或拒绝。 |
| 接受 | 在已接受的调色板契约下,保存最终的精确调色板数据。 |
| 映射 | 在拥有已接受调色板/主题集成的权威之下,记录一个可检查、稳定的语义角色映射。 |
| 验证 | 在所属主题记录中,记录针对精确调色板、角色映射和渲染值的上下文证据。 |
| 重新生成 | 从已接受的调色板连贯地更新已映射的角色,无需隐式运行生成器,也无需手动重新复制无关角色。 |
需求¶
- FR1 — 生成是可选的。 生成、手写和导入的 调色板在验证后是平等的。缺少生成来源信息仅表示 “并非由此配方生成”;它 MUST NOT 使有效的调色板数据变得无效。
- FR2 — 请求描述完整的作者意图。 一个生成请求 MUST
描述完整的族系集合;规范化种子;有版本号的强度与
中性配置文件;精确、有界且灵活的锚点;显式的色标
布局;亮色与暗色策略;目标色域与编码;以及每个其他
影响输出的参数。Astryx 工具 SHOULD 默认将族系渐变设为
21 个色标的
0, 5, …, 100布局,同时接受任何非空 作者定义的数值色标列表。紧凑和专用布局是有效的作者选择, 而非例外情况。每个候选方案都暴露精确的独立黑与白 值,用于直接主题创作。在生成的族系中,色标 0 和 100 会重复 这些值。作者 MAY 通过自定义色标列表省略重复的端点, 而不会丢失独立值。族系标识符black和white保留给这些独立值。 - FR2a — 自定义色标的语法是精确的。 每个色标 MUST 是一个有限的 JSON 数字,
范围从 0 到 100(含)。色标 MUST 唯一且严格递增。
整数和小数色标均有效;诸如
5和5.0之类的等效数字拼写 识别的是同一个色标,因此不能共存。端点 0 和 100 是可选的。单色标调色板有效。序列化使用 实现所产生的规范 JSON 数字拼写,且 MUST NOT 依赖 于区域设置。 - FR2b — 色标数字是稳定的坐标。 对于相同的配方、族系、 模式、种子、活力、配置文件和兼容锚点,一个共享色标 MUST 在紧凑、完整和自定义布局中产生相同的精确颜色。添加或移除 其他色标 MUST NOT 对其重新编号或改变它。生成的 TypeScript MUST 仅暴露所请求的色标键,因此省略的色标会在类型检查时失败。
- FR3 — 模式意图是显式的。 仅亮色、仅暗色、独立的亮色和 暗色输入、共享候选方案以及命名的暗色变换是互不相同的。一个 亮色渐变 MUST NOT 静默地变成一个经过审查的暗色渐变,且标签 MUST NOT 在暗色模式下被反转。
- FR4 — 约束与偏好保持区分。 色域有效性、 单调性、精确锚点以及有界锚点容差是硬约束。 强度、光学平衡和灵活锚点是优化偏好。 冲突 MUST 清晰失败,而不是移动精确锚点、削弱 容差、替换配置文件或更改色标布局。锚点 MUST NOT 将色标 0 或 100 变成色度值;冲突的端点锚点 会失败,并给出使用内部色标的指导。
- FR5 — 配方是确定性的且有版本号。 一个配方标识 MUST 固定 色彩空间、常量、配置文件、进度表、锚点、色域处理、精度、 舍入、序列化和打破平局。相同的规范化请求 MUST 在受支持的平台上产生字节级相同的规范候选输出, 且不受任何环境时间、区域设置、路径、网络、随机性、遍历或 未记录依赖项输入的影响。
- FR6 — 生成的候选方案带有可复现性证据。 生成器 MUST 输出完整的候选方案,外加一个独立的记录,其中标明规范化的 请求、配方与实现版本、输出格式版本、 调整、偏差以及每个规范输出的摘要。输出变化 MUST 改变相应的身份或摘要。
- FR7 — 生成止于候选方案。 输出 MUST 将自身标识为 候选方案,且 MUST NOT 采纳值、映射角色或声称视觉或可访问性 批准。预览是只读的。一个显式输出选项 MAY 将候选方案 保存为单独的 TypeScript 或 JSON 文件,但 MUST NOT 在没有 显式作者意图的情况下覆盖现有文件。一旦采纳,该调色板就是普通的 作者自有数据:它可以被自由编辑,并且不再受生成器控制。 被编辑的已接受数据 MUST NOT 声称可精确重新生成,并且普通 主题构建 MUST NOT 重新运行生成器。
- FR8 — 选定的配方保留完整族系证据。 第一个生产 配方 MUST 由其规范性算法和规范化夹具固定,而不是由另一个实现 固定。在发布之前,其版本固定的证据 MUST 覆盖完整族系集合、 渲染的亮色/暗色上下文、色相连续性、亮度与相邻色标 区分、色域、族系平衡、CVD 模拟、可复现性以及 性能。夹具覆盖蓝到紫、黄到棕、不成比例的 族系强度,以及蓝/紫、黄/绿和红/橙的区分。 在作者接受之前,输出仍然是候选方案。
- FR9 — 接受的映射是显式、可检查且连贯的。 承认
已接受调色板/主题集成的当前权威 MUST 定义稳定的语义角色引用,
或定义一个同等确定性的创作时映射契约。一旦编辑过或重新生成的调色板被显式接受,
映射到它的每个角色 MUST 连贯地更新,而无需作者
手动重新复制无关的值。工具 MAY 建议映射,但一个单独的显式
应用操作 MUST 展示目标和补丁、保留作者编辑,并允许
调整或拒绝。此需求不选择最终的
DefineThemeInput、编译器或工件形态。 - FR10 — 重新生成绝不隐式地重新着色主题。 生成一个新的 候选方案 MUST NOT 替换已采用的调色板,或更改已保存的主题值、 规范化令牌、CSS、已构建的运行时模块或已挂载行为。一次已提交的 调色板编辑 MAY 有意更改显式引用它的主题映射;该源码差异及其 渲染影响 MUST 一起审查。
- FR11 — 验证与构造分离。 调色板检查使用
主题包测试、内部测试工具中
validate*或check*角色,或者 一个显式接受的未来 CLI 检查器。仅用于验证的数据和辅助工具 MUST 保持在 Core 运行时主题输入和输出之外。 - FR12 — 可访问性是上下文相关的。 工具 MAY 报告显式配对 的测量属性和对比度。它们 MUST NOT 将孤立的调色板、 族系、色标或建议标记为可访问。主题证据点名精确的 前景、背景、文本大小、组件状态、模式和非颜色线索。
-
FR13 — 创作没有运行时成本。 生成器代码、颜色数学 依赖、候选方案、可复现性数据以及建议逻辑 MUST NOT 进入 Core 组件运行时、主题挂载、默认主题 CSS 或 JavaScript, 或主题包的默认运行时导出。
-
FR14 — 受支持的生成接口保持狭窄。
generateTonalPalette(request)是一个纯创作函数,返回候选数据而不读取或写入文件。astryx theme palette generate <config>是其非交互式文件适配器。 TypeScript 是主要已提交的输出,因此精确的族和 stop 键仍然可检查;JSON 可以被请求用于互操作性工具。这些接口 MUST NOT 隐式重写主题或执行语义映射。未来的显式一等调色板输入、稳定映射契约或编译器集成需要额外的当前权威;本要求既不批准也不禁止。 - FR15 — 视觉审查使用单一标准工件。 CLI 可以显式地从相同候选数据写入一个自包含的 HTML 预览。预览 MUST 将其自身标识为
palette-preview-v1,显示每一个已生成的族、模式、stop 和十六进制值,并且不需要网络资源。它 MUST NOT 做出可访问性声明。它遵循与调色板输出相同的覆盖保护,并且 MUST NOT 在没有单独明确操作的情况下打开浏览器。 - FR16 — 创作指导保留意图。 面向代理的文档和评估夹具 MUST 区分精确、有界和灵活的锚点;保留显式的小数和自定义布局;当未请求强调色时省略强调色;并在模糊强调色是一个主题值还是一组浅色和深色家族时提出问题,而不是猜测。
- FR17 — 新创作使用调色板;传统扩展保持兼容。 主题创作接口 MUST NOT 在它还替换中性色、表面、文本、边框或其他派生值时,将单个强调色输入呈现为孤立编辑。Playground MUST 省略
Create from accent,并保留对显式颜色 token 的直接编辑。CLI 主题文档和生成的主题模板 MUST 为新创作推荐受支持的调色板工作流。在替换优先补丁中,显式参考文档 MUST 将DefineThemeInput.color、ThemeAdaptationValue.color和expandColorScale()标识为已弃用的传统创作 API,同时准确记录其对未迁移主题的现有行为。ColorScaleConfig和ColorScaleTokens在此生命周期内保持稳定的公共类型;本记录不安排其移除。 - FR18 — 颜色刻度弃用是静态的、替换优先的且无损的。 在替换优先补丁之前,所有三个接口保持
stable,且没有任何声明或警告将其标记为弃用。该补丁 MUST 与创作/构建诊断一起发布可用的调色板替换、稳定的版本化说明、精确的现代化命令、维护中源码的迁移、声明@deprecated元数据。每个诊断 MUST 指明适用的DEP-*id、精确替换、稳定说明和迁移命令。弃用 MUST NOT 添加运行时兼容标志、运行时分支、渲染应用警告或可执行生产包字节。对于未迁移的源,现有 token 值字符串(包括 CSS 引用)、规范化、适配层、继承、生成的 CSS、构建以及挂载行为在弃用窗口内保持字节等效。可预览且幂等的迁移遵循spec:AST-040,将这些可观察项作为其基线保留,并报告动态、继承、带适配或其他不确定的情况而不重写它们,除非它可以证明替换保留相同行为。迁移从不调用调色板生成器:它将精确的当前 token 值字符串作为导入的、主题拥有的调色板数据或字面 token 值写入,并通过tokens引用它们。移除需要单独清理 id 和下方生命周期表中的次要版本发布批准。
弃用生命周期¶
三个传统接口遵循 spec:AST-017 FR28–FR31 和 FR29a–FR29d。它们共享一个创作机制,但是不同的公共契约,因此分别描述和移除。它们的直接权威是 spec:AST-008/FR18。
DefineThemeInput.color¶
- 包 / 接口:
@astryxdesign/core类型字段。 - 弃用 / 清理:
DEP-AST-008-COLOR-INPUT/CLN-AST-008-COLOR-INPUT。 - 旧契约:
color种子在defineTheme()规范化期间派生宽泛的主题 token 值,并可被后代主题继承。 - 替换:
astryx theme palette generate生成已审查的、主题拥有的 TypeScript 调色板数据;AST-040 codemod 也可以改为导入精确的现有 token 值字符串作为等效的调色板数据。主题通过现有tokens条目书写语义角色,这些条目引用该已提交数据。稍后的当前权威可以用一等集成替换此创作投影。 - 警告:
@deprecated加上精确源主题构建或验证诊断,每个都指明弃用 id、稳定的版本化说明和astryx upgrade --from <installed-version> --apply。 - 迁移 / 证明: AST-040 codemod 物化字节相等的 token 值字符串(包括 CSS 引用),并证明等效的规范化 token、生成的 CSS、适配层、继承和扩展行为。它报告并保持无法证明的动态或可继承用例不变。
- 状态 / 目标:
stable直到替换优先补丁发布,然后为deprecated;清理未排期,并且需要在冻结的次要版本计划中提供精确的清理 id。 - 回滚: 清理前,还原迁移补丁或保留弃用字段;清理后,兼容的恢复补丁恢复该字段及其字节等效的规范化。
ThemeAdaptationValue.color¶
- 包 / 接口:
@astryxdesign/core嵌套类型字段。 - 弃用 / 清理:
DEP-AST-008-ADAPTATION-COLOR/CLN-AST-008-ADAPTATION-COLOR。 - 旧契约: 适配规则提供从有效根颜色轴补全的部分颜色刻度配置。
- 替换: 适配规则通过现有
value.tokens条目书写条件特定的语义角色,这些条目引用相同的已提交主题拥有的调色板数据。 - 警告:
@deprecated加上携带相同说明和迁移字段的精确源主题验证诊断。 - 迁移 / 证明: AST-040 codemod 保留每个降级后的适配 token 字符串和规则顺序。除非它能证明等效的补全和 CSS,否则它报告并保持部分、继承或动态规则不变。
- 状态 / 目标:
stable直到替换优先补丁发布,然后为deprecated;清理未排期,且独立于根字段清理。 - 回滚: 清理前,保留或恢复弃用字段;清理后,兼容的恢复补丁恢复其补全和降级行为。
expandColorScale()¶
- 包 / 接口面:
@astryxdesign/core函数导出。 - 弃用 / 清理:
DEP-AST-008-EXPAND-COLOR-SCALE/CLN-AST-008-EXPAND-COLOR-SCALE。 - 旧契约: 一个公共创作辅助函数将
ColorScaleConfig展开为广泛的 token 覆盖,包括实时 CSS 引用。 - 替代方案: AST-040 codemod 将精确返回的 token 映射内联为已提交的 TypeScript 模块,其字符串被直接导入,或者将主题调用点迁移到由该已提交数据支持的现有
tokens/ 适配value.tokens引用。 - 警告:
@deprecated加上携带相同指令和迁移字段的精确来源创作或构建诊断。 - 迁移 / 证明: 当调用可静态解析时,AST-040 codemod 会物化字节相等的返回 token 字符串;动态调用会被报告并保持不变。旧辅助函数输出与迁移后的主题输出会在代表性用法和下游用法上进行对比。
- 状态 / 目标: 在替代优先补丁发布前为
stable,之后为deprecated;清理未排期,且与两个字段的清理相互独立。 - 回滚: 清理前,保留或恢复已弃用的导出;清理后,兼容的恢复补丁会恢复该导出及其字节相等的输出。
ColorScaleConfig 和 ColorScaleTokens 仍然是稳定的公共类型,本记录未为其分配清理 ID。
替代优先补丁会一并交付可用的调色板路径、稳定的版本化指令、AST-040 codemod、静态声明元数据、精确来源的主题构建或验证诊断、维护来源迁移,以及旧/新兼容性证明。FR17 的 Playground 和新创作指南要求立即生效,不需要等待替代优先补丁。该补丁的维护来源迁移覆盖示例、stories、测试和仓库自有主题中对三个遗留接口面的剩余使用。defineTheme、主题挂载和渲染后的应用永远不会发出弃用警告。对一个 ID 的清理批准并不授权移除另一个 ID。
实现契约¶
astryx-oklch-v1定义在唯一自有生产引擎中,该引擎固定其常量、变换和精确回归向量。- 纯创作 API 和 CLI 适配器使用同一个确定性引擎,并在配方语义上保持一致。CLI 遵循
architecture:cli-surface关于命令、响应、错误、文档、支持和写入契约的规定。 - 生成的 TypeScript 导出作者自有的调色板数据,而不导入生成器。生成的 JSON 包含相同的规范调色板值。
- 可选的 HTML 预览由单一版本化渲染器生成,而不是由每个代理或调用方临时拼凑。
- 每个公共函数、命令、包、schema 或工件在发布前都要分别通过 API 和 AST-017 兼容性验收。
- 聚焦的代理夹具覆盖锚点语言、可选强调色、澄清和自定义色标。预期决策仅用于评估,MUST NOT 包含在发送给代理的 prompts 中。
astryx-oklch-v1 规范配方¶
第一个生产配方在此定义,并由规范夹具固定:
- 将支持的种子色和锚点色规范化为小写六位 sRGB 十六进制。
- 通过标准 D65 OKLab 矩阵转换 sRGB,然后以 OKLCH 表示色相和色度。
- 使用 CIELAB L* 传递函数将请求的 tone 转换为明度:高于 8 的值使用
((tone + 16) / 116)³;较低的值使用tone / 903.3;结果对 OKLab 明度取立方根。 - 应用固定的 tone 色度包络
0.18 + 0.82 × sqrt(sin(π × tone / 100))。 - 应用色相平衡因子:
[70,115)为 0.94,[115,175)为 0.78,[175,230)为 0.82,[285,340)为 0.90,其他区域为 1。橙色色相[40,70)在 tone 低于 50 时向红色最多旋转 8 度,使低橙色的色标与红色家族保持明显区分。 - 在 tone 60 以上,绿色色相
[115,175)会衰减到其平衡色度的 72%,teal 色相[175,200)在 tone 95 时使用 smoothstep 衰减到 60%。这使它们的浅色色标在光学上保持平衡,同时不会削弱青色或改变中间调锚点。 - Vibrancy 50 为中性。0–25 的值插值到乘数 0.72;25–50 的值从 0.72 插值到 1;50 以上的值每点增加 0.0096。
- 跨家族协调将源色度 35% 与参考色度 0.18 按 65% 混合。中性配置文件为
neutral-v1(色相 0,色度 0)、warm-v1(色相 75,色度 0.018)、cool-v1(色相 250,色度 0.018)和custom(规范化的中性种子色)。 - 色标编号在两种模式下保留相同的字面 tone 含义。深色渐变将色度乘以 0.85,而不会悄然改变请求的 tone。因此,色标 0 在任一模式下都解析为纯黑,色标 100 解析为纯白。两个端点默认包含,MAY 由显式自定义布局省略。
- 超出色域的 OKLCH 候选保留明度和色相,同时通过
[0, 0.4]上的 20 次二分查找来确定色度。 - 精确锚点替换其色标。有界锚点仅在其声明的 OKLab 欧几里得
maxDeltaE范围内向请求的颜色移动;灵活锚点以 35% 的比例向请求的颜色混合。锚点修正使用 smoothstep 插值,并在最近锚点之外 25 个 tone 单位处衰减到零。 - 将最终颜色转换为 sRGB:每个钳制通道四舍五入到最接近的 8 位整数。输出小写
#rrggbb。规范 JSON 使用两个空格缩进、插入顺序的家族和色标,以及一个尾随换行符。候选对象将请求的色标布局公开为有序的stops数组;家族渐变对象是查找映射,不定义迭代顺序。 - 无效请求在生成候选之前失败。家族内锚点冲突会报告相关家族,并且不产生可采用输出。
以下规范候选夹具使用 UTF-8 规范 JSON 上的 SHA-256。
| 夹具 | 请求摘要 | 候选字节数 | SHA-256 |
|---|---|---|---|
default-three-family |
中性 #777777、蓝色 #0074e2、橙色 #d57113;浅色和深色模式;活力 50;21 个默认色阶 |
3755 | 11c40191d508274d89d631bb4e1cb662f70ff0dce6c0dec101c317f9f69d3e25 |
exact-anchor |
蓝色 #0074e2;仅浅色模式;色阶 20、50、80;精确的 50 号色阶锚点 #1682d5 |
327 | c42929be3c4b5cb857cada078f62bb5a2242c1a22cfa4ae7546a18592540f7f3 |
single-custom-stop |
红色 #d62830;仅深色模式;色阶 40 |
258 | 88d3d69865c74c7fb14347b9967575285a7d44ab893087a08bc842bb66b29bbb |
high-tone-balance |
绿色 #358a3a、蓝绿色 #0c7365、青色 #0c6f82;浅色和深色模式;色阶 60、80、95 |
910 | 873821574fdbe3357304dbc06986bd2e5ec88af80d0f36305626fd826c3cf07b |
精确的夹具等值是配方兼容性的发布门槛。单调性、相邻色阶距离、色相漂移、家族区分、色域事件和 CVD 模拟均作为完整候选方案的设计证据被记录;它们不会成为针对孤立颜色的通用可访问性或对比度保证。
当前状态影响¶
| 状态 | 必需结果 |
|---|---|
| 生成缺失 | 现有主题、构建、运行时字节和支持的包范围保持不变。 |
| 候选方案已生成 | 不改变任何源代码、主题、包或运行时输出。 |
| 调色板已接受 | 精确值以 theme:<name> 键进入主题拥有的调色板数据;后续的当前权威机构可标准化其形态。 |
| 映射已接受 | 在该权威机构下,稳定的语义角色引用是可检查、可审查且可一致更新的。 |
| 新候选方案已生成 | 已采纳的调色板和渲染输出保持不变,直至经过明确的审查和保存。 |
| 已采纳调色板被编辑 | 在该权威机构下,明确接受编辑会一致地更新映射的角色;无关的字面值保持不变。 |
| Playground 颜色编辑 | 显式令牌编辑保持不变;任何强调色编辑都不会静默扩展到无关的颜色令牌。 |
| 补丁之前的遗留表面 | 稳定、完全受支持且不带标签;Playground 和维护中的新创作指南立即遵循 FR17。 |
| 替换优先补丁 | 替换、指南、迁移、静态元数据、诊断、源代码迁移和兼容性证明一同发布。 |
| 使用了已弃用的 API | 规范化、令牌字符串、继承、CSS、构建和挂载行为保持字节等价。 |
| 迁移运行 | 经过验证的用法保留精确的可观察结果;不确定的动态、继承或带适配的用例保持不变。 |
验证¶
验证 MUST 涵盖跨平台确定性向量;硬性失败;每个候选来源和溯源状态;完整家族的回归/CVD 证据;候选方案与已接受方案的一致性;可检查的稳定角色映射;运行时/默认包中不存在相关代码;已接受映射的真实 Chromium 证据;Playground 中强调色编辑不会调用旧版颜色刻度扩展或改变无关令牌的证据;静态 @deprecated 声明元数据;精确来源的主题构建或验证诊断;不存在仅弃用相关的运行时分支、日志、可执行字节或输出变更;维护中源代码的迁移;以及 AST-040 预览、幂等性和拒绝夹具。迁移证明 MUST 比较令牌值字符串,包括 CSS 引用、规范化根层和适配层、生成的 CSS、继承以及后代扩展行为。
决策日志¶
DEC-5 和 DEC-9 — 保留完整配方证据¶
决策者: cixzhang,2026-09-01 至 2026-09-02
FR8 保留了 Ruby 的完整创作要求和所选 OKLCH 方向背后的比较证据。仅凭色彩空间名称或孤立的色阶并不能定义生产配方。
DEC-10 — 已接受的调色板是已提交的快照¶
决策者: cixzhang,2026-09-03
已接受的调色板是已提交的快照。主题映射使用字面 CSS 值或对已提交调色板数据的显式引用;生成永远不会隐式运行。生成的候选方案在作者明确接受之前,不会改变任何已接受的源代码或渲染输出。
已拒绝:在普通主题规范化或构建期间隐式运行生成器,因为它会在没有明确接受源代码变更的情况下重新着色主题。
DEC-11 — 生成具有一个创作引擎和两个适配器¶
决策者: cixzhang,2026-09-03
CLI 主题创作工作流是第一个受支持的消费方。纯 generateTonalPalette() API 支持无文件系统副作用的编程式创作;astryx theme palette generate 增加了预览和显式文件输出。两者都使用相同的 astryx-oklch-v1 引擎。两者都不会进入 Core 或 defineTheme()。
DEC-12 — 生成器默认值不限制调色板作者¶
决策者: rubyycheung,2026-09-03
第一代生产生成器默认将每个家族设置为常见的 21 位置 0, 5, …, 100 布局,并接受任何显式的非空数值色阶列表。每个候选方案都将精确的黑色和白色暴露为独立的创作值。色阶 0 和 100 会在每个生成的家族中重复这两个值,以便作者可以保留完整的坐标范围,或显式移除重复的端点,而不会丢失对任一纯色的访问。生成的 TypeScript 将这些值命名为 black 和 white;主题拥有的调色板包装器可以将它们与家族一起暴露,例如 neutralPalettes.black 和 neutralPalettes.white。这些名称被保留,不能用作家族标识符。生成的候选方案在审查和接受后归作者所有。因此,生成器默认值不会成为调色板有效性规则。
生成的调色板是可审查的起点。作者可以调整 family 级输入并重新生成,直到调色板符合其预期的表达;只有明确批准的输出才会成为该主题所拥有的调色板。
已否决:要求每个被接受的调色板都使用生成器的 21 档默认值。主题可能需要用于图标、插画、可视化或品牌表达的紧凑型或专用调色板。
DEC-13 — Intermediate stops are generated explicitly¶
Deciders: cixzhang、rubyycheung、2026-09-03
紧凑与完整预设共享相同的 0–100 色调坐标系,自定义布局仍然有效。需要 12.5 等中间值的作者在生成期间请求该档位,并审查输出的精确 hex 值。提交的 TypeScript 随后将 family[12.5] 暴露为实际的类型化键。
已否决:将调色板作者限制为两种档位数量、在布局变化时重新编号档位,或添加运行时 family.get(12.5) 在编写完成之后创建未审查的颜色。
DEC-14 — Playground color editing does not imply palette generation¶
Decider: rubyycheung、2026-09-30
Playground 保留直接的语义令牌编辑,并省略 Create from accent。当一个仅含单个 accent 的控件还会替换 neutral、surface、text、border 及相关值,且不暴露候选调色板或单独的映射决策时,它就不是调色板编写。受维护的编写界面会改为推荐受支持的调色板工作流。
已否决:在保留自动令牌重写的同时用另一个生成器替换该控件,因为那仍然会将生成、审查和映射混为一体。
DEC-15 — Legacy color-scale authoring follows static replacement-first deprecation¶
Decider: cixzhang、2026-10-07
DefineThemeInput.color、ThemeAdaptationValue.color 和 expandColorScale() 保持稳定,直到一个补丁发布完整的替代方案、版本化指南、AST-040 现代化、静态元数据、精确来源诊断、受维护来源迁移以及兼容性证明。此后它们进入 deprecated 状态,具有字节等价的可执行行为,且不附带运行时警告或分支。每个公共表面拥有独立的弃用与清理 id。
未来的第一类调色板输入、稳定的语义角色映射以及编译器集成,仍然对 AST-018(若经修订并被接受)或后续的当前权威保持开放。AST-008 要求显式接受、连贯的映射更新,并且在不选择该未来 API 形态时不得隐式运行生成器。
已否决:运行时兼容性标志或弃用警告,或永久禁止第一类调色板/主题集成。
Open questions¶
- OQ1 — What is the first-class accepted palette/theme contract? 后续的当前权威——仅当 AST-018 经修订并被接受时——必须确定公共输入形态、稳定的语义角色引用、编写与编译行为、验证以及产物生命周期。AST-008 要求显式审查、连贯的映射更新,并且在不从这些 API 形态中进行选择时不得隐式运行生成器。
本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 as/astryx