designlang 5.0.0 → 7.0.0

package/.github/FUNDING.yml

@@ -0,0 +1 @@
+github: [Manavarya09]

package/.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,62 @@
+name: Bug report
+description: Something in designlang is broken or produces wrong output.
+title: "[Bug]: "
+labels: ["bug"]
+body:
+  - type: input
+    id: url
+    attributes:
+      label: URL extracted
+      description: The site you ran designlang against.
+      placeholder: https://example.com
+    validations:
+      required: true
+  - type: input
+    id: command
+    attributes:
+      label: Command used
+      description: The exact command you ran.
+      placeholder: npx designlang https://example.com --full
+    validations:
+      required: true
+  - type: textarea
+    id: expected
+    attributes:
+      label: What you expected
+    validations:
+      required: true
+  - type: textarea
+    id: actual
+    attributes:
+      label: What actually happened
+      description: Include stack traces, log output, or relevant snippets from output files.
+    validations:
+      required: true
+  - type: input
+    id: version
+    attributes:
+      label: designlang version
+      description: Output of `npx designlang --version` (or the version in package.json)
+      placeholder: 7.0.0
+    validations:
+      required: true
+  - type: input
+    id: node
+    attributes:
+      label: Node.js version
+      description: Output of `node --version`
+      placeholder: v20.11.0
+    validations:
+      required: true
+  - type: input
+    id: os
+    attributes:
+      label: OS
+      placeholder: macOS 14.5 / Ubuntu 22.04 / Windows 11
+    validations:
+      required: true
+  - type: textarea
+    id: extra
+    attributes:
+      label: Anything else
+      description: Screenshots, env variables, network constraints, auth requirements, etc.

package/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,8 @@
+blank_issues_enabled: false
+contact_links:
+  - name: Question or discussion
+    url: https://github.com/Manavarya09/design-extract/discussions
+    about: Ask a question, share an extraction, or discuss ideas.
+  - name: designlang website
+    url: https://website-five-lime-65.vercel.app
+    about: Read more about what designlang does.

package/.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,28 @@
+name: Feature request
+description: Suggest a new extraction, output format, or CLI capability.
+title: "[Feature]: "
+labels: ["enhancement"]
+body:
+  - type: textarea
+    id: problem
+    attributes:
+      label: Problem
+      description: What are you trying to do that designlang doesn't support today?
+    validations:
+      required: true
+  - type: textarea
+    id: proposal
+    attributes:
+      label: Proposal
+      description: What should designlang do? CLI flag, command, new extractor, new output format?
+    validations:
+      required: true
+  - type: textarea
+    id: alternatives
+    attributes:
+      label: Alternatives you've considered
+  - type: textarea
+    id: context
+    attributes:
+      label: Additional context
+      description: Example sites, example outputs, links to similar tools, screenshots.

package/CHANGELOG.md

