brandmd

brandmd

从网站中提取设计系统，并生成 DESIGN.md 文件，供 AI 编码 Agent 用于生成符合品牌风格的 UI。

适用场景

• 用户说“匹配这个网站的设计”或“使用 [url] 的相同风格”
• 开始一个新的前端项目，且用户已有现成的网站
• 用户希望 AI 生成的组件在设计上保持一致
• 用户要求从某个 URL“提取设计令牌”或“获取设计系统”

运行方式

npx brandmd <url> -o DESIGN.md

为获得最佳结果，请提供设计元素最丰富的页面（通常是首页）。工具会从该单页的可见视口和延迟加载的内容中提取信息。

提取内容

输出遵循 Google Stitch 的 DESIGN.md 格式。第 1–5 节始终包含；第 6–7 节则根据标志选项决定是否包含。

1. 视觉主题与氛围 - 情绪、形状语言、层次感
2. 调色板与角色 - 带语义角色的颜色（背景、文本、强调色、边框）
3. 排版规则 - 主字体（按角色优先级选择：展示 > 标题 > 正文，跳过等宽／回退／图标字体）、各角色字体细分（标题、展示、正文、按钮）、所有检测到的字体及其使用频次、字号比例、字重、行高、字间距
4. 组件样式 - 按钮、卡片、输入框的圆角、颜色、阴影
5. 布局原则 - 间距比例、基础网格单位、边框圆角
6. 深色主题覆盖项（使用 --dark）- 深色模式的调色板与氛围
7. CSS 之外的视觉识别（使用 --vision）- 插画风格、摄影氛围、文案语气、微文案模式。需要 GEMINI_API_KEY（免费层级：aistudio.google.com/apikey）。

提取完成后

1. 阅读生成的 DESIGN.md，确认内容看起来正确
2. 向用户总结关键令牌（主色、字体、间距比例）
3. 在后续所有 UI 代码生成中使用这些令牌
4. 编写 CSS/Tailwind/styled-components 时，引用 DESIGN.md 中的具体十六进制颜色代码、字体名称和间距值

选项

• npx brandmd <url> - 将 DESIGN.md 输出到标准输出
• npx brandmd <url> -o DESIGN.md - 将 DESIGN.md 写入文件
• npx brandmd <url> --dark - 同时提取深色模式调色板（第 6 节）
• npx brandmd <url> --vision - 通过 Gemini 同时提取插画／摄影／语气／微文案（第 7 节）。需要 GEMINI_API_KEY 环境变量。
• npx brandmd <url> --css - 输出 CSS 自定义属性，而不是 DESIGN.md
• npx brandmd <url> --tailwind - 输出 Tailwind v4 @theme 块，而不是 DESIGN.md
• npx brandmd <url> --html - 输出 HTML 品牌指南（可视化、可分享）
• npx brandmd <url> --json - 将原始令牌输出为 JSON（用于程序调用）
• 多个 URL 可合并令牌：npx brandmd <url1> <url2> <url3>

限制

• 只从单个页面提取，而非整个网站（多个 URL 会合并令牌频次，但视觉分析截图仅取自第一个页面）
• 无法读取 Figma 令牌或设计工具文件
• 颜色角色分配基于启发式规则（依据使用频次和亮度）
• 需要可公开访问的 URL（不支持需要身份验证的页面）
• 对于受 Cloudflare 保护的网站：brandmd 最多等待 20 秒，让 JS 挑战自动完成（可通过 --cf-wait-ms 调整等待时间）。如果挑战仍未完成，工具会明确报错，而不是返回无效令牌。对于被硬性拦截的网站（openai.com、perplexity.ai、discord.com 等），工具会正确标记为受机器人防护，不会尝试绕过。