# DESIGN.md Extractor: Reverse-Engineer Any Website Design with Claude > A comprehensive guide to using the DESIGN.md Extractor skill for Claude Code: extracting visual tokens, generating DESIGN.md files, building interactive HTML previews, and exporting to Tailwind CSS. ## 1. What Is DESIGN.md Extractor and Why Extract Design Systems In modern web development, design systems are almost always proprietary, fragmented, or inaccessible: locked inside private Figma workspaces, scattered across dozens of CSS stylesheets, or residing solely in the minds of lead designers. When developers need to craft interfaces inspired by a reference site or rapidly adopt a client brand's visual language, they typically spend hours manually eyedropping hex values in DevTools and measuring button border radiuses with screen rulers. **DESIGN.md Extractor** is a specialized skill for Claude Code that automates the reverse-engineering of web UI design systems. The agent inspects a live page, extracts system tokens directly from the DOM and computed CSS styles, and synthesizes a machine-readable `DESIGN.md` specification alongside a self-contained visual showcase, `design-preview.html`. ```mermaid flowchart TD A["Target URL or Brand Name
'stripe.com'"] --> B["Claude Code + design-md-extractor"] B --> C["DOM & CSS Parser
(Read :root variables, compute styles)"] C --> D["Extract 4 Token Dimensions
(Colors, typography, spacing, shapes)"] D --> E["Generate DESIGN.md
(YAML specification + prose brief)"] D --> F["Build design-preview.html
(Offline UI kit powered by raw tokens)"] E & F --> G["Export to Tailwind CSS / Figma / Codebase"] ``` ### Manual Inspection vs. Automated Extraction | Phase | Manual DevTools Inspection | DESIGN.md Extractor Workflow | | :--- | :--- | :--- | | **Color Palette Extraction** | Manually copying individual `color` and `background` rules | Automated extraction of a complete token hierarchy (~35 tokens) from `:root` | | **Typography Analysis** | Sampling `font-size` on isolated heading elements | 7-level standardized scale with line-height and tracking rules | | **Grid & Spacing** | Heuristic guesses of margins and padding | Precise mathematical base grid unit (e.g. 8px increment scale) | | **Output Artifact** | Scattered notes or raw screenshots | Structured `DESIGN.md` file and interactive HTML UI kit | | **Turnaround Time** | 3 to 6 hours of repetitive labor | Under 60 seconds for an end-to-end extraction cycle | > [!NOTE] > The skill interacts with public, rendered client-side code to extract the exact CSS properties the browser uses for paint and layout operations, eliminating guesswork and human interpretation errors. --- ## 2. Architecture and Operating Principles: From URL to Design System The extraction pipeline consists of several interconnected execution phases designed to guarantee data fidelity. ### Step-by-Step Analysis Algorithm 1. **Page Ingestion and Rendering:** Claude navigates to the target URL, acquiring the complete HTML document and associated stylesheets. 2. **Parsing Global `:root` Variables:** The agent extracts all declared CSS custom properties (`--color-primary`, `--font-sans`, `--spacing-unit`, `--radius-lg`). 3. **Evaluating Computed Styles:** For elements lacking explicit CSS custom properties, the script samples high-signal components (buttons, headers, input fields, navigation bars) and reads actual browser computed styles. 4. **Token Normalization and Canonicalization:** Raw color values are converted to standard HEX or OKLCH, while font family definitions are mapped against Google Fonts or standard system fonts. 5. **Artifact Generation:** The agent generates the structured `DESIGN.md` specification and compiles the offline `design-preview.html` showcase. > [!TIP] > When evaluating sites built with utility-first frameworks like Tailwind CSS, the skill identifies classes like `p-4`, `rounded-xl`, and `bg-slate-900` to reconstruct the underlying Tailwind theme configuration. --- ## 3. Four Dimensions of Visual Tokens: Colors, Typography, Spacing, and Shapes DESIGN.md Extractor organizes visual tokens across four architectural pillars, creating an integrated design language. ### Color Palette (Colors) The extractor generates an expanded functional palette of approximately 35 tokens adhering to Material Design 3 and Radix UI patterns: - **Brand Accents:** `primary`, `secondary`, `tertiary`, paired with high-contrast foreground tokens like `on-primary` and `on-secondary`. - **Surfaces and Containers:** `background`, `surface`, `surface-variant`, `surface-container` (representing elevation tiers from base to elevated modals). - **System States:** `error`, `warning`, `success`, `info` alongside corresponding accessible text tokens. - **Neutrals and Dividers:** `outline`, `outline-variant`, `scrim`, and `shadow`. ### Typographic Hierarchy (Typography) The typography system is formalized into seven standardized functional scales: | Token Level | Primary Usage | Standard Size | Line Height | Font Weight | | :--- | :--- | :--- | :--- | :--- | | **`headline-xl`** | Hero banners, primary H1 | 48px – 64px | 1.1 – 1.15 | Bold / ExtraBold | | **`headline-lg`** | Section headings H2 | 32px – 40px | 1.2 | SemiBold | | **`title-md`** | Card and widget headers H3 | 20px – 24px | 1.3 | Medium / SemiBold | | **`body-lg`** | Lead paragraphs, intro copy | 18px | 1.5 – 1.6 | Regular | | **`body-md`** | Standard body copy | 15px – 16px | 1.5 – 1.6 | Regular | | **`label-md`** | Buttons, tabs, badges | 13px – 14px | 1.2 – 1.4 | Medium | | **`label-sm`** | Form hints, disclaimers | 11px – 12px | 1.3 | Regular / Medium | ### Spacing and Modular Grid (Spacing) The skill identifies the baseline spatial increment (typically 4px or 8px) and establishes a cohesive scale: - `xs` (4px), `sm` (8px), `md` (16px), `lg` (24px), `xl` (32px), `2xl` (48px). - In addition, macro layout constraints are captured: max container width (`max-width: 1280px`) and responsive gutter margins (`gutter: 24px`). ### Shapes and Elevation (Shapes & Elevation) - **Border Radiuses:** A scale extending from `none` (0px) to `full` (9999px for circular badges and pill buttons). - **Elevation Shadows:** Layered box-shadow tokens (`shadow-sm`, `shadow-md`, `shadow-xl`) that model physical component elevation. --- ## 4. Anatomy of DESIGN.md: YAML Specifications and Prose Sections A `DESIGN.md` file is structured as a hybrid document: the top section provides a strict YAML schema for linters, compilers, and code generators, while the bottom contains a comprehensive design brief for developers and AI agents. ### Example YAML Frontmatter ```yaml --- name: "Acme Cloud Platform" extractedFrom: "https://acme.example.com" version: "1.0.0" colors: primary: "#4F46E5" on-primary: "#FFFFFF" primary-container: "#EEF2FF" secondary: "#06B6D4" background: "#0F172A" surface: "#1E293B" surface-variant: "#334155" on-surface: "#F8FAFC" outline: "#475569" typography: fontFamilySans: "'Inter', -apple-system, sans-serif" fontFamilyMono: "'JetBrains Mono', monospace" headline-xl: fontSize: "48px" lineHeight: "1.1" fontWeight: "800" letterSpacing: "-0.02em" body-md: fontSize: "16px" lineHeight: "1.5" fontWeight: "400" letterSpacing: "0em" spacing: base: "8px" sm: "8px" md: "16px" lg: "24px" xl: "32px" shapes: borderRadiusSm: "4px" borderRadiusMd: "8px" borderRadiusLg: "16px" borderRadiusFull: "9999px" --- ``` ### Seven In-Depth Prose Sections Beneath the YAML frontmatter, the file provides seven detailed design guidelines: 1. **Brand & Style Personality:** Defines the voice and aesthetic posture (e.g. *"Minimalist engineering rigor inspired by Linear"* or *"Warm consumer fintech aesthetic like Stripe"*). 2. **Color Palette Rationale:** Prescribes token usage rules and enforces WCAG AA contrast compliance. 3. **Typography Rhythm:** Establishes vertical rhythm, optical kerning, and heading hierarchy. 4. **Layout & Spacing Philosophy:** Details responsive grid breakpoints, component padding, and container behavior. 5. **Elevation & Depth:** Guidelines for backdrop blur filters, gradients, and light-source shadow modeling. 6. **Shape & Border Language:** Corner radius consistency, stroke weights, and card borders. 7. **Component Blueprints:** Ready-to-implement structural recipes for buttons, inputs, cards, and navigation items. --- ## 5. Interactive Previews: Architecture of design-preview.html In addition to `DESIGN.md`, the skill compiles a standalone `design-preview.html` file that serves as an offline, interactive visual design showcase. ```mermaid flowchart LR subgraph design_preview_html["design-preview.html (Self-Contained Showcase)"] P["Color Swatches
(Click to copy HEX/RGB)"] T["Type Specimen
(Google Fonts preview)"] C["UI Sandbox
(Buttons, cards, inputs)"] S["Mockup View
(Synthesized landing block)"] end design_preview_html --> B["Open in Any Web Browser
(Zero dependencies, no local server required)"] ``` ### Key Advantages of the Self-Contained Preview - **Zero Dependencies:** No Node.js runtime, npm packages, or bundlers needed. Double-click the file in Finder or File Explorer to view instantly. - **Embedded Assets:** All icons and graphics are embedded as inline SVG or Base64 data URIs, ensuring complete functionality without an internet connection. - **One-Click Token Copy:** Clicking on any color swatch immediately copies its formatted hex or CSS variable string to the clipboard. - **Interactive State Validation:** All interactive components include fully rendered `:hover`, `:focus-visible`, `:active`, and `:disabled` states. --- ## 6. Installation and Execution in Claude Code The `design-md-extractor` skill responds to natural language commands or explicit slash invocations. ### Terminal Invocation Examples :::tabs @tab By Direct URL ```text /design-md-extractor https://linear.app ``` @tab By Brand Reference ```text Create a comprehensive DESIGN.md and preview for Stripe dashboard ``` @tab Local Prototype or Dev Server ```text Analyze the design system from our prototype at http://localhost:3000 and export DESIGN.md ``` ::: ### Execution Lifecycle 1. Claude Code launches the internal style-harvesting routines. 2. The agent reports progress in the terminal: parsing CSS custom properties, inspecting font weights, and computing component bounding boxes. 3. Upon completion, `DESIGN.md` and `design-preview.html` appear in the project root. 4. Claude prompts you to view the visual UI showcase via your browser (`open design-preview.html`). --- ## 7. Integrating Tokens into Tailwind CSS, Figma, and React Extracted tokens can be directly integrated into production workflows without manual reformatting. ### Exporting to Tailwind CSS Configuration Extend your `tailwind.config.ts` using the values extracted by the skill: ```typescript import type { Config } from 'tailwindcss'; const config: Config = { content: ['./src/**/*.{js,ts,jsx,tsx,mdx}'], theme: { extend: { colors: { brand: { primary: '#4F46E5', 'on-primary': '#FFFFFF', surface: '#1E293B', background: '#0F172A', }, }, borderRadius: { sm: '4px', md: '8px', lg: '16px', }, fontFamily: { sans: ['Inter', 'sans-serif'], }, }, }, plugins: [], }; export default config; ``` ### Binding to CSS Custom Properties Alternatively, import the extracted tokens into `globals.css`: ```css :root { --color-primary: #4f46e5; --color-on-primary: #ffffff; --color-surface: #1e293b; --radius-md: 8px; --spacing-base: 8px; } ``` ### Syncing with Figma via Tokens Studio Convert the YAML frontmatter into standard JSON (`tokens.json`) to import directly into the **Tokens Studio for Figma** plugin, automatically synchronizing Figma Variables with your codebase. --- ## 8. Practical Business Scenarios and Real-World Use Cases The design extractor provides tangible acceleration across product engineering and visual analytics. ### Four Primary Use Cases 1. **Competitor Benchmarking & Design Audits:** Deconstruct visual systems from industry benchmark products (Linear, Vercel, Apple, Stripe) before writing a single line of custom CSS. 2. **Client Project Onboarding:** Instead of waiting weeks for brand books or outdated design guidelines, extract live design tokens from the client's production web application in minutes. 3. **Rapid MVP Development Without a Dedicated Designer:** Founders and solo engineers can adopt the harmonious proportions and palettes of refined products, adjusting accent colors to launch high-polish MVPs quickly. 4. **Context Injection for Autonomous AI Agents:** The `DESIGN.md` file serves as system context for downstream coding agents, guaranteeing that generated components follow strict design tokens. --- ## 9. Hands-on Workshop: Extracting a Design System and Building a Component Follow this hands-on workflow to extract tokens and construct a production-ready React component. ### Step 1. Trigger the Extraction Workflow From your terminal, run the following prompt inside Claude Code: ```text Extract design system from https://news.ycombinator.com or your preferred inspiration website ``` Claude gathers live DOM styles and outputs `DESIGN.md`. ### Step 2. Inspect the Generated Visual Showcase Open the preview file in your web browser: ```bash open design-preview.html ``` Confirm that typography sizes, color contrasts, and component elevations accurately mirror the source product. ### Step 3. Generate a React Component from DESIGN.md Instruct Claude Code to build a component adhering to the generated specification: ```text Using the tokens and component rules defined in DESIGN.md, create a responsive PricingCard component in src/components/PricingCard.tsx with primary and secondary CTA buttons. ``` Claude references the exact radiuses, shadows, and colors from `DESIGN.md` to produce a production component: ```typescript import React from 'react'; interface PricingCardProps { title: string; price: string; features: string[]; isPopular?: boolean; } export const PricingCard: React.FC = ({ title, price, features, isPopular }) => { return (

