Technical Briefing: design-extract

The Problem

Extracting a complete design system from a live website has traditionally been fragmented and manual. Teams typically capture colors and fonts but miss layout patterns, responsive behavior, interaction states, and accessibility metrics. This creates synchronization gaps between design and development, as the extracted tokens decay out of date and the underlying architecture remains opaque.

What This Does

design-extract is a collection of four projects (src, website, chrome-extension, bin) that crawls any website with a headless browser and extracts the complete design system. It produces eight output files: AI-optimized markdown, visual HTML preview, W3C design tokens, Tailwind config, CSS custom properties, Figma variables, React theme, and shadcn/ui globals. Beyond colors and typography, it extracts layout systems (55 grids, 492 flex containers), captures responsive behavior across four breakpoints, records interaction states (hover, focus, active), scores WCAG accessibility, and supports multi-brand sync via --platforms <csv> which emits ios/, android/, flutter/, and wordpress-theme/ directories. A companion *-mcp.json enables region/component/health data serving via the MCP server.

Output structure includes 19 markdown sections: Color Palette, Typography, Spacing, Border Radii, Box Shadows, CSS Custom Properties, Breakpoints, Transitions & Animations, Component Patterns, Layout System, Responsive Design, Interaction States, Accessibility (WCAG 2.1), Gradients, Z-Index Map, SVG Icons, Font Files, and Quick Start.

How It Is Wired

Execution starts at start in bin/design-extract.js:117, which reaches 98 functions. The primary extraction flow flows through extractDesignLanguage in src/index.js:34 (reaches 11 functions, called from 6 places), which invokes safeExtract (27 calls) and mostCommonStyle (17 calls). Color transformation flows through rgbToHex and rgbToHsl (each called from 6 places), with oklabToRgb and oklchToRgb defined in src/utils.js (19 functions, hub module — 13 modules depend on it).

The import graph contains 103 modules with 198 edges and 5 modules in circular dependencies (src/index.js, src/apply.js, src/multibrand.js). src/utils.js is the highest-blast-radius hub: degrade here ripples widely. The MCP server entry point is run in src/mcp/server.js:62 (reaches 7 functions, called from 1 place). The CLI check command lives at check in bin/design-extract.js:642 (reaches 19 functions).

How To Use It

Setup: npx designlang https://example.com (no install needed) or npm install -g designlang for global use. As a Claude Code/Cursor/Windsurf skill: npx skills add Manavarya09/design-extract.

Configuration: No environment variables or API keys required — the tool crawls publicly accessible sites. For MCP server mode, ensure the src/mcp/ configuration is deployed.

Running it:

npx designlang https://stripe.com
# Full extraction with all platforms and agent rules:
npx designlang https://stripe.com --full --platforms ios,android,flutter,wordpress --emit-agent-rules

Output files are written to a folder named by the target URL domain, containing the eight design files plus optional *-mcp.json.

Real-World Use

A design system team needs to rebuild a marketing site in React using shadcn/ui. They point design-extract at the live site, receive a *-design-language.md file that feeds directly to an LLM for code generation, a *-shadcn-theme.css for immediate integration, and a *-design-tokens.json for the token pipeline. The WCAG accessibility report surfaces contrast failures before merge. The layout system extraction provides the grid/flex architecture as documentation, eliminating the reverse-engineering step.

Code Health & Issues

Static analysis of 103 JavaScript files found 58 issues across 6 kinds:

  • [HIGH] Import cycle member — src/index.js, src/apply.js, src/multibrand.js participate in circular imports. Fix: extract shared types, invert a dependency, or defer an import.
  • [HIGH] Pin third-party GitHub Actions to commit SHA — .github/workflows references @vN instead of 40-character SHAs. Fix: replace with commit SHAs; let Dependabot bump them.
  • [HIGH] CI does not invoke the test suite — 15 test files exist but no test command in any GitHub Actions workflow. Fix: add a test step to existing workflows.
  • [MEDIUM] Oversized files — src/crawler.js (806 lines), bin/design-extract.js (806 lines), tests/extractors.test.js. Fix: split into cohesive units by responsibility.
  • [MEDIUM] Deep nesting — website/app/components/A11ySlider.js, website/app/components/HeroExtractor.js max indentation depth 6. Fix: flatten with guard clauses.
  • [MEDIUM] Duplicated code — 26 repeated 6-line blocks across 16 files including src/formatters/_token-ref.js, website/lib/token-helpers.js. Fix: extract shared helpers.
  • [MEDIUM] Deps unmanaged — No Dependabot or Renovate configured across 2 manifest files. Fix: commit .github/dependabot.yml covering package ecosystems and github-actions.
  • [MEDIUM] Least-privilege GITHUB_TOKEN — 1 workflow declares no permissions; 1 references secrets. Fix: add permissions: contents: read at workflow top.
  • [LOW] No workflow timeouts — .github/workflows/manavarya-bot.yml has no timeout-minutes. Fix: add realistic bounds.

The Bottom Line

The extraction quality and output variety are genuine — eight file formats, layout/system capture, and multi-platform emitters are real capabilities, not marketing. The codebase shows signs of rapid growth without corresponding structural investment: circular imports, outsized files, and CI that doesn't run assertions. It is functional for greenfield adoption but requires disciplined refactoring (particularly the import cycles and test wiring) before it should be relied upon in a regulated or long-lived codebase. Teams needing quick design-to-code conversion will find immediate value; those requiring maintainable, evolving extraction pipelines should budget for the identified technical debt.