Design Systems

Design Systems Reference

Philosophy

This skill applies brand-faithful design tokens — not generic CSS. Every output should feel like the target brand's own design team built it:

• Token 级精度 — Colors are hex-exact, typography matches the brand's actual font stack and weight system, shadows reproduce the brand's elevation model exactly.
• Do's and Don'ts 是护栏 — Each DESIGN.md 的 Do/Don't 部分是红线。违反 = 不像目标品牌。没有例外。
• 交互式选择优先 — 50+ 个品牌不是一个静态列表。用浏览器交互预览让用户"看到"风格再决定，不是盲选。
• 混合时保持品牌灵魂 — Blend 多个设计系统时，每个系统的核心识别元素（字体、主色、阴影模式）至少保留一个。

Bundled Assets (USE THESE — do not reinvent)

The quality guarantee of this skill comes from using these assets. DESIGN.md 文件包含从真实网站提取的精确设计 token。不要凭记忆猜测品牌颜色——总是从文件读取。

The Workflow

Step 1: Understand the Project

Use AskUserQuestion to ask:

"告诉我你的项目是关于什么的——产品/项目名称，以及一句话描述你想要的视觉风格感觉。比如'给开发者用的命令行工具，想要极简科技感'或'面向设计师的作品展示，想要大胆有冲击力'。如果你已经知道要用哪个品牌风格，直接告诉我品牌名就行。"

Wait for the answer before proceeding.

If the user already specified a brand name (e.g., "用 Vercel 风格", "make it look like Stripe"): skip to Step 4 directly, using the Brand Name Alias Map below to resolve the directory name.

If the user gave a description but no brand: proceed to Step 2.

Step 2: Brand Selection Preview

Open the interactive 50+-brand browser preview. This is the primary flow — not a fallback.

_SKILL_DIR=$(ls -d ~/.agents/skills/design-systems 2>/dev/null || ls -d ~/.claude/skills/design-systems 2>/dev/null)
PYTHON=$(command -v python3 2>/dev/null || command -v python 2>/dev/null || echo "")
if [ -n "$PYTHON" ]; then
  "$PYTHON" "$_SKILL_DIR/assets/scripts/run_brand_preview.py" \
    --template "$_SKILL_DIR/assets/brand-preview-template.html" \
    --output   ./brand-preview.html \
    --port     17435 \
    --timeout  300 \
    "LANG=zh"
else
  CATALOG=$("$PYTHON" "$_SKILL_DIR/assets/scripts/brand-catalog.py")
  sed "s/__LANG__/zh/g; s/__RECEIVER_PORT__/17435/g; s/'__BRANDS_JSON__'/'$CATALOG'/g" \
    "$_SKILL_DIR/assets/brand-preview-template.html" > ./brand-preview.html
  open ./brand-preview.html 2>/dev/null || xdg-open ./brand-preview.html 2>/dev/null
  echo "Python not found — 无实时桥接。点击卡片后用复制按钮粘贴结果。"
fi

Tell the user: "我在浏览器里打开了 50+ 种品牌设计风格的预览卡片——从 Vercel 的极简黑白到 Spotify 的大胆暗色，从 Stripe 的金融科技到 SpaceX 的电影级纯黑。每张卡片都展示了真实的组件截图和配色方案。可以用顶部的类别筛选（AI & ML / Developer / Fintech 等），选好之后直接点卡片再点底部的「告诉 Agent →」按钮。如果不确定选什么，也可以告诉我你的项目类型，我帮你推荐。"

2a — 用户选择后

脚本打印 JSON（如 {"brand":"Stripe","dir":"stripe"}），或用户粘贴 JSON/品牌名。继续到 Step 4 读取该品牌的 DESIGN.md。

2b — "让 AI 来选" 选项

当用户说"你帮我选"、"不确定"、"推荐一个"、"你看着办"、"AI choose"时：

1. 根据用户在 Step 1 描述的项目类型、目标受众、行业，匹配最合适的品牌
2. 参考 Design System Categories 做行业匹配
3. 用 2-3 句话解释推荐理由
4. 确认："我为你推荐 [品牌]——[理由]。可以打开预览确认，或者直接继续？"
5. 如果用户确认，继续到 Step 3

AI 推荐决策矩阵：

Step 3: Brand Detail Preview (Optional)

用户想看某个品牌的完整组件目录时，打开其 preview.html：

open "$_SKILL_DIR/reference/{dir}/preview.html"

Tell the user: "已打开 {brand} 的完整组件目录——包含颜色、字体、按钮、卡片、输入框等所有设计 token 的可视化预览。你可以对照确认风格。"

