designlang 1.0.0 → 2.0.0

package/README.md

@@ -1,17 +1,21 @@
 <p align="center">
   <h1 align="center">designlang</h1>
-  <p align="center">Extract the complete design language from any website.</p>
+  <p align="center">Extract the complete design language from any website in seconds.</p>
 </p>
 
 <p align="center">
   <a href="https://www.npmjs.com/package/designlang"><img src="https://img.shields.io/npm/v/designlang?color=blue&label=npm" alt="npm version"></a>
-  <a href="https://github.com/Manavarya09/designlangtract/blob/main/LICENSE"><img src="https://img.shields.io/github/license/Manavarya09/designlangtract" alt="license"></a>
+  <a href="https://github.com/Manavarya09/design-extract/blob/main/LICENSE"><img src="https://img.shields.io/github/license/Manavarya09/design-extract" alt="license"></a>
   <a href="https://nodejs.org"><img src="https://img.shields.io/node/v/designlang" alt="node version"></a>
 </p>
 
 ---
 
-**designlang** uses Playwright to headlessly crawl any website, extracts computed styles from the live DOM, and generates a full design system you can immediately use in your project. The primary output is an **AI-optimized markdown file** that an LLM can use to faithfully recreate the design.
+**designlang** crawls any website with a headless browser, extracts every computed style from the live DOM, and generates **8 output files** — including an AI-optimized markdown file, visual HTML preview, Tailwind config, Figma variables, React theme, shadcn/ui theme, W3C design tokens, and CSS custom properties.
+
+It also does **WCAG accessibility scoring**, **component screenshot capture**, **multi-page crawling**, **design comparison** between two sites, and **historical tracking** of how a site's design evolves over time.
+
+**No other tool does all of this from a single command.**
 
 ## Quick Start
 
@@ -19,134 +23,155 @@
 npx designlang https://stripe.com
 ```
 
-That's it. Four files appear in `./designlangtract-output/`:
+## What You Get (8 Files)
 
 | File | What it is |
 |------|------------|
-| `*-design-language.md` | AI-optimized markdown — the full design system in natural language with code examples |
-| `*-design-tokens.json` | [W3C Design Tokens](https://design-tokens.github.io/community-group/format/) format for tooling |
+| `*-design-language.md` | AI-optimized markdown — the full design system described for LLMs |
+| `*-preview.html` | Visual HTML report with swatches, type scale, shadows, a11y score |
+| `*-design-tokens.json` | [W3C Design Tokens](https://design-tokens.github.io/community-group/format/) for tooling |
 | `*-tailwind.config.js` | Drop-in Tailwind CSS theme extension |
 | `*-variables.css` | CSS custom properties ready to import |
+| `*-figma-variables.json` | Figma Variables import (with dark mode support) |
+| `*-theme.js` | React/CSS-in-JS theme object (Chakra, Stitches, Vanilla Extract) |
+| `*-shadcn-theme.css` | shadcn/ui globals.css theme variables |
 
 ## Install
 
 ```bash
-# Use directly with npx (no install needed)
+# Use directly (no install needed)
 npx designlang https://example.com
 
 # Or install globally
 npm install -g designlang
-designlang https://example.com
 ```
 
-> Playwright's Chromium is auto-installed on first run via the `postinstall` script.
+## Features
 
-## What It Extracts
-
-| Category | Details |
-|----------|---------|
-| **Colors** | Full palette with primary/secondary/accent/neutral classification, gradients, background & text colors |
-| **Typography** | Font families, type scale (heading/body/caption), weights, line heights, letter spacing |
-| **Spacing** | All unique values with automatic base-unit detection (e.g. 4px grid) |
-| **Border Radii** | Unique values labeled xs through full |
-| **Box Shadows** | Parsed and classified by visual weight (xs/sm/md/lg/xl) |
-| **CSS Variables** | All `:root` custom properties, categorized by type |
-| **Breakpoints** | Media query breakpoints with standard labels (sm/md/lg/xl) |
-| **Animations** | Transitions, easing functions, durations, `@keyframes` |
-| **Components** | Detected patterns for buttons, cards, inputs, links — with base styles |
+### Multi-Page Crawling
 
-## CLI Options
+Crawl multiple pages for a site-wide design system:
 
+```bash
+designlang https://stripe.com --depth 5
 ```
-designlang <url> [options]
 
-Options:
-  -o, --out <dir>       Output directory (default: ./designlangtract-output)
-  -n, --name <name>     Output file prefix (default: derived from URL hostname)
-  -w, --width <px>      Viewport width (default: 1280)
-  -h, --height <px>     Viewport height (default: 800)
-  --wait <ms>           Wait after page load for SPAs (default: 0)
-  --dark                Also extract dark mode color scheme
-  --verbose             Show detailed extraction progress
-  -V, --version         Show version
-  -h, --help            Show help
+### WCAG Accessibility Scoring
+
+Every extraction includes a WCAG 2.1 contrast analysis:
+
 ```
