extract-design

提取设计 — Dembrandt

Dembrandt 使用无头 Chromium 浏览器访问任意 URL，遍历数千个 DOM 元素，读取计算后的 CSS，并返回结构化的设计系统：带置信度评分的颜色、字体样式、间距比例、边框半径、边框、阴影和交互式组件样式。

运行方式

# Zero-install — npx fetches the package on first run (lowest friction)
npx -y dembrandt https://dembrandt.com

# Or install once (global), then call `dembrandt` directly
npm i -g dembrandt

# Basic extraction — outputs to terminal
dembrandt https://dembrandt.com

# JSON output — pipe into files or other tools
dembrandt https://dembrandt.com --json-only > dembrandt-tokens.json

# W3C DTCG format (design-tokens.org standard)
dembrandt https://dembrandt.com --dtcg --save-output

# Generate DESIGN.md (human + AI readable brand doc)
dembrandt https://dembrandt.com --design-md

# Multi-page crawl (follows internal links)
dembrandt https://dembrandt.com --crawl 5

# Dark mode colors
dembrandt https://dembrandt.com --dark-mode

# Mobile viewport
dembrandt https://dembrandt.com --mobile

# Everything saved to output/
dembrandt https://dembrandt.com --save-output

# Tailwind v4 @theme CSS — observed values only  [dembrandt 0.28+]
dembrandt https://dembrandt.com --tailwind src/app.css

# Self-contained HTML report — open offline or attach as a CI artifact  [dembrandt 0.19+]
dembrandt https://dembrandt.com --html report.html

# Drift gate — compare against a saved baseline; exits 1 on drift  [dembrandt 0.19+]
dembrandt https://app.example.com --compare baseline.json --html report.html

MCP 用法（默认异步）

要将 Dembrandt 作为 MCP 工具提供给 Agent，请将此服务添加到 Agent 的 MCP 配置中（无需安装——npx 会在首次运行时获取它）：

{ "mcpServers": { "dembrandt": { "command": "npx", "args": ["-y", "dembrandt", "mcp"] } } }

使用 Dembrandt MCP 服务时，所有提取工具都会立即返回 job_id，而不会阻塞。轮询 get_job_status，直到 status 为 "completed"：

1. get_design_tokens({ url: "dembrandt.com", pages: 5 })
   → { job_id: "job_123_abc", status: "queued" }

2. get_job_status({ job_id: "job_123_abc" })
   → { status: "running" }   // poll again

3. get_job_status({ job_id: "job_123_abc" })
   → { status: "completed", result: { ... } }

4. get_findings({ job_id: "job_123_abc" })      // no need to resend the extraction
   → { findings: [ ... ], contrast: { ... } }

将 job_id 传给分析工具，而不是传入提取结果。 所有纯分析工具都接受它，队列会将整个提取结果保留一小时，因此，由 get_color_palette 这类范围较窄的工具启动的任务也可以用于 export_dtcg。内联传入提取结果也可行；如果两者都提供，则以内联结果为准，但实际提取结果太大，无法作为工具参数经由模型传回。 [dembrandt 0.29+]

向任意提取工具传入 sync: true，即可阻塞并直接返回结果（适用于网络较快的情况；网络较慢的网站可能导致超时；当 pages 大于 1 时，耗时也会相应增加）。

提取工具：get_design_tokens（全部内容）、get_color_palette、get_typography、get_component_styles、get_surfaces、get_spacing、get_brand_identity、get_motion（时长、缓动、命名关键帧、悬停模式，以及与之配套的渐变） [dembrandt 0.36+]。所有工具都接受 slow、mobile（移动端视口）和 cookie（用于需要身份验证的页面的 cookie 字符串）；get_design_tokens 和 get_color_palette 还接受 darkMode 和 wcag（对比度分析）。 [dembrandt 0.23.1+ for mobile/cookie/wcag]

每个提取工具也会执行爬取，这是影响令牌质量的最大因素：一个页面只能提供该页面的令牌。 [dembrandt 0.29+]

