extract-design
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
ChineseExtract Design — Dembrandt
提取设计系统 — Dembrandt
Dembrandt runs a headless Chromium browser against any URL, walks up to thousands of DOM elements, reads computed CSS, and returns a structured design system: colors with confidence scoring, typography styles, spacing scale, border radius, borders, shadows, and interactive component styles.
Dembrandt通过无头Chromium浏览器访问任意URL,遍历数千个DOM元素,读取计算后的CSS样式,返回结构化的设计系统:包含置信度评分的颜色、排版样式、间距比例、圆角、边框、阴影以及交互式组件样式。
How to Run
运行方式
bash
undefinedbash
undefinedZero-install — npx fetches the package on first run (lowest friction)
零安装 — npx会在首次运行时拉取包(最低使用门槛)
npx -y dembrandt https://stripe.com
npx -y dembrandt https://stripe.com
Or install once (global), then call dembrandt
directly
dembrandt或全局安装一次,之后直接调用dembrandt
dembrandtnpm i -g dembrandt
npm i -g dembrandt
Basic extraction — outputs to terminal
基础提取 — 结果输出到终端
dembrandt https://stripe.com
dembrandt https://stripe.com
JSON output — pipe into files or other tools
JSON格式输出 — 可写入文件或传递给其他工具
dembrandt https://stripe.com --json-only > stripe-tokens.json
dembrandt https://stripe.com --json-only > stripe-tokens.json
W3C DTCG format (design-tokens.org standard)
W3C DTCG格式(符合design-tokens.org标准)
dembrandt https://stripe.com --dtcg --save-output
dembrandt https://stripe.com --dtcg --save-output
Generate DESIGN.md (human + AI readable brand doc)
生成DESIGN.md(人类与AI均可读取的品牌文档)
dembrandt https://stripe.com --design-md
dembrandt https://stripe.com --design-md
Multi-page crawl (follows internal links)
多页面爬取(跟随内部链接)
dembrandt https://stripe.com --crawl 5
dembrandt https://stripe.com --crawl 5
Dark mode colors
提取深色模式颜色
dembrandt https://stripe.com --dark-mode
dembrandt https://stripe.com --dark-mode
Mobile viewport
移动端视口提取
dembrandt https://stripe.com --mobile
dembrandt https://stripe.com --mobile
Everything saved to output/
所有结果保存到output/目录
dembrandt https://stripe.com --save-output
dembrandt https://stripe.com --save-output
Tailwind v4 @theme CSS — observed values only [dembrandt 0.28+]
生成Tailwind v4 @theme CSS — 仅包含观测到的值 [dembrandt 0.28+]
dembrandt https://stripe.com --tailwind src/app.css
dembrandt https://stripe.com --tailwind src/app.css
Self-contained HTML report — open offline or attach as a CI artifact [dembrandt 0.19+]
生成独立HTML报告 — 可离线打开或作为CI产物附加 [dembrandt 0.19+]
dembrandt https://stripe.com --html report.html
dembrandt https://stripe.com --html report.html
Drift gate — compare against a saved baseline; exits 1 on drift [dembrandt 0.19+]
漂移检测 — 与已保存的基线对比;若存在漂移则以状态码1退出 [dembrandt 0.19+]
dembrandt https://app.example.com --compare baseline.json --html report.html
undefineddembrandt https://app.example.com --compare baseline.json --html report.html
undefinedMCP Usage (async by default)
MCP使用方式(默认异步)
To expose Dembrandt as MCP tools, add this server to the agent's MCP config (no install — fetches it on first run):
npxjson
{ "mcpServers": { "dembrandt": { "command": "npx", "args": ["-y", "--package", "dembrandt", "dembrandt-mcp"] } } }When using the Dembrandt MCP server, all extraction tools return a immediately rather than blocking. Poll until is :
job_idget_job_statusstatus"completed"1. get_design_tokens({ url: "stripe.com" })
→ { 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: { ... } }Pass to any extraction tool to block and return the result directly (useful on fast networks, risks timeout on slow sites).
sync: trueExtraction tools: (everything), , , , , , . All accept , (mobile viewport), and (cookie string for authenticated pages); and also accept and (contrast analysis). [dembrandt 0.23.1+ for mobile/cookie/wcag]
get_design_tokensget_color_paletteget_typographyget_component_stylesget_surfacesget_spacingget_brand_identityslowmobilecookieget_design_tokensget_color_palettedarkModewcagPure tools (no browser, synchronous, take an extraction object): (0-100 drift score between two extractions), (design-system lint: contrast, consistency, duplication), (W3C Design Tokens format), (DESIGN.md brand guide), (self-contained HTML report). Job control: , , . [dembrandt 0.23.1+ for get_findings/export_dtcg/generate_design_md/list_jobs]
compute_driftget_findingsexport_dtcggenerate_design_mdrender_reportget_job_statuslist_jobscancel_jobNote: dembrandt <=0.23.0 fails to start via the npx one-liner above () — the MCP SDK was an optional peer dependency. Fixed in 0.23.1; require it.
McpDepsMissingError要将Dembrandt作为MCP工具暴露,可将该服务器添加到Agent的MCP配置中(无需安装 — 会在首次运行时拉取):
npxjson
{ "mcpServers": { "dembrandt": { "command": "npx", "args": ["-y", "--package", "dembrandt", "dembrandt-mcp"] } } }使用Dembrandt MCP服务器时,所有提取工具会立即返回而非阻塞进程。轮询直到变为:
job_idget_job_statusstatus"completed"1. get_design_tokens({ url: "stripe.com" })
→ { job_id: "job_123_abc", status: "queued" }
2. get_job_status({ job_id: "job_123_abc" })
→ { status: "running" } // 继续轮询
3. get_job_status({ job_id: "job_123_abc" })
→ { status: "completed", result: { ... } }向任意提取工具传递可阻塞进程并直接返回结果(适用于网络较快的场景,在加载缓慢的网站上可能超时)。
sync: true提取工具包括:(提取全部内容)、、、、、、。所有工具均支持、(移动端视口)、(用于认证页面的Cookie字符串)参数;和还支持和(对比度分析)参数。 [dembrandt 0.23.1+版本支持mobile/cookie/wcag]
get_design_tokensget_color_paletteget_typographyget_component_stylesget_surfacesget_spacingget_brand_identityslowmobilecookieget_design_tokensget_color_palettedarkModewcag纯工具(无需浏览器,同步执行,接收提取对象):(两个提取结果间的0-100漂移评分)、(设计系统检查:对比度、一致性、重复项)、(W3C设计令牌格式导出)、(生成DESIGN.md品牌指南)、(生成独立HTML报告)。任务控制工具:、、。 [dembrandt 0.23.1+版本支持get_findings/export_dtcg/generate_design_md/list_jobs]
compute_driftget_findingsexport_dtcggenerate_design_mdrender_reportget_job_statuslist_jobscancel_job注意:dembrandt <=0.23.0版本无法通过上述npx一行命令启动(会报)——MCP SDK为可选对等依赖。该问题已在0.23.1版本修复,请使用该版本及以上。
McpDepsMissingErrorOutput Structure
输出结构
Dembrandt returns a structured object. The key sections:
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`.
colors.semantic — Primary, secondary, background, text, and accent detection
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.
typography.sources — Google Fonts, Adobe Fonts, variable font detection.
`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
borderRadius.values — Border radius tokens with element context
borders.combinations — Width + style + color combinations
shadows — Box shadow elevation system
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 — Detected CSS framework (Tailwind, shadcn, MUI, etc.)
iconSystem — Detected icon library (Heroicons, FA, Material, etc.)Dembrandt返回结构化对象,核心部分如下:
colors.palette — 去重后的颜色及置信度(高/中/低)。
每个条目包含十六进制值(`normalized`)、对应的`lch`和
`oklch`颜色值,以及推导的`role`、
`onColor`、`hover`属性。
colors.semantic — 自动识别主色、辅助色、背景色、文本色和强调色
colors.cssVariables — 已命名的CSS自定义属性。`value`为作者原始字符串
(保留作者的原始写法),同时包含计算后的十六进制、LCH及OKLCH值。
typography.styles — 不同场景下的字体族、字号、字重、行高。
每个条目包含`count`,即使用该精确样式的元素数量。
typography.sources — 识别Google Fonts、Adobe Fonts及可变字体。
`urls`列出已去重的字体资源及Web字体样式表URL,方便重新获取或验证
真实文件。`filteredFamilies`列出因使用量阈值被过滤的字体族
— 在判断某字体缺失前请先检查该字段。
spacing.commonValues — 边距/内边距比例及对应的rem等效值
spacing.scaleType — 4px、8px或自定义网格
borderRadius.values — 圆角令牌及对应的元素上下文
borders.combinations — 宽度+样式+颜色的组合
shadows — 盒阴影层级系统
components.buttons — 包含hover/active/focus状态的按钮变体
components.inputs — 包含focus状态的输入框样式
components.links — 链接颜色及hover状态
components.badges — 徽章/标签/芯片变体
breakpoints — 从CSS媒体查询中提取的响应式断点
frameworks — 检测到的CSS框架(Tailwind、shadcn、MUI等)
iconSystem — 检测到的图标库(Heroicons、FA、Material等)Working with Extracted Tokens
提取令牌的使用场景
Seeding a Tailwind theme (dembrandt 0.28+)
生成Tailwind主题 (dembrandt 0.28+)
Don't hand-map the JSON. writes a Tailwind v4 block directly:
--tailwind@themebash
dembrandt https://stripe.com --tailwind # → output/<domain>/theme.css
dembrandt https://stripe.com --tailwind src/app.css # or straight into the projectcss
@import "tailwindcss";
@theme {
--color-primary: #ea580c;
--text-display: 96px;
--text-display--line-height: 1;
--spacing: 8px;
--radius-lg: 8px;
--breakpoint-md: 700px;
}Observed values only: no 50–950 shade ramps, no interpolated scale steps, no derived hover or on-colour variants. An invented shade is indistinguishable from a measured one once it is in the file, so the export is a starting point you extend by hand. Colours keep their semantic role name () or the page's own custom property name where one is declared; the rest are numbered . Spacing collapses to v4's multiplier when the page has a base-N rhythm, and falls back to named steps otherwise. Tailwind's defaults still apply to anything not listed, so the block extends the theme rather than replacing it.
--color-primary--color-brand-N--spacingv4 only. For a v3 , map the output by hand — → , → , → , → , → .
tailwind.config.jscolors.semantictheme.colorstypography.stylesfontFamilyspacing.commonValuesspacingborderRadius.valuesborderRadiusshadowsboxShadow无需手动映射JSON。参数可直接生成Tailwind v4的代码块:
--tailwind@themebash
dembrandt https://stripe.com --tailwind # → 输出到output/<domain>/theme.css
dembrandt https://stripe.com --tailwind src/app.css # 或直接写入项目文件css
@import "tailwindcss";
@theme {
--color-primary: #ea580c;
--text-display: 96px;
--text-display--line-height: 1;
--spacing: 8px;
--radius-lg: 8px;
--breakpoint-md: 700px;
}仅包含观测到的值:无50–950的色阶渐变、无插值比例步骤、无推导的hover或on-colour变体。人工生成的色阶与测量得到的色阶在文件中无法区分,因此该导出结果仅作为手动扩展的起点。颜色保留其语义角色名称()或页面自身声明的自定义属性名称;其余颜色编号为。当页面存在基准N节奏时,间距会折叠为v4的乘数,否则回退为命名步骤。Tailwind的默认值仍适用于未列出的内容,因此该代码块是对主题的扩展而非替换。
--color-primary--color-brand-N--spacing仅支持v4版本。若需生成v3的,需手动映射输出: → 、 → 、 → 、 → 、 → 。
tailwind.config.jscolors.semantictheme.colorstypography.stylesfontFamilyspacing.commonValuesspacingborderRadius.valuesborderRadiusshadowsboxShadowSeeding a shadcn/ui theme
生成shadcn/ui主题
Map semantic colors to shadcn CSS variables in HSL:
css
:root {
--background: /* from colors.semantic.background (0.22.0+), else colors.palette — lightest neutral */;
--foreground: /* from colors.semantic.text (0.22.0+), else colors.palette — darkest neutral */;
--primary: /* from colors.semantic.primary */;
--primary-foreground: /* contrasting color */;
--muted: /* mid-tone neutral */;
--border: /* from borders.combinations[0].color */;
--radius: /* from borderRadius.values[0].value */;
}将语义颜色映射为HSL格式的shadcn CSS变量:
css
:root {
--background: /* 来自colors.semantic.background(0.22.0+),否则取colors.palette中最浅的中性色 */;
--foreground: /* 来自colors.semantic.text(0.22.0+),否则取colors.palette中最深的中性色 */;
--primary: /* 来自colors.semantic.primary */;
--primary-foreground: /* 对比色 */;
--muted: /* 中间色调中性色 */;
--border: /* 来自borders.combinations[0].color */;
--radius: /* 来自borderRadius.values[0].value */;
}Reading confidence levels
理解置信度等级
Dembrandt scores every color by semantic context:
| Confidence | Meaning |
|---|---|
| high | Appears on semantically labeled elements (buttons, CTAs, headers with brand classes). Almost certainly a brand color. |
| medium | Moderate frequency or moderate context. Likely a brand color. |
| low | Rare, low semantic context. May be a one-off or component-specific color. |
Since 0.28.0 confidence also has a usage floor, as spacing and radii always had: a colour seen once caps at low, twice at medium, and high needs three occurrences whatever its semantic context scores. Hover and focus colours are the exception and keep medium — their single occurrence is provenance, not a usage claim.
Start with confidence colors when building a palette. Include for full coverage. Treat as reference only.
highmediumlowDembrandt会根据语义上下文为每个颜色评分:
| 置信度 | 含义 |
|---|---|
| 高 | 出现在带有语义标记的元素上(按钮、CTA、带有品牌类的标题)。几乎可以确定为品牌色。 |
| 中 | 出现频率中等或上下文相关性中等。很可能是品牌色。 |
| 低 | 出现次数少、语义上下文弱。可能是一次性或组件专属颜色。 |
从0.28.0版本开始,置信度还增加了使用量阈值,与间距和圆角的规则一致:仅出现一次的颜色最高为低置信度,出现两次为中置信度,无论语义上下文评分如何,出现三次及以上才会评为高置信度。Hover和Focus颜色是例外,保持中置信度——它们的单次出现属于来源验证,而非使用量统计。
构建调色板时优先使用高置信度颜色。包含中置信度颜色以覆盖全部场景。低置信度颜色仅作为参考。
Colour notation
颜色表示法
Never convert a colour by hand and never re-derive one with your own maths. Every palette entry and every CSS variable already carries and alongside the hex, so read the field you need straight from the JSON. only changes what the terminal prints, so it is the wrong tool when you are consuming JSON or MCP output.
lchoklch--color-formatUse hex () as the identity of a colour: it is what dedup, drift comparison and every downstream tool key on. Two entries with the same hex are the same token even when their emitted notations differ. When an author declared a token in a modern notation, preserves it exactly, which is what you want when writing CSS back into that codebase, since it keeps the author's own notation and stays inside their gamut.
normalizedcssVariables[name].value切勿手动转换颜色,也不要用自己的算法重新推导颜色。每个调色板条目和CSS变量都已附带和值,可直接从JSON中读取所需字段。仅改变终端打印的颜色表示法,因此在使用JSON或MCP输出时,该参数并无作用。
lchoklch--color-format使用十六进制值()作为颜色的唯一标识:去重、漂移对比及所有下游工具均以此为依据。即使输出表示法不同,十六进制值相同的条目即为同一令牌。当作者使用现代表示法声明令牌时,会完全保留原始写法,这在将CSS写回原代码库时非常有用,因为它保留了作者的原始表示法并维持在其色域范围内。
normalizedcssVariables[name].valueFlags Reference
参数参考
| Flag | What it does |
|---|---|
| Clean JSON to stdout — pipe into files or tools |
| Save JSON to |
| W3C Design Tokens Community Group format |
| Generate |
| Self-contained HTML report (inline CSS, embedded JSON). Open offline or attach as a CI artifact. (0.19+) |
| Diff against a saved extraction; prints a drift verdict and exits |
| Generate a PDF brand guide |
| Extract dark color scheme and merge into palette |
| Extract at 390px mobile viewport |
| Crawl up to N pages and merge tokens |
| Discover pages from sitemap.xml |
| 3× timeouts — use on slow-loading or JS-heavy sites |
| Save a full-page screenshot |
| Include pre-filter raw colors in JSON output |
| Notation for colors printed to the terminal: |
| Write a Tailwind v4 |
| Use Firefox instead of Chromium |
| Opt-in anti-detection: navigator spoofing + human mouse simulation. Use only when authorized. |
| Custom user agent string |
| Browser locale, e.g. |
| Browser timezone, e.g. |
| Custom |
| Physical screen resolution to report, e.g. |
| 参数 | 功能 |
|---|---|
| 向标准输出打印纯净JSON — 可写入文件或传递给其他工具 |
| 将JSON保存到 |
| 输出W3C设计令牌社区组格式 |
| 生成 |
| 生成独立HTML报告(内联CSS、嵌入JSON)。可离线打开或作为CI产物附加。 (0.19+) |
| 与已保存的提取结果对比;打印漂移判定结果,若存在漂移则以状态码1退出。用于CI门禁。 (0.19+) |
| 生成PDF格式品牌指南 |
| 提取深色配色方案并合并到调色板中 |
| 以390px移动端视口进行提取 |
| 爬取最多N个页面并合并令牌 |
| 从sitemap.xml中发现页面 |
| 超时时间延长3倍 — 适用于加载缓慢或JS密集型网站 |
| 保存全页面截图 |
| 在JSON输出中包含未过滤的原始颜色 |
| 终端打印的颜色表示法: |
| 生成Tailwind v4 |
| 使用Firefox而非Chromium |
| 可选反检测模式:伪造导航信息 + 模拟人类鼠标操作。仅在获得授权时使用。 |
| 自定义User-Agent字符串 |
| 浏览器区域设置,例如 |
| 浏览器时区,例如 |
| 自定义 |
| 报告的物理屏幕分辨率,例如 |
Drift Detection & CI (dembrandt 0.19+)
漂移检测与CI集成 (dembrandt 0.19+)
--comparebash
undefined--comparebash
undefined1. capture a baseline (in the SAME environment you will check against)
1. 捕获基线(需与后续检查使用相同环境)
dembrandt https://app.example.com --json-only > baseline.json
dembrandt https://app.example.com --json-only > baseline.json
2. later — compare; exits 0 if stable, 1 if drifted
2. 后续检查 — 对比结果;稳定则返回状态码0,存在漂移则返回状态码1
dembrandt https://app.example.com --compare baseline.json --html report.html
- Runs the canonical drift engine over **structured tokens** — deterministic, not a pixel/render diff.
- **Exit code:** `0` stable, `1` drift. Gates a pipeline directly.
- `--html` writes a self-contained report; with `--compare` it includes a drift banner (added/removed/changed tokens). Attach it as a CI artifact.
**Baselines churn once on 0.28.0.** Three fixes move colour and typography values: the palette usage floor, `body` ending at the 24px reading range (non-heading text above it takes `text`, so hero copy stops landing on the body token), and families under 2% of counted text being dropped. Measured on dembrandt.com against a 0.27.1 extraction, drift came out at 15 against a threshold of 10 — enough to fail a gate. On the first run after upgrading, re-approve with `--compare <baseline> --approve` or regenerate the baseline. Drift after that is real drift.
**Determinism:** capture the baseline in the *same environment* you check it in (both production, or both the same preview). A baseline from one environment compared against another shows false drift.
**In CI:** run `--compare <baseline> --html report.html` against a preview/deployed URL, fail the job on exit `1`, upload the HTML artifact. **Programmatic:** import `computeDrift` from `dembrandt/drift` and `generateHtmlReport` from `dembrandt/report` to diff and render server-side without the CLI.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`重新确认或重新生成基线。之后出现的漂移即为真实漂移。
**确定性:**需在与后续检查相同的环境中捕获基线(均为生产环境,或均为同一预览环境)。不同环境的基线与提取结果对比会产生虚假漂移。
**在CI中使用:**针对预览/部署URL运行`--compare <baseline> --html report.html`,若退出码为1则终止任务,并上传HTML产物。**程序化使用:**从`dembrandt/drift`导入`computeDrift`,从`dembrandt/report`导入`generateHtmlReport`,无需CLI即可在服务端进行对比和渲染。Anti-Bot and SPA Handling
反机器人与SPA处理
Dembrandt handles common extraction challenges automatically:
- SPA hydration — waits 8s for React/Vue/Svelte to render before extracting
- Lazy content — scrolls the full page to trigger lazy-loaded components
- Cloudflare / bot walls — auto-retries with a visible browser if headless is blocked
- Slow sites — use for 3× timeouts on heavy JS bundles
--slow - Cookie banners — dismisses common CMP dialogs (OneTrust, cookielaw, GDPR patterns) automatically
- Bot detection bypass — use to opt in to navigator spoofing and human mouse simulation; off by default so the tool identifies itself honestly
--stealth
Dembrandt可自动处理常见的提取挑战:
- SPA hydration — 等待8秒让React/Vue/Svelte完成渲染后再提取
- 懒加载内容 — 滚动全页触发懒加载组件
- Cloudflare / 机器人墙 — 若无头浏览器被拦截,自动重试使用可视化浏览器
- 缓慢网站 — 使用参数为大型JS包设置3倍超时时间
--slow - Cookie横幅 — 自动关闭常见的CMP弹窗(OneTrust、cookielaw、GDPR模式)
- 机器人检测绕过 — 使用参数可选择伪造导航信息和模拟人类鼠标操作;默认关闭,工具会如实标识自身
--stealth
Checklist After Extraction
提取后检查清单
- Identify the 3–5 high-confidence colors — these are the core brand palette
- Check — is it correct?
colors.semantic.primary - Look at — what are the heading and body fonts?
typography.styles - Check — 4px or 8px grid?
spacing.scaleType - Review — how many variants exist?
components.buttons - Check — is Tailwind, shadcn, or MUI detected? This shapes how you apply the tokens.
frameworks - Use if the site has a dark theme
--dark-mode - Use if the site has a multi-section design system spread across routes
--crawl 3
- 识别3-5个高置信度颜色 — 这些是核心品牌调色板
- 检查— 是否正确?
colors.semantic.primary - 查看— 标题和正文字体是什么?
typography.styles - 检查— 是4px还是8px网格?
spacing.scaleType - 查看— 存在多少种变体?
components.buttons - 检查— 是否检测到Tailwind、shadcn或MUI?这会影响令牌的应用方式。
frameworks - 若网站支持深色模式,使用参数
--dark-mode - 若网站的设计系统分布在多个路由中,使用参数
--crawl 3