@@ -0,0 +1,43 @@
+# Changelog
+
+## [7.0.0] — 2026-04-18
+
+### Breaking
+
+- **Design token JSON format** — the default `*-design-tokens.json` now follows the W3C Design Tokens Community Group (DTCG) v1 spec: every leaf is `{ "$value": ..., "$type": ... }`, with two layers (`primitive.*` and `semantic.*`) and composite tokens for typography, shadow, border, and gradient. If a downstream consumer expects the pre-v7 flat shape, pass `--tokens-legacy` to preserve it.
+
+  Before (v6):
+  ```json
+  { "color": { "primary": "#3b82f6" }, "fontFamily": { "sans": "Inter" } }
+  ```
+
+  After (v7, default):
+  ```json
+  {
+    "$metadata": { "generator": "designlang", "version": "7.0.0" },
+    "primitive": { "color": { "brand": { "primary": { "$value": "#3b82f6", "$type": "color" } } } },
+    "semantic":  { "color": { "action": { "primary": { "$value": "{primitive.color.brand.primary}", "$type": "color" } } } }
+  }
+  ```
+
+  Migration: either (a) update consumers to read the DTCG shape (recommended — long-term stable, ecosystem-compatible), or (b) add `--tokens-legacy` to the CLI invocation.
+
+### Added
+
+- **MCP server** — new `designlang mcp --output-dir <dir>` subcommand. Stdio JSON-RPC. Resources: `designlang://tokens/primitive`, `designlang://tokens/semantic`, `designlang://regions`, `designlang://components`, `designlang://health`. Tools: `search_tokens`, `find_nearest_color`, `get_region`, `get_component`, `list_failing_contrast_pairs`.
+- **Agent rules emitter** — `--emit-agent-rules` writes `.cursor/rules/designlang.mdc`, `.claude/skills/designlang/SKILL.md`, `CLAUDE.md.fragment`, and `agents.md`. All four template from the resolved semantic tokens.
+- **Multi-platform emitters** — `--platforms <csv>` (values `web`, `ios`, `android`, `flutter`, `wordpress`, `all`). Additive to default web output. Emits iOS SwiftUI, Android Compose + XML, Flutter Dart + ThemeData, and a full WordPress block-theme skeleton (`theme.json` v3, `style.css`, `functions.php`, `index.php`, `templates/index.html`).
+- **Stack + Tailwind fingerprint** — framework detection, Tailwind utility-class frequency map, analytics stack inventory. Surfaced on `design.stack`.
+- **CSS health audit** — specificity distribution, `!important` count, duplicate declarations, unused CSS via Playwright Coverage API, `@keyframes` catalog, vendor-prefix audit. Surfaced on `design.cssHealth` and added as an additive `cssHealth` dimension in the design score.
+- **A11y remediation** — for every failing WCAG contrast pair, suggests the nearest palette color that passes AA (4.5:1 / 3:1) or AAA (7:1 / 4.5:1). Surfaced on `design.accessibility.remediation`.
+- **Semantic regions** — classifies page sections into `nav`, `hero`, `features`, `pricing`, `testimonials`, `cta`, `footer`, `sidebar`, `content`. Surfaced on `design.regions`.
+- **Reusable component detection** — DOM subtree structural hash + cosine-similarity style vector clustering with variant detection. Surfaced on `design.componentClusters` and rendered in the markdown output.
+- **MCP companion file** — `*-mcp.json` written at extract time so later `designlang mcp` invocations can serve regions / components / health / remediation from disk, not just memory.
+
+### Dependencies
+
+- Added `@modelcontextprotocol/sdk` (runtime).
+
+### Tests
+
+- 241/241 passing (baseline 186 + 55 new tests).

package/README.md