选项	说明
pages	最多提取 N 个页面，并合并为一组令牌（1 到 20）。页面来自 DOM 链接；如果 sitemap 为 true，则来自 sitemap.xml
paths	明确指定额外路径，例如 ["/pricing", "/docs"]。此选项会覆盖自动发现
sitemap	从 sitemap.xml 中发现页面。单独使用时最多提取 20 个页面；上限由 pages 设置
header	额外的 HTTP 标头，可以是字符串或列表，例如 "Authorization: Bearer ..."，用于访问 cookie 无法触达的页面
cookieFile	已保存会话的路径：JSON cookie 数组、Playwright storageState 文件（包含 cookies、localStorage，以及 --save-storage-state 添加的 sessionStorage 区块），或 Netscape cookies.txt。操作者只需通过 dembrandt <url> --login --save-storage-state <path> 生成一次；Agent 无法自行登录 [dembrandt 0.39+]
basicAuth	用于访问浏览器提示框保护的预发布主机的 HTTP Basic 凭据，格式为 "user:password" [dembrandt 0.39+]
userAgent	自定义用户代理字符串
noSandbox	禁用浏览器沙箱。在 Docker 和大多数 CI 容器中必须启用，否则浏览器无法启动

无法加载的页面会被丢弃，合并时会保留其余页面，因此爬取不会因一个无效 URL 而失败。 纯工具（不使用浏览器、同步；提取结果放在 result 中，或使用 job_id 指定已完成的任务 [dembrandt 0.29+]）：compute_drift（计算两次提取之间 0–100 的偏差分数；任务形式使用 baselineJobId 和 candidateJobId）、get_findings（设计系统检查：对比度、一致性、重复项）、export_dtcg（W3C Design Tokens 格式）、generate_design_md（DESIGN.md 品牌指南）、render_report（独立 HTML 报告）、export_tailwind（Tailwind v4 @theme 块）、export_shadcn（shadcn/ui 主题；页面未提供的插槽保留 shadcn 默认值）。任务控制：get_job_status、list_jobs、cancel_job。 [get_findings/export_dtcg/generate_design_md/list_jobs 需要 dembrandt 0.23.1+，两个导出工具需要 0.36+]

三个工具使用自己的输入，而不是提取结果 [dembrandt 0.36+]：validate_dtcg（根据 2025.10 规范检查 DTCG 文档，包括此服务生成的文档，避免手动编辑意外破坏文档）、check_contrast（按文字大小对应的阈值，根据 WCAG 2.1 对指定的颜色组合进行评级，适用于即将发布的颜色，而非页面上已有的颜色），以及 check_robots（在启动浏览器运行前，查询 robots.txt 是否允许访问某个 URL）。

注意：如果 PATH 中已有 dembrandt，npx 会优先运行它，而不是获取最新版，因此全局安装的 dembrandt 会悄悄覆盖它。症状：固定版本支持的选项被报为未知选项，或爬取结果只有一个页面。使用 dembrandt --version 检查并升级全局安装，或将 MCP 配置指向明确路径。

注意：dembrandt <=0.23.0 无法通过上面的 npx 单行命令启动（McpDepsMissingError）——MCP SDK 是可选的对等依赖项。此问题已在 0.23.1 中修复；请使用该版本。

输出结构

Dembrandt 会返回一个结构化对象。主要部分：

colors.palette        — Deduplicated colors with confidence (high/medium/low).
                        Each entry carries hex (`normalized`), plus `lch` and
                        `oklch` of the same colour, and derived `role`,
                        `onColor`, `hover`. With `--wcag`, entries also carry
                        `contrastAgainst`, the pairs this colour was actually
                        observed against on the page, deduped by the other
                        colour and sorted by ratio (dembrandt 0.31+). `tokens`
                        lists the custom property names that declare that
                        exact colour, read from html and body, so a colour
                        with tokens is one the site named (dembrandt 0.37+).
colors.detected       — Every colour that passed the alpha gate, with no
                        frequency threshold and no perceptual merge, so six
                        near-identical reds stay six entries. `usageFrac`
                        counts elements; `areaFrac` is the share of painted
                        background area, which ranks a hero fill above many
                        small glyphs the way a count alone does not (dembrandt
                        0.32+). Use `palette` for a design system and
                        `detected` when you need recall.
