designlang 3.0.0 → 4.0.1

package/README.md

@@ -1,21 +1,24 @@
 <p align="center">
-  <h1 align="center">designlang</h1>
-  <p align="center">Extract the complete design language from any website in seconds.</p>
+  <h1 align="center">DESIGNLANG</h1>
+  <p align="center">Reverse-engineer any website's complete design system in one command.</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/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>
+  <a href="https://website-five-lime-65.vercel.app"><img src="https://img.shields.io/badge/website-live-red" alt="website"></a>
 </p>
 
 ---
 
-**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.
+<p align="center">
+  <img src="designlang.png" alt="designlang in action" width="100%">
+</p>
 
-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.
+**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, React theme, shadcn/ui theme, Figma variables, W3C design tokens, and CSS custom properties.
 
-**No other tool does all of this from a single command.**
+But unlike every other tool out there, it also extracts **layout patterns** (grids, flexbox, containers), captures **responsive behavior** across 4 breakpoints, records **interaction states** (hover, focus, active), scores **WCAG accessibility**, and lets you **compare multiple brands** or **sync live sites to local tokens**.
 
 ## Quick Start
 
@@ -23,18 +26,26 @@ It also does **WCAG accessibility scoring**, **component screenshot capture**, *
 npx designlang https://stripe.com
 ```
 
+Get everything at once:
+
+```bash
+npx designlang https://stripe.com --full
+```
+
 ## What You Get (8 Files)
 
 | File | What it is |
 |------|------------|
-| `*-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 |
+| `*-design-language.md` | AI-optimized markdown — feed it to any LLM to recreate the design |
+| `*-preview.html` | Visual report with swatches, type scale, shadows, a11y score |
+| `*-design-tokens.json` | [W3C Design Tokens](https://design-tokens.github.io/community-group/format/) format |
+| `*-tailwind.config.js` | Drop-in Tailwind CSS theme |
+| `*-variables.css` | CSS custom properties |
 | `*-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 |
+| `*-theme.js` | React/CSS-in-JS theme (Chakra, Stitches, Vanilla Extract) |
+| `*-shadcn-theme.css` | shadcn/ui globals.css variables |
+
+The markdown output has **14 sections**: Color Palette, Typography, Spacing, Border Radii, Box Shadows, CSS Custom Properties, Breakpoints, Transitions & Animations, Component Patterns, Layout System, Responsive Design, Interaction States, Accessibility (WCAG 2.1), and Quick Start.
 
 ## Install
 
@@ -44,94 +55,141 @@ npx designlang https://example.com
 
 # Or install globally
 npm install -g designlang
+
+# As an agent skill (Claude Code, Cursor, Codex, 40+ agents)
+npx skills add Manavarya09/design-extract
 ```
 
-## Features
+## What Makes This Different
 
-### Multi-Page Crawling
+Most design extraction tools give you colors and fonts. That's it. designlang fills 5 market gaps that no other tool addresses:
 
-Crawl multiple pages for a site-wide design system:
+### 1. Layout System Extraction
 
-```bash
-designlang https://stripe.com --depth 5
+Extracts the structural skeleton — grid column patterns, flex direction usage, container widths, gap values, and justify/align patterns.
+
+```
+Layout: 55 grids, 492 flex containers
 ```
 
-### WCAG Accessibility Scoring
+Every other tool gives you the paint. designlang gives you the architecture.
 
-Every extraction includes a WCAG 2.1 contrast analysis:
+### 2. Responsive Multi-Breakpoint Capture
 
+Crawls the site at 4 viewports (mobile, tablet, desktop, wide) and maps exactly what changes:
+
+```bash
+designlang https://vercel.com --responsive
 ```
-A11y: 94% WCAG score (7 failing pairs)
+
+```
+Responsive: 4 viewports, 3 breakpoint changes
+  375px → 768px: Nav visibility hidden → visible, Hamburger shown → hidden
+  768px → 1280px: Max grid columns 1 → 3, H1 size 32px → 48px
 ```
 
-Failing color pairs are highlighted in both the markdown and HTML preview with exact contrast ratios.
+No other tool captures how the design *adapts*, just how it looks at one size.
 
-### Component Screenshots
+### 3. Interaction State Capture
 
-Capture PNG screenshots of detected UI components:
+Programmatically hovers and focuses interactive elements, capturing the actual style transitions:
 
 ```bash
-designlang https://vercel.com --screenshots
+designlang https://stripe.com --interactions
 ```
 
-Saves screenshots of buttons, cards, inputs, navigation, hero sections, and a full-page capture.
-
-### Visual HTML Preview
+```css
+/* Button Hover */
+background-color: rgb(83, 58, 253) → rgb(67, 47, 202);
+box-shadow: none → 0 4px 12px rgba(83, 58, 253, 0.4);
 
-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)
+/* Input Focus */
+border-color: rgb(200, 200, 200) → rgb(83, 58, 253);
+outline: none → 2px solid rgb(83, 58, 253);
+```
 
-### Design Comparison
+### 4. Live Site Sync
 
-Compare two sites side-by-side:
+Treat the deployed site as your source of truth, not Figma:
 
 ```bash
