brandmd

brandmd 是一款命令行工具，可将任何实时网站转换为机器可读的设计规范。它通过渲染页面并观察其实际样式，将结果写入 DESIGN.md。该格式由开放的 @google/design.md 规范定义：包含颜色、排版、圆角、间距和组件的类型化 Token 的 YAML frontmatter，随后是概览、颜色、排版、布局、海拔与深度、形状、组件以及注意事项等正文部分。生成的文件旨在通过官方 @google/design.md lint 命令的验证。 其开发动机在于，当 AI 编码代理缺乏项目的颜色、字体、间距和组件约定时，会生成通用且平庸的界面。在项目根目录下放置 DESIGN.md，可以让 Claude Code、Cursor、Gemini CLI、Codex 和 Google Stitch 等代理预先获得这些上下文。只需一次调用（例如对 URL 运行 npx brandmd 并写入 DESIGN.md）即可，无需手动编写规范。 提取过程在本地完成。该工具通过 Playwright 启动无头浏览器，滚动以触发延迟加载内容，关闭 Cookie 横幅和覆盖层，读取 :root 的 CSS 自定义属性（包括媒体查询），并收集可见元素的计算样式。随后，它会对相似颜色进行聚类，推导间距比例和基础网格单位，识别圆角和阴影样式，并识别按钮、卡片和输入框等组件模式。排版检测具有角色感知能力，优先级为：展示字体 > 标题字体 > 正文字体，同时跳过等宽字体、回退字体和图标字体。默认路径不涉及 LLM 调用或 API 密钥。 除了默认的 DESIGN.md，该工具还提供多种输出形式：用于脚本和工具链的原始 JSON tokens、CSS 自定义属性、Tailwind v4 @theme 块，以及包含色板、字体样本、间距可视化和阴影示例的独立 HTML 品牌指南。可以通过传递多个 URL 来合并跨页面的 Token，且频率按页面归一化，以防止按钮密集的文档页覆盖首页的权重。可选的 dark 标志可使用 prefers-color-scheme 提取深色主题 Token。可选的 vision 标志可使用 Gemini API 密钥，通过截图分析并添加插图风格、摄影氛围和文案语气提示。 agent 标志还会将 Cursor 规则和技能文件写入通用 .agents/skills 路径和 Claude Code 技能目录，从而无需手动配置即可获取品牌上下文。brandmd 本身也作为可安装的 Agent Skill 分发，且配套仓库为 Tailwind CSS、shadcn/ui、Vercel、Mintlify 和 Anthropic 提供了现成的品牌技能。 该工具采用“故障关闭”设计。拦截页、拒绝访问响应、登录墙以及证据不足的页面会导致所有格式均以退出代码 2 拒绝执行且不写入任何产出，以防止低质量捕获覆盖高质量的 DESIGN.md；override 标志可强制输出，但会在每种格式中标记该产出。写入操作是事务性的，使用临时文件和带回滚的重命名。退出代码可区分成功、操作或验证错误、拒绝以及由 check 子命令检测到的漂移。 check 子命令将部署的页面与已提交的 DESIGN.md 进行对比以检测设计漂移。它通过语义角色而非无序的十六进制值集来比较颜色，并在角色丢失、重绘或主次字体更改时使构建失败。文档坦诚地说明了其局限性：组件漂移会被报告但不会导致构建失败，次要字体更改可能会被忽略，且动态变化的页面可能会产生伪重大变更，因此在信任结果前应先复现。独立的 diff 子命令可比较两个 DESIGN.md 文件，并生成关于共享和唯一颜色、排版、间距、圆角及组件差异的 Markdown 报告，以及一份“复制指南”综合分析。仓库中包含来自 Stripe、Linear、GitHub、Vercel、Notion、Cursor、Anthropic、Figma、Supabase、Raycast 等公司的输出示例。该项目采用 MIT 许可证。