colors.semantic       — Primary, secondary, background, text, and accent detection
colors.semanticEvidence — How `primary` was decided (dembrandt 0.39+).
                        `primary.decision` is `elected` or `refused`; `rule`
                        names the rule that chose it, `reason` says it in
                        words, `tokens` lists the custom properties that
                        declare the colour, `alternates` the chromatic
                        runners-up. A refused primary is written down with
                        the candidates that lost, so an absent `primary` is
                        a decision, not a failed run. Read this before
                        trusting a primary on a dark or monochrome brand.
colors.occurrences    — The measurement the palette is read from (0.39+):
                        one row per colour per `paints` (`fill`, `text`,
                        `border`) with `count`, summed fill `area` and the
                        first declaring `cssVar`. `slot` and `state` are null
                        until classification lands.
colors.cssVariables   — Named CSS custom properties. `value` is the author's
                        string verbatim (the only record of the authored
                        notation), plus computed hex + LCH + OKLCH.
typography.styles     — Font family, size, weight, line-height per context.
                        Each entry carries `count`, the number of elements
                        rendering that exact style. `code`, `pre`, `kbd` and
                        `samp` land in a `mono` context, so a mono face used
                        only in code blocks is visible (dembrandt 0.32+).
                        `isFluid` is read from the authored declaration, so a
                        `clamp()` or viewport-relative ramp is detected
                        (dembrandt 0.32+).
typography.sources    — Google Fonts, Adobe Fonts, variable font detection.
                        `customFonts` names the declared @font-face families;
                        `selfHostedFonts` keeps the file names. `fontDisplay`
                        is the first font-display value seen, or null
                        (dembrandt 0.37+).
                        `urls` lists the resolved font asset and webfont
                        stylesheet URLs, deduped, so you can re-fetch or verify
                        the real files. `filteredFamilies` lists families
                        dropped by the usage floor — check it before concluding
                        a face is missing.
spacing.commonValues  — Margin/padding scale with rem equivalents
spacing.scaleType     — 4px, 8px, or custom grid. Since 0.34.0 the verdict is
                        weighted: a page reads custom unless 60% of its spacing
                        lands on the step, so sites that used to claim a grid
                        now report custom truthfully
borderRadius.values   — Border radius tokens with element context
borders.combinations  — Width + style + color combinations
shadows               — Box shadow elevation system. One string per shadow,
                        layers comma-separated as CSS writes them. The `--dtcg`
                        export splits them into structured layers (0.32+).
components.buttons    — Button variants with hover/active/focus states
components.inputs     — Input styles with focus states
components.links      — Link colors and hover states
components.badges     — Badge/tag/chip variants
breakpoints           — Responsive breakpoints from CSS media queries
frameworks            — What builds the UI. Before 0.38 only CSS frameworks
                        (Tailwind, shadcn, MUI). From 0.38 each entry carries
                        `category` (js-framework, meta-framework, js-library,
                        css-framework, ui-library, web-components, css-in-js,
                        site-builder), `version` when the page states one, and
                        `coverage`: the share of the page under that
                        framework's mount point, 0 to 1.
iconSystem            — Detected icon library (Heroicons, FA, Material, etc.),
                        with `version` when the page states one (0.38+)
pages                 — Present only on a merged multi-page result (`--crawl`,
                        `--sitemap`, extra paths, or MCP `pages`). One entry per
                        page extracted, so you can tell which URLs the merged
                        tokens came from. Every merged palette, typography,
                        spacing, radius, border and shadow value then carries
                        `pageCount` and `scope`: `site` when every page has
                        it, `page` when one does, `section` between (0.39+).
coverage              — On a merged result only (0.39+): `score` 0-100 as the
                        mean of family means, `byFamily` with `meanCoverage`
                        and `pageLocal` counts, and `outliers`, the page-local
                        tokens capped at five per family. A page-local token
                        is drift inside one snapshot. `totalPages` travels
                        with the score; 2 of 2 and 2 of 7 are not the same.
meta.context          : the browser context the run was measured under
                        (0.39+): viewport, deviceScaleFactor, isMobile,
                        hasTouch, colorScheme, reducedMotion, forcedColors,
                        locale, timezoneId, userAgent. `--compare` warns when
                        two snapshots differ in a rendering dial.
