Back to Details

design-md-convention

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

DESIGN.md — Convention Design System AI-Friendly

DESIGN.md — 适配AI的设计系统约定

Convention inspirée de VoltAgent/awesome-design-md (55+ design systems populaires, concept Google Stitch).
Principe : un fichier 
DESIGN.md
en markdown à la racine du projet sert de source de vérité pour les agents IA qui génèrent ou modifient l'UI. Pas de Figma, pas de JSON complexe, juste du texte lisible par humain et par LLM.
本约定灵感来源于VoltAgent/awesome-design-md（涵盖50+热门设计系统，源自Google Stitch概念）。
核心原则：在项目根目录下创建一个
DESIGN.md
Markdown文件，作为AI Agent生成或修改UI时的唯一可信源。无需依赖Figma，无需复杂JSON，只需人类和LLM均可读取的文本。

Pourquoi DESIGN.md ?

为什么选择DESIGN.md？

Problème sans DESIGN.mdSolution avec DESIGN.md
IA génère des couleurs aléatoiresIA lit la palette définie
Incohérence spacing entre composantsIA applique l'échelle documentée
Typographie variableIA utilise les tokens définis
Onboarding designer/dev lentDESIGN.md = réponse unique
Dépendance à Figma pour chaque décisionMarkdown versionné avec le code
无DESIGN.md时的问题使用DESIGN.md后的解决方案
AI生成随机颜色AI读取已定义的调色板
组件间距不一致AI应用已记录的间距尺度
排版不统一AI使用已定义的令牌
设计师/开发人员上手慢DESIGN.md=统一参考文档
每项决策都依赖FigmaMarkdown随代码版本化管理

Structure recommandée

推荐结构

Un DESIGN.md contient 7 sections obligatoires :
  1. Principes visuels — ton, personnalité, do/don't
  2. Design tokens — couleurs, typographie, espacements, rayons, ombres
  3. Grille & layout — breakpoints, colonnes, gutters, container widths
  4. Composants — liste + variantes + règles d'usage
  5. Patterns d'interaction — hover, focus, active, disabled, loading
  6. Accessibilité — niveau cible (AA/AAA), contrastes, focus rings
  7. Références — lien vers Figma (optionnel), design system inspiré
Voir 
.claude/templates/DESIGN.md.template
pour la structure complète.
DESIGN.md需包含7个必填章节：
  1. 视觉原则 — 风格调性、品牌个性、可做/不可做规则
  2. 设计令牌（design tokens） — 颜色、排版、间距、圆角、阴影
  3. 网格与布局 — 断点、列数、gutter（间距槽）、容器宽度
  4. 组件 — 列表+变体+使用规则
  5. 交互模式 — 悬停、聚焦、激活、禁用、加载状态
  6. 无障碍访问 — 目标等级（AA/AAA）、对比度、聚焦环
  7. 参考资料 — Figma链接（可选）、参考的设计系统
完整结构可参考
.claude/templates/DESIGN.md.template
。

Règles de rédaction

撰写规则

1. Concis et structuré

1. 简洁结构化

  • Tableaux > prose
  • Tokens > valeurs hardcoded
  • Exemples concrets > théorie
  • 表格 > 长篇叙述
  • 令牌 > 硬编码值
  • 具体示例 > 理论描述

2. Tokens nommés, pas valeurs brutes

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 |
❌ 错误示例
主按钮：背景色 #3B82F6

✅ 正确示例
| 令牌 | 值 | 用途 |
|-------|--------|-------|
| `color.primary.500` | #3B82F6 | 主按钮、活跃链接 |
| `color.primary.600` | #2563EB | 主元素悬停状态 |

3. Do / Don't explicites

3. 明确可做/不可做规则

undefined
undefined

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
undefined
可做
  • 使用
    button.primary
    作为页面核心操作按钮（最多1个）
  • 使用
    button.secondary
    作为次要操作按钮
不可做
  • 同一页面禁止出现2个主按钮
  • 禁止使用调色板外的自定义颜色
undefined

4. Versionner avec le code

4. 随代码版本化管理

DESIGN.md
est dans le repo, reviewé en PR au même titre que le code.
DESIGN.md
需纳入代码仓库，与代码一同参与PR评审。

Intégration avec agents Claude Craft

与Claude Craft Agent集成

Les agents suivants lisent 
DESIGN.md
par défaut :
  • @ui-designer
     — génère UI conforme aux tokens
  • @ux-ergonome
     — valide les patterns d'interaction
  • @accessibility-expert
     — vérifie contrastes vs niveau cible
  • @{react,vue,angular}-reviewer
     — flag les valeurs hardcoded
以下Agent默认会读取
DESIGN.md
：
  • @ui-designer
     — 生成符合令牌规范的UI
  • @ux-ergonome
     — 验证交互模式合规性
  • @accessibility-expert
     — 对照目标等级检查对比度
  • @{react,vue,angular}-reviewer
     — 标记硬编码值问题

Workflow recommandé

推荐工作流

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
1. 新项目 → 将.claude/templates/DESIGN.md.template复制到根目录
2. 填写7个章节（30-60分钟）
3. 提交DESIGN.md到版本库
4. 在项目的@.claude/CLAUDE.md中引用："@DESIGN.md"
5. AI Agent会自动加载该文件
6. 设计系统每次迭代时更新DESIGN.md

Génération assistée

辅助生成功能

Command dédiée (Phase 4) : 
/uiux:generate-design-md
  • Analyse 
    tailwind.config.js
    ou tokens existants
  • Pré-remplit les sections
  • Demande validation sur les zones ambiguës
专属命令（第4阶段）：
/uiux:generate-design-md
  • 分析
    tailwind.config.js
    或现有令牌
  • 预填充章节内容
  • 对模糊内容请求确认

Exemples de DESIGN.md inspirants

参考示例

Anti-patterns

反模式避坑

Anti-patternSolution
DESIGN.md > 500 lignesExtraire sous-fichiers 
docs/design/*.md
Prose sans tableauxReformater en tokens structurés
Pas de do/don'tAjouter règles explicites
Screenshots uniquementCompléter par description textuelle (LLM ne voit pas toujours les images)
Désynchro avec codeAjouter check CI (lint tokens)
Date de dernière mise à jour : 2026-04-15 Version : 1.0.0
反模式解决方案
DESIGN.md超过500行拆分到子文件
docs/design/*.md
无表格的长篇叙述重构为结构化令牌
无明确的可做/不可做规则添加明确规则
仅包含截图补充文字描述（LLM并非总能识别图像）
与代码不同步添加CI检查（令牌校验）
最后更新日期： 2026-04-15 版本： 1.0.0