+A11y: 94% WCAG score (7 failing pairs)
+```
+
+Failing color pairs are highlighted in both the markdown and HTML preview with exact contrast ratios.
 
-### Examples
+### Component Screenshots
+
+Capture PNG screenshots of detected UI components:
 
 ```bash
-# Basic extraction
-designlang https://vercel.com
+designlang https://vercel.com --screenshots
+```
+
+Saves screenshots of buttons, cards, inputs, navigation, hero sections, and a full-page capture.
 
-# Custom output directory
-designlang https://stripe.com --out ./stripe-design
+### Visual HTML Preview
 
-# Extract dark mode too
-designlang https://github.com --dark
+Every run generates a `*-preview.html` file — a gorgeous dark-themed report you can open in your browser with:
+- Color swatches for the full palette
+- Live type scale rendering
+- Spacing scale visualization
+- Shadow cards with actual CSS shadows
+- Accessibility score and failing pair analysis
+- Component screenshots (when `--screenshots` is used)
 
-# Wait for SPA to render
-designlang https://app.example.com --wait 3000
+### Design Comparison
 
-# Custom viewport
-designlang https://example.com --width 1440 --height 900
+Compare two sites side-by-side:
+
+```bash
+designlang diff https://vercel.com https://stripe.com
 ```
 
-## The Markdown Output
+Generates `diff.md` and `diff.html` showing color, typography, spacing, and accessibility differences.
 
-The `*-design-language.md` file is the hero output. It's structured for AI/LLM consumption with:
+### Historical Tracking
 
-- Color palette tables with hex, RGB, and HSL values
-- Typography scale with size, weight, line-height, and letter-spacing
-- Spacing scale with token names and px/rem conversions
-- CSS code blocks for shadows, component patterns, and animations
-- A "Quick Start" section with step-by-step instructions to recreate the design
+Track how a site's design evolves over time:
 
-Feed it to any AI coding assistant and it can recreate the site's visual design from scratch.
+```bash
+# Each extraction auto-saves a snapshot
+designlang https://stripe.com
 
-## Claude Code Plugin
+# View history
+designlang history https://stripe.com
+```
 
-**designlang** also works as a [Claude Code](https://claude.ai/claude-code) plugin.
+Shows color changes, font swaps, accessibility score trends, and CSS variable count over time.
 
-After installing, use the `/extract-design` slash command:
+### Framework Themes
 
-```
-/extract-design https://stripe.com
-```
+Generates ready-to-use theme files for:
 
-Claude will extract the design, read the markdown output, and help you integrate it into your project.
+- **React/CSS-in-JS** — theme object compatible with Chakra UI, Stitches, Vanilla Extract
+- **shadcn/ui** — CSS variables in the exact format shadcn expects (paste into globals.css)
+- **Tailwind** — full theme extension with colors, fonts, spacing, radii, shadows, screens
 
-## How It Works
+## What It Extracts
+
+| Category | Details |
+|----------|---------|
+| **Colors** | Full palette with primary/secondary/accent/neutral classification, gradients |
+| **Typography** | Font families, type scale, heading/body styles, weight distribution |
+| **Spacing** | All unique values with automatic base-unit detection (4px/8px grid) |
+| **Border Radii** | Unique values labeled xs through full |
+| **Box Shadows** | Parsed and classified by visual weight |
+| **CSS Variables** | All `:root` custom properties, categorized |
+| **Breakpoints** | Media query breakpoints with standard labels |
+| **Animations** | Transitions, easing functions, durations, `@keyframes` |
+| **Components** | Buttons, cards, inputs, links — with base styles |
+| **Accessibility** | WCAG 2.1 contrast ratios for all fg/bg color pairs |
+
+## Full CLI Reference
 
-1. **Crawl** — Launches headless Chromium via Playwright, navigates to the URL, waits for network idle and font loading
-2. **Extract** — Runs a single `page.evaluate()` call that walks up to 5,000 DOM elements and collects computed styles, CSS custom properties, media queries, and keyframes
-3. **Process** — Nine extractor modules parse, deduplicate, cluster, and classify the raw style data into a unified design object
-4. **Format** — Four formatter modules generate the output files
+```
+designlang <url> [options]
 
