需要从线上网站逆向提取真实设计 tokens…

当你面对一个现成网站，想拿到其真实 DOM 计算样式、W3C DTCG tokens、品牌色/字体/间距/组件状态，并据此生成 Tailwind、shadcn、DESIGN.md 或 CI 漂移门禁时使用。

适用场景

解决思路

1. 零安装运行：npx -y dembrandt https://dembrandt.com，首次运行由 npx 拉取包，摩擦最低。
2. 或全局安装一次：npm i -g dembrandt，然后直接调用 dembrandt。
3. 基础提取输出到终端：dembrandt https://dembrandt.com。
4. JSON 输出并重定向到文件或管道给其他工具：dembrandt https://dembrandt.com --json-only > dembrandt-tokens.json。
5. W3C DTCG 格式并保存：dembrandt https://dembrandt.com --dtcg --save-output。
6. 生成 DESIGN.md：dembrandt https://dembrandt.com --design-md。
7. 多页爬取并合并 tokens：dembrandt https://dembrandt.com --crawl 5。
8. 提取暗色模式颜色：dembrandt https://dembrandt.com --dark-mode。
9. 移动视口提取：dembrandt https://dembrandt.com --mobile。
10. 全部保存到 output/：dembrandt https://dembrandt.com --save-output。
11. 生成 Tailwind v4 @theme CSS，仅观测值：dembrandt https://dembrandt.com --tailwind src/app.css（0.28+）。
12. 生成自包含 HTML 报告，可离线打开或作为 CI artifact：dembrandt https://dembrandt.com --html report.html（0.19+）。
13. 用作漂移门禁，对比保存的 baseline，漂移时 exit 1：dembrandt https://app.example.com --compare baseline.json --html report.html（0.19+）。
14. MCP 配置：把 Dembrandt 暴露为 MCP tools，无需安装，npx 首次运行拉取：{ "mcpServers": { "dembrandt": { "command": "npx", "args": ["-y", "--package", "dembrandt", "dembrandt-mcp"] } } }。
15. MCP 提取工具默认异步：调用 get_design_tokens({ url: "dembrandt.com", pages: 5 }) 会立即返回 job_id 和 status queued。
16. 轮询 get_job_status({ job_id: "job_123_abc" }) 直到 status 为 completed，再取 result。
17. 调用 get_findings({ job_id: "job_123_abc" }) 获取 findings 和 contrast，无需重新发送提取结果。
18. 把 job_id 交给分析工具，而不是把提取结果传回模型；队列会保留整个提取一小时，因此窄工具如 get_color_palette 启动的 job 仍可喂给 export_dtcg；同时传 job_id 和内联提取时内联提取优先，但真实提取太大不适合作为工具参数传输。
19. 对任意提取工具传 sync: true 可阻塞并直接返回结果；适合快速网络，慢站点有超时风险，pages 大于 1 时会按比例更慢。
20. 使用提取工具：get_design_tokens 提取一切，get_color_palette、get_typography、get_component_styles、get_surfaces、get_spacing、get_brand_identity、get_motion 提取 durations、easings、named keyframes、hover patterns 及随附渐变（0.36+）；所有工具接受 slow、mobile、cookie，get_design_tokens 和 get_color_palette 还接受 darkMode、wcag（0.23.1+ 支持 mobile/cookie/wcag）。
21. 每个提取工具都会爬取，这是提升 token 质量的最大杠杆：一页只能得到一页的 tokens。
22. 使用 pages：提取最多 N 页并合并为一个 token set，范围 1 到 20；页面来自 DOM 链接，sitemap 为 true 时来自 sitemap.xml。
23. 使用 paths：显式命名额外路径，例如 /pricing、/docs；会覆盖 discovery。
24. 使用 sitemap：从 sitemap.xml 发现页面；单独使用最多 20 页，pages 可封顶。
25. 使用 header：添加一个额外 HTTP header，例如 Authorization: Bearer ...，用于 cookie 到达不了的页面。
26. 使用 userAgent：自定义 user agent 字符串。
27. 使用 noSandbox：禁用浏览器 sandbox；在 Docker 和大多数 CI 容器中必须使用，否则 launch 会失败。
28. 某页加载失败会被丢弃，合并继续处理其余页面，因此爬取不会因单个坏 URL 失败。
29. 纯工具不启动浏览器、同步执行；提取结果放在 result，或用 job_id 指定已完成 job：compute_drift 计算两个提取之间 0-100 漂移分，支持 baselineJobId 和 candidateJobId；get_findings 做设计系统 lint，检查 contrast、consistency、duplication；export_dtcg 导出 W3C Design Tokens；generate_design_md 生成 DESIGN.md 品牌指南；render_report 渲染自包含 HTML 报告；export_tailwind 导出 Tailwind v4 @theme block；export_shadcn 导出 shadcn/ui theme，页面未提供的 slot 保留 shadcn 默认值；job 控制工具为 get_job_status、list_jobs、cancel_job（0.23.1+ 支持 get_findings/export_dtcg/generate_design_md/list_jobs，0.36+ 支持两个 emitter）。
30. 三个工具接收自己的输入而不是提取结果（0.36+）：validate_dtcg 按 2025.10 spec 检查 DTCG 文档，包括本 server 生成的文档，防止手工编辑悄悄破坏；check_contrast 按 WCAG 2.1 和你指定的阈值给颜色对打分，用于即将上线而非已在页面上的颜色；check_robots 在花费浏览器运行前询问 robots.txt 是否允许某 URL。
31. 注意 npx 会优先运行 PATH 上的 dembrandt-mcp，而不是 --package 指定的版本，因此全局安装的 dembrandt 会静默遮蔽 pinned 版本；症状是 pinned 版本支持的选项被当作未知选项拒绝，或 crawl 只返回单页；用 dembrandt --version 检查并升级全局安装，或把 MCP 配置指向显式路径。
32. 注意 dembrandt <=0.23.0 通过上述 npx 一行命令启动 MCP 会失败并报 McpDepsMissingError，因为 MCP SDK 曾是 optional peer dependency；0.23.1 修复，需要求该版本以上。
33. 读取 colors.palette：去重颜色及 confidence high/medium/low；每项携带 hex normalized、同一颜色的 lch 和 oklch、派生的 role、onColor、hover；使用 --wcag 时还携带 contrastAgainst，即页面上实际观测到的颜色对，按另一颜色去重并按 ratio 排序（0.31+）。
34. 读取 colors.detected：所有通过 alpha gate 的颜色，无频率阈值、无感知合并，因此六个接近的红色会保留六个条目；usageFrac 统计元素数量；areaFrac 是绘制背景面积占比，能把 hero 填充排在许多小字形之前，而仅靠计数做不到（0.32+）；建设计系统用 palette，需要 recall 用 detected。
35. 读取 colors.semantic：检测 primary、secondary、background、text、accent。
36. 读取 colors.cssVariables：命名 CSS custom properties；value 是作者字符串原文，是作者 notation 的唯一记录，同时带 computed hex、LCH、OKLCH。
37. 读取 typography.styles：按上下文列出 font family、size、weight、line-height；每项携带 count，即渲染该精确样式的元素数；code、pre、kbd、samp 会落到 mono context，因此只用于代码块的 mono 字体可见（0.32+）；isFluid 从作者声明读取，因此可检测 clamp() 或 viewport-relative ramp（0.32+）。
38. 读取 typography.sources：Google Fonts、Adobe Fonts、variable font 检测；urls 列出解析后的字体资源和 webfont stylesheet URL，去重，便于重新获取或验证真实文件；filteredFamilies 列出被 usage floor 丢弃的字体族，判断字体缺失前先检查它。
39. 读取 spacing.commonValues：margin/padding scale 及 rem 等价值。
40. 读取 spacing.scaleType：4px、8px 或 custom grid；0.34.0 起判定加权，除非 60% 的 spacing 落在步进上，否则报告 custom，过去声称有 grid 的站点现在会真实报告 custom。
41. 读取 borderRadius.values：带元素上下文的 border radius tokens。
42. 读取 borders.combinations：width、style、color 的组合。
43. 读取 shadows：box shadow elevation system；每个 shadow 一个字符串，多层按 CSS 写法逗号分隔；--dtcg 导出会拆成结构化 layer（0.32+）。
44. 读取 components.buttons：button variants 及 hover/active/focus 状态。
45. 读取 components.inputs：input 样式及 focus 状态。
46. 读取 components.links：link 颜色及 hover 状态。
47. 读取 components.badges：badge/tag/chip variants。
48. 读取 breakpoints：来自 CSS media queries 的响应式断点。
49. 读取 frameworks：检测到的 CSS framework，如 Tailwind、shadcn、MUI 等。
50. 读取 iconSystem：检测到的 icon library，如 Heroicons、FA、Material 等。
51. 读取 pages：仅在合并多页结果时出现，即 --crawl、--sitemap、额外 paths 或 MCP pages；每页一个条目，可看出合并 tokens 来自哪些 URL；palette 条目此时还携带 pageCount。
52. 读取 wcag：使用 --wcag 时，返回真实渲染颜色之间的观测对比对，包括 fg、bg、ratio、aa/aaLarge/aaa 布尔值。
53. 读取 meta.crawl：使用 --crawl、--sitemap 或显式 paths 时出现，包含 technique、pagesRequested、pagesFound（0.31+）。
54. 读取 meta.robotsWarnings：robots.txt 禁止的页面，包括入口 URL 或 crawl 中发现的页面；默认仅提示、不阻止提取，这是唯一记录被标记内容的字段（0.31+）；设置 DEMBRANDT_ENFORCE_ROBOTS=1 后，disallow 或无法读取 robots.txt 会跳过目标并以 exit 4 退出；站点没有 robots.txt 即 404/410 不算拒绝，仍会运行（0.32+）。
55. 播种 Tailwind theme 时不要手工映射 JSON；使用 --tailwind 直接写 Tailwind v4 @theme block：dembrandt https://dembrandt.com --tailwind 输出到 output/<domain>/theme.css，或 dembrandt https://dembrandt.com --tailwind src/app.css 直接写入项目（0.28+）。
56. Tailwind 输出仅包含观测值：没有 50-950 shade ramps，没有插值 scale steps，没有派生 hover 或 on-colour variants；一旦写入文件，编造的 shade 和测量的 shade 无法区分，所以导出只是起点，之后手工扩展。
57. Tailwind 输出中颜色保留语义角色名如 --color-primary，或页面声明的 custom property 名；其余编号为 --color-brand-N；当页面有 base-N 节奏时 spacing 折叠为 v4 的 --spacing multiplier，否则回退为命名步骤；Tailwind 默认值仍适用于未列出的内容，因此该 block 是扩展 theme 而不是替换。
58. 仅支持 Tailwind v4；对于 v3 tailwind.config.js，手工映射：colors.semantic 到 theme.colors，typography.styles 到 fontFamily，spacing.commonValues 到 spacing，borderRadius.values 到 borderRadius，shadows 到 boxShadow。
59. 播种 shadcn/ui theme 时使用 --shadcn（0.34.0+）写 theme，不要手工映射变量：dembrandt stripe.com --shadcn 输出到 output/<domain>/shadcn.css。
60. 该 shadcn 文件包含 :root block 和 Tailwind v4 所需的 @theme inline mapping，使用 oklch；只有页面提供值时才写 slot，其余在文件头中列出并留给 shadcn 自身默认值，因此未观测 slot 不会作为看似测量过的合理值出现；--dark-mode 产生 .dark block，每次运行一种颜色方案。
61. 不要从 borderRadius.values[0] 推导 --radius：该列表按长度排序，第一项是页面上最小 radius，不是按钮和输入使用的 radius；该 flag 取最常使用的值。
62. 按 confidence 读取颜色：high 表示出现在语义标注元素上，如 buttons、CTAs、带品牌 class 的 headers，几乎肯定是品牌色；medium 表示中等频率或中等上下文，很可能是品牌色；low 表示罕见、低语义上下文，可能是一次性或组件特定颜色。
63. 0.28.0 起 confidence 还有 usage floor，和 spacing、radii 一样：颜色出现一次最高为 low，两次为 medium，high 需要三次出现，无论语义上下文得分如何；hover 和 focus 颜色例外并保持 medium，因为单次出现是 provenance 而非 usage claim。
64. 构建 palette 时从 high confidence 颜色开始；为完整覆盖可包含 medium；low 仅作参考。
65. 颜色 notation：绝不要手工转换颜色，也绝不要用自己的数学重新推导；每个 palette entry 和 CSS variable 已经同时携带 hex、lch、oklch，直接从 JSON 读取所需字段；--color-format 只改变终端打印，消费 JSON 或 MCP 输出时用它是错误工具。
66. 用 hex normalized 作为颜色身份：dedup、drift comparison 和所有下游工具都以它为 key；两个条目 hex 相同就是同一 token，即使输出 notation 不同；当作者用现代 notation 声明 token 时，cssVariables[name].value 精确保留它，把 CSS 写回该代码库时使用它，可保留作者自己的 notation 并留在其 gamut 内。
67. 使用 --json-only：干净 JSON 到 stdout，可管道到文件或工具。
68. 使用 --save-output：保存 JSON 到 output/<domain>/<timestamp>.json。
69. 使用 --dtcg：W3C Design Tokens Community Group 格式；shadow token 有多层时 $value 是数组，消费者读 $value.offsetX 必须用 Array.isArray 分支（0.32+）。
70. 使用 --design-md：生成 DESIGN.md，既是人类可读也是 AI 可读的品牌文档。
71. 使用 --html [path]：自包含 HTML 报告，内联 CSS、嵌入 JSON，可离线打开或作为 CI artifact 附加（0.19+）。
72. 使用 --compare <baseline.json>：与保存的提取 diff，打印 drift verdict，漂移时 exit 1，用作 CI gate（0.19+）。
73. 使用 --brand-guide：生成 PDF 品牌指南。
74. 使用 --dark-mode：提取暗色 color scheme 并合并到 palette。
75. 使用 --mobile：在 390px 移动视口提取。
76. 使用 --crawl <n>：爬最多 N 页并合并 tokens。
77. 使用 --sitemap：从 sitemap.xml 发现页面。
78. 使用 --slow：3× 超时，用于慢加载或 JS 重站点。
79. 使用 --screenshot <path>：保存全页截图。
80. 使用 --raw-colors：在 JSON 输出中包含过滤前 raw colors。
81. 使用 --color-format <fmt>：终端打印颜色的 notation，可选 hex 默认、rgb、oklch、lch、source 即 as authored；仅展示用，JSON 输出不变，export 路径忽略它（0.28+）。
82. 使用 --tailwind [path]：写入 Tailwind v4 @theme CSS 文件，仅观测值；默认 output/<domain>/theme.css（0.28+）。
83. 使用 --shadcn [path]：写入 shadcn/ui theme，仅观测 slots，包含 @theme inline；默认 output/<domain>/shadcn.css（0.34+）。
84. 使用 --browser firefox：用 Firefox 替代 Chromium。
85. 使用 --stealth：opt-in 反检测，navigator spoofing 加 human mouse simulation；仅在获得授权时使用。
86. 使用 --user-agent <string>：自定义 user agent 字符串。
87. 使用 --locale <string>：浏览器 locale，例如 fi-FI、en-GB，默认 en-US。
88. 使用 --timezone <string>：浏览器 timezone，例如 Europe/Helsinki，默认 America/New_York。
89. 使用 --accept-language <string>：自定义 Accept-Language header 值。
90. 使用 --screen-size <WxH>：报告物理屏幕分辨率，例如 1920x1080。
91. 用 --compare 把提取变成 gate：先保存 known-good baseline，再用后续提取对比。
92. 第 1 步，在与将要检查的环境相同的环境中捕获 baseline：dembrandt https://app.example.com --json-only > baseline.json。
93. 第 2 步，之后对比；稳定时 exits 0，漂移时 exits 1：dembrandt https://app.example.com --compare baseline.json --html report.html。
94. --compare 在 structured tokens 上运行 canonical drift engine，是确定性的，不是像素或渲染 diff。
95. 退出码：0 表示稳定，1 表示漂移；可直接 gate 一个 pipeline。
96. --html 写入自包含报告；与 --compare 一起时包含 drift banner，显示 added/removed/changed tokens；把它作为 CI artifact 上传。
97. baseline 在 0.28.0 会 churn 一次：三个修复会移动颜色和 typography 值，palette usage floor、body 结束于 24px reading range，超过它的非标题文本进入 text，因此 hero copy 不再落到 body token，以及低于 counted text 2% 的字体族被丢弃；在 dembrandt.com 上对 0.27.1 提取测量，drift 为 15，threshold 为 10，足以让 gate 失败；升级后第一次运行要用 --compare <baseline> --approve 重新批准或重新生成 baseline；之后的 drift 才是真 drift。
98. 0.32.0 不需要重新批准：Schema 1.12.0 在两个参考站点对 threshold 10 测得 7 和 6，唯一差异是新增 mono context；Tailwind shadow ladder 会按 depth 而非仅 blur 重排，因此 --shadow-sm/md/lg/xl 可能在站点未变时移动。
99. 0.35.0 改变 gate 能因什么失败：在此之前，品牌色变化会被所有未变的 palette entry 稀释，一个真实 stripe.com baseline 把 semantic.primary 改成 magenta 仍得分 stable 并 exit 0；现在 semantic map 按自身权重评分，移动的 role 能达到 threshold；run-to-run variance 容差不变，单个 palette entry 出现或消失仍不 gate；在两个参考站点对 0.34.2 测量为 0 和 4，threshold 为 10，因此未变站点无需重新批准；品牌色真实移动的站点会失败于之前通过的 gate。
100. 同样在 0.35.0：off-grid spacing findings 之前完全没产生，因为检查对比的是一个 extractor 从 1.14.0 起不再写的 spacing.scaleType 拼写；现在包含 off-grid 值的站点会携带该 finding 并降低 consistency score。
101. 确定性：在与检查环境相同的环境中捕获 baseline，两者都是 production，或两者都是同一 preview；一个环境的 baseline 与另一个环境比较会出现 false drift。
102. 在 CI 中：对 preview/deployed URL 运行 --compare <baseline> --html report.html，失败于 exit 1 时让 job 失败，并上传 HTML artifact。
103. 以编程方式：从 dembrandt/drift 导入 computeDrift，从 dembrandt/report 导入 generateHtmlReport，在服务端 diff 和渲染，无需 CLI。
104. SPA hydration：等待 8 秒让 React/Vue/Svelte 渲染后再提取。
105. Lazy content：滚动整页以触发懒加载组件。
106. Cloudflare 或 bot walls：如果 headless 被阻止，自动用 visible browser 重试。
107. 慢站点：对重 JS bundle 使用 --slow 获得 3× 超时。
108. Cookie banners：自动 dismiss 常见 CMP 对话框，如 OneTrust、cookielaw、GDPR patterns。
109. Bot detection bypass：用 --stealth 选择加入 navigator spoofing 和 human mouse simulation；默认关闭，因此工具诚实表明自身。
110. robots.txt：每个 origin 读取一次，并与浏览器实际发送的 User-Agent 匹配；默认 advisory；对 scheduled jobs 和服务端使用，设置 DEMBRANDT_ENFORCE_ROBOTS=1，此时没人决定可以抓什么，disallow 或无法读取文件会跳过目标并以 exit 4 退出；缺少 robots.txt 不算拒绝（0.32+）。
111. 提取后检查：识别 3 到 5 个 high-confidence 颜色，这些是核心品牌 palette。
112. 提取后检查：检查 colors.semantic.primary 是否正确。
113. 提取后检查：查看 typography.styles，确定 heading 和 body 字体。
114. 提取后检查：检查 spacing.scaleType 是 4px、8px 还是 custom；custom 是真实答案，不是缺口。
115. 提取后检查：查看 components.buttons，确定有多少 variants。
116. 提取后检查：检查 frameworks，是否检测到 Tailwind、shadcn 或 MUI；这决定如何应用 tokens。
117. 提取后检查：如果站点有 dark theme，使用 --dark-mode。
118. 提取后检查：如果站点多路由分布着多 section 设计系统，使用 --crawl 3。

适用边界 · 注意事项

• 不适用于未获授权、robots.txt 不允许或需要违反站点条款的抓取；--stealth 只能在获得授权时使用。
• 不适用于需要像素级渲染对比或完整视觉回归测试的场景；它是结构化 token 提取，不是像素 diff。
• 如果项目必须使用 Tailwind v3 或非 v4，不要期望 --tailwind/--shadcn 直接产出；需要手工映射或改用其他流程。