-designlang diff https://vercel.com https://stripe.com
+designlang sync https://stripe.com --out ./src/tokens
 ```
 
-Generates `diff.md` and `diff.html` showing color, typography, spacing, and accessibility differences.
+Detects design changes and auto-updates your local `design-tokens.json`, `tailwind.config.js`, and `variables.css`.
 
-### Historical Tracking
+### 5. Multi-Brand Comparison
 
-Track how a site's design evolves over time:
+Compare N brands side-by-side:
 
 ```bash
-# Each extraction auto-saves a snapshot
-designlang https://stripe.com
+designlang brands stripe.com vercel.com github.com linear.app
+```
+
+Generates a matrix with color overlap analysis, typography comparison, spacing systems, and accessibility scores. Outputs both `brands.md` and `brands.html`.
+
+### 6. Clone Command
+
+Generate a working Next.js app with the extracted design applied:
 
-# View history
-designlang history https://stripe.com
+```bash
+designlang clone https://stripe.com
+cd cloned-design && npm install && npm run dev
 ```
 
-Shows color changes, font swaps, accessibility score trends, and CSS variable count over time.
+One command → a running app with the site's colors, fonts, spacing, and component patterns.
+
+### 7. Design System Scoring
 
-### Framework Themes
+Rate any site's design quality across 7 categories:
 
-Generates ready-to-use theme files for:
+```bash
+designlang score https://vercel.com
+```
 
-- **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
+```
+  68/100  Grade: D
+
+  Color Discipline     ██████████░░░░░░░░░░ 50
+  Typography           ██████████████░░░░░░ 70
+  Spacing System       ████████████████░░░░ 80
+  Shadows              ██████████░░░░░░░░░░ 50
+  Border Radii         ████████░░░░░░░░░░░░ 40
+  Accessibility        ███████████████████░ 94
+  Tokenization         ████████████████████ 100
+```
 
-## What It Extracts
+### 8. Watch Mode
 
-| 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 |
+Monitor a site for design changes:
+
+```bash
+designlang watch https://stripe.com --interval 60
+```
+
+Checks hourly and alerts when colors, fonts, or accessibility scores change.
+
+## All Features
+
+| Feature | Flag / Command | Description |
+|---------|---------------|-------------|
+| Base extraction | `designlang <url>` | Colors, typography, spacing, shadows, radii, CSS vars, breakpoints, animations, components |
+| Layout system | automatic | Grid patterns, flex usage, container widths, gap values |
+| Accessibility | automatic | WCAG 2.1 contrast ratios for all fg/bg pairs |
+| Design scoring | automatic | 7-category quality rating (A-F) with actionable issues |
+| Dark mode | `--dark` | Extracts dark color scheme |
+| Multi-page | `--depth <n>` | Crawl N internal pages for site-wide tokens |
+| Screenshots | `--screenshots` | Capture buttons, cards, inputs, nav, hero, full page |
+| Responsive | `--responsive` | Crawl at 4 viewports, map breakpoint changes |
+| Interactions | `--interactions` | Capture hover/focus/active state transitions |
+| Everything | `--full` | Enable screenshots + responsive + interactions |
+| Clone | `designlang clone <url>` | Generate a working Next.js starter with extracted design |
+| Score | `designlang score <url>` | Rate design quality with visual bar chart breakdown |
+| Watch | `designlang watch <url>` | Monitor for design changes on interval |
+| Diff | `designlang diff <A> <B>` | Compare two sites (MD + HTML) |
+| Multi-brand | `designlang brands <urls...>` | N-site comparison matrix |
+| Sync | `designlang sync <url>` | Update local tokens from live site |
+| History | `designlang history <url>` | Track design changes over time |
 
 ## Full CLI Reference
 
@@ -145,29 +203,86 @@ Options:
   --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)
+  --depth <n>             Internal pages to crawl (default: 0)
   --screenshots           Capture component screenshots
+  --responsive            Capture at multiple breakpoints
+  --interactions          Capture hover/focus/active states
+  --full                  Enable all captures
   --framework <type>      Only generate specific theme (react, shadcn)
   --no-history            Skip saving to history
   --verbose               Detailed progress output
 
 Commands:
+  clone <url>             Generate a working Next.js starter from extracted design
+  score <url>             Rate design quality (7 categories, A-F, bar chart)
+  watch <url>             Monitor for design changes on interval
   diff <urlA> <urlB>      Compare two sites' design languages
-  history <url>           View design history for a site
+  brands <urls...>        Multi-brand comparison matrix
+  sync <url>              Sync local tokens with live site
+  history <url>           View design change history
+```
+
+## Example Output
+
+Running `designlang https://vercel.com --full`:
+
+```
+  designlang
+  https://vercel.com
+
+  Output files:
+  ✓ vercel-com-design-language.md (32.6KB)
+  ✓ vercel-com-design-tokens.json (5.6KB)
+  ✓ vercel-com-tailwind.config.js (3.4KB)
+  ✓ vercel-com-variables.css (18.6KB)
+  ✓ vercel-com-preview.html (31.8KB)
+  ✓ vercel-com-figma-variables.json (12.4KB)
+  ✓ vercel-com-theme.js (1.4KB)
+  ✓ vercel-com-shadcn-theme.css (477B)
+  ✓ screenshots/button.png
+  ✓ screenshots/card.png
+  ✓ screenshots/nav.png
+  ✓ screenshots/hero.png
+  ✓ screenshots/full-page.png
+
+  Summary:
+  Colors: 27 unique colors
+  Fonts: Geist, Geist Mono
+  Spacing: 18 values (base: 2px)
+  Shadows: 11 unique shadows
+  Radii: 10 unique values
+  Breakpoints: 45 breakpoints
+  Components: 11 types detected
+  CSS Vars: 407 custom properties
+  Layout: 55 grids, 492 flex containers
+  Responsive: 4 viewports, 3 breakpoint changes
+  Interactions: 8 state changes captured
+  A11y: 94% WCAG score (7 failing pairs)
+  Design Score: 68/100 (D) — 4 issues
 ```
 
 ## How It Works
 
