{
  "markdown": "# DesignScan\n\nURL → design tokens → `DESIGN.md`. Point it at any website and get a\nspec-compliant [DESIGN.md](https://github.com/google-labs-code/design.md) file\n(YAML tokens + prose) that AI coding agents can read to match that site's look.\n\n## Preview\n\nEvery run can also emit a self-contained HTML proof sheet (`--preview`) that\nrenders the extracted tokens — color roles, type specimens, spacing/radius\nscales, components — so you can eyeball the result before trusting it:\n\n[![DesignScan preview proof sheet for stripe.com](examples/stripe.preview.png)](examples/stripe.preview.html)\n\n## Notes for your coding agent\n\nA `DESIGN.md` is always *consumed by an AI coding agent* (Cursor, Claude Code, …).\nSo rather than run our own LLM to resolve semantic intent, every file ends with a\n**Notes for your coding agent** section: deterministic, per-extraction\ninstructions computed from the actual tokens — heading hierarchy vs. a muted\n`text` color, sub-AA body contrast, brand-font fallback, the primary-button\ncontract, shape/spacing rhythm. The reasoning stays on our side (no API key); the\n*application* happens for free inside the agent you already use.\n\nIt measurably changes the output. Below: the same `stripe.DESIGN.md` cloned by an\nagent that **ignored** the notes (left) vs one that **followed** them (right) —\nidentical tokens, layout, and copy:\n\n![Same DESIGN.md, with vs without the agent notes](examples/agent-notes.proof.png)\n\n## Brand corpus\n\nA growing, curated library of real-brand specs lives in [`examples/`](examples) —\neach one a `DESIGN.md`, an HTML preview, and the raw token JSON, indexed in\n[`examples/README.md`](examples/README.md) (visual gallery: [`index.html`](examples/index.html)).\n\n[![DesignScan brand corpus gallery](examples/gallery.png)](examples/README.md)\n\nRebuild it from the committed JSON with `pnpm seed rebuild` (no network), or add\nbrands with `pnpm seed add <url>` — degenerate / bot-challenged pages are skipped\nautomatically so the corpus only holds trustworthy specs.\n\n## Monorepo layout\n\n| Path | What |\n|------|------|\n| [`packages/extractor`](packages/extractor) | The extraction + generation engine (Playwright → tokens → `DESIGN.md`). |\n| [`packages/designscan`](packages/designscan) | The short npm name — a thin CLI shim over the engine (`npx designscan <url>`). |\n| [`examples/`](examples) | The brand corpus — `DESIGN.md` + HTML preview + token JSON per brand, with a gallery index. |\n\n## Install (as a CLI / library)\n\nThe engine ships as the publishable [`@designscan/extractor`](packages/extractor)\npackage — a `designscan` CLI and a typed library — with\n[`designscan`](packages/designscan) as its short npx alias.\n\n```bash\n# one-off, no install\nnpx designscan stripe.com --md --out stripe.DESIGN.md\n\n# or install the CLI\nnpm i -g @designscan/extractor\nnpx playwright install chromium   # one-time (the engine drives headless Chromium)\ndesignscan stripe.com --md --preview --out stripe.DESIGN.md\n```\n\n## Quick start (from this repo)\n\nThis is a [pnpm](https://pnpm.io) workspace (`corepack enable` to get pnpm).\n\n```bash\npnpm install\npnpm --filter @designscan/extractor exec playwright install chromium  # one-time\n\n# token profile (JSON) for any URL\npnpm extract stripe.com\n\n# generate a DESIGN.md (light theme by default)\npnpm extract stripe.com --md --out out/stripe.DESIGN.md\n\n# pick a theme: light (default) | dark | both\npnpm extract vercel.com --md --theme dark --out out/vercel.dark.DESIGN.md\n\n# both = bundle light + dark into one file (parallel *-dark tokens)\npnpm extract vercel.com --md --theme both --out out/vercel.DESIGN.md\n\n# --preview = also write a self-contained HTML proof sheet beside the file,\n# rendering every token (swatches, type specimens, scales, components) so you\n# can eyeball the extraction before trusting it (--theme both adds a Light/Dark toggle)\npnpm extract stripe.com --md --preview --out out/stripe.DESIGN.md\n# → out/stripe.DESIGN.md  +  out/stripe.preview.html\n\n# --format = pick your output: json (profile) | md (DESIGN.md) | w3c | css\npnpm extract stripe.com --format w3c --out out/stripe.tokens.json  # W3C Design Tokens (Style Dictionary etc.)\npnpm extract stripe.com --format css --out out/stripe.tokens.css   # CSS custom properties, paste-ready\n# (--theme both folds a genuinely distinct dark pass into every format)\n\n# --strict = exit non-zero if the result looks degenerate (bot challenge / too\n# few signals), for CI/automation that must not consume junk tokens\npnpm extract stripe.com --strict --quiet\n\n# seed / rebuild the curated brand corpus under examples/\npnpm seed add tailwindcss.com vercel.com   # extract live + add to the corpus\npnpm seed rebuild                          # regen md/preview/gallery from JSON\n```\n\n## Scripts (root)\n\n| Script | Does |\n|--------|------|\n| `pnpm extract <url> [--format json\\|md\\|w3c\\|css] [--theme light\\|dark\\|both] [--preview] [--strict] [--timeout ms] [--out f]` | Extract tokens in your format: profile JSON, `DESIGN.md` (`--md` shorthand), W3C Design Tokens, or CSS custom properties (`--theme both` = light + dark in one file; `--preview` = HTML proof sheet beside it; `--strict` = non-zero exit on a degenerate result) |\n| `pnpm seed rebuild` / `pnpm seed add <url…>` | Build the brand corpus under `examples/` (md + preview + gallery; `add` extracts live) |\n| `pnpm build` | Compile the publishable package (`tsc` → `dist`) |\n| `pnpm typecheck` | Type-check all packages |\n| `pnpm test` | Run the test suite (vitest) |\n| `pnpm check` | Biome — format + lint (use `pnpm format` to auto-fix) |\n| `pnpm lint:designmd` | Validate `examples/*.DESIGN.md` against the official spec |\n\nAll of these run on every push/PR via [GitHub Actions](.github/workflows/ci.yml).\nThe engine is consumable as a library through its public API\n([`packages/extractor/src/index.ts`](packages/extractor/src/index.ts)).\n\n## Status\n\n- [x] **Step 1 — Extraction engine** (Playwright → clean token profile)\n- [x] **Step 2 — Generator** (token profile → spec-valid `DESIGN.md`, lint-clean)\n- [x] **Step 3 — HTML preview** (`--preview` → self-contained token proof sheet, light/dark toggle)\n- [~] **Step 4** — agent guidance. Each `DESIGN.md` now ships a **Notes for your\n      coding agent** section: deterministic, per-extraction instructions (contrast,\n      heading hierarchy, font fallback) so the consuming agent applies the tokens\n      with intent — no LLM on our side. (Optional LLM-refined prose still future.)\n- [~] **Step 5** — brand-seed library (`pnpm seed`, curated [corpus](examples) + gallery) done; `npx … add` / checkout next\n\nSee [`packages/extractor/README.md`](packages/extractor/README.md) for the full\nroadmap and engine details.\n",
  "bytes": 6682,
  "sha": "480834ae36e6d12ebc7725e25558dda9862516453442d74b869c89e19a3cb016",
  "repo_slug": "ms-zaman/designscan",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_ms_zaman_designscan_29a2739a/readme"
}