DESIGN.md组件变体机制详解hover/active/pressed为何是独立条目【免费下载链接】design.mdA format specification for describing a visual identity to coding agents. DESIGN.md gives agents a persistent, structured understanding of a design system.项目地址: https://gitcode.com/GitHub_Trending/de/design.mdDESIGN.md 是一个面向 AI 编码代理的设计系统格式规范它用一份 Markdown 文件把品牌的视觉身份颜色、字体、组件样式结构化地描述清楚。本文将深入讲解 DESIGN.md 中**组件变体component variants**机制为什么hover、active、pressed这些状态要写成button-primary-hover、button-primary-active这样的独立条目而不是嵌套在按钮里。先认识一下组件令牌 DESIGN.md 文件分两层YAML frontmatter机器可读存放colors、typography、spacing、components等设计令牌Markdown 正文人类可读按固定顺序组织的设计说明其中components部分是一个组件名 → 属性集合的映射。完整规范见 docs/spec.md官方速查见 README.md。一个按钮的标准写法如下components: button-primary: backgroundColor: {colors.primary-60} textColor: {colors.primary-20} rounded: {rounded.md} padding: 12px注意值里的{colors.primary-60}是令牌引用——指向文件里已定义的颜色令牌。这是 DESIGN.md 的核心设计组件不写死色值而是引用基础令牌改一处全局生效。关键机制变体就是独立条目 规范原文docs/spec.md是这么定义的Variants. A component may have a variant for different UI states such as active, hover, pressed, etc. Those variant components may be defined under a different but related key, for example, button-primary, button-primary-hover, button-primary-active.也就是说hover状态不是一个字段而是一个全新的组件条目用关联的键名表示components: button-primary: backgroundColor: {colors.primary-60} textColor: {colors.primary-20} rounded: {rounded.md} padding: 12px button-primary-hover: # 独立条目 backgroundColor: {colors.primary-70}这个机制背后有 4 个刻意的设计取舍。为什么是独立条目而不是嵌套1. 扁平令牌结构每个条目都可被寻址DESIGN.md 的令牌体系借鉴了 W3C Design Token 规范整体是扁平的映射结构map 套 map。每个components下的条目都是一个独立的令牌组拥有自己的地址components.button-primary-hover。如果写成嵌套的states.hover就破坏了一层组件 一个令牌组的模型令牌引用语法{path.to.token}也就无法统一寻址了。扁平结构让每个变体都能被独立引用、导出和追踪。2. 只写变化项部分覆盖更简洁观察上面的例子button-primary-hover只写了backgroundColor一项。变体条目只需要声明与基础状态不同的属性——圆角、文字色、内边距不变就不用重复写。AI 代理会查看所有变体并做出合适的样式决策自动把基础条目和变体条目合并理解。这比在按钮里嵌一个完整的hover: { backgroundColor: ..., textColor: ..., rounded: ... }子块要简洁得多。3. 校验器可以逐项检查 ✅这是最实际的工程理由。DESIGN.md 配套的 CLI 内置 linter会对每个组件条目独立执行检查规则完整规则表见 packages/cli/src/linter/rules/规则对变体的意义contrast-ratio检查每个条目的backgroundColor/textColor对比度是否达到 WCAG AA4.5:1broken-ref检查变体里的{colors.xxx}引用是否存在orphaned-tokens发现定义了却从未被任何组件引用的颜色如果 hover 状态藏在按钮内部linter 就无法把它当作一个独立对象来报告问题。例如 README 中的示例报告{ severity: warning, path: components.button-primary, message: textColor (#ffffff) on backgroundColor (#1A1C1E) has contrast ratio 15.42:1 — passes WCAG AA. }注意path直接指向独立条目——变体天然就是这样的检查单元。4. diff 能精确定位哪个状态变了CLI 的diff命令可以对比两个版本的 DESIGN.md报告令牌级变化。独立条目让新增了一个 pressed 状态、hover 背景色被改深了这类变化都能被清晰捕获方便团队审查设计系统的演进命令用法见 README.md。看看真实的设计系统怎么写的 仓库的 examples/ 目录下有三个完整的 DESIGN.md 示例都展示了变体写法Atmospheric Glass玻璃拟态天气应用——按钮悬停时降低亮度列表项悬停时透出白色半透明层button-primary: backgroundColor: {colors.primary} textColor: {colors.on-primary} typography: {typography.label-sm} rounded: {rounded.xl} height: 48px padding: 0 24px button-primary-hover: backgroundColor: {colors.primary-fixed-dim} list-item-interactive-hover: backgroundColor: rgba(255, 255, 255, 0.1) 完整文件examples/atmospheric-glass/DESIGN.mdPaws Paths宠物遛弯服务——主按钮和次按钮各自带 hover 变体悬停时切换到对应的 container 颜色 完整文件examples/paws-and-paths/DESIGN.mdTotality Festival日食音乐节——除了按钮 hover连玻璃卡片也有交互变体button-secondary-hover: backgroundColor: rgba(0, 227, 253, 0.1) card-glass-level-2: backgroundColor: rgba(52, 52, 58, 0.2) rounded: {rounded.xl} padding: {spacing.gutter} card-glass-interactive-hover: backgroundColor: rgba(56, 57, 63, 0.4) 完整文件examples/totality-festival/DESIGN.md可以看到一个规律变体只描述状态切换时真正改变的属性通常是backgroundColor其余全部继承自基础条目的语境。编写组件变体的 3 步清单 ✍️先写基础条目button-primary里写全backgroundColor、textColor、rounded、padding等按状态加后缀button-primary-hover、button-primary-active、button-primary-pressed键名保持相关但不同的命名变体只写差异项哪变了写哪个不重复基础属性合法的组件属性只有 8 个backgroundColor、textColor、typography、rounded、padding、size、height、width见 README.md。属性名写错会触发unknown-key警告值引用不存在的令牌会触发broken-ref错误——写完跑一次lint就能验证入口说明见 README.md。写在最后hover/active/pressed 是独立条目这个看似简单的设计其实让 DESIGN.md 同时满足了三个需求AI 代理能按状态取用样式、linter 能按条目做质量检查、diff 能按令牌做变更追踪。扁平 部分覆盖的变体模型正是它作为给编码代理看的设计规范能够自动化的关键。 延伸阅读完整格式规范docs/spec.md设计哲学PHILOSOPHY.mdCLI 包源码packages/cli/src/【免费下载链接】design.mdA format specification for describing a visual identity to coding agents. DESIGN.md gives agents a persistent, structured understanding of a design system.项目地址: https://gitcode.com/GitHub_Trending/de/design.md创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 DESIGN.md组件变体机制详解：hover/active/pressed为何是独立条目
DESIGN.md组件变体机制详解hover/active/pressed为何是独立条目【免费下载链接】design.mdA format specification for describing a visual identity to coding agents. DESIGN.md gives agents a persistent, structured understanding of a design system.项目地址: https://gitcode.com/GitHub_Trending/de/design.mdDESIGN.md 是一个面向 AI 编码代理的设计系统格式规范它用一份 Markdown 文件把品牌的视觉身份颜色、字体、组件样式结构化地描述清楚。本文将深入讲解 DESIGN.md 中**组件变体component variants**机制为什么hover、active、pressed这些状态要写成button-primary-hover、button-primary-active这样的独立条目而不是嵌套在按钮里。先认识一下组件令牌 DESIGN.md 文件分两层YAML frontmatter机器可读存放colors、typography、spacing、components等设计令牌Markdown 正文人类可读按固定顺序组织的设计说明其中components部分是一个组件名 → 属性集合的映射。完整规范见 docs/spec.md官方速查见 README.md。一个按钮的标准写法如下components: button-primary: backgroundColor: {colors.primary-60} textColor: {colors.primary-20} rounded: {rounded.md} padding: 12px注意值里的{colors.primary-60}是令牌引用——指向文件里已定义的颜色令牌。这是 DESIGN.md 的核心设计组件不写死色值而是引用基础令牌改一处全局生效。关键机制变体就是独立条目 规范原文docs/spec.md是这么定义的Variants. A component may have a variant for different UI states such as active, hover, pressed, etc. Those variant components may be defined under a different but related key, for example, button-primary, button-primary-hover, button-primary-active.也就是说hover状态不是一个字段而是一个全新的组件条目用关联的键名表示components: button-primary: backgroundColor: {colors.primary-60} textColor: {colors.primary-20} rounded: {rounded.md} padding: 12px button-primary-hover: # 独立条目 backgroundColor: {colors.primary-70}这个机制背后有 4 个刻意的设计取舍。为什么是独立条目而不是嵌套1. 扁平令牌结构每个条目都可被寻址DESIGN.md 的令牌体系借鉴了 W3C Design Token 规范整体是扁平的映射结构map 套 map。每个components下的条目都是一个独立的令牌组拥有自己的地址components.button-primary-hover。如果写成嵌套的states.hover就破坏了一层组件 一个令牌组的模型令牌引用语法{path.to.token}也就无法统一寻址了。扁平结构让每个变体都能被独立引用、导出和追踪。2. 只写变化项部分覆盖更简洁观察上面的例子button-primary-hover只写了backgroundColor一项。变体条目只需要声明与基础状态不同的属性——圆角、文字色、内边距不变就不用重复写。AI 代理会查看所有变体并做出合适的样式决策自动把基础条目和变体条目合并理解。这比在按钮里嵌一个完整的hover: { backgroundColor: ..., textColor: ..., rounded: ... }子块要简洁得多。3. 校验器可以逐项检查 ✅这是最实际的工程理由。DESIGN.md 配套的 CLI 内置 linter会对每个组件条目独立执行检查规则完整规则表见 packages/cli/src/linter/rules/规则对变体的意义contrast-ratio检查每个条目的backgroundColor/textColor对比度是否达到 WCAG AA4.5:1broken-ref检查变体里的{colors.xxx}引用是否存在orphaned-tokens发现定义了却从未被任何组件引用的颜色如果 hover 状态藏在按钮内部linter 就无法把它当作一个独立对象来报告问题。例如 README 中的示例报告{ severity: warning, path: components.button-primary, message: textColor (#ffffff) on backgroundColor (#1A1C1E) has contrast ratio 15.42:1 — passes WCAG AA. }注意path直接指向独立条目——变体天然就是这样的检查单元。4. diff 能精确定位哪个状态变了CLI 的diff命令可以对比两个版本的 DESIGN.md报告令牌级变化。独立条目让新增了一个 pressed 状态、hover 背景色被改深了这类变化都能被清晰捕获方便团队审查设计系统的演进命令用法见 README.md。看看真实的设计系统怎么写的 仓库的 examples/ 目录下有三个完整的 DESIGN.md 示例都展示了变体写法Atmospheric Glass玻璃拟态天气应用——按钮悬停时降低亮度列表项悬停时透出白色半透明层button-primary: backgroundColor: {colors.primary} textColor: {colors.on-primary} typography: {typography.label-sm} rounded: {rounded.xl} height: 48px padding: 0 24px button-primary-hover: backgroundColor: {colors.primary-fixed-dim} list-item-interactive-hover: backgroundColor: rgba(255, 255, 255, 0.1) 完整文件examples/atmospheric-glass/DESIGN.mdPaws Paths宠物遛弯服务——主按钮和次按钮各自带 hover 变体悬停时切换到对应的 container 颜色 完整文件examples/paws-and-paths/DESIGN.mdTotality Festival日食音乐节——除了按钮 hover连玻璃卡片也有交互变体button-secondary-hover: backgroundColor: rgba(0, 227, 253, 0.1) card-glass-level-2: backgroundColor: rgba(52, 52, 58, 0.2) rounded: {rounded.xl} padding: {spacing.gutter} card-glass-interactive-hover: backgroundColor: rgba(56, 57, 63, 0.4) 完整文件examples/totality-festival/DESIGN.md可以看到一个规律变体只描述状态切换时真正改变的属性通常是backgroundColor其余全部继承自基础条目的语境。编写组件变体的 3 步清单 ✍️先写基础条目button-primary里写全backgroundColor、textColor、rounded、padding等按状态加后缀button-primary-hover、button-primary-active、button-primary-pressed键名保持相关但不同的命名变体只写差异项哪变了写哪个不重复基础属性合法的组件属性只有 8 个backgroundColor、textColor、typography、rounded、padding、size、height、width见 README.md。属性名写错会触发unknown-key警告值引用不存在的令牌会触发broken-ref错误——写完跑一次lint就能验证入口说明见 README.md。写在最后hover/active/pressed 是独立条目这个看似简单的设计其实让 DESIGN.md 同时满足了三个需求AI 代理能按状态取用样式、linter 能按条目做质量检查、diff 能按令牌做变更追踪。扁平 部分覆盖的变体模型正是它作为给编码代理看的设计规范能够自动化的关键。 延伸阅读完整格式规范docs/spec.md设计哲学PHILOSOPHY.mdCLI 包源码packages/cli/src/【免费下载链接】design.mdA format specification for describing a visual identity to coding agents. DESIGN.md gives agents a persistent, structured understanding of a design system.项目地址: https://gitcode.com/GitHub_Trending/de/design.md创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考