mcpField
D
design-md-convention

design-md-convention

github.com/thebeardedbearsas设计与 UI107115 次安装今天更新
代码仓库

关于 design-md-convention

design-md-convention 提倡在项目根目录用可版本管理的 DESIGN.md 记录设计系统。它为 AI Agent 和项目团队提供易读的参考，涵盖视觉令牌、组件、交互模式与无障碍规则。

主要功能

  1. 01建议包含七个文档章节
  2. 02结构化设计令牌与使用规则
  3. 03明确列出应做与避免事项
  4. 04与代码一同维护版本化 Markdown
  5. 05提供 Claude Craft Agent 集成说明

适用场景

  1. 01为 Agent 提供一致的 UI 生成依据
  2. 02将设计决策与源代码一同记录
  3. 03使组件符合无障碍和交互规则

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/thebeardedbearsas/claude-craft --skill design-md-convention

安装后在 Claude Code 中输入/design-md-convention确认已加载。

详细介绍

DESIGN.md — 适合 AI 的设计系统规范

灵感来自 VoltAgent/awesome-design-md（55+ 个热门设计系统，Google Stitch 概念）。

原则： 在项目根目录放置一个 Markdown 格式的 DESIGN.md，作为生成或修改 UI 的 AI Agent 的唯一事实来源。不需要 Figma，也不需要复杂的 JSON，只需人类和大模型都能读懂的文本。

为什么需要 DESIGN.md？

没有 DESIGN.md 时的问题使用 DESIGN.md 后的解决方案
AI 随机生成颜色AI 读取定义好的调色板
组件间的间距不一致AI 应用文档化的间距比例
排版不一致AI 使用定义好的令牌
设计师/开发者上手缓慢DESIGN.md = 唯一答案
每项决策都依赖 Figma与代码一同进行版本控制的 Markdown

推荐结构

一个 DESIGN.md 包含7 个必需部分：

  1. 视觉原则 — 基调、个性、应做/不应做
  2. 设计令牌 — 颜色、排版、间距、圆角、阴影
  3. 网格与布局 — 断点、列、槽宽、容器宽度
  4. 组件 — 列表 + 变体 + 使用规则
  5. 交互模式 — hover、focus、active、disabled、loading
  6. 无障碍 — 目标级别（AA/AAA）、对比度、焦点环
  7. 参考资料 — Figma 链接（可选）、灵感来源的设计系统

完整结构见 .claude/templates/DESIGN.md.template。

编写规则

1. 简洁且结构清晰
  • 表格优于散文
  • 令牌优于硬编码值
  • 具体示例优于理论
2. 使用命名令牌，而非原始值
❌ MAUVAIS
Primary button: background #3B82F6

✅ BON
| Token | Valeur | Usage |
|-------|--------|-------|
| `color.primary.500` | #3B82F6 | Boutons primaires, liens actifs |
| `color.primary.600` | #2563EB | Hover des éléments primaires |
3. 明确列出应做/不应做
### Boutons

**DO**
- Utiliser `button.primary` pour l'action principale d'un écran (1 max)
- Utiliser `button.secondary` pour actions secondaires

**DON'T**
- Jamais 2 boutons primaires sur le même écran
- Jamais de couleur custom hors palette
4. 与代码一同进行版本控制

DESIGN.md 位于代码仓库中，与代码一样在 PR 中进行审查。

与 Claude Craft Agent 集成

以下 Agent 默认会读取 DESIGN.md：

  • @ui-designer — 生成符合令牌规范的 UI
  • @ux-ergonome — 验证交互模式
  • @accessibility-expert — 检查对比度是否符合目标级别
  • @{react,vue,angular}-reviewer — 标记硬编码值

推荐工作流

1. Nouveau projet → copier .claude/templates/DESIGN.md.template à la racine
2. Remplir les 7 sections (30-60 min)
3. Commiter DESIGN.md
4. Référencer depuis @.claude/CLAUDE.md projet : "@DESIGN.md"
5. Les agents IA le chargent automatiquement
6. Mettre à jour à chaque évolution du design system

辅助生成

专用命令（Phase 4）：/uiux:generate-design-md

  • 分析 tailwind.config.js 或现有令牌
  • 预先填充各部分
  • 对有歧义的部分请求确认

值得借鉴的 DESIGN.md 示例

反模式

反模式解决方案
DESIGN.md 超过 500 行拆分为子文件 docs/design/*.md
只有散文，没有表格重新整理为结构化令牌
没有应做/不应做规范添加明确规则
只有截图补充文字描述（大模型不一定总能看到图片）
与代码不同步添加 CI 检查（令牌 lint）

最后更新时间： 2026-04-15 版本： 1.0.0

评论

支持 Markdown