-## Limitations
+Options:
+  -o, --out <dir>         Output directory (default: ./design-extract-output)
+  -n, --name <name>       Output file prefix (default: derived from URL)
+  -w, --width <px>        Viewport width (default: 1280)
+  --height <px>           Viewport height (default: 800)
+  --wait <ms>             Wait after page load for SPAs (default: 0)
+  --dark                  Also extract dark mode styles
+  --depth <n>             Pages to crawl (default: 0, just the URL)
+  --screenshots           Capture component screenshots
+  --framework <type>      Only generate specific theme (react, shadcn)
+  --no-history            Skip saving to history
+  --verbose               Detailed progress output
+
+Commands:
+  diff <urlA> <urlB>      Compare two sites' design languages
+  history <url>           View design history for a site
+```
 
-- **Cross-origin stylesheets** — CSS loaded from CDNs may not be inspectable via `document.styleSheets` (CORS). Computed styles are still captured since `getComputedStyle()` sees the final resolved values.
-- **Shadow DOM** — Elements inside closed shadow roots are not accessible. Open shadow roots are partially supported.
-- **CSS-in-JS** — Styles injected at runtime (styled-components, Emotion) are captured via computed styles but not as raw CSS rules.
-- **Element cap** — DOM traversal is capped at 5,000 elements to prevent hanging on very large pages.
+## How It Works
 
-## Tech Stack
+1. **Crawl** — Launches headless Chromium via Playwright
+2. **Extract** — `page.evaluate()` walks up to 5,000 DOM elements collecting computed styles
+3. **Process** — 10 extractor modules parse, deduplicate, cluster, and classify the raw data
+4. **Format** — 8 formatter modules generate the output files
+5. **Score** — Accessibility extractor calculates WCAG contrast ratios
+6. **Capture** — Optional Playwright screenshots of detected components
 
-- [Playwright](https://playwright.dev/) — headless browser automation
-- [Commander](https://github.com/tj/commander.js/) — CLI framework
-- [Chalk](https://github.com/chalk/chalk) + [Ora](https://github.com/sindresorhus/ora) — terminal styling
+## Claude Code Plugin
 
-Zero external dependencies for color parsing, clustering, or CSS processing — all handled with ~200 lines of pure JS utilities.
+**designlang** also works as a [Claude Code](https://claude.ai/claude-code) plugin. Use `/extract-design <url>` in your coding session.
 
 ## Contributing
 
-Contributions are welcome! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
-
-1. Fork the repo
-2. Create a feature branch (`git checkout -b feature/my-feature`)
-3. Make your changes
-4. Test on a few websites (`node bin/designlangtract.js https://example.com`)
-5. Commit and push
-6. Open a pull request
+See [CONTRIBUTING.md](CONTRIBUTING.md). PRs welcome!
 
 ## License
 

package/bin/design-extract.js

@@ -10,6 +10,11 @@ import { formatMarkdown } from '../src/formatters/markdown.js';
 import { formatTokens } from '../src/formatters/tokens.js';
 import { formatTailwind } from '../src/formatters/tailwind.js';
 import { formatCssVars } from '../src/formatters/css-vars.js';
+import { formatPreview } from '../src/formatters/preview.js';
+import { formatFigma } from '../src/formatters/figma.js';
+import { formatReactTheme, formatShadcnTheme } from '../src/formatters/theme.js';
+import { diffDesigns, formatDiffMarkdown, formatDiffHtml } from '../src/diff.js';
+import { saveSnapshot, getHistory, formatHistoryMarkdown } from '../src/history.js';
 import { nameFromUrl } from '../src/utils.js';
 
 const program = new Command();
@@ -17,40 +22,47 @@ const program = new Command();
 program
   .name('designlang')
   .description('Extract the complete design language from any website')
-  .version('1.0.0')
+  .version('2.0.0');
+
+// ── Main command: extract ──────────────────────────────────────
+program
   .argument('<url>', 'URL to extract design language from')
   .option('-o, --out <dir>', 'output directory', './design-extract-output')
   .option('-n, --name <name>', 'output file prefix (default: derived from URL)')
   .option('-w, --width <px>', 'viewport width', parseInt, 1280)
