--- name: design-mirror description: Mirror web UI designs with precision — extract styles, layout, motion, and generate replica pages for verification. --- # Design Mirror Mirror any web UI with precision. This skill extracts complete design systems from websites — colors, typography, spacing, layout, components, and motion — then generates documentation and standalone replica pages for visual verification. **Strategy**: Structured data first, screenshots as optional supplement. ## MCP Requirements | MCP | Purpose | Required | |-----|---------|----------| | `chrome-devtools` | Browser interaction: navigation, script injection, screenshots, state triggers | ✅ Required | **MCP Tools Used**: - `navigate_page` — Navigate to target URL - `evaluate_script` — Inject and execute extraction scripts - `take_screenshot` — Capture page\/element screenshots - `click` \/ `hover` — Trigger interaction states - `take_snapshot` — Capture page DOM snapshot ## Output location (REQUIRED) - Save all generated deliverables under: `.\/style\/` - Create the `style\/` directory if it does not exist - Never write generated outputs under the skill folder (`.codex\/skills\/...`) Recommended structure: ``` style\/ ├── -style.md # Style guide document (for reading) ├── -evidence\/ # Extraction evidence (JSON\/CSS\/JS) └── -replica\/ # Replica page (for verification) ├── index.html ├── styles.css └── scripts.js ``` ## Reference - `references\/complete-examples\/motherduck-design-system-style.md` — Complete Style Guide example, demonstrating: - CSS Variables definition format - Font Requirements (Web Font loading) - Component Internals (internal structure) - Image Dimensions (placeholder sizing) - Replica Validation (verification checklist) --- ## Available Scripts | Script | Namespace | Purpose | |--------|-----------|---------| | `scripts\/dom-snapshot.js` | `window.__dmDom` | Complete styles + DOM structure + pseudo elements | | `scripts\/layout-tools.js` | `window.__dmLayout` | Flex\/grid layout + container dimensions | | `scripts\/css-vars-extractor.js` | `window.__dmCssVars` | CSS variable definitions + usage | | `scripts\/asset-manifest.js` | `window.__dmAssets` | Fonts \/ icons \/ third-party libraries | | `scripts\/state-differ.js` | `window.__dmState` | State trigger + style diff (hover\/focus\/active) | | `scripts\/motion-tools.js` | `window.__dmMotion` | Animation capture + quickAudit | | `scripts\/library-detect.js` | (returns object) | Third-party library detection | | `scripts\/extract-keyframes.py` | CLI | Offline @keyframes extraction from CSS | | `scripts\/screenshot-optimizer.py` | CLI | Compress\/resize screenshots | --- ## Workflow > **Workflow Overview**: > - Phase 0: Define inputs and output type > - Phase 1: Structured data extraction (bulk extraction) > - Phase 1.5: Screenshots (optional supplement) > - Phase 2: Semantic token generation > - Phase 2.5: Font loading preparation > - Phase 3: Write Style Guide documentation > - Phase 4: Generate Replica page > - **Phase 4.5: Component-level style validation (CRITICAL for accuracy)** ⬅️ Most commonly skipped step ### Phase 0 — Inputs 1) Project name + style\/variant name 2) Sources: URL \/ web repo \/ both 3) Motion importance: if meaningful motion exists, motion capture is required 4) **Output type** (IMPORTANT - determines replica structure): - `layout-replica` (**DEFAULT**): Replicate original page layout structure for validating extraction accuracy - `component-showcase`: Generate component showcase page, grouped by type (for design system documentation) **Intent Detection Rules**: | User Expression | Output Type | |-----------------|-------------| | "replicate", "mirror", "clone", "copy page" | `layout-replica` | | "component library", "design system", "showcase", "component gallery" | `component-showcase` | | Not specified | `layout-replica` (default) | ### Phase 1 — Structured Data Extraction (PRIMARY) > **Core principle**: Extract structured JSON data that can be directly used for replication, rather than relying on screenshots that require visual interpretation. #### Step 1: Inject Tool Scripts Navigate to target page, then inject scripts via `evaluate_script`: ```javascript \/\/ Inject in this order: \/\/ 1. dom-snapshot.js \/\/ 2. layout-tools.js \/\/ 3. css-vars-extractor.js \/\/ 4. asset-manifest.js \/\/ 5. state-differ.js \/\/ 6. motion-tools.js ``` #### Step 2: Extract Core Data Run these extractions in order: ```javascript \/\/ 1. CSS Variables (tokens that are already defined) const cssVars = __dmCssVars.extractAll(); \/\/ 2. Page skeleton (layout structure) - CRITICAL for layout-replica const skeleton = __dmLayout.skeleton(); \/\/ 3. Asset manifest (fonts, icons, libraries) const assets = __dmAssets.scan(); \/\/ 4. Interactive elements with full styles const interactive = __dmDom.captureInteractive(); \/\/ 5. State differences (hover\/focus\/active) const states = await __dmState.auditInteractive(); \/\/ 6. Motion audit (transitions + animations) const motion = __dmMotion.quickAudit(); ``` #### Step 3: Deep Component Extraction For key components, extract detailed information: ```javascript \/\/ Navigation __dmDom.capture('.navbar', { children: true }); __dmLayout.inspect('.navbar'); \/\/ Primary button __dmDom.capture('.btn-primary'); await __dmState.diff('.btn-primary'); \/\/ Cards __dmDom.capture('.card'); __dmLayout.inspect('.card-container'); \/\/ Forms __dmDom.captureMany(['input', 'textarea', 'select']); ``` #### Step 3.5: Component Internal Structure Extraction (CRITICAL) > **This step ensures icons, thumbnails, and decorative elements within components are not lost** For each key component, extract its **internal child element structure**: ```javascript \/\/ Extract component internal structure function extractComponentInternals(selector) { const component = document.querySelector(selector); if (!component) return null; const children = Array.from(component.children); return { selector: selector, childCount: children.length, children: children.map((child, index) => { const style = getComputedStyle(child); const rect = child.getBoundingClientRect(); return { index: index, tag: child.tagName.toLowerCase(), className: child.className, \/\/ Critical dimension info dimensions: { width: rect.width + 'px', height: rect.height + 'px', aspectRatio: rect.width \/ rect.height }, \/\/ Background info (image\/gradient\/color) background: { color: style.backgroundColor, image: style.backgroundImage, size: style.backgroundSize, position: style.backgroundPosition }, \/\/ Whether it's an image element isImage: child.tagName === 'IMG', imageSrc: child.tagName === 'IMG' ? child.src : null, \/\/ Whether it's an SVG icon isSvg: child.tagName === 'SVG' || child.querySelector('svg') !== null, \/\/ Border and radius borderRadius: style.borderRadius, border: style.border }; }) }; } \/\/ Execute for all key components const components = [ '.calendar-card', '.vip-card', '.tag-card', '.image-card', '.nav-item' ]; const componentInternals = {}; components.forEach(selector => { componentInternals[selector] = extractComponentInternals(selector); }); console.log('Component Internals:', componentInternals); ``` **Save this data to the `componentInternals` field in `extracted-data.json`.** #### Step 3.6: Image\/Icon Dimensions Extraction (CRITICAL) > **Ensure all image and icon dimensions are recorded for generating correctly-sized placeholders** ```javascript \/\/ Extract all image dimensions function extractImageDimensions() { const images = document.querySelectorAll('img'); return Array.from(images).map(img => { const rect = img.getBoundingClientRect(); const style = getComputedStyle(img); return { src: img.src, alt: img.alt, \/\/ Actual rendered dimensions (for placeholders) renderedWidth: rect.width, renderedHeight: rect.height, aspectRatio: rect.width \/ rect.height, \/\/ CSS dimension settings cssWidth: style.width, cssHeight: style.height, objectFit: style.objectFit, \/\/ Parent container info parentClass: img.parentElement?.className || '', parentDimensions: { width: img.parentElement?.getBoundingClientRect().width, height: img.parentElement?.getBoundingClientRect().height } }; }); } \/\/ Extract all SVG icon dimensions function extractSvgDimensions() { const svgs = document.querySelectorAll('svg'); return Array.from(svgs).map(svg => { const rect = svg.getBoundingClientRect(); return { width: rect.width, height: rect.height, viewBox: svg.getAttribute('viewBox'), parentClass: svg.parentElement?.className || '' }; }); } const imageDimensions = extractImageDimensions(); const svgDimensions = extractSvgDimensions(); ``` **Save output to the `imageDimensions` and `svgDimensions` fields in `extracted-data.json`.** #### Step 4: Layout Pattern Extraction ```javascript \/\/ Find all flex\/grid containers const containers = __dmLayout.auditContainers(); \/\/ Inspect specific layouts __dmLayout.inspect('.hero-section'); __dmLayout.inspect('.card-grid'); __dmLayout.inspect('.footer'); ``` #### Step 5: Section-Level Layout Extraction (CRITICAL for Layout Replica) > **This step is critical for preventing layout detail omissions** For each major section on the page, extract its internal layout structure: ```javascript \/\/ Iterate all major sections, extract layout patterns const sections = document.querySelectorAll('section, [class*="section"], [class*="block"], main > div'); sections.forEach((section, index) => { const sectionData = { index: index, className: section.className, \/\/ 1. Section overall layout layout: { display: getComputedStyle(section).display, flexDirection: getComputedStyle(section).flexDirection, gridTemplateColumns: getComputedStyle(section).gridTemplateColumns, gap: getComputedStyle(section).gap, alignItems: getComputedStyle(section).alignItems, justifyContent: getComputedStyle(section).justifyContent }, \/\/ 2. Section header layout (commonly missed!) header: extractSectionHeader(section), \/\/ 3. Child container layouts childContainers: extractChildContainers(section) }; console.log(`Section ${index}:`, sectionData); }); \/\/ Extract section header layout pattern function extractSectionHeader(section) { const header = section.querySelector('[class*="header"], [class*="title"], h2, h3'); if (!header) return null; const parent = header.parentElement; const siblings = Array.from(parent.children); return { element: header.className || header.tagName, parentLayout: { display: getComputedStyle(parent).display, flexDirection: getComputedStyle(parent).flexDirection, justifyContent: getComputedStyle(parent).justifyContent, alignItems: getComputedStyle(parent).alignItems }, siblingCount: siblings.length, \/\/ Detect horizontal sibling elements (e.g., title + category tabs) hasHorizontalSiblings: getComputedStyle(parent).display === 'flex' && getComputedStyle(parent).flexDirection === 'row' }; } \/\/ Extract child container layouts function extractChildContainers(section) { const containers = section.querySelectorAll('[class*="grid"], [class*="list"], [class*="cards"], [class*="tabs"]'); return Array.from(containers).map(c => ({ className: c.className, display: getComputedStyle(c).display, flexWrap: getComputedStyle(c).flexWrap, gap: getComputedStyle(c).gap })); } ``` **Save output to the `sectionLayouts` field in `extracted-data.json`.** The purpose of this step is to: 1. **Systematic traversal** rather than relying on manual observation 2. Auto-detect each section's **header layout pattern** (horizontal\/vertical) 3. Record **child container flex\/grid configurations** 4. Generate a reviewable layout manifest for reference when generating replica ### Phase 1.5 — Screenshots (OPTIONAL SUPPLEMENT) > Screenshots are now **optional**, only needed for: > - Complex gradients\/textures that can't be fully described in CSS > - Visual composition verification > - States that are hard to capture programmatically **If screenshots are needed:** #### Step 1: Take Screenshot (MCP) ```javascript \/\/ Use take_screenshot tool \/\/ Prefer webp format (best compression ratio) mcp__chrome-devtools__take_screenshot({ format: "webp", \/\/ Prefer webp, fallback to jpeg quality: 80, \/\/ Compression quality fullPage: false \/\/ Prefer viewport screenshots over full page }); ``` #### Step 2: Validate & Compress (MANDATORY) > ⚠️ **Each screenshot MUST be validated for size and compressed immediately after saving** ```bash # Check file sizes ls -lh evidence\/*.png evidence\/*.webp evidence\/*.jpg 2>\/dev\/null # If exceeds 2MB, use optimization script python scripts\/screenshot-optimizer.py evidence\/fullpage.png --max-size 2MB --out evidence\/fullpage.jpg ``` **Screenshot Specifications:** | Rule | Requirement | |------|-------------| | **Format** | WebP (preferred) > JPEG > PNG (prohibited for large images) | | **Single file size** | < 2MB | | **Total count** | Maximum 5-6 screenshots | | **Priority** | Element-level > Viewport > Full page screenshots | | **Compression** | Must validate and compress immediately after saving | **Automatic Compression Workflow:** ```python # Run immediately after taking screenshot import subprocess from pathlib import Path def ensure_screenshot_size(filepath: str, max_mb: float = 2.0): """Ensure screenshot does not exceed specified size""" path = Path(filepath) size_mb = path.stat().st_size \/ (1024 * 1024) if size_mb > max_mb: print(f"⚠️ {path.name} is {size_mb:.1f}MB, compressing...") output = path.with_suffix('.jpg') subprocess.run([ 'python', 'scripts\/screenshot-optimizer.py', str(path), '--out', str(output), '--max-size', f'{max_mb}MB' ]) # Delete original PNG if output.exists() and path.suffix == '.png': path.unlink() print(f"✓ Compressed to {output.name}") else: print(f"✓ {path.name} is {size_mb:.1f}MB (OK)") ``` ### Phase 2 — Semantic Tokenization (REQUIRED) Convert extracted data into semantic tokens: 1. **From CSS Variables**: Use existing `--var-name` definitions from `__dmCssVars.extractAll()` 2. **From Computed Styles**: Cluster repeated values from `__dmDom.captureInteractive()` 3. **From State Diffs**: Extract transition patterns from `__dmState.auditInteractive()` 4. **From Layout**: Extract spacing\/sizing patterns from `__dmLayout.skeleton()` 5. **From Motion**: Extract timing tokens from `__dmMotion.quickAudit()` 6. **From Component Internals**: Extract child element dimensions from Step 3.5 7. **From Image Dimensions**: Extract placeholder sizes from Step 3.6 Token naming convention: ```css --color-[purpose]: #value; \/* accent, text, surface, border *\/ --space-[size]: Npx; \/* 4, 8, 12, 16, 24, 32 *\/ --motion-[duration]: Nms; \/* 100, 200, 300, 600 *\/ --ease-[type]: function; \/* default, inout, emphasis *\/ --radius-[size]: Npx; \/* sm, md, lg *\/ ``` ### Phase 2.5 — Font Loading Preparation (REQUIRED) > **Ensure replica page correctly loads and displays fonts** Based on `__dmAssets.scanFonts()` results, identify Web Fonts that need loading: ```javascript \/\/ Analyze font loading requirements function analyzeFontRequirements(fonts) { const results = { webFonts: [], \/\/ Fonts to load from CDN systemFonts: [], \/\/ System fonts (no loading required) fontFaceRules: [] \/\/ @font-face rules to generate }; \/\/ Common system font list const systemFontList = [ '-apple-system', 'BlinkMacSystemFont', 'Segoe UI', 'PingFang SC', 'Microsoft YaHei', 'Hiragino Sans GB', 'Helvetica Neue', 'Helvetica', 'Arial', 'sans-serif', 'Apple Color Emoji', 'Segoe UI Emoji', 'Segoe UI Symbol' ]; fonts.loaded.forEach(font => { const isSystem = systemFontList.some(sys => font.family.toLowerCase().includes(sys.toLowerCase()) ); if (!isSystem) { results.webFonts.push({ family: font.family, weight: font.weight, style: font.style }); } else { results.systemFonts.push(font.family); } }); return results; } ``` **Common Web Font Loading Solutions:** | Font | Loading Method | |------|----------------| | Alibaba Sans | `` or Google Fonts | | Noto Sans SC | `` | | Source Han Sans | Adobe Fonts or local @font-face | | Custom fonts | Download font files and generate @font-face | **Save output to `fontRequirements` field in `extracted-data.json`.** ### Phase 3 — Write the Style Guide #### Required Sections (minimum) 1. **Overview** — project summary, visual signatures 2. **Design Philosophy** — principles, constraints 3. **CSS Variables** — extracted + proposed semantic tokens 4. **Color Palette** — with usage mapping 5. **Typography** — families, scale, weights 6. **Spacing System** — scale + usage 7. **Layout Patterns** — page skeleton + component layouts + responsive breakpoints 8. **Component Styles** — key components with full styles 9. **State Matrix** — hover\/focus\/active\/disabled for interactive elements 10. **Animation Checklist** — transitions + keyframes + delay chains 11. **Asset Dependencies** — fonts, icons, third-party libraries 12. **Accessibility Styles** — focus-visible, reduced-motion, color-scheme 13. **Copy-Paste Examples** — 5+ ready-to-use code snippets #### Section Templates See `references\/section-templates.md` for standard formats. ### Phase 4 — Replica Page Generation Generate a standalone HTML page for visual verification. **Output type determines structure.** #### Output Structure ``` style\/ ├── -style.md # Style guide document ├── -evidence\/ # Extraction evidence └── -replica\/ # Replica page ├── index.html # Main page ├── styles.css # All styles (tokens + components + states + animations) └── scripts.js # Interactions + animations ``` --- ## Replica Type A: Layout Replica (DEFAULT) > **Use case**: When user requests "replicate", "mirror", or "clone" a page > **Core objective**: Generate a replica page matching the original page's layout structure ### Layout Replica Requirements **0. Layout Structure (CRITICAL)** - ⚠️ **Strictly follow** the page structure extracted by `__dmLayout.skeleton()` - Section order must exactly match the original page - Internal section layouts (flex\/grid direction, gap, alignment) must match - **Prohibited**: Reorganizing content into "showcase" or "component gallery" format - Fixed-position elements (sidebar, header, floating buttons) must maintain original positioning **0.5. Web Font Loading (CRITICAL)** > **Ensure fonts display correctly, not falling back to system fonts** Based on `fontRequirements` data, add font loading in ``: ```html