-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
+1. **Crawl** — Launches headless Chromium via Playwright, waits for network idle and fonts
+2. **Extract** — Single `page.evaluate()` walks up to 5,000 DOM elements collecting 25+ computed style properties including layout (grid, flex, container) data
+3. **Process** — 12 extractor modules parse, deduplicate, cluster, and classify the raw data
+4. **Format** — 8 formatter modules generate output files
+5. **Score** — Accessibility extractor calculates WCAG contrast ratios for all color pairs
+6. **Capture** — Optional: screenshots, responsive viewport crawling, interaction state recording
+
+## Agent Skill
+
+Works with **Claude Code, Cursor, Codex, and 40+ AI coding agents** via the skills ecosystem:
+
+```bash
+npx skills add Manavarya09/design-extract
+```
+
+In Claude Code, use `/extract-design <url>`.
 
-## Claude Code Plugin
+## Website
 
-**designlang** also works as a [Claude Code](https://claude.ai/claude-code) plugin. Use `/extract-design <url>` in your coding session.
+**[website-five-lime-65.vercel.app](https://website-five-lime-65.vercel.app)** — the brutalist product page.
 
 ## Contributing
 

package/bin/design-extract.js

@@ -19,6 +19,8 @@ import { captureResponsive } from '../src/extractors/responsive.js';
 import { captureInteractions } from '../src/extractors/interactions.js';
 import { syncDesign } from '../src/sync.js';
 import { compareBrands, formatBrandMatrix, formatBrandMatrixHtml } from '../src/multibrand.js';
+import { generateClone } from '../src/clone.js';
+import { watchSite } from '../src/watch.js';
 import { nameFromUrl } from '../src/utils.js';
 
 const program = new Command();
@@ -26,7 +28,7 @@ const program = new Command();
 program
   .name('designlang')
   .description('Extract the complete design language from any website')
-  .version('3.0.0');
+  .version('4.0.1');
 
 // ── Main command: extract ──────────────────────────────────────
 program
@@ -155,6 +157,11 @@ program
         const total = ic.buttons.length + ic.links.length + ic.inputs.length;
         console.log(`  ${chalk.gray('Interactions:')} ${total} state changes captured`);
       }
+      if (design.score) {
+        const s = design.score;
+        const gradeColor = s.grade === 'A' ? chalk.green : s.grade === 'B' ? chalk.cyan : s.grade === 'C' ? chalk.yellow : chalk.red;
+        console.log(`  ${chalk.gray('Design Score:')} ${gradeColor(`${s.overall}/100 (${s.grade})`)}${s.issues.length > 0 ? ` — ${s.issues.length} issues` : ''}`);
+      }
 
       // Accessibility summary
       if (design.accessibility) {
@@ -338,4 +345,145 @@ program
     }
   });
 