-  .option('-h, --height <px>', 'viewport height', parseInt, 800)
+  .option('--height <px>', 'viewport height', parseInt, 800)
   .option('--wait <ms>', 'wait after page load (ms)', parseInt, 0)
   .option('--dark', 'also extract dark mode styles')
+  .option('--depth <n>', 'number of internal pages to also crawl', parseInt, 0)
+  .option('--screenshots', 'capture component screenshots')
+  .option('--framework <type>', 'generate framework theme (react, shadcn)')
+  .option('--no-history', 'skip saving to history')
   .option('--verbose', 'show detailed progress')
   .action(async (url, opts) => {
-    // Ensure URL has protocol
     if (!url.startsWith('http')) url = `https://${url}`;
-
     const prefix = opts.name || nameFromUrl(url);
     const outDir = resolve(opts.out);
 
     console.log('');
-    console.log(chalk.bold('  design-extract'));
-    console.log(chalk.gray(`  ${url}`));
+    console.log(chalk.bold('  designlang'));
+    console.log(chalk.gray(`  ${url}${opts.depth > 0 ? ` (+ ${opts.depth} pages)` : ''}`));
     console.log('');
 
     const spinner = ora('Launching browser...').start();
 
     try {
-      spinner.text = 'Crawling page and extracting styles...';
+      spinner.text = `Crawling${opts.depth > 0 ? ` (depth: ${opts.depth})` : ''}...`;
       const design = await extractDesignLanguage(url, {
         width: opts.width,
-        height: opts.height,
+        height: parseInt(opts.height) || 800,
         wait: opts.wait,
         dark: opts.dark,
+        depth: opts.depth,
+        screenshots: opts.screenshots,
+        outDir,
       });
 
-      spinner.text = 'Generating output files...';
-
+      spinner.text = 'Generating outputs...';
       mkdirSync(outDir, { recursive: true });
 
       const files = [
@@ -58,12 +70,31 @@ program
         { name: `${prefix}-design-tokens.json`, content: formatTokens(design), label: 'Design Tokens (W3C)' },
         { name: `${prefix}-tailwind.config.js`, content: formatTailwind(design), label: 'Tailwind Config' },
         { name: `${prefix}-variables.css`, content: formatCssVars(design), label: 'CSS Variables' },
+        { name: `${prefix}-preview.html`, content: formatPreview(design), label: 'Visual Preview' },
+        { name: `${prefix}-figma-variables.json`, content: formatFigma(design), label: 'Figma Variables' },
       ];
 
+      // Framework-specific themes
+      if (opts.framework === 'react') {
+        files.push({ name: `${prefix}-theme.js`, content: formatReactTheme(design), label: 'React Theme' });
+      } else if (opts.framework === 'shadcn') {
+        files.push({ name: `${prefix}-shadcn-theme.css`, content: formatShadcnTheme(design), label: 'shadcn/ui Theme' });
+      } else {
+        // Generate both by default
+        files.push({ name: `${prefix}-theme.js`, content: formatReactTheme(design), label: 'React Theme' });
+        files.push({ name: `${prefix}-shadcn-theme.css`, content: formatShadcnTheme(design), label: 'shadcn/ui Theme' });
+      }
+
       for (const file of files) {
         writeFileSync(join(outDir, file.name), file.content, 'utf-8');
       }
 
+      // Save to history
+      if (opts.history !== false) {
+        const histInfo = saveSnapshot(design);
+        if (opts.verbose) spinner.info(`Snapshot #${histInfo.snapshotCount} saved for ${histInfo.hostname}`);
+      }
+
       spinner.succeed('Extraction complete!');
       console.log('');
       console.log(chalk.bold('  Output files:'));
@@ -72,12 +103,20 @@ program
         const sizeStr = size > 1024 ? `${(size / 1024).toFixed(1)}KB` : `${size}B`;
         console.log(`  ${chalk.green('✓')} ${chalk.cyan(file.name)} ${chalk.gray(`(${sizeStr})`)} — ${file.label}`);
       }
+      if (opts.screenshots && design.componentScreenshots && Object.keys(design.componentScreenshots).length > 0) {
+        for (const [, info] of Object.entries(design.componentScreenshots)) {
+          console.log(`  ${chalk.green('✓')} ${chalk.cyan(info.path)} — ${info.label} screenshot`);
+        }
+      }
       console.log('');
       console.log(chalk.gray(`  Saved to ${outDir}`));
 
-      // Summary stats
+      // Summary
       console.log('');
       console.log(chalk.bold('  Summary:'));
+      if (design.meta.pagesAnalyzed > 1) {
+        console.log(`  ${chalk.gray('Pages:')} ${design.meta.pagesAnalyzed} pages analyzed`);
+      }
       console.log(`  ${chalk.gray('Colors:')} ${design.colors.all.length} unique colors`);
       console.log(`  ${chalk.gray('Fonts:')} ${design.typography.families.map(f => f.name).join(', ') || 'none detected'}`);
       console.log(`  ${chalk.gray('Spacing:')} ${design.spacing.scale.length} values${design.spacing.base ? ` (base: ${design.spacing.base}px)` : ''}`);
@@ -86,6 +125,13 @@ program
       console.log(`  ${chalk.gray('Breakpoints:')} ${design.breakpoints.length} breakpoints`);
       console.log(`  ${chalk.gray('Components:')} ${Object.keys(design.components).length} patterns detected`);
       console.log(`  ${chalk.gray('CSS Vars:')} ${Object.values(design.variables).reduce((s, v) => s + Object.keys(v).length, 0)} custom properties`);
+
+      // Accessibility summary
+      if (design.accessibility) {
+        const a = design.accessibility;
+        const scoreColor = a.score >= 80 ? chalk.green : a.score >= 50 ? chalk.yellow : chalk.red;
+        console.log(`  ${chalk.gray('A11y:')} ${scoreColor(`${a.score}% WCAG score`)} (${a.failCount} failing pairs)`);
+      }
       console.log('');
 
     } catch (err) {
@@ -101,4 +147,73 @@ program
     }
   });
 