{title}

{price}
); }; ``` --- ## 10. Self-Assessment and Production Checklist Test your comprehension of the design system extraction workflow. ### Review Questions > **1. Where does DESIGN.md Extractor source its exact color and typography parameters?** > > > [!TIP] > > **Answer:** The skill queries live CSS custom properties (`:root`) and computed styles directly from the rendered browser DOM, avoiding approximation or arbitrary guesswork. > **2. Which two primary artifacts are generated upon completing an extraction?** > > > [!TIP] > > **Answer:** A machine-readable `DESIGN.md` document (featuring YAML frontmatter and seven descriptive prose sections) and an offline visual UI preview in `design-preview.html`. > **3. How does DESIGN.md accelerate other Claude AI coding workflows?** > > > [!TIP] > > **Answer:** It acts as an authoritative design system context. AI coding agents read tokens directly from `DESIGN.md`, ensuring all newly generated UI components strictly match your chosen visual tokens. ### Production Readiness Checklist - [ ] `DESIGN.md` contains valid YAML frontmatter specifying core color, font, and spacing tokens. - [ ] All seven descriptive prose sections document the target brand's specific aesthetic without generic boilerplate. - [ ] `design-preview.html` opens cleanly in local browsers without script or console errors. - [ ] Verified that primary brand colors meet WCAG AA contrast ratios for accessible text display. - [ ] Extracted design tokens are mapped into `tailwind.config.ts` or `globals.css`. - [ ] Initial synthesized components have been validated against the target grid system.