Communitygithub.com

设计系统

用于启动设计系统、样式指南或令牌集,添加或修改组件/令牌,标准化偏离的界面,或审计指南中松散的色彩、孤立的元素、缺失的状态以及不匹配的界面。

设计系统 是什么?

该技能定义了一套完整的创建、修改和审计设计系统的流程。它强调以分层方式构建:先建立基础层(如颜色角色、字阶、间距等),通过交互规则,然后逐个添加组件,每个阶段都需要暂停并获得批准。修改时,必须列出所有受影响的界面和代码位置,经批准后再进行传播。审计时,只生成报告,不擅自修复。技能包含明确的规则表、默认值、常见错误和量化的完成条件。它通过引用 `references/` 目录中的适配器(如 Paper、Figma、HTML)和清单(如令牌角色、组件解剖、审计检查表)来支持多种设计工具。该技能适用于 Claude Code、Cursor、Codex 等 AI 代理工具,通过结构化的 Markdown 文档指导代理逐步执行设计系统任务。

兼容平台~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/diego3g/design-skills/tree/HEAD/skills/design-system

在你喜欢的 AI 中提问

打开一个已预加载此 Agent Skill 的新对话。

文档

设计系统 是做什么的?

概述

设计系统是一个决策只做一次,然后处处复用的地方。每一种颜色都是一个令牌,每一个交互元素都显示其所有状态,每一个变更都会影响到使用该元素的所有界面。分层构建,基础先行,每一层都需要暂停并等待批准。审计只报告,从不自行修复。

何时使用

  • “为……启动一个样式指南/设计系统/令牌”
  • 添加组件、变体或令牌,或修改现有组件/令牌
  • “使这些界面保持一致”、“标准化”、“审计指南”,或者界面中存在松散的十六进制值和孤立的元素

何时不使用

  • 关于某个值的问题(“我们的主色是什么?”):直接回答。
  • 对方已精确描述的小修改(一个值、一个标签、一个尺寸),即使是对共享元素的修改:在其定义处一次性修改,并说明受影响的界面。不需要状态矩阵,不需要暂停。

开始之前

  1. 阅读项目根目录下的 DESIGN.md(如果存在):它是项目的设计概要。
  2. 查找现有内容:令牌、指南、组件、界面和代码。现有指南在视觉外观上具有最高优先级。 即使其规则与下面的默认值不同,也应遵循其规则,并提及差异一次。
  3. 在 references/adapters/ 中为您的工具选择适配器(paper.md、figma.md、html.md)。如果没有适配器匹配您的工具,请在您的工具中执行相同的操作,并说明哪些是手动映射的。如果没有设计工具,则使用 HTML 构建(html.md)。如果只有一张图片,请说明从中读取的值是估算值。
  4. 确定模式:创建、添加或修改或审计。

步骤 · 创建

  1. 基础草案:

    • 颜色角色(令牌角色);
    • 字阶;
    • 间距;
    • 圆角;
    • 阴影(最多两个);
    • 布局宽度;
    • 运动时长;
    • 一个简短的“我们如何书写”部分。

    按角色命名令牌(text-muted、border-hover、danger-bg),绝不能仅按值命名(gray-500)。

  2. 交互规则(一次): 对于有边框元素、无边框元素和主要操作,编写悬停、按下、聚焦(仅键盘)、禁用、加载和选中的外观。组件遵循这些规则,而不是各自发明。

  3. 暂停并向对方展示基础草案和交互规则。 先不要构建组件。

  4. 逐个添加组件,按照第一批界面需要的顺序。 每个组件在指南中都有一个部分,包含组件解剖结构:带有规则及其原因的图例、示例,以及一个变体 × 状态的状态矩阵。将每个组件添加到组件索引中。

步骤 · 添加或修改某个元素

  1. 检查现有组件加上某个变体是否能覆盖需求。优先重用,而不是创建孤立的元素。
  2. 使用组件解剖结构绘制它,包括完整的状态矩阵。新的颜色、尺寸或图标需要立即成为令牌或图标集条目,而不是以后。
  3. 列出所有使用该元素的界面和代码位置。
  4. 暂停并向对方展示变更内容和该列表。
  5. 获得批准后,进行传播:
    • 更新列表上的每个界面;
    • 更新代码(如果有);
    • 更新组件索引;
    • 报告哪些内容在何处发生了变更。

步骤 · 审计

  1. 对指南、界面和代码(如果有)执行审计检查表。
  2. 编写报告:按严重性排序的发现,每个发现包含出现位置、重要性和建议的修复方案。
  3. 暂停并向对方展示报告。在对方指定要修复哪些内容之前,不要更改任何文件。 保存原始文件的副本并不能使编辑它们变得可接受。

规则

硬性规则(任何项目):

规则原因
每种颜色都是一个令牌;界面或代码中不能有松散的十六进制值松散的值会变成几乎相同的副本,导致无法一次性更改
仅使用一套图标集混用图标集看起来像混搭的产品
设计和代码同步变更,设计先行否则指南在一周内就会失去权威性
每个交互元素都有一个状态矩阵临时绘制的状态在界面上永远不会一致
对共享元素的变更,在传播前需列出受影响的界面否则一个“小”变更会悄无声息地重绘二十个界面

默认值(现有指南会覆盖它们):

默认值原因
悬停时,有边框元素仅加深边框颜色卡片和字段的背景变化显得沉重
悬停效果应弱于选中效果当悬停看起来像选中时,人们会认为选择了两个东西
选中状态绝不改变字体重量重量变化会改变文本宽度
占位符应比弱化文本更浅否则占位符看起来像已输入的文本
堆叠列表和菜单中的项目之间有微小间距,切勿紧贴紧贴的高亮会合并成一个块
焦点环仅在键盘操作时出现鼠标点击后出现焦点环看起来像 Bug
加载状态保持元素的确切尺寸避免布局偏移
阴影仅用于浮动元素(菜单、弹出框、对话框、提示),强度分为两级到处都是阴影会破坏它们本应创建的层次结构
每个界面最多一个主要操作两个主要操作意味着界面没有做出决定

完成条件

  • 创建: 基础草案和交互规则已获批准;每个组件都有其解剖结构、状态矩阵和索引条目。
  • 修改: 列出的每个界面和代码位置都已更新,并且索引已更新。
  • 审计: 已提交按严重性排序的报告,且未更改任何文件。

常见错误

想法现实
“我会一次性构建整个指南:令牌和十个组件”在未经批准的基础上构建十个组件意味着十次返工。先构建基础、暂停、再构建组件。
“审计发现了问题,我就直接修复它们”对方可能不同意一半的修复方案。先报告、暂停,只修复他们选择的。
“我把原始文件保存在备份文件夹里,所以修复是安全的”备份并不能使对方同意修复方案。先报告。
“按钮有悬停和禁用状态,足够了”状态矩阵包含每种状态 × 每种变体:正常、悬停、按下、聚焦、禁用、加载、选中。
“--teal-600 是一个令牌”这是一个值。组件需要角色(--color-primary),以便值可以在一个地方更改。
“这个界面需要一个稍微不同的卡片”将其设为卡片的变体,或使用卡片。孤立元素是漂移的开始。

相关技能