@@ -45,7 +45,9 @@ npx designlang https://stripe.com --full
 | `*-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.
+The markdown output has **19 sections**: Color Palette, Typography, Spacing, Border Radii, Box Shadows, CSS Custom Properties, Breakpoints, Transitions & Animations, Component Patterns (with full CSS snippets), Layout System, Responsive Design, Interaction States, Accessibility (WCAG 2.1), Gradients, Z-Index Map, SVG Icons, Font Files, Image Style Patterns, and Quick Start.
+
+In v7 a companion `*-mcp.json` file is also written alongside the 8 outputs so that `designlang mcp` can serve regions, components, and health data from disk on later invocations. Opting into `--platforms <csv>` additively emits `ios/`, `android/`, `flutter/`, and/or `wordpress-theme/` directories in the output folder, and `--emit-agent-rules` adds a `.cursor/`, `.claude/`, `CLAUDE.md.fragment`, and `agents.md` set.
 
 ## Install
 
@@ -169,6 +171,147 @@ designlang watch https://stripe.com --interval 60
 
 Checks hourly and alerts when colors, fonts, or accessibility scores change.
 
+### 9. Apply Command (NEW in v5)
+
+Extract a site's design and write tokens directly into your project — auto-detects your framework:
+
+```bash
+designlang apply https://stripe.com --dir ./my-app
+```
+
+Detects Tailwind, shadcn/ui, or plain CSS and writes to the right config files automatically.
+
+### 10. Auth Extraction (NEW in v5)
+
+Extract from authenticated or protected pages with cookies and custom headers:
+
+```bash
+designlang https://internal-app.com --cookie "session=abc123" --header "Authorization:Bearer token"
+```
+
+### 11. Gradient Extraction (NEW in v5)
+
+Detects all CSS gradients — type (linear/radial/conic), direction, color stops, and classifies them as subtle, brand, bold, or complex.
+
+### 12. Z-Index Map (NEW in v5)
+
+Builds a layer hierarchy from all z-index values, groups them into layers (base, sticky, dropdown, modal, etc.), and flags z-index wars or excessive values (>9999).
+
+### 13. SVG Icon Extraction (NEW in v5)
+
+Finds and deduplicates all inline SVGs, classifies them by size and style (outline/solid/duotone), and extracts the icon color palette.
+
+### 14. Font File Detection (NEW in v5)
+
+Identifies every font source — Google Fonts, self-hosted, CDN, or system — and generates ready-to-use `@font-face` CSS.
+
+### 15. Image Style Patterns (NEW in v5)
+
+Detects image aspect ratios, border treatments, filters, and classifies patterns like avatar, hero, thumbnail, and gallery.
+
+### 16. Dark Mode Diffing (NEW in v5)
+
+Compare light and dark mode side-by-side — see exactly which colors change and which CSS variables are overridden:
+
+```bash
+designlang https://vercel.com --dark
+```
+
+### 17. MCP Server (NEW in v7)
+
+One-command integration with any MCP-aware AI agent (Cursor, Claude Code, Windsurf, and more):
+
+```bash
+designlang mcp --output-dir ./design-extract-output
+```
+
+Launches a stdio JSON-RPC server that exposes the extracted design as MCP resources and tools.
+
+**Resources:**
+
+- `designlang://tokens/primitive` — primitive token layer
+- `designlang://tokens/semantic` — semantic token layer (with DTCG alias references)
+- `designlang://regions` — classified page regions (nav, hero, pricing, etc.)
+- `designlang://components` — reusable component clusters with variants
+- `designlang://health` — CSS health audit
+
+**Tools:**
+
+- `search_tokens` — query tokens by name, value, or type
+- `find_nearest_color` — snap any color to the nearest palette token
+- `get_region` — fetch a classified region by name
+- `get_component` — fetch a component cluster by id
+- `list_failing_contrast_pairs` — list every WCAG-failing fg/bg pair with remediation suggestions
+
+### 18. Multi-Platform Output (NEW in v7)
+
+Emit iOS SwiftUI, Android Compose, Flutter, and WordPress block-theme files in a single run, in addition to the default web output:
+
+```bash
+designlang https://stripe.com --platforms all
+```
+
+Resulting tree:
+
+```
+design-extract-output/
+├── stripe-com-*.{md,json,css,js,html}    (default web output)
+├── ios/
+│   └── DesignTokens.swift
+├── android/
+│   ├── Theme.kt
+│   ├── colors.xml
+│   └── dimens.xml
+├── flutter/
+│   └── design_tokens.dart               (+ buildDesignlangTheme())
+└── wordpress-theme/
+    ├── theme.json
+    ├── style.css
+    ├── functions.php
+    ├── index.php
+    └── templates/index.html
+```
+
+Values for `--platforms` are any comma-separated subset of `web,ios,android,flutter,wordpress,all`. The flag is additive — the default web output is always emitted.
+
+### 19. Agent Rules Emitter (NEW in v7)
+
+Write agent-facing rule files generated from the resolved semantic tokens:
+
+```bash
+designlang https://stripe.com --emit-agent-rules
+```
+
+Writes:
+
+- `.cursor/rules/designlang.mdc` — Cursor rule
+- `.claude/skills/designlang/SKILL.md` — Claude Code skill
+- `CLAUDE.md.fragment` — snippet you can paste into your project's CLAUDE.md
+- `agents.md` — generic, vendor-neutral agent guidance
+
+Each file is templated from the semantic layer of the extracted token set, so the agent sees real token names and values — not placeholders.
+
+### 20. Stack + Tailwind Fingerprint (NEW in v7)
+
+Automatic framework, utility-class, and analytics detection surfaced on `design.stack`:
+
+- **Framework**: Next.js, Nuxt, Gatsby, Remix, Astro, Shopify, WordPress, Framer, Webflow, and more.
+- **Tailwind**: when Tailwind is in use, records utility-class frequency so you see which utilities drive the design.
+- **Analytics**: inventory of analytics scripts — GA4, Plausible, PostHog, Segment, Mixpanel, Amplitude, and friends.
+
+### 21. CSS Health Audit (NEW in v7)
+
+A dedicated audit pass surfaced on `design.cssHealth`:
+
+- Specificity graph (distribution, hotspots)
+- `!important` count
+- Duplicate declarations
+- Unused CSS via the Playwright Coverage API
+- `@keyframes` catalog
+- Vendor-prefix audit
+
+Also contributes a `cssHealth` dimension to the overall design score.
+
 ## All Features
 
 | Feature | Flag / Command | Description |