wcag                  : with `--wcag`, observed contrast pairs (fg, bg, ratio,
                        aa/aaLarge/aaa booleans) between real rendered colours.
meta.crawl            : present when `--crawl`, `--sitemap` or explicit paths
                        are used, with `technique`, `pagesRequested`,
                        `pagesFound` (dembrandt 0.31+).
meta.robotsWarnings   : pages robots.txt disallowed, whether that was the
                        entry URL or one discovered during a crawl. The check
                        is advisory by default, it does not block
                        extraction, and this is the only record of what it
                        flagged (dembrandt 0.31+). Set
                        `DEMBRANDT_ENFORCE_ROBOTS=1` to make a disallow, or a
                        robots.txt we could not read, skip the target with exit
                        `4`. A site with no robots.txt (404/410) is not a
                        refusal and still runs (dembrandt 0.32+).

使用提取的 Token

初始化 Tailwind 主题 (dembrandt 0.28+)

不要手动映射 JSON。--tailwind 会直接写入 Tailwind v4 @theme 块：

dembrandt https://dembrandt.com --tailwind            # → output/<domain>/theme.css
dembrandt https://dembrandt.com --tailwind src/app.css  # or straight into the project

@import "tailwindcss";

@theme {
  --color-primary: #ea580c;
  --text-display: 96px;
  --text-display--line-height: 1;
  --spacing: 8px;
  --radius-lg: 8px;
  --breakpoint-md: 700px;
}

仅包含观察到的值：没有 50–950 色阶、没有插值生成的比例步长，也没有派生的悬停或前景色变体。虚构的色阶一旦写入文件，就无法与测量值区分，因此导出结果只是起点，需要你手动扩展。颜色会保留其语义角色名称（--color-primary），或在页面声明了自定义属性名时使用该名称；其余颜色会编号为 --color-brand-N。如果页面采用 base-N 节奏，间距会折叠为 v4 的 --spacing 乘数；否则会回退为命名步长。未列出的内容仍使用 Tailwind 默认值，因此该代码块是扩展主题，而非替换主题。

仅适用于 v4。对于 v3 的 tailwind.config.js，请手动映射输出——colors.semantic → theme.colors、typography.styles → fontFamily、spacing.commonValues → spacing、borderRadius.values → borderRadius、shadows → boxShadow。

初始化 shadcn/ui 主题

--shadcn（0.34.0+）会写入主题，因此无需手动映射变量：

dembrandt stripe.com --shadcn        # output/<domain>/shadcn.css

该文件包含 :root 块以及 Tailwind v4 所需的 @theme inline 映射，颜色使用 oklch。只有页面提供了值的插槽才会写入；其余插槽会在文件头部列出，并保留 shadcn 自身的默认值，因此未观察到的插槽不会以看似合理、仿佛经过测量的值出现。--dark-mode 会生成 .dark 块；每次运行处理一种配色方案。

不要根据 borderRadius.values[0] 推导 --radius：该列表按长度排序，因此第一项是页面上最小的圆角，而不是按钮和输入框使用的圆角。该标志会采用使用频率最高的值。

读取置信度等级

Dembrandt 根据语义上下文为每种颜色评分：

置信度	含义
高	出现在带有语义标签的元素上（按钮、CTA、带有品牌类名的标题）。几乎可以确定是品牌色。
中	出现频率或上下文适中。很可能是品牌色。
低	很少出现，语义上下文较弱。可能是一次性使用或特定组件的颜色。

从 0.28.0 版本起，置信度也设有使用次数下限，间距和圆角一直如此：某种颜色只出现一次时，置信度最高为低；出现两次时最高为中；无论语义上下文评分如何，都需要出现三次才算高。悬停和焦点颜色是例外，仍保持中置信度——它们只出现一次反映的是来源，而非使用次数。

构建调色板时，请从置信度为 high 的颜色开始。要全面覆盖，请加入 medium。仅将 low 作为参考。

颜色表示法

切勿手动转换颜色，也不要用自己的数学计算重新推导颜色。每个调色板条目和每个 CSS 变量都已在十六进制值旁附带 lch 和 oklch，因此只需从 JSON 中直接读取所需字段。--color-format 只会改变终端输出的内容，因此在使用 JSON 或 MCP 输出时不应使用它。