+// ── Clone command ───────────────────────────────────────────
+program
+  .command('clone <url>')
+  .description('Generate a working Next.js starter from a site\'s design')
+  .option('-o, --out <dir>', 'output directory', './cloned-design')
+  .action(async (url, opts) => {
+    if (!url.startsWith('http')) url = `https://${url}`;
+
+    console.log('');
+    console.log(chalk.bold('  designlang clone'));
+    console.log(chalk.gray(`  ${url}`));
+    console.log('');
+
+    const spinner = ora('Extracting design...').start();
+
+    try {
+      const design = await extractDesignLanguage(url);
+      spinner.text = 'Generating Next.js project...';
+
+      const result = generateClone(design, resolve(opts.out));
+
+      spinner.succeed('Clone generated!');
+      console.log('');
+      for (const f of result.files) {
+        console.log(`  ${chalk.green('✓')} ${chalk.cyan(f)}`);
+      }
+      console.log('');
+      console.log(chalk.bold('  To run:'));
+      console.log(chalk.gray(`  cd ${opts.out} && npm install && npm run dev`));
+      console.log('');
+
+    } catch (err) {
+      spinner.fail('Clone failed');
+      console.error(chalk.red(`\n  ${err.message}\n`));
+      process.exit(1);
+    }
+  });
+
+// ── Watch command ───────────────────────────────────────────
+program
+  .command('watch <url>')
+  .description('Monitor a site for design changes')
+  .option('--interval <minutes>', 'check interval in minutes', parseInt, 60)
+  .action(async (url, opts) => {
+    if (!url.startsWith('http')) url = `https://${url}`;
+    const intervalMs = (opts.interval || 60) * 60 * 1000;
+
+    console.log('');
+    console.log(chalk.bold('  designlang watch'));
+    console.log(chalk.gray(`  ${url} (every ${opts.interval || 60}min)`));
+    console.log('');
+
+    const check = async () => {
+      const spinner = ora('Checking for design changes...').start();
+      try {
+        const result = await watchSite(url);
+
+        if (result.isFirstRun) {
+          spinner.succeed('Baseline captured. Watching for changes...');
+        } else if (result.changes.length === 0) {
+          spinner.succeed(`No changes — ${new Date().toLocaleTimeString()}`);
+        } else {
+          spinner.warn(`${result.changes.length} changes detected!`);
+          for (const c of result.changes) {
+            console.log(`  ${chalk.yellow('≠')} ${c.what}: ${c.from} → ${c.to}`);
+          }
+        }
+      } catch (err) {
+        spinner.fail(`Check failed: ${err.message}`);
+      }
+    };
+
+    await check();
+    console.log(chalk.gray(`\n  Next check in ${opts.interval || 60} minutes. Press Ctrl+C to stop.\n`));
+    setInterval(check, intervalMs);
+  });
+
+// ── Score command ───────────────────────────────────────────
+program
+  .command('score <url>')
+  .description('Score a website\'s design system quality')
+  .action(async (url) => {
+    if (!url.startsWith('http')) url = `https://${url}`;
+
+    const spinner = ora('Analyzing design...').start();
+
+    try {
+      const design = await extractDesignLanguage(url);
+      const s = design.score;
+
+      spinner.stop();
+      console.log('');
+      console.log(chalk.bold('  Design System Score'));
+      console.log(chalk.gray(`  ${url}`));
+      console.log('');
+
+      const gradeColor = s.grade === 'A' ? chalk.green : s.grade === 'B' ? chalk.cyan : s.grade === 'C' ? chalk.yellow : chalk.red;
+      console.log(`  ${gradeColor.bold(`  ${s.overall}/100  Grade: ${s.grade}`)}`);
+      console.log('');
+
+      // Category breakdown
+      const cats = [
+        ['Color Discipline', s.scores.colorDiscipline],
+        ['Typography', s.scores.typographyConsistency],
+        ['Spacing System', s.scores.spacingSystem],
+        ['Shadows', s.scores.shadowConsistency],
+        ['Border Radii', s.scores.radiusConsistency],
+        ['Accessibility', s.scores.accessibility],
+        ['Tokenization', s.scores.tokenization],
+      ];
+
+      for (const [name, score] of cats) {
+        const bar = '█'.repeat(Math.round(score / 5)) + '░'.repeat(20 - Math.round(score / 5));
+        const color = score >= 80 ? chalk.green : score >= 60 ? chalk.yellow : chalk.red;
+        console.log(`  ${chalk.gray(name.padEnd(20))} ${color(bar)} ${score}`);
+      }
+
+      if (s.strengths.length > 0) {
+        console.log('');
+        console.log(chalk.bold('  Strengths:'));
+        for (const str of s.strengths) {
+          console.log(`  ${chalk.green('✓')} ${str}`);
+        }
+      }
+
+      if (s.issues.length > 0) {
+        console.log('');
+        console.log(chalk.bold('  Issues:'));
+        for (const issue of s.issues) {
+          console.log(`  ${chalk.yellow('!')} ${issue}`);
+        }
+      }
+      console.log('');
+
+    } catch (err) {
+      spinner.fail('Scoring failed');
+      console.error(chalk.red(`\n  ${err.message}\n`));
+      process.exit(1);
+    }
+  });
+
 program.parse();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "designlang",
-  "version": "3.0.0",
+  "version": "4.0.1",
   "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": {