尧图网络 高端网站定制 · 原创设计
免费咨询热线
400-888-6620
免费获取方案
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),仅供参考
RELATED

相关推荐

3条命令在Docker容器里跑起Windows:dockur/windows完整指南 [特殊字符]

3条命令在Docker容器里跑起Windows:dockur/windows完整指南 [特殊字符]

3条命令在Docker容器里跑起Windows:dockur/windows完整指南 🐳 【免费下载链接】windows Windows inside a Docker container. 项目地址: https://gitcode.com/GitHub_Trending/wi/windows 想让 Windows 跑进 Docker 容器,却不想手动点安装向导、不想折腾虚拟…

📅 2026/9/11 8:07:02
标星60K的Java八股文PLUS版:从源码到面试的体系化知识库

标星60K的Java八股文PLUS版:从源码到面试的体系化知识库

说实话,第一眼看到这个标题,我第一反应是“又来一个卖课的营销号”。但点进去看了一眼仓库的目录结构、更新频率和 issue 区的讨论氛围之后,我承认这次确实有点东西。“Java 八股文 PLUS 版”,听起来像个噱头,实际上它…

📅 2026/9/12 10:39:58
Hard Disk Sentinel绿色便携版:硬盘健康监控与故障预警实战指南

Hard Disk Sentinel绿色便携版:硬盘健康监控与故障预警实战指南

主机里那块硬盘,往往是最沉默、也最容易在关键时刻掉链子的硬件。以前在项目里遇到过一块外表正常的 1TB 机械盘,突然在一天早晨被系统提示“有坏道”,随后开机越来越慢、文件频繁损坏,最后靠数据恢复软件才勉强救回大部分资料。从…

📅 2026/11/1 15:17:44
MORE NEWS

更多资讯

📰

咸宁高压电工证报名费多久拿证?怕考不过白交培训费?别急,看完这篇再决定

咸宁高压电工证报名费多久拿证?怕考不过白交培训费?别急,看完这篇再决定 怕考不过白交培训费?你不是一个人。很多刚毕业的工科生,像你一样,面对【咸宁高压电工证报名费】,既想抓住机会,又担心花冤枉钱。特别是你这种应届毕业生,一边在找工作,一边又…

📰

平凉安吉电工证培训机构复审延期怎么办理 郑州报考避坑指南

平凉安吉电工证培训机构复审延期怎么办理 郑州报考避坑指南 急需特种作业证才能上岗找工作,这个问题对新乡应届工程类毕业生来说尤其紧迫。刚毕业就面临就业压力,而特种作业操作证作为进入电力、建筑、制造等行业的重要门槛,直接影响求职机会和薪资水平。…

📰

珠海市电工证考试值不值得考?上岗找工作别踩坑

珠海市电工证考试值不值得考?上岗找工作别踩坑 你是不是正在找工作,但因为没有电工证被拒?别急, 珠海市电工证考试 就是你急需的“敲门砖”。别再犹豫 值不值得考 了,现在就带你搞懂一切,助你顺利上岗。 一、珠海市电工证考试值不值得考?…

📰

海南那里可以考电工证 一个真实经历告诉你外省证怎么转

海南那里可以考电工证 一个真实经历告诉你外省证怎么转 之前考的证在外省能不能转过来?这是不少在海南从业的电工朋友最关心的问题。今天我就从一个焦作培训机构学员的 真实经历…

📰

电工证是卡片还是纸?外省证书能转吗?南阳毕业生看过来

电工证是卡片还是纸?外省证书能转吗?南阳毕业生看过来 之前考的证在外省能不能转过来?这几乎是所有打算考证或者已经考过但不在本地的电工学员最关心的问题。特别是像南阳卧龙区的应届毕业生,很多人拿着外地考的电工证,却不知道在本地是否被认可,甚至担…

📰

低压电工作业算几级通过率揭秘 你在外省的证还能用吗

低压电工作业算几级通过率揭秘 你在外省的证还能用吗 之前考的证在外省能不能转过来?你是不是也遇到过这个问题?低压电工作业算几级?其实这事儿很多人不清楚,但如果你是焦作转岗的从业者,这个问题可不能忽视。下面我来告诉你,低压电工证到底算几级,还…

TODAY

今日更新

THIS WEEK

本周精选

THIS MONTH

本月热门

读完文章,想聊聊您的网站?

告诉我们您的行业与需求,资深顾问一对一梳理方案与报价,全程免费。

📞 💬