Astryx 主题规格Theme Spec编写指南从模板字段到 Neutral 参考实现的完整实践【免费下载链接】astryxAn open source design system thats fully customizable and agent ready项目地址: https://gitcode.com/GitHub_Trending/as/astryx本指南以 theme-spec.md 知识模板 为骨架结合仓库中真实落地的主题规格记录 neutral.spec.md 及其主题源码 neutralTheme.ts系统讲解 Astryx 开源设计系统中主题规格文档应当如何编写、审阅与验证。读完本文你将掌握主题规格记录的全部 frontmatter 字段、13 个正文章节的职责边界以及如何借助defineTheme归一化模型、语义 token 架构与验证地图把一份草稿draft推进为可发布的当前current主题记录。一、什么是主题规格文档它处于知识体系中的哪个位置在 Astryx 仓库中docs/templates/knowledge/目录存放着所有知识记录knowledge record的起点模板版本清单记录在 versions.json 中其中theme模板的template_version为1。theme-spec.md就是主题类知识记录的官方模板它的kind: theme、id形如theme:package-theme-name例如theme:neutral。根据 docs/themes/README.md主题规格是某个已发布主题包的唯一权威归属者canonical owner负责记录该主题的受众与视觉意图intent继承自何处的基线inherited base可移植 token 的选择portable token choices主题本地角色theme-local roles色调色板族与所选色调tonal palette families and selected tones组件/状态映射component/state mappings兼容性compatibility制品形态artifact shape以及可测量的证据measured evidence。主题规格记录与各层知识记录有明确的分工边界不应越界记录类型归属职责参考文档architecture / system spec跨主题 API、词汇边界、继承规则、校验、编译行为、共享制品策略theme-authoring-contract.md、theme-tokens.md、theme-compilation.md、component-theming-surface.mddesign record跨主题的视觉与无障碍方法论含对比度证据如何判定design/README.mdarchitecture / tooling共享测量工具实现—package-local theme spec本文主角上述方法论的应用token/色板映射、必备配对/状态、例外、测量收据、已知缺口theme-spec.mdcomponent / family record可观察的组件行为docs/architectureconsumer docs受支持的语法、示例与使用指导—需要特别强调的两条规则来自 docs/themes/README.md只有current记录才是政策policy。draft 可以引用另一个 draft 以推进决策但 current 记录只能依赖 current 记录。current 主题记录需要来自.github/ENGOWNERS与.github/DESIGNOWNERS并集成员的 exact-head 审批。主题记录不声明owners字段记录元数据本身永远不会授予审批权。二、Frontmatter主题规格的元数据契约模板的 frontmatter 是主题记录的身份证所有字段必须按语义填写。下表逐字段说明含义并给出 Neutral 参考实现的真实取值模板字段含义Neutral 参考取值neutral.spec.mdschema_version知识记录 schema 版本2template_version模板版本1kind记录类型固定为themethemeid全局唯一 ID形如theme:package-theme-nametheme:neutralauthority权威状态draft/currentcurrentapproved_by审批人current 记录必填rubyycheungapproved_at审批时间current 记录必填2026-09-04review_triggers触发复审的事件类别[tokens, palette-values, component-mappings, contrast, artifacts]verified_by验证证据测试或制品路径[scripts/check-badge-contrast.test.mjs]package对应的发布包名astryxdesign/theme-neutralsource_theme主题源码相对路径packages/themes/neutral/src/neutralTheme.tsreferences该记录依赖的 architecture / design / system 记录[architecture:theme-authoring-contract, architecture:theme-tokens, architecture:theme-compilation, architecture:component-theming-surface, spec:AST-006]模板中的review_triggers默认值为[tokens, component-mappings, contrast, artifacts]Neutral 增加了palette-values因为它的发行涉及色板值本身。一个值得注意的细节references使用单一的references列表而非多个关系字段统一承载 architecture、design、system 等知识关系。这意味着模板作者在填写时必须想清楚这个主题依赖了哪些已定稿的系统级记录。Neutral 的五个引用中spec:AST-006是跨主题 local-token 契约的决策来源详见 docs/specs/AST-006/spec.md。另外注意模板注释的约束当前主题记录不能引用 draft 或不存在的记录——如果共享对比度方法论的设计记录尚未 current则该依赖只能留在 Open questions 一节不能写进 frontmatterNeutral 就是这么处理的见其无障碍章节。三、正文 13 个章节职责边界与写法要点模板正文由 13 个小节组成每一节都有明确的职责边界。下面按模板顺序逐一解读并给出 Neutral 的实践示范。3.1 Intent and audience意图与受众说明该主题为谁而做、视觉气质是什么。这是整份记录的北极星后续所有 token 与映射决策都应能回溯到这里。Neutral 的写法值得借鉴Neutral 服务于需要安静灰度基底、克制的表面以及可辨识的状态色与分类色的构建者。它在保持产品中立的同时让状态与交互状态在两种色彩模式下都可辨认。3.2 Inheritance and base继承与基线记录该主题是否扩展了其他已发布主题。Neutral 声明从 Astryx 核心默认值出发覆盖了选定的排版、动效、圆角、阴影、语义色、语法高亮、图标与组件值当前不扩展任何其他已发布包主题。这一点对应defineTheme的extends能力——详见 theme-authoring-contract.md 的 INV3扩展一个真实的DefinedTheme会语义化拍平flatten其解析后的 token、local-token 归属与谱系元数据、组件规则、媒体表面、adaptations 与轴线、图标与指示器子主题的归一化表示是完整自足的。3.3 Portable token overrides可移植 token 覆盖记录主题对可移植语义 token如--color-background-surface、--color-text-primary的具体取值。这些 token 名由跨主题的 token 架构统一拥有见 theme-tokens.md主题规格只记录本主题选择了哪些值不重新发明词汇表。3.4 Theme-local role definitions主题本地角色定义这是模板中注释最多的章节也是整个主题规格体系中最精细的机制。模板注释明确写道只记录事实性的主题自有的角色与证据。公开的主题 API 提案属于独立的 system spec。主题本地角色通过localTokens机制实现。以 Neutral 为例neutralTheme.ts其候选实现拥有一个已批准角色并提议了若干相关角色精确名称Neutral 专属含义建议值状态--astryx-theme-neutral-color-status-fill-accent填充的 accent 状态[#0074e2, #6d9cfe]Approved--astryx-theme-neutral-color-status-fill-success填充的成功状态[#198100, #64af4c]Proposed--astryx-theme-neutral-color-status-fill-warning填充的警告状态#ffce2fProposed--astryx-theme-neutral-color-status-fill-error填充的错误状态[#c9303a, #ff705d]Proposed--astryx-theme-neutral-color-on-tint-neutral置于语义着色表面上的中性内容[#fafafa4D, #0a0a0a4D]Proposed--astryx-theme-neutral-color-on-tint-overlay-hover置于语义着色表面上的悬停覆盖层[#fafafa1A, #0a0a0a1A]Proposed--astryx-theme-neutral-color-on-tint-overlay-pressed置于语义着色表面上的按压覆盖层[#fafafa33, #0a0a0a33]Proposedlocal-token 的使用要点来自 theme-tokens.md 与 theme-authoring-contract.md本地 token 是一个独立的 enrolled 映射可复用TokenValue形态但绝不进入TokenName、默认值、tokenVar、tokenVars、resolveThemeToken、resolveThemeTokens、生成的便携文档或 Core 组件源码INV8一个名字不能同时出现在可移植tokens和localTokens中否则 CSS 与非 CSS 解析会产生矛盾胜者本地 token 的 key、组件中的var(...)引用、DefinedTheme映射与最终发射的自定义属性必须使用同一个完整名称提议值优先使用[light, dark]的TokenValue元组其归一化行为与可移植tokens下的元组完全一致前缀只是作者约定不授予、不保留、不限制归属权AST-006 的 2026-09-12 修订使 key 有效性判定与归属前缀无关。Neutral 的实际声明代码neutralTheme.tsexport const neutralTheme defineTheme({ name: neutral, localTokens: { --astryx-theme-neutral-color-status-fill-accent: [#0074e2, #6d9cfe], // ... 其余本地角色 }, components: { badge: { variant:info: { backgroundColor: var(--astryx-theme-neutral-color-status-fill-accent), color: var(--color-on-accent), }, }, }, });一旦发布这个精确名称与填充 accent 状态的语义就成为Neutral 主题家族的公开兼容性契约。它不可移植到其他主题也不供 Core 组件源码使用。3.5 Tonal palette definitions色调色板定义记录主题的色板清单与证据。模板注释提醒色板生成或制品 API 属于独立的 system spec本节只记录事实性色板库存与证据。Neutral 的做法是候选源码包含 neutral、red、orange、yellow、green、teal、cyan、blue、purple、pink 十族的完整 light/dark 斜坡提交的请求、生成模块与收据receipt使得被审阅的astryx-oklch-v1结果可复现。相关文件位于 packages/themes/neutral/src/neutralPalettes.ts、neutralPalettes.generated.ts 与 neutralPalettes.generated.receipt.json。两个关键纪律重新生成色板是一次显式的、被审阅的变更绝不会在正常主题构建期间发生对应 DEC-2 的否决项色板生成采用 OKLCH 色彩空间其跨主题编写与校验契约由 draft 的 docs/specs/AST-018/spec.md 单独拥有。Neutral 的 DEC-3 还批准了一项暗色模式调整对彩色族在 stop 25 之前将实现色度realized chroma降至 50%黄色族以 65% 覆盖保留其识别度并在 stop 60 处平滑恢复到标准配方亮色斜坡、中性斜坡与 stop 60–100 保持不变不引入透明度、不改变色调坐标。3.6 Component and state mappings组件与状态映射记录主题对组件目标component target/样式键style key的覆盖。模板要点本主题只记录映射到哪些组件与状态组件的可观察行为属于组件/家族记录。Neutral 将共享的 status-fill 角色映射到 Badge、StatusDot、AvatarStatusDot、Stepper 指示器与 ProgressBar凡已有相同语义的状态处Banner 使用提议的 tint 内容与交互角色。源码见 neutralTheme.ts。同时它明确排除两类情况table-row-status没有已批准的主题目标不映射SegmentedControl 的几何/阴影改动独立审阅不混入本次。关键审查标准每个映射都必须经过 exact-head 主题审阅与渲染后的 light/dark 证据仅凭共享颜色本身不够。这一条是整个章节的灵魂——颜色相同不等于语义相同。3.7 Compatibility and migration兼容性与迁移记录本主题发布的包输出以及任何命名/语义变更如何不破坏消费者。Neutral 的做法已有的 Neutral 编写方式与可移植 token 名保持稳定审阅后的映射通过运行时主题与 CLI 模板发射一旦发布精确名称与已批准语义成为 Neutral 家族的公开兼容契约local-token 名称、enrolled 主题名或语义含义的任何变更必须通过显式的审阅迁移或别名来保留后代与消费者编译后的 CSS 不会把角色扩宽到其已批准上下文之外。跨版本破坏分类与迁移由 docs/specs/AST-017/spec.md 拥有见 theme-authoring-contract.md 的 Change coupling 一节即使归一化 token 与 CSS 未变只要主题源码或构建在 Core 版本变更后无法原样工作就必须进入 AST-017 的破坏分类流程。3.8 Accessibility and contrast evidence无障碍与对比度证据模板中注释最长的章节明确要求本主题只拥有方法论的应用——所选前景/背景或图形对象配对、必备模式与状态、例外、测量收据与已知缺口不复制共享方法论或测量工具实现。Neutral 的诚实示范由于跨主题对比度方法论的设计记录尚不存在本规格不选择也不复述任何方法论该依赖被留在 Open questionsOQ1因此也没有出现在 frontmatter 的 references 中。同时它明确说明当前 Neutral 的收据包括 Badge 对比度检查scripts/check-badge-contrast.test.mjs与源码旁的配对文档accent 填充值#0074e2/#6d9cfe本身不是无障碍声明必须配合真实的前景/背景配对达到阈值没有任何色板 stop 本身是可访问的颜色也不能替代组件契约要求的其他信号。3.9 Build and artifact contract构建与制品契约记录包的运行时、CSS、声明与导出输出。Neutral 的关键决策完整色板保留在主题自有源文件中供编写与审计而defineTheme使用的已生成选中 stop 引用进入运行时与 CLI 模板制品完整编写色板不会被打包进生成的 CSS 或通用主题构建制品。这一源文件与生成引用分离的策略避免体积膨胀与语义泄漏。3.10 Verification map验证地图模板给出三列表格结构每个契约都必须有证据、代表状态与失败信号Theme contractEvidenceRepresentative statesFailure signalrequirementtest or artifactmodes and stateswhat regression looks likeNeutral 的真实验证地图neutral.spec.md包含五条当前值清单、本地角色契约、组件映射、对比度、既有包契约。例如本地角色契约一行Theme contractEvidenceRepresentative statesFailure signalLocal role contractAST-006 实现与 Neutral fixtures精确的 declaration/use/output 名称公开含义重命名已发布的名称或含义在未做审阅兼容处理的情况下变更或泄漏进 portable/Core API这份验证地图与verified_byfrontmatter 字段呼应构成记录-源码-测试三方闭环。3.11 Decision log决策日志记录已定案的输入每条决策包含参考 ID、决策人与日期、结论与否决项。Neutral 有 4 条决策是模板使用的范本DEC-1拥有一个精确的 Neutral filled-accent-status 角色theme:neutral/DEC-1并明确否决将该角色视为全局的、视为一次性私有输出、或仅因两个上下文当前共享颜色就应用它DEC-2批准 Neutral 色板作为决策锚点明确否决在正常构建期间重新生成色板、在色板生成中静默改变运行时 token 映射、要求完整组件级对比度达标后才能将色板作为基线DEC-3暗色色度抑制方案否决降低整个色板的活力、使用半透明颜色、在该色板值变更中改变语义 token 映射DEC-4通过审阅的色板引用映射角色role-aware 而非盲目的就近取色否决盲目最近色转换。每条决策都标注**Reference:**、**Decider:**决策人日期便于审计追溯。3.12 Open questions开放问题记录尚未定案的依赖与待验证项通常标注(checkable)。Neutral 的两个开放问题OQ1提议元组与 Badge 映射、以及后续每个映射的交互状态其渲染后 light/dark 证据是否完整——在真实配对达到适用对比度方法论之前主题晋升与实现保持阻塞OQ2提议的 success/warning/error/tint 角色在每个列出的组件映射中是否有稳定语义——在审阅者确认每个映射代表相同语义角色而非仅仅共享当前颜色值之前额外名称保持为提议。开放问题是草稿推进到当前的门禁DEC 与 OQ 编号联动例如 DEC-1 明确直到 OQ1 通过且决策人批准精确记录头为止任何值或映射均未获授权。3.13 Content boundary内容边界收尾章节划定本记录的拥有范围与不拥有范围。模板原文明确本记录拥有该主题的意图、已选 token/色板映射、必备配对与状态、主题专属例外、测量收据、已知缺口、兼容性、制品与证据。跨主题的对比度方法论归未来的 design record共享测量/工具实现归 architecture 或 tooling跨主题 API 归独立的 architecture 或 system spec组件行为归组件/家族记录消费者语法与示例归消费者文档。Neutral 的 Content boundary 还补充了spec:AST-006对跨主题 local-token API、命名空间、校验、谱系与编译不变量的归属权。四、模板背后的系统模型defineTheme 归一化与 token 双层架构主题规格文档不是凭空书写的它描述的对象是defineTheme产生的归一化主题。理解底层模型才能写出与实现严格一致的规格。4.1 DefineThemeInput → DefinedTheme 的归一化根据 theme-authoring-contract.mdDefineThemeInput接受名称与可选归一化基线、高阶颜色/排版/圆角/动效配置、显式语义 token 覆盖、可选的主题家族本地 token 声明、组件目标/样式键覆盖、图标与指示器注册表、语法 token、onDark/onLight表面覆盖以及带固定命名宽度映射的有序环境 adaptations。归一化遵循唯一确定的优先级顺序解析后的基线主题resolved base theme由颜色、排版、圆角、动效配置生成的值显式 token 覆盖生成的组件排版随后是显式组件覆盖继承与显式的媒体表面覆盖继承与显式的主题本地声明需对照解析后的 token、组件与媒体表面校验继承与显式的图标/指示器注册表条目。关键不变量的实际意义INV1/INV2一份输入只产出一份归一化主题运行时与构建消费者看到的是同一个DefinedTheme优先级是确定性的INV5显式 token 逐 token 胜过生成值生成值只是连贯的默认值INV6组件覆盖按组件 × 样式键 × CSS 属性深度合并重复声明一个属性不会丢掉同键上继承的其他属性INV7onDark/onLight按系统默认 → 继承表面 → 本地覆盖的顺序组合INV9主题编写authoring与主题输出compiler/runtime是分离系统。负责这些语义的源码位于 packages/core/src/theme/defineTheme.ts配套实现包括themeAdaptations.ts、expandColorScale.ts、expandTypeScale.ts、expandRadiusScale.ts、expandMotionScale.ts、mergeComponents.ts、onMediaTokens.ts与localTokens.ts均在 packages/core/src/theme/ 下。CLI 的作者视角投影在 packages/cli/assets/theme.template.ts由 scripts/check-theme-template.test.mjs 保证模板与实现不漂移。4.2 可移植 token 与本地 token 的双层架构根据 theme-tokens.mdCore token 在tokens.stylex.ts中以成对导出声明*Defaults对象持有默认 CSS 值*Vars对象通过stylex.defineVars由默认值创建并被组件样式消费。defineTheme将核心默认值组合成完整 token 类型tokenVar、tokenVars、resolveThemeToken、resolveThemeTokens则把同一词汇表暴露给 canvas、SVG、图表、测试与构建工具等非 StyleX 消费者保证主题作者与组件作者始终引用同一套稳定语义名。领域层 token语法高亮与数据可视化保持独立可导入使不使用这些领域的应用无需引入其实现模块。这套分层正是规格文档中Portable token overrides与Theme-local role definitions两章分而治之的根源。五、实操从模板起步编写一份新的主题规格结合以上全部内容编写一份符合规范的 theme spec 的完整流程如下复制模板以 docs/templates/knowledge/theme-spec.md 为起点schema_version: 2、template_version: 1、kind: theme按 versions.json 确认当前模板版本放置位置主题规格与其包同目录存放即packages/themes/theme/theme.spec.md与组件规格的组织方式一致见 docs/themes/README.md填写 frontmatterid: theme:package-theme-name如theme:neutral填写package、source_theme、references、review_triggers与verified_by初稿阶段authority: draft、approved_by/approved_at: null逐节填充正文先写 Intent/Inheritance再写 token 与色板然后写组件映射最后补齐验证地图、决策日志与开放问题对照 Content boundary 自查确认没有把组件行为、跨主题 API、对比度方法论、测量工具实现写进本记录晋升 current通过verified_by列出的测试与制品验证补齐渲染后的 light/dark 与交互状态证据解决全部 checkable 的开放问题并由.github/ENGOWNERS与.github/DESIGNOWNERS的并集成员完成 exact-head 审批。六、结语一份合格主题规格的验收标准回看整份模板与 Neutral 参考实现一份合格的主题规格应当同时满足完整性13 个章节全部落笔frontmatter 的references与正文依赖一一对应边界清晰只记录该主题的意图、选值与证据不越权到组件行为、跨主题 API 或共享方法论证据驱动每个契约在 Verification map 中都有证据、代表状态与失败信号且verified_by与测试路径真实存在可追溯决策日志给出决策人与日期、明确否决项开放问题可检查checkable并阻塞晋升诚实没有证据的对比度结论不写色板与 token 值以源码为准草稿与当前状态的差异一目了然。以 Neutral 为镜Astryx 的主题规格体系把视觉设计意图变成了一份可审阅、可验证、可追溯的工程契约——这正是 docs/themes/README.md 所定义的主题规格是某个已发布主题包决策的唯一权威归属者。【免费下载链接】astryxAn open source design system thats fully customizable and agent ready项目地址: https://gitcode.com/GitHub_Trending/as/astryx创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考