如果项目需要暗色模式，打开 preview-dark.html：

open "$_SKILL_DIR/reference/{dir}/preview-dark.html"

Step 4: Read the DESIGN.md

Read: ~/.claude/skills/design-systems/reference/{directory}/DESIGN.md

Read the full DESIGN.md file to get the complete design specification including:

1. Visual Theme & Atmosphere — 情绪、密度、设计哲学
2. Color Palette & Roles — 语义颜色名 + hex + 功能角色
3. Typography Rules — 字体族、完整层级表
4. Component Stylings — 按钮、卡片、输入框、导航及状态
5. Layout Principles — 间距系统、网格、留白哲学
6. Depth & Elevation — 阴影系统、表面层级
7. Do's and Don'ts — 设计护栏和反模式
8. Responsive Behavior — 断点、触控目标、折叠策略
9. Agent Prompt Guide — 快速颜色参考、现成提示词

Step 5: Apply the Design System

When generating code based on a DESIGN.md:

1. 提取关键设计 token — 颜色 hex 值、字体栈、间距值、圆角值
2. 遵循 Do's and Don'ts — 这是最关键的护栏，违反 = 不像目标品牌
3. 使用 Agent Prompt Guide — 直接复制 Example Component Prompts 作为代码模板
4. 严格遵循字体规则 — 字体族 + 字重 + 字距是品牌识别的灵魂
5. 深度系统 — 阴影/边框处理方式决定了视觉品质感

Brand Name Alias Map

When the user mentions a brand name or design style, map it to the correct directory:

Design System Categories

AI & Machine Learning

claude, cohere, elevenlabs, minimax, mistral.ai, ollama, opencode.ai, replicate, runwayml, together.ai, voltagent, x.ai

Developer Tools & Platforms

cursor, expo, linear.app, lovable, mintlify, posthog, raycast, resend, sentry, supabase, superhuman, vercel, warp, zapier

Infrastructure & Cloud

clickhouse, composio, hashicorp, mongodb, sanity

Design & Productivity

airtable, cal, clay, figma, framer, intercom, miro, notion, pinterest, webflow

Fintech & Crypto

coinbase, kraken, revolut, wise

Enterprise & Consumer

airbnb, apple, bmw, ibm, nvidia, spacex, spotify, uber

Payments

stripe

Design Laws (Never Break These)

品牌忠诚度（核心 7 条）

1. 永远从 DESIGN.md 读取 token。 不要凭记忆猜测品牌颜色。每个品牌有精确的 hex 值、字体栈和阴影系统——它们是品牌识别的 DNA。
2. Do's and Don'ts 是红线。 每个 DESIGN.md 的第 7 节是设计护栏。违反 = 不像目标品牌。没有例外。
3. 字体是品牌灵魂。 字体族 + 字重 + 字距的组合定义了品牌的视觉声音。Inter Variable 在 weight 510 跟 400 完全是两个品牌。
4. 阴影系统决定品质感。 Vercel 的 shadow-as-border、Stripe 的蓝色多层阴影、Linear 的半透明边框——每个品牌的深度系统都有独特签名。
5. 不混合互斥的设计 DNA。 如果两个品牌的核心识别冲突（比如 Vercel 的极简白底 vs SpaceX 的纯黑电影级），blend 时只保留一个作为底色系统，另一个贡献点缀元素。
6. 不使用 placeholder 文案。 应用设计系统时生成的 UI 必须有真实内容——不是 Lorem ipsum，不是 "Your text here"。内容要匹配品牌的调性。
7. 暗色/亮色模式必须完整。 如果目标品牌有 dark mode 设计 token，应用时必须完整实现——不只是反转颜色，而是使用该品牌特定的暗色色板和对比度系统。

品质感护栏（视觉红线）

8. 禁止 emoji 充当 icon。 🚀⚙️🎯 不是设计元素。使用 SVG icon（推荐 Lucide、Phosphor、Heroicons）或品牌自有的图标库。emoji 的渲染跨平台不一致、视觉重量无法控制、与任何专业设计系统都格格不入。
9. 禁止纯黑 #000 和纯白 #fff。 自然界不存在纯黑纯白。品牌 DESIGN.md 里的背景色和文字色都已包含色相偏移（Vercel 的 #000000 除外——那是它的品牌决定）。如果 DESIGN.md 没有给出纯色值，永远用带微调的中性色。
10. 禁止 AI 泛用色板。 青色-on-暗底、紫蓝渐变、霓虹点缀——这是 AI 生成物的指纹。每个品牌的 DESIGN.md 都定义了精确的主色和辅色，照着用，不要"觉得好看"就自由发挥。
11. 禁止渐变文字当标题。 渐变文字是装饰不是信息。品牌标题的视觉冲击力来自字体选择、字重对比和负字距——不是 background-clip: text。
12. 禁止 glassmorphism 滥用。 毛玻璃效果（blur + 半透明背景）只在品牌 DESIGN.md 明确要求时使用。不是每个卡片都需要 backdrop-filter: blur()。大多数品牌用纯色表面 + 精确阴影系统来表达层级。

