DesignScan

DesignScan

URL → 设计令牌 → DESIGN.md。将任意网站 URL 交给它，即可生成符合规范的 DESIGN.md 文件（YAML 令牌 + 文本说明），供 AI 编码 Agent 阅读并匹配该网站的视觉风格。

预览

每次运行还可以生成一份独立的 HTML 效果预览（--preview），呈现提取的令牌——颜色角色、字体样张、间距/圆角比例、组件——让你在信任结果之前先直观检查：

给编码 Agent 的说明

DESIGN.md 总是由 AI 编码 Agent 使用（Cursor、Claude Code 等）。 因此，我们不会自行运行大模型来判断语义意图，而是在每个文件末尾加入 给编码 Agent 的说明部分：根据实际令牌计算得出的确定性提取指引，涵盖标题层级与低饱和度 text 颜色的关系、低于次级 AA 标准的正文对比度、品牌字体回退、主按钮规范、形状/间距节奏。推理过程由我们负责（无需 API 密钥）；你已经在使用的 Agent 会免费完成应用。

这会显著影响输出。下方展示的是同一份 stripe.DESIGN.md：左侧由忽略说明的 Agent 克隆，右侧由遵循说明的 Agent 克隆——令牌、布局和文案完全相同：

品牌资料库

examples/ 中收录了不断扩充、经过筛选的真实品牌规范库——每个品牌都有一份 DESIGN.md、一个 HTML 预览和原始令牌 JSON，并在 examples/README.md 中编入索引（视觉图库：index.html）。

使用 pnpm seed rebuild 从已提交的 JSON 重建资料库（无需网络），或使用 pnpm seed add <url> 添加品牌——系统会自动跳过退化页面或受到机器人验证拦截的页面，确保资料库只收录可信的规范。

Monorepo 布局

路径	内容
packages/extractor	提取与生成引擎（Playwright → 令牌 → DESIGN.md）。
packages/designscan	简短的 npm 名称——引擎外层的轻量 CLI 封装（npx designscan <url>）。
examples/	品牌资料库——每个品牌包含 DESIGN.md、HTML 预览和令牌 JSON，并提供图库索引。

安装（作为 CLI / 库）

引擎以可发布的 @designscan/extractor 软件包形式提供，包含 designscan CLI 和带类型的库；另提供 designscan 作为简短的 npx 别名。

# one-off, no install
npx designscan stripe.com --md --out stripe.DESIGN.md

# or install the CLI
npm i -g @designscan/extractor
npx playwright install chromium   # one-time (the engine drives headless Chromium)
designscan stripe.com --md --preview --out stripe.DESIGN.md

快速开始（从此仓库开始）

这是一个 pnpm 工作区（运行 corepack enable 获取 pnpm）。

pnpm install
pnpm --filter @designscan/extractor exec playwright install chromium  # one-time

# token profile (JSON) for any URL
pnpm extract stripe.com

# generate a DESIGN.md (light theme by default)
pnpm extract stripe.com --md --out out/stripe.DESIGN.md

# pick a theme: light (default) | dark | both
pnpm extract vercel.com --md --theme dark --out out/vercel.dark.DESIGN.md

# both = bundle light + dark into one file (parallel *-dark tokens)
pnpm extract vercel.com --md --theme both --out out/vercel.DESIGN.md

# --preview = also write a self-contained HTML proof sheet beside the file,
# rendering every token (swatches, type specimens, scales, components) so you
# can eyeball the extraction before trusting it (--theme both adds a Light/Dark toggle)
pnpm extract stripe.com --md --preview --out out/stripe.DESIGN.md
# → out/stripe.DESIGN.md  +  out/stripe.preview.html

# --format = pick your output: json (profile) | md (DESIGN.md) | w3c | css
pnpm extract stripe.com --format w3c --out out/stripe.tokens.json  # W3C Design Tokens (Style Dictionary etc.)
pnpm extract stripe.com --format css --out out/stripe.tokens.css   # CSS custom properties, paste-ready
# (--theme both folds a genuinely distinct dark pass into every format)

# --strict = exit non-zero if the result looks degenerate (bot challenge / too
# few signals), for CI/automation that must not consume junk tokens
pnpm extract stripe.com --strict --quiet

# seed / rebuild the curated brand corpus under examples/
pnpm seed add tailwindcss.com vercel.com   # extract live + add to the corpus
pnpm seed rebuild                          # regen md/preview/gallery from JSON

脚本（根目录）

脚本	功能
pnpm extract <url> [--format json|md|w3c|css] [--theme light|dark|both] [--preview] [--strict] [--timeout ms] [--out f]	按指定格式提取令牌：配置 JSON、DESIGN.md（--md 简写）、W3C Design Tokens 或 CSS 自定义属性（--theme both = 在一个文件中同时输出浅色 + 深色主题；--preview = 在旁边生成 HTML 效果预览；--strict = 结果退化时以非零状态码退出）
pnpm seed rebuild / pnpm seed add <url…>	构建 examples/ 下的品牌资料库（md + 预览 + 图库；add 会实时提取）
pnpm build	编译可发布的软件包（tsc → dist）
pnpm typecheck	对所有软件包进行类型检查
pnpm test	运行测试套件（vitest）
pnpm check	Biome——格式化 + lint（使用 pnpm format 自动修复）
pnpm lint:designmd	根据官方规范验证 examples/*.DESIGN.md

每次推送/PR 时，以上脚本都会通过 GitHub Actions 运行。 该引擎也可通过其公共 API 作为库使用 （packages/extractor/src/index.ts）。

状态

• 步骤 1 — 提取引擎（Playwright → 干净的令牌配置文件）
• 步骤 2 — 生成器（令牌配置文件 → 符合规范的 DESIGN.md，通过 lint 检查）
• 步骤 3 — HTML 预览（--preview → 独立的令牌演示页，可切换浅色／深色模式）
• [~] 步骤 4 — Agent 指引。现在，每个 DESIGN.md 都包含 给编码 Agent 的说明部分：针对每次提取生成确定性指引（对比度、标题层级、字体回退），让使用令牌的 Agent 能有目的地应用令牌——我们这边不使用大模型。（可选的大模型优化文案仍在未来计划中。）
• [~] 步骤 5 — 品牌种子库（pnpm seed，精选语料库 + 图库）已完成；下一步是 npx … add / checkout

完整路线图和引擎详情请参见 packages/extractor/README.md。