Astryx 主题规范Theme Specifications主题包决策的知识契约与 Neutral 实战解析【免费下载链接】astryxAn open source design system thats fully customizable and agent ready项目地址: https://gitcode.com/GitHub_Trending/as/astryx本指南讲解 Astryx 开源设计系统中“主题规范Theme Specifications”机制它如何以随包共置的知识记录knowledge record承载单个已发布主题包的意图、令牌选择、组件映射、对比度证据与决策日志以及这套规范在astryxdesign/theme-neutral中的完整落地形态。读完你将掌握主题规范的定位、theme:package记录 ID 规则、引用关系边界、审批与兼容性契约并能直接照模板为任意主题包编写规范记录。主题规范不是又一份文档模板而是主题包决策的“canonical owner”。在 Astryx 仓库中docs/themes/README.md 是这套机制的索引与指引页真正的事实记录record与主题包源码共置存放于packages/themes/theme/theme.spec.md其结构与组件规范component specs保持一致。主题规范是什么谁对主题包决策负责一份主题规范是某个已发布主题包在下列维度上的唯一权威记录受众与视觉意图audience and visual intent继承的基座inherited base可移植令牌选择portable token choices主题本地角色theme-local roles色调调色板家族与所选 stoptonal palette families and selected tones组件 / 状态映射component/state mappings兼容性compatibility产物形态artifact shape实测证据measured evidence。指引页明确说明它只是指南和索引不是权威记录本体。权威记录放在主题包内部例如 Neutral 的 packages/themes/neutral/neutral.spec.md。新建记录从模板 docs/templates/knowledge/theme-spec.md 出发并使用theme:package-theme-name形式的 ID例如theme:neutral。目前仓库中的现行记录current records是Neutral — 已批准approval 元数据标记其authority: current批准人为rubyycheung批准日期 2026-09-04。记录之间的职责分工一份主题记录站在知识图谱的哪一层主题记录介于系统主题架构system theming architecture与消费方 / 组件记录之间它使用一个类型化的references列表来表达架构、设计、系统及其他知识关系而不是拆成多个关系字段。README 给出了明确的分层记录层拥有的内容架构与系统规范跨主题 API、词汇边界、继承规则、校验、编译器行为、共享产物策略设计记录跨主题的视觉与无障碍方法论含对比度证据如何判定架构 / 工具链共享测量实现shared measurement implementation包内主题规范本层方法论的具体应用令牌 / 调色板映射、必备配对 / 状态、例外、测量收据、已知缺口组件与家族记录可观察的组件行为消费方文档受支持的语法、示例与使用指南这一分层在 Neutral 规范的 frontmatter 中得到印证neutral.spec.md 的references指向references: [ architecture:theme-authoring-contract, architecture:theme-tokens, architecture:theme-compilation, architecture:component-theming-surface, spec:AST-006, ]政策等级与审批约束只有current记录是政策。draft 记录在决策开发期可以链接另一个 draft但 current 记录只允许依赖 current 记录。current 主题记录需要来自.github/ENGOWNERS与.github/DESIGNOWNERS提交并集committed union的“精确头部批准”exact-head approval。主题记录不声明owners字段记录元数据也永远不授予批准权——批准权只属于工程与设计 owner 集合。从模板到事实主题规范的标准章节骨架模板 docs/templates/knowledge/theme-spec.md 的 frontmatter 定义了记录的身份与治理信息--- schema_version: 2 template_version: 1 kind: theme id: theme:package-theme-name authority: draft approved_by: null approved_at: null review_triggers: [tokens, component-mappings, contrast, artifacts] verified_by: [test-or-evidence] package: astryxdesign/theme-name source_theme: packages/themes/name/src/nameTheme.ts references: [architecture:surface, design:contrast-methodology] ---其中review_triggers枚举了触发复审的维度令牌tokens、组件映射component-mappings、对比度contrast、产物artifacts。正文骨架由以下小节组成每节都有明确的归属边界Intent and audience— 该主题为谁而做、视觉意图是什么Inheritance and base— 继承自哪个基座Portable token overrides— 可移植令牌覆写Theme-local role definitions— 主题本地角色定义注释明确事实性的主题自有角色与证据记录于此公共主题 API 提案属于独立系统规范Tonal palette definitions— 色调调色板定义调色板生成或产物 API 属于独立系统规范Component and state mappings— 组件与状态映射Compatibility and migration— 兼容性与迁移Accessibility and contrast evidence— 无障碍与对比度证据必须链接当前跨主题设计记录本主题只拥有其应用不复制共享方法论Build and artifact contract— 构建与产物契约Verification map— 验证映射表主题契约 / 证据 / 代表性状态 / 失败信号四列Decision log— 决策日志Open questions— 未决问题Content boundary— 内容边界。实战范例Neutral 主题规范的完整落地Neutral 规范是当前仓库中唯一authority: current的主题记录其 neutral.spec.md 完整展示了模板每一个章节的实际填充方式。意图、继承与可移植令牌意图为需要“安静灰度基座”的构建者服务——克制的表面restrained surfaces 可区分的语义色与类别色在明暗两种色彩模式下保持产品中立product-neutral同时状态与交互仍可识别。继承从 Astryx Core 默认值出发覆写排版、动效、圆角、阴影、语义色、语法高亮、图标与组件值不扩展其他已发布包主题。对应源码见 packages/themes/neutral/src/neutralTheme.ts。可移植令牌Neutral 拥有自己的灰度画布 / 表面层级、近黑 / 近白内容角色、状态与类别选择、中性边界与语法选择跨主题的令牌词汇仍归architecture:theme-tokens见 docs/architecture/theme-tokens.md。主题本地角色从提案到批准的契约Neutral 规范的表 3 展示了“角色名 — 含义 — 建议值 — 状态”的登记格式Exact nameNeutral-only meaningProposed valueStatus--astryx-theme-neutral-color-status-fill-accentFilled accent status[#0074e2, #6d9cfe]Approved--astryx-theme-neutral-color-status-fill-successFilled success status[#198100, #64af4c]Proposed--astryx-theme-neutral-color-status-fill-warningFilled warning status#ffce2fProposed--astryx-theme-neutral-color-status-fill-errorFilled error status[#c9303a, #ff705d]Proposed--astryx-theme-neutral-color-on-tint-neutralNeutral content on a semantic tinted surface[#fafafa4D, #0a0a0a4D]Proposed--astryx-theme-neutral-color-on-tint-overlay-hoverHover overlay on a semantic tinted surface[#fafafa1A, #0a0a0a1A]Proposed--astryx-theme-neutral-color-on-tint-overlay-pressedPressed overlay on a semantic tinted surface[#fafafa33, #0a0a0a33]Proposed这些名称对应的正是localTokens机制——由spec:AST-006确立的主题家族本地令牌契约。规范给出的落地方案展示了“声明即消费”的完整链路localTokens: { --astryx-theme-neutral-color-status-fill-accent: [#0074e2, #6d9cfe], }, components: { badge: { variant:info: { backgroundColor: var(--astryx-theme-neutral-color-status-fill-accent), }, }, },localTokens键、组件var(...)引用、DefinedTheme映射与最终发射的 CSS 自定义属性使用完全相同的名字。建议值优先采用已批准的[light, dark]双值TokenValue元组——它与现有tokens下同名元组的归一化行为完全一致。Neutral 采用既有的name: neutral逐字节注册因其已是合法的小写 kebab-case 标识符无需名称归一化。源码佐证neutralTheme.ts 中的真实实现packages/themes/neutral/src/neutralTheme.ts 是上述契约的真实执行者neutralLocalTokens除了规范表中 7 个角色外还包含muted-accent与两个破坏性叠加层destructive overlay并通过withAlpha辅助函数在调色板 stop 上叠加透明度const neutralLocalTokens: Recordstring, TokenValue { --astryx-theme-neutral-color-status-fill-accent: [#0074e2, #6d9cfe], --astryx-theme-neutral-color-status-fill-success: [#198100, #64af4c], --astryx-theme-neutral-color-status-fill-warning: #ffce2f, --astryx-theme-neutral-color-status-fill-error: [#c9303a, #ff705d], --astryx-theme-neutral-color-status-muted-accent: [ blue.light[85], withAlpha(blue.dark[75], 3D), ], --astryx-theme-neutral-color-on-tint-neutral: [#fafafa4D, #0a0a0a4D], // ... };随后这些角色被映射到statusFill常量并接入 Badge、StatusDot、AvatarStatusDot、Stepper、ProgressBar 与 Banner 的组件映射中。规范特别强调一旦发布精确名称与其“填充强调状态”语义即成为 Neutral 家族公共兼容性契约——该角色不可移植到其他主题也不面向 Core 组件源码。调色板可复现的 OKLCH 生成结果与暗色渐变处理Neutral 调色板包含 10 个色族的完整明暗 rampneutral、red、orange、yellow、green、teal、cyan、blue、purple、pink。其可复现性来自“请求 生成模块 收据”三位一体请求packages/themes/neutral/palette.config.json 声明recipe: astryx-oklch-v1、vibrancy: 50、neutralProfile: neutral-v1、modeStrategy: light-and-dark以及 0–100 共 21 个 stop生成结果src/neutralPalettes.generated.ts经 neutralPalettes.ts 汇出为neutralPalettes收据src/neutralPalettes.generated.receipt.json精选 stop 引用src/neutralPaletteRefs.generated.ts 只包含neutralTheme.ts实际使用的 stop避免消费方为未用 stop 付费。palette.config.json中的darkChromaTaper正是规范 DEC-3 的技术依据darkChromaTaper: { edgeMultiplier: 0.5, throughStop: 25, recoverAtStop: 60, familyMultipliers: { yellow: 0.65 } }即暗色模式下彩色族通过 stop 25 将实际色度realized chroma降到 50%黄色族以 65% 系数保留身份到 stop 60 平滑恢复为标准配方明色 ramp、中性 ramp 与 stop 60–100 保持不变不使用透明度、不改色调坐标。重新生成是一次显式的、经评审的调色板变更绝不发生在普通主题构建过程中。组件与状态映射语义先行的“角色感知”映射规范列出的映射面包括 Badgeinfo/success/warning/error 10 个类别色变体、StatusDot、AvatarStatusDot、Stepper 指示器、ProgressBar以及 Banner 的 tint-content 与交互角色。映射原则DEC-4是角色感知而非盲目的“就近取色”很暗的前景色保持其更暗的角色普通背景不会自动变成纯黑有已批准匹配时语义 / 类别 / 语法 / 彩色效果值使用命名调色板 stop 引用alpha 变体从被引用 stop 派生而非复制 hex无匹配的意图性值保持为显式主题本地值。同时规范明确不新增组件状态并刻意排除table-row-status无已批准的 theming 目标与 SegmentedControl 的几何 / 阴影改动独立评审。neutralTheme.ts中对应实现还包含 Banner 的status:info/success/warning/error文本色映射、segmented-control的宽敞 inset、以及--shadow-inset-*系列聚焦 / 选中 / 状态内阴影。兼容性、对比度证据与验证映射兼容性现有 Neutral 作者侧配置与可移植令牌名保持稳定一旦 Neutral 显式提供localTokens其精确名称与含义即进入公共兼容契约。本地令牌名、注册主题名或语义含义的变更必须通过显式评审的迁移或别名来保护后裔与消费方。对比度当前尚无跨主题的对比度方法论记录因此 Neutral 规范不选择也不复述方法论而是将其列为未解决依赖。现有 Neutral 特有收据包括 Badge 对比度检查scripts/check-badge-contrast.test.mjs见 scripts与 Neutral 源码旁记录的配对。规范明确强调没有哪个调色板 stop 自身“可访问”颜色也不能替代组件契约要求的其他信号。验证映射规范以四列表Theme contract / Evidence / Representative states / Failure signal给出可执行的验收标准例如本地角色契约的失败信号是“名称或含义未经评审兼容处理即变更或泄漏进可移植 / Core API”。决策日志DEC-1 到 DEC-4 的治理脉络Neutral 规范的决策日志完整记录了每一项已结算输入DEC-1系统边界决策人cixzhang2026-08-31— Neutral 拥有主题本地定义可采纳--astryx-theme-neutral-color-status-fill-accent拒绝将其视为全局角色、一次性私有输出或仅因两个上下文当前共享颜色就套用。DEC-2rubyycheung2026-09-02— 批准精确调色板作为后续颜色 / 对比度决策的稳定锚点运行时令牌映射被刻意排除另行在 stacked change 中评审。Neutral 同时是仓库中“调色板感知主题模板”的参考实现。DEC-32026-09-04— 暗色渐变抑制50% 色度乘数到 stop 25stop 60 平滑恢复黄色 65%拒绝整体降低活力、使用半透明色或在该变更中改语义映射。DEC-42026-09-04— 通过已评审的调色板引用映射角色令牌名与含义不变alpha 变体从 stop 派生。未决问题以checkable标记的 OQ1渲染明暗证据完整性与 OQ2proposed 角色的跨组件语义稳定性保留在规范中直到评审通过。内容边界什么属于、什么不属于主题记录规范以“内容边界”收尾防止记录越权本记录拥有意图、事实值清单、已批准的本地令牌名与含义、建议值、所选映射、必备配对 / 状态、主题特有例外、测量收据、已知缺口、兼容性与包事实。而跨主题的本地令牌 / 调色板 API 属于spec:AST-006可观察的组件行为属于组件 / 家族记录消费方支持的语法与示例属于消费方文档。这一边界与 README 的分层职责完全一致。为新的主题包编写规范操作清单复制模板 docs/templates/knowledge/theme-spec.md 到packages/themes/theme/theme.spec.md将id设为theme:package-theme-name如theme:gothicpackage设为astryxdesign/theme-namesource_theme指向packages/themes/name/src/nameTheme.ts在references中声明架构 / 设计 / 系统依赖确保 current 记录只依赖 current 记录逐节填充意图、继承、令牌、调色板、映射、兼容性、证据、验证映射、决策日志与未决问题提交审批current 主题记录需要.github/ENGOWNERS与.github/DESIGNOWNERS提交并集的 exact-head 批准且记录不声明owners字段。遵循这套机制主题包的颜色、令牌与映射决策就有了与源码同构、可审计、可复现、可引用的知识契约——这正是 Astryx 以“规范驱动”管理多主题设计系统的方式。【免费下载链接】astryxAn open source design system thats fully customizable and agent ready项目地址: https://gitcode.com/GitHub_Trending/as/astryx创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考