# extract-design-system ## Metadata ```yaml task_id: extract-design-system version: 1.0.0 owner: ux-design-expert (Sati) consumers: - ux-design-expert - architect - dev elicit: true category: design-system-extraction complexity: HIGH estimated_tokens: ~2000 per execution ``` ## Purpose Reverse-engineer a complete design system from any source: live URL, source code repository, local codebase, or visual assets. Produces a comprehensive MASTER.md, tokens.css, tailwind.config.ts, and optionally saves to the Reference Store. This is the flagship extraction task in the LMAS design pipeline. It supports three input families (code, visual, hybrid) and auto-detects the optimal extraction strategy based on source type. The output is a production-ready design system package that can be consumed directly by `@dev` for implementation or by `@architect` for system-level decisions. --- ## Inputs | Input | Required | Type | Description | |-------|----------|------|-------------| | `source` | YES | string | URL, file/directory path, or image path to extract from | | `--mode` | NO | string | `source` \| `visual` \| `hybrid` (default: auto-detect) | | `--output` | NO | string | Output directory (default: `design-system/`) | | `--save-ref` | NO | boolean | Also save to Reference Store (`project-refs/design/`) | | `--name` | NO | string | Design system name (auto-detected if omitted) | | `--depth` | NO | string | Analysis depth: `quick` \| `standard` \| `deep` (default: `standard`) | | `--format` | NO | string | Output formats: `all` \| `css` \| `tailwind` \| `master` (default: `all`) | | `--dark-mode` | NO | boolean | Include dark mode token layer (default: `true`) | --- ## Execution Modes **Choose your execution mode:** ### 1. YOLO Mode - Fast, Autonomous (0-1 prompts) - Auto-detect everything, extract with defaults - Minimal user interaction - **Best for:** Quick extractions, known sources, CI pipelines ### 2. Interactive Mode - Balanced, Educational (5-10 prompts) **[DEFAULT]** - Confirm source detection and mode selection - Review extracted tokens before output generation - **Best for:** First extraction from a new source, learning the tool ### 3. Pre-Flight Planning - Comprehensive Upfront Planning - Full source audit before extraction begins - All naming conventions and output preferences decided upfront - **Best for:** Enterprise design systems, multi-brand extraction **Parameter:** `mode` (optional, default: `interactive`) **Usage:** ``` *extract-design-system {source} # Interactive (default) *extract-design-system {source} yolo # YOLO mode *extract-design-system {source} preflight # Pre-flight planning *extract-design-system {source} --depth deep --save-ref # Deep + reference store ``` --- ## Task Definition (LMAS Task Format V1.0) ```yaml task: extractDesignSystem() responsavel: Sati (Empathizer) responsavel_type: Agente atomic_layer: Organism inputs: - campo: source tipo: string origem: User Input obrigatorio: true validacao: URL, file path, directory path, or image path — must be accessible - campo: mode tipo: string origem: User Input obrigatorio: false validacao: source|visual|hybrid (auto-detect if omitted) - campo: output tipo: string origem: User Input obrigatorio: false validacao: Valid directory path, will be created if missing - campo: save_ref tipo: boolean origem: User Input obrigatorio: false validacao: true|false - campo: name tipo: string origem: User Input / Auto-detected obrigatorio: false validacao: Alphanumeric + hyphens, kebab-case - campo: depth tipo: string origem: User Input obrigatorio: false validacao: quick|standard|deep - campo: format tipo: string origem: User Input obrigatorio: false validacao: all|css|tailwind|master - campo: dark_mode tipo: boolean origem: User Input obrigatorio: false validacao: true|false saidas: - campo: master_document tipo: file destino: {output}/MASTER.md persistido: true - campo: css_tokens tipo: file destino: {output}/tokens.css persistido: true - campo: tailwind_config tipo: file destino: {output}/tailwind.config.ts persistido: true - campo: extraction_summary tipo: object destino: Console persistido: false - campo: reference_entry tipo: file destino: project-refs/design/{name}.yaml persistido: conditional (--save-ref) ``` --- ## Mode Selection (Auto-Detection) When `--mode` is not provided, auto-detect based on source type: | Source Type | Detection Pattern | Selected Mode | Rationale | |-------------|------------------|--------------|-----------| | Live URL | `https?://` (not GitHub) | `hybrid` | Source code extraction + visual analysis | | GitHub URL | `github.com/{owner}/{repo}` | `source` | Clone and analyze code directly | | GitLab URL | `gitlab.com/{owner}/{repo}` | `source` | Clone and analyze code directly | | Local directory | Path exists and `isDirectory()` | `source` | Direct file analysis | | Single CSS/SCSS file | `.css`, `.scss`, `.less` extension | `source` | Parse single stylesheet | | Single TS/JS file | `.ts`, `.js` with theme/token exports | `source` | Parse single config | | Single JSON/YAML file | `.json`, `.yaml`, `.yml` | `source` | Parse structured tokens | | Image file | `.png`, `.jpg`, `.jpeg`, `.webp`, `.svg` | `visual` | Claude vision analysis | | PDF file | `.pdf` | `visual` | Claude vision analysis | | Figma URL | `figma.com/` | `visual` | Screenshot + extraction | | Unknown | Anything else | `hybrid` | Try both, merge results | ### Depth Defaults by Source Type | Source Type | Default Depth | Pages Analyzed | Token Categories | |-------------|--------------|----------------|-----------------| | Live URL | `standard` | 1 (homepage) | All | | Live URL + `--depth deep` | `deep` | 3-5 key pages | All + component variants | | GitHub repo | `standard` | N/A | All found in config | | Local directory | `standard` | N/A | All found in files | | Image | `quick` | 1 | Colors, typography, spacing | | Image + `--depth deep` | `deep` | 1 | All + component identification | --- ## Constitutional Gates > **Reference:** Constitution Article IV (No Invention) > **Enforcement:** Automatic validation during extraction ### Gate 1: No Invention (Article IV) ```yaml constitutional_gate: article: IV name: No Invention severity: WARN validation: - Extracted tokens MUST come from actual source analysis - Visual-mode tokens MUST be marked as confidence: approximate - NEVER invent tokens that were not found in the source - Recommendations section clearly separated from extracted data on_violation: action: WARN message: | CONSTITUTIONAL WARNING: Article IV - No Invention All design tokens must trace to actual source data. Do not invent tokens or values not found in the source. ``` --- ## Pre-Conditions **Purpose:** Validate prerequisites BEFORE task execution (blocking) ```yaml pre-conditions: - [ ] Source is accessible (URL reachable, file/directory exists, image readable) tipo: pre-condition blocker: true validacao: | URL: HTTP HEAD returns 2xx or 3xx File: fs.existsSync(source) returns true Directory: fs.statSync(source).isDirectory() returns true error_message: "Source not accessible: {source}. Verify path/URL and try again." - [ ] Output directory is writable (or can be created) tipo: pre-condition blocker: true validacao: | Directory exists and is writable, or parent directory allows creation error_message: "Cannot write to output directory: {output}" - [ ] At least one extraction tool available (Browser MCP, Read tool, or gh CLI) tipo: pre-condition blocker: true validacao: | For URL sources: Browser MCP or fetch available For GitHub: gh CLI available For local: Read/Glob tools available (always true in Claude Code) error_message: "No extraction tools available for source type: {sourceType}" ``` --- ## Post-Conditions **Purpose:** Validate execution success AFTER task completes ```yaml post-conditions: - [ ] MASTER.md generated with at least colors and typography sections tipo: post-condition blocker: true validacao: | File exists at {output}/MASTER.md Contains ## Color Palette section with at least 1 token Contains ## Typography section with at least 1 font family error_message: "MASTER.md incomplete: missing core sections" - [ ] tokens.css generated with valid CSS custom properties tipo: post-condition blocker: true validacao: | File exists at {output}/tokens.css Contains :root { block Contains at least 1 --token-name: value; declaration error_message: "tokens.css invalid or empty" - [ ] tailwind.config.ts generated with valid TypeScript tipo: post-condition blocker: true validacao: | File exists at {output}/tailwind.config.ts Contains export default { block Contains theme.extend with at least colors key error_message: "tailwind.config.ts invalid or empty" - [ ] Extraction summary displayed with token counts tipo: post-condition blocker: false validacao: | Summary includes: source, mode, token counts by category, confidence level error_message: "Extraction summary incomplete" ``` --- ## Acceptance Criteria **Purpose:** Definitive pass/fail criteria for task completion ```yaml acceptance-criteria: - [ ] Design system extracted with tokens in at least 3 categories (colors, typography, spacing) tipo: acceptance-criterion blocker: true validacao: | Token count > 0 for colors AND typography AND spacing error_message: "Extraction too shallow: need tokens in at least 3 categories" - [ ] All output files are syntactically valid tipo: acceptance-criterion blocker: true validacao: | MASTER.md: valid markdown (headers, tables render) tokens.css: parseable CSS (no syntax errors) tailwind.config.ts: valid TypeScript syntax error_message: "Output files contain syntax errors" - [ ] Visual-mode tokens marked with approximate confidence tipo: acceptance-criterion blocker: true validacao: | If mode == visual or hybrid: All vision-derived values have confidence: approximate annotation error_message: "Visual tokens missing confidence annotations (Article IV)" - [ ] Reference store entry valid if --save-ref used tipo: acceptance-criterion blocker: false validacao: | If --save-ref: file exists at project-refs/design/{name}.yaml YAML is valid and follows reference-store-schema error_message: "Reference store entry invalid" ``` --- ## Execution Flow ### Step 1: Source Detection & Validation **Goal:** Determine source type, select extraction mode, validate accessibility. 1. **Parse source argument:** - If starts with `http://` or `https://` → URL type - If matches `github.com/{owner}/{repo}` → GitHub type - If matches `gitlab.com/{owner}/{repo}` → GitLab type - If matches `figma.com/` → Figma type - If path ends with image extension → Image type - If path ends with `.pdf` → PDF type - If path ends with `.css`, `.scss`, `.less` → Single stylesheet type - If path ends with `.ts`, `.js`, `.json`, `.yaml`, `.yml` → Single config type - If path is directory → Local directory type - Else → Unknown (try hybrid) 2. **Auto-select mode** (if `--mode` not provided): - Apply mapping from Mode Selection table above - Log: `Auto-detected mode: {mode} for source type: {sourceType}` 3. **Validate source accessibility:** ```javascript // URL validation async function validateURL(url) { try { // Try Browser MCP first const response = await navigateToURL(url); return { accessible: true, method: 'browser' }; } catch { // Fallback: try fetch/curl try { const result = await bash(`curl -sI -o /dev/null -w "%{http_code}" "${url}"`); const statusCode = parseInt(result.trim()); return { accessible: statusCode >= 200 && statusCode < 400, method: 'curl' }; } catch { return { accessible: false, method: null }; } } } // GitHub validation async function validateGitHub(url) { const match = url.match(/github\.com\/([^/]+)\/([^/]+)/); if (!match) return { accessible: false }; const [_, owner, repo] = match; try { await bash(`gh repo view ${owner}/${repo} --json name`); return { accessible: true, owner, repo }; } catch { return { accessible: false }; } } // Local path validation async function validateLocal(path) { // Use Glob/Read tools — always available in Claude Code const exists = await fileExists(path); const isDir = exists && await isDirectory(path); return { accessible: exists, isDirectory: isDir }; } ``` 4. **Set analysis depth** based on source type defaults (override with `--depth`) 5. **Auto-detect name** (if `--name` not provided): - URL: extract domain name (e.g., `stripe.com` → `stripe`) - GitHub: use repo name - Local dir: use directory name - File: use filename without extension - Image: use `visual-extraction-{timestamp}` --- ### Step 2: Extraction — Source Code Mode **Goal:** Extract design tokens from source code, config files, and stylesheets. #### 2a. Live Website (URL → Source Code) 1. **Navigate to URL** using Browser MCP (`mcp__claude-in-chrome__navigate`): ``` Navigate to: {source} Wait for: page fully loaded (DOMContentLoaded + 2s for dynamic content) ``` 2. **Extract CSS custom properties** from `:root` and all stylesheets: ```javascript // Execute in browser context via mcp__claude-in-chrome__javascript_tool (function extractDesignTokens() { const tokens = { customProperties: {}, colors: new Set(), fonts: new Set(), fontSizes: new Set(), fontWeights: new Set(), lineHeights: new Set(), spacings: new Set(), borderRadii: new Set(), shadows: [], transitions: new Set(), zIndices: new Set(), breakpoints: {} }; // 1. Extract CSS custom properties from all stylesheets try { for (const sheet of document.styleSheets) { try { for (const rule of sheet.cssRules) { if (rule.selectorText === ':root' || rule.selectorText === ':host') { for (const prop of rule.style) { if (prop.startsWith('--')) { tokens.customProperties[prop] = rule.style.getPropertyValue(prop).trim(); } } } } } catch (e) { // Cross-origin stylesheet — skip silently } } } catch (e) { // Stylesheets not accessible } // 2. Extract computed styles from all visible elements const elements = document.querySelectorAll('body *:not(script):not(style):not(link)'); const sampleSize = Math.min(elements.length, 500); // Cap at 500 elements for (let i = 0; i < sampleSize; i++) { const el = elements[i]; const computed = getComputedStyle(el); // Colors tokens.colors.add(computed.color); tokens.colors.add(computed.backgroundColor); tokens.colors.add(computed.borderColor); // Typography tokens.fonts.add(computed.fontFamily); tokens.fontSizes.add(computed.fontSize); tokens.fontWeights.add(computed.fontWeight); tokens.lineHeights.add(computed.lineHeight); // Spacing (collect unique padding/margin/gap values) ['padding', 'margin', 'gap', 'rowGap', 'columnGap'].forEach(prop => { const val = computed[prop]; if (val && val !== '0px' && val !== 'normal') tokens.spacings.add(val); }); // Border radius const radius = computed.borderRadius; if (radius && radius !== '0px') tokens.borderRadii.add(radius); // Box shadow const shadow = computed.boxShadow; if (shadow && shadow !== 'none') tokens.shadows.push(shadow); // Transitions const transition = computed.transition; if (transition && transition !== 'all 0s ease 0s') tokens.transitions.add(transition); // Z-index const zIndex = computed.zIndex; if (zIndex !== 'auto') tokens.zIndices.add(zIndex); } // 3. Detect media query breakpoints from stylesheets try { for (const sheet of document.styleSheets) { try { for (const rule of sheet.cssRules) { if (rule instanceof CSSMediaRule) { const match = rule.conditionText.match(/min-width:\s*(\d+)px/); if (match) tokens.breakpoints[match[1] + 'px'] = true; } } } catch (e) { /* cross-origin */ } } } catch (e) { /* no access */ } // Convert Sets to sorted Arrays return { customProperties: tokens.customProperties, colors: [...tokens.colors].filter(c => c !== 'rgba(0, 0, 0, 0)'), fonts: [...tokens.fonts], fontSizes: [...tokens.fontSizes].sort((a, b) => parseFloat(a) - parseFloat(b)), fontWeights: [...tokens.fontWeights].sort(), lineHeights: [...tokens.lineHeights], spacings: [...tokens.spacings].sort((a, b) => parseFloat(a) - parseFloat(b)), borderRadii: [...tokens.borderRadii], shadows: [...new Set(tokens.shadows)], transitions: [...tokens.transitions], zIndices: [...tokens.zIndices].sort((a, b) => Number(a) - Number(b)), breakpoints: Object.keys(tokens.breakpoints).sort((a, b) => parseInt(a) - parseInt(b)), elementCount: elements.length, sampledCount: sampleSize }; })(); ``` 3. **Take full-page screenshot** for visual cross-reference: ``` mcp__claude-in-chrome__get_page_text → capture page structure mcp__claude-in-chrome__computer → screenshot for visual analysis ``` 4. **Deep mode (--depth deep):** Navigate to additional pages: - Parse `