@@ -177,12 +320,19 @@ Checks hourly and alerts when colors, fonts, or accessibility scores change.
 | 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 |
+| Gradients | automatic | Gradient type, direction, stops, classification |
+| Z-index map | automatic | Layer hierarchy, z-index wars detection |
+| SVG icons | automatic | Deduplicated icons, size/style classification, color palette |
+| Font files | automatic | Source detection (Google/self-hosted/CDN/system), @font-face CSS |
+| Image styles | automatic | Aspect ratios, shapes, filters, pattern classification |
+| Dark mode | `--dark` | Extracts dark color scheme + light/dark diff |
+| Auth pages | `--cookie`, `--header` | Extract from authenticated/protected pages |
 | 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 |
+| Apply | `designlang apply <url>` | Auto-detect framework and write tokens to your project |
 | 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 |
@@ -190,6 +340,15 @@ Checks hourly and alerts when colors, fonts, or accessibility scores change.
 | 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 |
+| MCP server | `designlang mcp` | Expose extraction as MCP resources + tools |
+| Multi-platform | `--platforms <csv>` | Emit iOS / Android / Flutter / WordPress outputs |
+| Agent rules | `--emit-agent-rules` | Cursor, Claude Code, generic agent rule files |
+| Stack fingerprint | automatic | Framework + Tailwind + analytics detection |
+| CSS health | automatic | Specificity, !important, unused CSS, keyframes |
+| A11y remediation | automatic | Nearest palette color passing AA / AAA for every failing pair |
+| Semantic regions | automatic | nav / hero / pricing / testimonials / cta / footer classification |
+| Reusable components | automatic | DOM subtree + style-vector clustering with variants |
+| DTCG tokens | default | W3C Design Tokens v1 with semantic + composite layers (`--tokens-legacy` for pre-v7) |
 
 ## Full CLI Reference
 
@@ -208,11 +367,17 @@ Options:
   --responsive            Capture at multiple breakpoints
   --interactions          Capture hover/focus/active states
   --full                  Enable all captures
+  --cookie <cookies...>   Cookies for authenticated pages (name=value)
+  --header <headers...>   Custom headers (name:value)
   --framework <type>      Only generate specific theme (react, shadcn)
+  --platforms <csv>       Additional platforms: web,ios,android,flutter,wordpress,all (additive)
+  --emit-agent-rules      Emit Cursor / Claude Code / CLAUDE.md / agents.md rule files
+  --tokens-legacy         Emit pre-v7 flat design-tokens.json shape (backward compat)
   --no-history            Skip saving to history
   --verbose               Detailed progress output
 
 Commands:
+  apply <url>             Extract and apply design directly to your project
   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
@@ -220,6 +385,7 @@ Commands:
   brands <urls...>        Multi-brand comparison matrix
   sync <url>              Sync local tokens with live site
   history <url>           View design change history
+  mcp                     Launch stdio MCP server (--output-dir <dir>)
 ```
 
 ## Example Output
@@ -252,9 +418,14 @@ Running `designlang https://vercel.com --full`:
   Shadows: 11 unique shadows
   Radii: 10 unique values
   Breakpoints: 45 breakpoints
-  Components: 11 types detected
+  Components: 11 types detected (with CSS snippets)
   CSS Vars: 407 custom properties
   Layout: 55 grids, 492 flex containers
+  Gradients: 4 unique gradients
+  Z-Index: 8 layers mapped
+  Icons: 23 unique SVGs
+  Font Files: 4 font sources detected
+  Images: 6 style patterns
   Responsive: 4 viewports, 3 breakpoint changes
   Interactions: 8 state changes captured
   A11y: 94% WCAG score (7 failing pairs)
@@ -264,8 +435,8 @@ Running `designlang https://vercel.com --full`:
 ## How It Works
 
 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
+2. **Extract** — Single `page.evaluate()` walks up to 5,000 DOM elements collecting 25+ computed style properties, layout data, inline SVGs, font sources, and image metadata
+3. **Process** — 17 extractor modules parse, deduplicate, cluster, and classify the raw data (including gradients, z-index layers, icons, fonts, and image patterns)
 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
@@ -290,4 +461,4 @@ See [CONTRIBUTING.md](CONTRIBUTING.md). PRs welcome!
 
 ## License
 
-[MIT](LICENSE) - Manavarya Singh
+[MIT](LICENSE) - Manav Arya Singh