布局纪律（结构红线）

13. 禁止千篇一律的等大卡片网格。 同尺寸卡片 + icon + 标题 + 描述，无限重复 = AI 模板签名。用不对称布局、大小对比、交错排列打破节奏。
14. 禁止卡片嵌套卡片。 视觉层级应该扁平清晰——不是 Russian doll。如果信息需要嵌套容器，说明层级设计有问题。
15. 禁止居中一切。 左对齐文本 + 不对称布局 = 有设计感。全居中 = 模板感。品牌 DESIGN.md 的 Layout Principles 里定义了网格对齐方式，遵循它。
16. 禁止间距均匀化。 全篇同一个 padding 值 = 没有视觉节奏。用紧凑分组 + 大间距分离创造呼吸感。参考 DESIGN.md 的 spacing scale。

交互与动效（行为红线）

17. 禁止 bounce/elastic 缓动。 真实物体减速是平滑的，不是弹跳的。使用 ease-out-quart 或品牌 DESIGN.md 指定的缓动曲线。
18. 禁止动画布局属性。 width、height、padding、margin 的动画是性能杀手。只用 transform 和 opacity。
19. 禁止所有按钮都是 primary。 一个页面只有一个 primary CTA。其余用 ghost、secondary、text link。按钮层级 = 视觉优先级。
20. 禁止重复信息。 标题下面紧跟一段话重复标题内容 = 浪费像素。每个元素必须有新的信息增量。

Syncing from Upstream

上游仓库 VoltAgent/awesome-design-md 持续新增品牌。同步到本地：

_SKILL_DIR=$(ls -d ~/.claude/skills/design-systems 2>/dev/null || ls -d ~/.agents/skills/design-systems 2>/dev/null || echo ".")

# 预览变更（不修改文件）
python3 "$_SKILL_DIR/assets/scripts/sync_upstream.py" --dry-run

# 执行同步
python3 "$_SKILL_DIR/assets/scripts/sync_upstream.py"

# 同时更新已有品牌的文件（上游有更新时）
python3 "$_SKILL_DIR/assets/scripts/sync_upstream.py" --update-existing

# 查看当前同步状态
python3 "$_SKILL_DIR/assets/scripts/sync_upstream.py" --status

同步后：

1. 新品牌的 4 个文件（DESIGN.md / README.md / preview.html / preview-dark.html）已复制到 reference/
2. brands-config.json 已自动更新（分类、风格、别名）
3. brand-catalog.py 下次运行自动读取新数据，无需改代码
4. 需手动更新本文件的 Design System Categories 列表和 Brand Name Alias Map

Multi-System Blending

When the user wants to blend multiple design systems (e.g., "Vercel 的排版 + Stripe 的配色"):

1. Read both DESIGN.md files
2. 从第一个系统取排版和布局 token
3. 从第二个系统取颜色和组件 token
4. Never violate Do's and Don'ts from either system
5. Document the blend decision in code comments

Quick Reference: Common Patterns

Shadow-as-Border (Vercel Pattern)

border: none;
box-shadow: rgba(0, 0, 0, 0.08) 0px 0px 0px 1px;

Blue-Tinted Multi-Layer Shadow (Stripe Pattern)

box-shadow:
  rgba(50,50,93,0.25) 0px 30px 45px -30px,
  rgba(0,0,0,0.1) 0px 18px 36px -18px;

Semi-Transparent Dark Borders (Linear Pattern)

border: 1px solid rgba(255,255,255,0.08);
background: rgba(255,255,255,0.02);

Aggressive Negative Letter-Spacing (Vercel/Linear Pattern)

/* Display 48px */
letter-spacing: -2.4px;
/* Heading 32px */
letter-spacing: -1.28px;
/* Body 16px */
letter-spacing: normal;

Light-Weight Headlines (Stripe Pattern)

/* Weight 300 at display sizes — whisper authority */
font-weight: 300;