+// ── Diff command ──────────────────────────────────────────────
+program
+  .command('diff <urlA> <urlB>')
+  .description('Compare design languages of two websites')
+  .option('-o, --out <dir>', 'output directory', './design-diff-output')
+  .action(async (urlA, urlB, opts) => {
+    if (!urlA.startsWith('http')) urlA = `https://${urlA}`;
+    if (!urlB.startsWith('http')) urlB = `https://${urlB}`;
+
+    console.log('');
+    console.log(chalk.bold('  designlang diff'));
+    console.log(chalk.gray(`  ${urlA}`));
+    console.log(chalk.gray(`  ${urlB}`));
+    console.log('');
+
+    const spinner = ora('Extracting Site A...').start();
+
+    try {
+      const designA = await extractDesignLanguage(urlA);
+      spinner.text = 'Extracting Site B...';
+      const designB = await extractDesignLanguage(urlB);
+
+      spinner.text = 'Comparing...';
+      const diff = diffDesigns(designA, designB);
+
+      const outDir = resolve(opts.out);
+      mkdirSync(outDir, { recursive: true });
+
+      const mdContent = formatDiffMarkdown(diff);
+      const htmlContent = formatDiffHtml(diff);
+
+      writeFileSync(join(outDir, 'diff.md'), mdContent, 'utf-8');
+      writeFileSync(join(outDir, 'diff.html'), htmlContent, 'utf-8');
+
+      spinner.succeed('Comparison complete!');
+      console.log('');
+      console.log(`  ${chalk.green('✓')} ${chalk.cyan('diff.md')} — Markdown comparison`);
+      console.log(`  ${chalk.green('✓')} ${chalk.cyan('diff.html')} — Visual comparison`);
+      console.log('');
+      console.log(chalk.gray(`  Saved to ${outDir}`));
+
+      // Quick summary
+      for (const s of diff.sections) {
+        if (s.changed && s.changed.length > 0) {
+          for (const c of s.changed) {
+            console.log(`  ${chalk.yellow('≠')} ${s.name} — ${c.property}: ${c.a} → ${c.b}`);
+          }
+        }
+      }
+      console.log('');
+
+    } catch (err) {
+      spinner.fail('Comparison failed');
+      console.error(chalk.red(`\n  ${err.message}\n`));
+      process.exit(1);
+    }
+  });
+
+// ── History command ──────────────────────────────────────────
+program
+  .command('history <url>')
+  .description('View design history for a website')
+  .action(async (url) => {
+    if (!url.startsWith('http')) url = `https://${url}`;
+    const history = getHistory(url);
+    console.log('');
+    console.log(formatHistoryMarkdown(url, history));
+  });
+
 program.parse();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "designlang",
-  "version": "1.0.0",
+  "version": "2.0.0",
   "description": "Extract the complete design language from any website — colors, typography, spacing, shadows, and more. Outputs AI-optimized markdown, W3C design tokens, Tailwind config, and CSS variables.",
   "type": "module",
   "bin": {