TypeUI DESIGN.md Extractor (Chrome Extension)

---
name: design-md-chrome-extractor
description: Chrome extension that extracts design tokens from any website and generates DESIGN.md or SKILL.md files for use with AI coding agents
triggers:
  - extract design system from website
  - generate DESIGN.md from site styles
  - create design skill for AI agent
  - extract colors and typography from webpage
  - generate SKILL.md design file
  - build design system documentation from URL
  - capture website design tokens
  - create TypeUI design blueprint
---

# TypeUI DESIGN.md Extractor (Chrome Extension)

> Skill by [ara.so](https://ara.so) — Daily 2026 Skills collection.

A Chrome extension that reads visual styles from any live website — typography, colors, spacing, border radius, shadows, and motion — and generates structured `DESIGN.md` or `SKILL.md` files compatible with AI coding agents like Claude Code, Cursor, Codex, and Google Stitch.

---

## What It Does

- **Auto-extracts** computed CSS styles from any active browser tab
- **Generates `DESIGN.md`** — a human-readable design system documentation file
- **Generates `SKILL.md`** — an agent-ready skill file for AI coding assistants
- Follows the open-source [TypeUI DESIGN.md](https://www.typeui.sh/design-skills) format
- Outputs downloadable markdown files for immediate use in AI workflows

---

## Installation (Developer / Load Unpacked)

```bash
# 1. Clone the repository
git clone https://github.com/bergside/design-md-chrome.git
cd design-md-chrome

# 2. Open Chrome and navigate to extensions
# chrome://extensions

# 3. Enable Developer Mode (toggle top-right)

# 4. Click "Load unpacked" and select the project folder

After loading:

• The extension icon appears in your Chrome toolbar
• Navigate to any website
• Click the extension icon to open the popup

---

Project Structure

design-md-chrome/
├── manifest.json          # Chrome extension manifest (MV3)
├── popup.html             # Extension popup UI
├── popup.js               # Popup logic, UI interactions, file download
├── content.js             # Content script — injected into active tab to extract styles
├── background.js          # Service worker for Chrome extension messaging
├── generator.js           # DESIGN.md / SKILL.md markdown generation logic
├── tests/
│   └── run-tests.mjs      # Node.js test runner
└── README.md

---

How Style Extraction Works

The content script (content.js) is injected into the active tab and uses getComputedStyle to sample elements across the DOM, collecting:

Token Category	What Gets Extracted
Typography	Font families, sizes, weights, line heights, letter spacing
Colors	Background, text, border, and accent colors (deduped)
Spacing	Margin/padding values across key elements
Border Radius	Extracted from buttons, cards, inputs
Shadows	box-shadow values from elevated elements
Motion	transition and animation properties

Example: Content Script Extraction Pattern

// content.js — core extraction logic pattern
function extractDesignTokens() {
  const elements = document.querySelectorAll(
    'h1, h2, h3, p, a, button, input, [class*="card"], [class*="container"]'
  );

  const tokens = {
    typography: new Set(),
    colors: new Set(),
    spacing: new Set(),
    borderRadius: new Set(),
    shadows: new Set(),
    motion: new Set(),
  };

  elements.forEach((el) => {
    const styles = window.getComputedStyle(el);

    // Typography
    tokens.typography.add({
      fontFamily: styles.fontFamily,
      fontSize: styles.fontSize,
      fontWeight: styles.fontWeight,
      lineHeight: styles.lineHeight,
      letterSpacing: styles.letterSpacing,
    });

    // Colors
    tokens.colors.add(styles.color);
    tokens.colors.add(styles.backgroundColor);
    tokens.colors.add(styles.borderColor);

    // Spacing
    tokens.spacing.add(styles.padding);
    tokens.spacing.add(styles.margin);

    // Radius
    tokens.borderRadius.add(styles.borderRadius);

    // Shadows
    if (styles.boxShadow !== 'none') {
      tokens.shadows.add(styles.boxShadow);
    }

    // Motion
    if (styles.transition !== 'all 0s ease 0s') {
      tokens.motion.add(styles.transition);
    }
  });

  return {
    typography: [...tokens.typography],
    colors: [...tokens.colors].filter(Boolean),
    spacing: [...tokens.spacing].filter(Boolean),
    borderRadius: [...tokens.borderRadius].filter(Boolean),
    shadows: [...tokens.shadows],
    motion: [...tokens.motion],
    url: window.location.href,
    title: document.title,
  };
}

// Send extracted tokens back to popup via Chrome messaging
chrome.runtime.onMessage.addListener((request, sender, sendResponse) => {
  if (request.action === 'extractStyles') {
    sendResponse(extractDesignTokens());
  }
});

---

Triggering Extraction from Popup

// popup.js — trigger content script and receive tokens
async function runExtraction() {
  const [tab] = await chrome.tabs.query({ active: true, currentWindow: true });

  // Inject content script if not already present
  await chrome.scripting.executeScript({
    target: { tabId: tab.id },
    files: ['content.js'],
  });

  // Request extraction
  chrome.tabs.sendMessage(tab.id, { action: 'extractStyles' }, (tokens) => {
    if (chrome.runtime.lastError) {
      console.error('Extraction failed:', chrome.runtime.lastError.message);
      return;
    }
    displayTokens(tokens);
    window.__extractedTokens = tokens; // store for generation
  });
}

document.getElementById('btn-extract').addEventListener('click', runExtraction);

---

Generating DESIGN.md

// generator.js — generate DESIGN.md from extracted tokens
function generateDesignMd(tokens) {
  const { url, title, typography, colors, spacing, borderRadius, shadows, motion } = tokens;

  return `# DESIGN.md — ${title}

## Mission
Define a consistent, accessible design system for ${title} (${url}).

## Brand
- **Product**: ${title}
- **URL**: ${url}
- **Audience**: Web users
- **Surface**: Web application

## Style Foundations

### Typography
${typography.map(t => `- Font: ${t.fontFamily}, Size: ${t.fontSize}, Weight: ${t.fontWeight}`).join('\n')}

### Colors
${colors.slice(0, 20).map(c => `- \`${c}\``).join('\n')}

### Spacing
${[...new Set(spacing)].slice(0, 10).map(s => `- ${s}`).join('\n')}

### Border Radius
${[...new Set(borderRadius)].slice(0, 8).map(r => `- ${r}`).join('\n')}

### Shadows
${shadows.slice(0, 6).map(s => `- ${s}`).join('\n')}

### Motion
${motion.slice(0, 6).map(m => `- ${m}`).join('\n')}

## Accessibility
- Follow WCAG 2.2 AA standards
- Minimum contrast ratio: 4.5:1 for text, 3:1 for UI components
- All interactive elements must have visible focus states
- Support keyboard navigation throughout

## Writing Tone
- Implementation-ready and precise
- Avoid ambiguity in component descriptions
- Use design token references over raw values

## Rules: Do
- Use extracted color tokens consistently
- Apply spacing scale from extracted values
- Maintain border radius consistency per component type
- Use motion values for transitions

## Rules: Don't
- Do not introduce new colors outside the extracted palette
- Do not use arbitrary spacing values
- Do not remove focus indicators
- Do not use motion that violates prefers-reduced-motion

## Quality Gates
- [ ] All colors reference extracted tokens
- [ ] Typography scale applied consistently
- [ ] WCAG AA contrast validated
- [ ] Keyboard navigation verified
`;
}

---

Generating SKILL.md

// generator.js — generate agent-ready SKILL.md
function generateSkillMd(tokens) {
  const { url, title } = tokens;

  return `---
name: ${title.toLowerCase().replace(/\s+/g, '-')}-design-system
description: Design system skill extracted from ${title} (${url})
triggers:
  - implement ${title} design
  - use ${title} styles
  - apply ${title} design system
  - build UI matching ${title}
---

# ${title} Design System Skill

Extracted design system from ${url}.

## Style Foundations
[...generated token documentation...]

## Component Patterns
[...inferred patterns from extracted styles...]
`;
}

---

Downloading Generated Files

// popup.js — download as .md file
function downloadMarkdown(content, filename) {
  const blob = new Blob([content], { type: 'text/markdown' });
  const url = URL.createObjectURL(blob);
  const a = document.createElement('a');
  a.href = url;
  a.download = filename;
  a.click();
  URL.revokeObjectURL(url);
}

// Usage
document.getElementById('btn-download-design').addEventListener('click', () => {
  const tokens = window.__extractedTokens;
  const content = generateDesignMd(tokens);
  downloadMarkdown(content, 'DESIGN.md');
});

document.getElementById('btn-download-skill').addEventListener('click', () => {
  const tokens = window.__extractedTokens;
  const content = generateSkillMd(tokens);
  downloadMarkdown(content, 'SKILL.md');
});

---

Using Generated Files with AI Agents

Claude Code

# Place DESIGN.md in your project root
cp ~/Downloads/DESIGN.md ./DESIGN.md

# Reference in CLAUDE.md
echo "Follow the design system defined in DESIGN.md" >> CLAUDE.md

Cursor

# Add to .cursorrules
Follow the design system documented in DESIGN.md for all UI implementations.

Codex / OpenAI

# Pass as context file
codex --context DESIGN.md "build a login page"

Google Stitch

Upload DESIGN.md as a project reference document in the Stitch workspace.

---

Running Tests

# Run the test suite locally (Node.js required)
node tests/run-tests.mjs

Writing Tests

// tests/run-tests.mjs
import { generateDesignMd, generateSkillMd } from '../generator.js';

const mockTokens = {
  url: 'https://example.com',
  title: 'Example Site',
  typography: [
    { fontFamily: 'Inter, sans-serif', fontSize: '16px', fontWeight: '400', lineHeight: '1.5', letterSpacing: '0px' }
  ],
  colors: ['rgb(0, 0, 0)', 'rgb(255, 255, 255)', 'rgb(59, 130, 246)'],
  spacing: ['16px', '24px', '32px'],
  borderRadius: ['4px', '8px', '9999px'],
  shadows: ['0 1px 3px rgba(0,0,0,0.1)'],
  motion: ['all 0.2s ease'],
};

// Test DESIGN.md generation
const designMd = generateDesignMd(mockTokens);
console.assert(designMd.includes('## Mission'), 'Missing Mission section');
console.assert(designMd.includes('Inter, sans-serif'), 'Missing font family');
console.assert(designMd.includes('WCAG'), 'Missing accessibility section');
console.log('✅ DESIGN.md generation tests passed');

// Test SKILL.md generation
const skillMd = generateSkillMd(mockTokens);
console.assert(skillMd.includes('---'), 'Missing YAML frontmatter');
console.assert(skillMd.includes('triggers:'), 'Missing triggers');
console.log('✅ SKILL.md generation tests passed');

---

Manifest Configuration (MV3)

{
  "manifest_version": 3,
  "name": "TypeUI DESIGN.md Extractor",
  "version": "1.0.0",
  "description": "Extract design tokens from any website and generate DESIGN.md / SKILL.md",
  "permissions": [
    "activeTab",
    "scripting",
    "downloads"
  ],
  "action": {
    "default_popup": "popup.html",
    "default_icon": "icon.png"
  },
  "background": {
    "service_worker": "background.js"
  },
  "content_scripts": [],
  "host_permissions": [
    "<all_urls>"
  ]
}

Note: "content_scripts" is intentionally empty — scripts are injected programmatically via chrome.scripting.executeScript for on-demand extraction only.

---

Available Extension Actions

Button	Action
Auto-extract	Injects content script and collects computed styles
Generate DESIGN.md	Produces design system documentation from tokens
Generate SKILL.md	Produces agent-ready skill file from tokens
Refresh	Re-runs extraction for current page state
Download	Saves the generated file locally
? (Explain)	Shows how the file was generated with TypeUI reference

---

Troubleshooting

Extension not extracting styles

Problem: Extension shows no data after clicking extract
Fix: Refresh the page, then re-click extract. Some SPAs need full load.

// Check if content script is reachable
chrome.tabs.sendMessage(tabId, { action: 'ping' }, (response) => {
  if (chrome.runtime.lastError) {
    // Re-inject the content script
    chrome.scripting.executeScript({
      target: { tabId },
      files: ['content.js'],
    });
  }
});

CORS / CSP blocked pages

Problem: Extension cannot inject scripts on chrome://, file://, or CSP-restricted pages
Fix: Navigate to a public HTTP/HTTPS website. Extension requires scripting access.

Empty color palette

Problem: Colors list is empty or shows only defaults
Fix: Scroll through the page before extracting — lazy-loaded components need to render first.

Download not triggering

Problem: Download button clicks but no file appears
Fix: Check Chrome's download settings. Ensure the "downloads" permission is in manifest.json.

Tests failing in Node.js

# Ensure you're using Node.js 18+ for ESM support
node --version  # should be v18+

# Run with explicit ESM flag if needed
node --experimental-vm-modules tests/run-tests.mjs

---

Curated Design Skills

Browse pre-extracted design systems at typeui.sh/design-skills — ready-to-use SKILL.md files for popular products and design systems.

---

License

MIT — open source, free to use and modify.