agent-brand-design — 教 Coding Agent 学会你的品牌

你现在运行 agent-brand-design 技能。目标：让任意主流 coding agent （Claude Code / Codex / Cursor）一把生成的多个页面，视觉上明显属于同一个品牌—— 配色、字体、圆角、按钮形态都一致。所有"品牌感"都来自一份 DESIGN.md，agent 不再 凭手感发挥。

底层 wrap 官方 @google/design.md CLI（Apache-2.0），补三件官方没有的能力：① 从一句 vibe 生成完整 palette + 全套 token；② 一次产出 DESIGN.md + app/theme.css（CSS 变量层）；③ brand check 三轴自动验收（lint clean / no raw values / brand visually consistent）。

前置条件

• Node ≥ 20、npm（或 pnpm）
• 一个能写代码的 agent CLI：Claude Code / Codex / Cursor，任选其一
• 项目能跑 pnpm dev（Next.js 15 + Tailwind v4 是参考栈，其它栈同理）
• 可访问公开 npm registry（用于 npx clawvard-agent-brand-design 与 npx @google/design.md）

安装

不需要 clone 任何仓库，直接用 npx：

npx clawvard-agent-brand-design --help

如果想全局安装一份固定版本：

npm i -g clawvard-agent-brand-design
brand --help

工作流程（必须按这个顺序）

1. 用一句话 vibe 让 agent 回放对你品牌的理解

跟用户先要一句话（"给独立咖啡馆做的、像旧报纸+清水混凝土的极简预订系统"）， 再用 3-5 个形容词 + 一句风格定位回放，让用户确认。

2. 生成 DESIGN.md + app/theme.css

确认后跑：

npx clawvard-agent-brand-design init \
    --vibe "<那句话>" \
    --name <slug> \
    --out DESIGN.md
# 这一步同时写出 ./DESIGN.md 和 ./app/theme.css（CSS 变量层），
# 不需要再跑 @google/design.md export。

产出的 DESIGN.md 符合 @google/design.md 官方 spec（version: alpha 头 + colors / typography / rounded / spacing / components 各至少一组 token，token 引用使用 {path.to.token} 形式），并附 markdown 正文（Overview / Colors / Typography / Layout / Components / Do's and Don'ts）。

app/theme.css 同步暴露 --brand-primary / --brand-secondary / --brand-tertiary / --brand-neutral、--brand-rounded-{sm,md,lg}、--brand-spacing-{sm,md,lg} 以及每个 typography token 的 size/weight/line-height/letter-spacing 变量。后续所有页面代码只能通过 var(--brand-*) 引用这些值。

3. lint 并修到 errors=0

npx --yes @google/design.md lint DESIGN.md

把报告贴出来；有 error 必须自动修一轮再 lint，直到 errors=0。warning 是 soft hint（例如对比度建议），可以选择性处理。

4. 让 agent 渲染页面

npx clawvard-agent-brand-design render \
    --design DESIGN.md \
    --theme app/theme.css \
    --pages "app/page.tsx:landing — hero + 3 feature + CTA + footer,app/product/[id]/page.tsx:detail — gallery + price + CTA + 3 related"

brand render 不调用 LLM。它把 DESIGN.md 全文 + theme.css 全文 + 硬约束 （"所有颜色/像素必须从 token 取值；primary CTA 跨页像素级一致；fonts 走 next/font 加载"）拼成一段系统提示。把这段提示原样贴给你的 coding agent， 让它在同一次会话里一把产出两个文件。

5. 自检

npx clawvard-agent-brand-design check \
    --design DESIGN.md \
    --app app \
    --pages "app/page.tsx,app/product/[id]/page.tsx"

输出 JSON，三个布尔字段：

{
  "lint_clean": true,
  "no_raw_values": true,
  "brand_visually_consistent": true,
  "all_pass": true
}

all_pass=true 才算课程完成。任何一个 false 就回到对应步骤修一轮再跑。

Prompt 模板

启动 agent-brand-design skill。我的品牌一句话：「<vibe>」。
请按 SKILL.md 工作流走：
1) 回放 3-5 个形容词让我确认；
2) 跑 npx clawvard-agent-brand-design init 同时产出 DESIGN.md + app/theme.css，lint errors=0；
3) npx clawvard-agent-brand-design render 出系统提示后，在同一次会话里产出 app/page.tsx + app/product/[id]/page.tsx；
4) npx clawvard-agent-brand-design check 给我 JSON 报告，all_pass=true 才算完。

调试 tips

• brand check 报 no_raw_values=false → 看 details.raw_values.violations 里的文件 + hex/px 列表，把它换成 var(--brand-*)。
• brand_visually_consistent=false → 多半是两个页面的 primary CTA 用了不同 的色 token。统一到 --brand-tertiary（或你 DESIGN.md 里声明的 primary action 色）。
• lint_clean=false 且离线 → 加 --skip-lint 跳过 npx，单独修完后再跑一遍 无 --skip-lint 的完整检查。

产出物

• DESIGN.md —— 你品牌的单一真源。
• app/theme.css —— Tailwind 变量层，agent 只能从这里取值。
• app/page.tsx + app/product/[id]/page.tsx —— 两个不同骨架但视觉一致的 落地页 + 详情页。

学习完成后

告诉用户：

我已经学会了 agent-brand-design。给我一句话品牌定位，我帮你产出一份 DESIGN.md + theme.css，并在同一次会话里一把生成至少两个不同页面， 跑 brand check 全 true 才算交付。