使用十六进制值（normalized）作为颜色的标识：去重、漂移比较和所有下游工具都以它为键。即使输出的表示法不同，十六进制值相同的两个条目也是同一个设计令牌。当作者使用现代表示法声明令牌时，cssVariables[name].value 会原样保留该表示法；将 CSS 写回该代码库时应使用此值，因为这样既能保留作者自己的表示法，也能确保颜色仍处于其色域内。

标志参考

标志	功能
--json-only	将纯净的 JSON 输出到 stdout，可通过管道传入文件或工具
--save-output	将 JSON 保存到 output/<domain>/<timestamp>.json
--dtcg	W3C Design Tokens Community Group 格式。当阴影包含多个图层时，阴影令牌的 $value 是一个数组，因此读取 $value.offsetX 的使用方必须根据 Array.isArray 分支处理。(0.32+)
--design-md	生成 DESIGN.md——以文字为主的品牌文档
--html [path]	生成独立的 HTML 报告（内联 CSS、嵌入 JSON）。可离线打开，也可作为 CI 构建产物附加。(0.19+)
--compare <baseline.json>	与保存的提取结果进行差异比较；输出偏差判定，若存在偏差则以状态码 1 退出。可用作 CI 门禁。(0.19+)
--brand-guide	生成 PDF 品牌指南
--dark-mode	提取深色配色方案并合并到调色板中
--mobile	在 390px 移动视口下提取
--crawl <n>	抓取最多 N 个页面并合并令牌
--sitemap	从 sitemap.xml 中发现页面
--slow	将超时时间延长至 3 倍——用于加载缓慢或大量依赖 JS 的网站
--screenshot <path>	保存整页截图
--raw-colors	在 JSON 输出中包含筛选前的原始颜色
--color-format <fmt>	终端中打印颜色的表示法：hex（默认）、rgb、oklch、lch、source（按原始写法）。仅影响显示，因此不会更改 JSON 输出，导出路径也会忽略此选项。(0.28+)
--tailwind [path]	写入 Tailwind v4 @theme CSS 文件——仅包含观察到的值。默认为 output/<domain>/theme.css。(0.28+)
--shadcn [path]	写入 shadcn/ui 主题——仅包含观察到的插槽，并包含 @theme inline。默认为 output/<domain>/shadcn.css。(0.34+)
--browser firefox	使用 Firefox 代替 Chromium
--stealth	可选启用反检测功能：伪装 navigator + 模拟人类鼠标操作。仅在获得授权时使用。
--user-agent <string>	自定义用户代理字符串
--locale <string>	浏览器区域设置，例如 fi-FI、en-GB（默认值：en-US）
--timezone <string>	浏览器时区，例如 Europe/Helsinki（默认值：America/New_York）
--accept-language <string>	自定义 Accept-Language 标头值
--header <string>	额外请求标头，格式为 Name: value；需要多个标头时可重复使用此标志（从 0.39 起可重复使用）
--screen-size <WxH>	要报告的物理屏幕分辨率，例如 1920x1080

漂移检测与 CI (dembrandt 0.19+)

--compare 会将提取转变为一道门禁。保存一个已知良好的基线，然后将之后的提取结果与之比较：

# 1. capture a baseline (in the SAME environment you will check against)
dembrandt https://app.example.com --json-only > baseline.json

# 2. later — compare; exits 0 if stable, 1 if drifted
dembrandt https://app.example.com --compare baseline.json --html report.html

• 对结构化令牌运行规范漂移引擎——结果具有确定性，不是像素／渲染差异。
• 退出代码：0 表示稳定，1 表示发生漂移。可直接用于管道门禁。
• --html 会生成自包含报告；与 --compare 一起使用时，报告会包含漂移横幅（新增／移除／更改的令牌）。可将其作为 CI 构建产物附加。

基线在 0.28.0 版本会发生一次变化。 三项修复会改变颜色和排版值：调色板使用率下限、body 在 24px 阅读范围处截止（超过该范围的非标题文本会使用 text，因此主视觉文案不再落到 body 令牌上），以及占计数文本不足 2% 的字体系列会被剔除。在 dembrandt.com 上，将 0.27.1 的提取结果作为基线进行测量，漂移值为 15，超过 10 的阈值——足以导致门禁失败。升级后的首次运行中，使用 --compare <baseline> --approve 重新批准，或重新生成基线。此后的漂移才是真正的漂移。

0.32.0 无需重新批准。 在两个参考站点上，Schema 1.12.0 的测量值分别为 7 和 6，低于 10 的阈值；唯一差异是新增了 mono 上下文。Tailwind 的阴影阶梯会按深度而非仅按模糊程度重新排序，因此对于未更改的站点，--shadow-sm/md/lg/xl 也可能发生变化。

0.35.0 改变了门禁可能因哪些情况而失败。 在此之前，更改后的品牌颜色会被所有保持不变的调色板条目所稀释：一个真实的 stripe.com 基线中，semantic.primary 变为洋红色，得分仍显示稳定，退出代码为 0。现在，语义映射会按自身权重单独评分，因此角色变更会达到阈值。运行间波动的容差保持不变，单个调色板条目的新增或消失仍不会触发门禁。在两个参考站点上与 0.34.2 进行测量，结果分别为 0 和 4，低于 10 的阈值，因此未发生变化的站点无需重新批准。品牌颜色确实发生变化的站点，则会导致此前能通过的门禁失败。

同样在 0.35.0 中：过去完全不会生成网格外间距问题，因为检查所用的 spacing.scaleType 拼写已在提取器 1.14.0 中停止写入。现在，含有网格外数值的站点会报告此问题，并获得较低的一致性评分。

确定性： 请在同一环境中采集和检查基线（两者都使用生产环境，或同一个预览环境）。将一个环境中的基线与另一个环境进行比较会产生虚假漂移。

在 CI 中： 对预览／已部署的 URL 运行 --compare <baseline> --html report.html，在退出代码为 1 时将作业标记为失败，并上传 HTML 构建产物。以编程方式使用： 从 dembrandt/drift 导入 computeDrift，并从 dembrandt/report 导入 generateHtmlReport，无需使用 CLI 即可在服务端进行差异比较和渲染。

反爬虫与 SPA 处理

Dembrandt 会自动处理常见的提取难题：

• SPA 水合——提取前等待 8s，让 React/Vue/Svelte 完成渲染
• 延迟加载内容——滚动整个页面以触发延迟加载的组件
• Cloudflare／反机器人墙——无头模式被拦截时，自动使用可见浏览器重试
• 加载缓慢的网站——对包含大型 JS 包的站点使用 --slow，将超时时间延长至 3 倍
• Cookie 横幅——自动关闭常见的 CMP 对话框（OneTrust、cookielaw、GDPR 模式）
• 绕过机器人检测——使用 --stealth 以启用 navigator 欺骗和模拟人类鼠标操作；默认关闭，以便工具如实表明自身身份
• robots.txt——每个源站只读取一次，并根据浏览器实际发送的 User-Agent 进行匹配。默认仅作提示；对于定时任务和服务端使用场景，由于没有人来决定是否允许抓取，可设置 DEMBRANDT_ENFORCE_ROBOTS=1。如果目标被禁止抓取，或 robots.txt 文件无法读取，则跳过该目标并以退出代码 4 结束。缺少 robots.txt 不代表拒绝抓取 (0.32+)

提取后的检查清单

• 确认 3–5 种高置信度颜色——它们构成品牌的核心配色
• 检查 colors.semantic.primary——是否正确？
• 查看 typography.styles——标题和正文分别使用什么字体？
• 检查 spacing.scaleType——是 4px、8px，还是自定义？自定义也是有效答案，并非缺失信息
• 查看 components.buttons——共有多少种变体？
• 检查 frameworks——css-framework 和 ui-library 条目会影响你如何应用这些设计令牌。coverage 接近 0 表示页面上有一个小部件，而不是页面基于它构建。没有 version 表示页面未注明版本；不要猜测。
• 如果网站有深色主题，请使用 --dark-mode
• 如果设计系统分布在多个路由中且包含多个部分，请使用 --crawl 3