designlang 12.0.0 → 12.1.0

package/.claude/launch.json

@@ -6,6 +6,12 @@
       "runtimeExecutable": "npm",
       "runtimeArgs": ["--prefix", "website", "run", "dev"],
       "port": 3000
+    },
+    {
+      "name": "grade-preview",
+      "runtimeExecutable": "npx",
+      "runtimeArgs": ["--yes", "http-server", "design-extract-output", "-p", "4173", "-c-1", "--silent"],
+      "port": 4173
     }
   ]
 }

package/CHANGELOG.md

@@ -1,5 +1,27 @@
 # Changelog
 
+## [12.1.0] — 2026-04-29
+
+**Design Report Card — a shareable audit page, generated from any URL.**
+
+### Added
+
+- **`designlang grade <url>`** — produces a standalone, self-contained HTML
+  "Design Report Card" alongside JSON and Markdown variants. Letter grade
+  (A–F) hero, eight scored dimensions with arc gauges, evidence pulled from
+  the audited site itself (palette swatches, type specimen, spacing rhythm),
+  and a strengths / what-to-fix ledger. Editorial layout, paper/ink theme
+  with a dark toggle, print-ready, OG-meta for shareable links.
+- New formatter: **`src/formatters/grade.js`** with `formatGrade` (HTML) and
+  `formatGradeMarkdown` exports. Reuses the existing `scoreDesignSystem`
+  output — no scoring changes.
+- Flags: `--format html|md|json|all`, `--open` to launch the report in your
+  browser when it finishes.
+
+Why this exists: html.to.design, Locofy, Builder, Polypane all ship
+extraction or layout cloning. None of them grade the design system itself
+in a form you can post on Twitter or email to a client. This is that.
+
 ## [10.5.0] — 2026-04-22
 
 **The states LLMs always botch.**

package/README.md

@@ -18,454 +18,76 @@
 
 [![designlang on npm](https://pkgfolio.vercel.app/embed/pkg/designlang?v=2)](https://www.npmjs.com/package/designlang)
 
-**designlang** crawls any website with a headless browser, extracts every computed style from the live DOM, and generates **17+ output files** — including an AI-optimized markdown file, visual HTML preview, Tailwind config, React theme, shadcn/ui theme, Figma variables, W3C design tokens, CSS custom properties, motion tokens, typed component anatomy stubs, a brand voice summary, **page intent + section roles**, **visual DNA** (material language + imagery style), **component library detection**, a **logo file**, a **multi-page consistency report**, and a **prompt pack** of ready-to-paste prompts for v0, Lovable, Cursor, and Claude Artifacts.
+**designlang** points a headless browser at any URL and reads the design system off the live DOM. One command emits 17+ files — DTCG tokens, Tailwind config, shadcn theme, Figma variables, motion tokens, typed component anatomy, brand voice, page-intent labels, and a paste-ready prompt pack for v0 / Lovable / Cursor / Claude Artifacts.
 
-But unlike every other tool out there, it also extracts **layout patterns** (grids, flexbox, containers), **motion language** (durations, easings, springs, scroll-linked animations), **component anatomy** (slots, variant × size × state matrices), **brand voice** (tone, CTA verbs, heading style), captures **responsive behavior** across 4 breakpoints, records **interaction states** (hover, focus, active), scores **WCAG accessibility**, lints your own token files, and lets you **drift-check a codebase against a live site**, **visual-diff two URLs**, **compare multiple brands**, or **sync live sites to local tokens**.
+It also goes where extractors don't: **layout patterns**, **responsive behavior across 4 breakpoints**, **hover / focus / active states**, **WCAG contrast scoring**, **multi-page consistency**, **drift checks against a live source-of-truth**, **visual-diffs**, and a **shareable graded report card**.
 
-## What's New in v10 — The Intent Release
-
-Everything else captures *how* a site looks. v10 captures *what it is* — the semantic signal an LLM needs to rebuild a site faithfully instead of restyling a generic scaffold.
-
-- **Page Intent** — classifier labels the URL as `landing` / `pricing` / `docs` / `blog` / `blog-post` / `product` / `about` / `dashboard` / `auth` / `legal`, with a confidence score and rival alternates. URL + title + meta + DOM-shape signals. Heuristic-only by default; opt into `--smart` for LLM refinement.
-- **Section Roles** — every semantic region gets a role (`hero`, `feature-grid`, `logo-wall`, `stats`, `testimonial`, `pricing-table`, `faq`, `steps`, `comparison`, `gallery`, `bento`, `cta`, `footer`), plus reading order and extracted slot copy (headings, lede, CTA counts).
-- **Multi-Page Crawl** — `--full` (or `--pages <n>`) auto-discovers the site's own canonical pages from its nav (pricing/docs/blog/about/product) and runs the full pipeline on each, then emits a cross-page consistency report — shared tokens, per-page uniques, and pairwise Jaccard scores. LLMs get a real design language, not just a homepage snapshot.
-- **Material Language** — classifies the visual vocabulary as `glassmorphism` / `neumorphism` / `flat` / `brutalist` / `skeuomorphic` / `material-you` / `soft-ui` / `mixed` from shadow complexity, backdrop-filter usage, saturation, and geometry.
-- **Imagery Style** — fingerprints the images: `photography` / `3d-render` / `isometric` / `flat-illustration` / `gradient-mesh` / `icon-only` / `screenshot` / `mixed`, plus dominant aspect ratio and image-radius profile.
-- **Component Library Detection** — identifies `shadcn/ui`, `radix-ui`, `headlessui`, `mui`, `chakra-ui`, `mantine`, `ant-design`, `bootstrap`, `heroui`, `tailwind-ui`, `vuetify`, or plain `tailwindcss`, with evidence and alternates.
-- **Logo Extraction** — `--full` writes `*-logo.svg` (or `.png`) plus `*-logo.json` with dimensions, aspect, and sampled clearspace.
-- **Prompt Pack** — a `*-prompts/` directory with `v0.txt`, `lovable.txt`, `cursor.md`, `claude-artifacts.md`, and atomic `recipe-<component>.md` cards — tokens, section order, voice, and library inlined so one paste is enough.
-- **`--smart` mode** — when a heuristic classifier returns low confidence, fall back to a small LLM call (uses `OPENAI_API_KEY` or `ANTHROPIC_API_KEY` from env). Completely optional — no key, no behavior change.
-
-## What's New in v9 — The Motion & Voice Release
-
-- **Motion Language** — durations bucketed into semantic tokens (`instant`/`xs`/`sm`/`md`/`lg`/`xl`), easings classified into families (ease-out, spring-overshoot, steps), scroll-linked animation detection (`animation-timeline`, `view-timeline-name`), keyframe kind classification (slide / fade / reveal / rotate / scale / pulse), and a `feel` fingerprint — *springy*, *responsive*, *smooth*, *mechanical*, or *mixed*.
-- **Component Anatomy v2** — every component cluster is now an *anatomy tree* with slots (label, icon, badge, heading, media), variant × size × state matrices, and an emitted `*-anatomy.tsx` file of typed React stubs you can wire into your design system.
-- **Brand Voice** — extracts tone (friendly / formal / technical / playful / neutral), pronoun posture (`we→you` / `you-only` / `we-only` / `third-person`), heading style (Title Case / Sentence case / all-lowercase), top CTA verbs, and a microcopy inventory. Feeds LLMs the *voice*, not just the paint.
-- **`designlang lint`** — audit your own `design-tokens.json` (DTCG or flat) or `variables.css` for color sprawl, spacing-scale drift, radius/shadow bloat, and WCAG fg/bg contrast fails. Exits non-zero on errors — CI-ready.
-- **`designlang drift`** — point at a live site, pass your local token file, and get a verdict: `in-sync` / `minor-drift` / `notable-drift` / `major-drift`. Integrates cleanly with the existing GitHub Action.
-- **`designlang visual-diff`** — capture two URLs side-by-side and emit a single-file HTML report with component screenshots, file-size deltas, and changed color tokens. No heavy pixel-diff dependencies — runs in pure Node + Playwright.
-
-## Quick Start
-
-```bash
-npx designlang https://stripe.com
-```
-
-Get everything at once:
+## Quick start
 
 ```bash
-npx designlang https://stripe.com --full
+npx designlang https://stripe.com           # extract everything
+npx designlang grade https://stripe.com     # shareable HTML report card  ← v12.1
+npx designlang clone https://stripe.com     # working Next.js starter
+npx designlang --full https://stripe.com    # screenshots + responsive + interactions
 ```
 
-## What You Get (11+ Files)
-
-| File | What it is |
-|------|------------|
-| `*-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 (Chakra, Stitches, Vanilla Extract) |
-| `*-shadcn-theme.css` | shadcn/ui globals.css variables |
-| `*-motion-tokens.json` | **(v9)** Motion tokens — durations, easings, springs, scroll-linked flag |
-| `*-anatomy.tsx` | **(v9)** Typed React stubs for every detected component + variants |
-| `*-voice.json` | **(v9)** Brand voice fingerprint — tone, CTA verbs, heading style |
-
-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
 
 ```bash
-# Use directly (no install needed)
-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
-```
-
-## What Makes This Different
-
-Most design extraction tools give you colors and fonts. That's it. designlang fills 5 market gaps that no other tool addresses:
-
-### 1. Layout System Extraction
-
-Extracts the structural skeleton — grid column patterns, flex direction usage, container widths, gap values, and justify/align patterns.
-
-```
-Layout: 55 grids, 492 flex containers
-```
-
-Every other tool gives you the paint. designlang gives you the architecture.
-
-### 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
-```
-
-```
-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
-```
-
-No other tool captures how the design *adapts*, just how it looks at one size.
-
-### 3. Interaction State Capture
-
-Programmatically hovers and focuses interactive elements, capturing the actual style transitions:
-
-```bash
-designlang https://stripe.com --interactions
-```
-
-```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);
-
-/* Input Focus */
-border-color: rgb(200, 200, 200) → rgb(83, 58, 253);
-outline: none → 2px solid rgb(83, 58, 253);
-```
-
-### 4. Live Site Sync
-
-Treat the deployed site as your source of truth, not Figma:
-
-```bash
-designlang sync https://stripe.com --out ./src/tokens
-```
-
-Detects design changes and auto-updates your local `design-tokens.json`, `tailwind.config.js`, and `variables.css`.
-
-### 5. Multi-Brand Comparison
-
-Compare N brands side-by-side:
-
-```bash
-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:
-
-```bash
-designlang clone https://stripe.com
-cd cloned-design && npm install && npm run dev
-```
-
-One command → a running app with the site's colors, fonts, spacing, and component patterns.
-
-### 7. Design System Scoring
-
-Rate any site's design quality across 7 categories:
-
-```bash
-designlang score https://vercel.com
-```
-
-```
-  68/100  Grade: D
-
-  Color Discipline     ██████████░░░░░░░░░░ 50
-  Typography           ██████████████░░░░░░ 70
-  Spacing System       ████████████████░░░░ 80
-  Shadows              ██████████░░░░░░░░░░ 50
-  Border Radii         ████████░░░░░░░░░░░░ 40
-  Accessibility        ███████████████████░ 94
-  Tokenization         ████████████████████ 100
-```
-
-### 8. Watch Mode
-
-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.
-
-### 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.
-
-### 22. Chrome Extension (NEW in v7.1)
-
-A Manifest-v3 popup lives in [`chrome-extension/`](chrome-extension/). One click on any tab opens `designlang.manavaryasingh.com` with the URL prefilled — no copy-paste, no context switch. There is also a **Copy CLI** button that puts `npx designlang <url>` in your clipboard.
-
-- **Permissions:** `activeTab` only, plus host access to the hosted extractor.
-- **Install:** toggle developer mode at `chrome://extensions`, click *Load unpacked*, pick the `chrome-extension/` folder.
-- **Firefox + Edge** work with the same MV3 manifest.
-
-### 24. Motion Language (NEW in v9)
-
-Extracts the full motion fingerprint, not just transition strings:
-
-```bash
-designlang https://linear.app
-# emits linear-app-motion-tokens.json
-```
-
-```
-Motion: feel = springy, 2 spring easings, scroll-linked = yes
-Durations: instant (80ms), xs (150ms), sm (220ms), md (380ms)
-Easings: ease-out (61%), spring-overshoot (18%), ease-in-out (21%)
-Keyframes: fade-up (slide-y, used 18x), scale-in (reveal, used 4x)
-```
-
-### 25. Component Anatomy v2 (NEW in v9)
-
-Every detected component becomes an anatomy tree with typed React stubs:
-
-```bash
-designlang https://stripe.com
-# emits stripe-com-anatomy.tsx
-```
-
-```tsx
-export interface ButtonProps {
-  variant?: 'primary' | 'secondary' | 'ghost';
-  size?: 'sm' | 'md' | 'lg';
-  disabled?: boolean;
-  leadingIcon?: React.ReactNode;
-  badge?: React.ReactNode;
-  children?: React.ReactNode;
-}
-```
-
-### 26. Brand Voice (NEW in v9)
-
-Pulls the voice alongside the visual:
-
-```bash
-designlang https://vercel.com
-# emits vercel-com-voice.json + a Brand Voice section in the markdown
+npm i -g designlang                         # global
+npx skills add Manavarya09/design-extract   # as an agent skill (40+ agents)
 ```
 
-```
-Tone: technical · Pronoun: we→you · Headings: Sentence case (tight)
-Top CTA verbs: start (14), get (8), deploy (5), try (3)
-Sample headings:
-  > Develop. Preview. Ship.
-  > The React framework for the web.
-```
-
-### 27. `designlang lint` — Token Quality Linter (NEW in v9)
+## What you get
 
-Audit your own token file with the same rules the scorer runs against live sites:
-
-```bash
-designlang lint ./src/tokens/design-tokens.json
-```
+Each run writes 17+ files to `./design-extract-output/`. The headline outputs:
 
-```
-Score: 74/100  Grade: C   Tokens: 126
-
-  colorDiscipline      ██████████████░░░░░░ 72
-  spacingSystem        ████████████████░░░░ 84
-  borderRadii          ████████████░░░░░░░░ 60
-  shadows              ██████████░░░░░░░░░░ 50
-  accessibility        █████████████████░░░ 88
-
-  WARN  [color-sprawl] 3 near-duplicate color pair(s) within 8 RGB units
-  ERROR [contrast-wcag-aa] 2 fg/bg pair(s) fail WCAG AA (4.5:1)
-```
-
-Exits non-zero on any `error`-level finding — drop into CI.
-
-### 28. `designlang drift` — Codebase ↔ Live Site Sync Check (NEW in v9)
-
-Point at a deployed site, pass your local tokens, and get a verdict:
-
-```bash
-designlang drift https://yourapp.com --tokens ./src/tokens.json --tolerance 8
-```
-
-```
-Verdict: notable-drift (drift ratio: 0.24)
-
-| token          | local    | nearest live       | Δ  |
-|----------------|----------|--------------------|----|
-| color.primary  | #4338CA  | #5B4CF5 (primary)  | 22 |
-| color.border   | #D4D4D8  | #E5E5EA (surface)  | 18 |
-```
-
-Configurable `--fail-on <level>` for CI: `minor-drift` / `notable-drift` / `major-drift`.
-
-### 29. `designlang visual-diff` — Two-URL Side-by-Side (NEW in v9)
-
-Capture screenshots + token deltas for two URLs in a single self-contained HTML report:
-
-```bash
-designlang visual-diff https://staging.app.com https://app.com
-```
+| File | What it is |
+|---|---|
+| `*-design-language.md` | 19-section markdown — feed any LLM to recreate the design |
+| `*-design-tokens.json` | W3C DTCG tokens (primitive + semantic + composite layers) |
+| `*-tailwind.config.js` | Drop-in Tailwind theme |
+| `*-shadcn-theme.css` | shadcn/ui `globals.css` variables |
+| `*-figma-variables.json` | Figma Variables import (light + dark) |
+| `*-variables.css` | CSS custom properties |
+| `*-anatomy.tsx` | Typed React stubs for every detected component + variants |
+| `*-motion-tokens.json` | Durations, easings, springs, scroll-linked flag |
+| `*-voice.json` | Brand voice — tone, pronoun posture, CTA verbs |
+| `*-prompts/` | Paste-ready prompts for v0, Lovable, Cursor, Claude Artifacts |
+| `*-mcp.json` | Disk-backed MCP server payload |
+| `*-grade.html` | **v12.1** Shareable Design Report Card (letter grade + evidence) |
 
-Emits `visual-diff-<timestamp>.html` with embedded images (base64), file-size deltas, and a changed-color-tokens table. Nothing else to serve — just open the file.
+Multi-platform (`--platforms web,ios,android,flutter,wordpress,all`) adds `ios/`, `android/`, `flutter/`, and a WordPress block theme. `--emit-agent-rules` adds Cursor / Claude Code / generic agent rule files.
 
-### 30. Better Auth + Network Control (v7.1)
+## Why designlang vs anything else
 
-Extracting from authenticated, self-signed, or non-default environments now takes one flag:
+Other tools give you the paint. designlang reads the architecture:
 
-- **`--cookie-file <path>`** — loads cookies from JSON array, Playwright `storageState.json`, or Netscape `cookies.txt` (browser extensions, curl exports). Merges cleanly with the existing `--cookie name=value` flag.
-- **`--insecure`** — ignore HTTPS/SSL certificate errors for self-signed dev servers, corporate staging, or MITM tools.
-- **`--user-agent <ua>`** — override the browser User-Agent string.
+- **Layout system** — grids, flex containers, container widths, gaps — not just tokens.
+- **Responsive** — crawls 4 breakpoints and reports what changes (`--responsive`).
+- **Interaction states** — programmatically hovers and focuses, captures the deltas (`--interactions`, `--deep-interact`).
+- **Motion language** — durations, easing families, spring detection, scroll-linked flag, `feel` fingerprint (springy / smooth / mechanical / mixed).
+- **Component anatomy** — slot trees with variant × size × state matrices, emitted as typed `.tsx`.
+- **Brand voice** — tone, pronoun posture, heading style, CTA verb inventory.
+- **Page intent + section roles** — `landing` / `pricing` / `docs` etc., with semantic regions (`hero`, `feature-grid`, `pricing-table`, `cta`…).
+- **Multi-page consistency** — auto-discovers canonical pages, reconciles shared vs per-route tokens.
+- **WCAG** — every fg/bg pair scored, with a remediation palette suggesting nearest passing colors.
+- **Drift + lint + visual-diff** — `designlang drift`, `lint`, `visual-diff` all CI-ready, exit non-zero on failure.
+- **Live-site sync** — treat the deployed site as source of truth (`designlang sync`).
+- **MCP server** — `designlang mcp` exposes tokens, regions, components, and contrast pairs to any MCP-aware agent.
 
 ```bash
-designlang https://staging.internal --cookie-file ./session.json --insecure
+designlang grade https://stripe.com         # ← v12.1: shareable report card
+designlang clone https://stripe.com         # → working Next.js app
+designlang apply https://stripe.com -d ./app   # auto-detect framework, write tokens
+designlang brands stripe.com vercel.com linear.app   # N-brand matrix
+designlang drift https://yourapp.com --tokens ./src/tokens.json
+designlang lint ./src/tokens/design-tokens.json     # CI-ready linter
+designlang visual-diff https://staging.app https://app   # single-file HTML diff
+designlang mcp                              # stdio MCP server for Cursor / Claude Code
 ```
 
-## All Features
+## All features
 
 | Feature | Flag / Command | Description |
 |---------|---------------|-------------|
@@ -492,6 +114,7 @@ designlang https://staging.internal --cookie-file ./session.json --insecure
 | 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 |
+| Grade (NEW v12.1) | `designlang grade <url>` | Generate a shareable HTML "Design Report Card" — letter grade, 8 dimensions, evidence (palette, type, rhythm), strengths + fixes |
 | 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 |
@@ -544,6 +167,7 @@ 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)
+  grade <url>                       Generate a shareable HTML Design Report Card (--format html|md|json|all, --open)
   watch <url>                       Monitor for design changes on interval
   diff <urlA> <urlB>                Compare two sites' design languages
   brands <urls...>                  Multi-brand comparison matrix
@@ -555,56 +179,26 @@ Commands:
   visual-diff <before> <after>      (v9) Side-by-side HTML diff of two URLs
 ```
 
-## Example Output
+## Example output
 
-Running `designlang https://vercel.com --full`:
+`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 (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)
-  Design Score: 68/100 (D) — 4 issues
+Colors: 27 · Fonts: Geist + Geist Mono · Spacing: 18 (base 2px)
+Shadows: 11 · Radii: 10 · CSS vars: 407 · Layout: 55 grids / 492 flex
+Responsive: 4 viewports, 3 breakpoint changes · Interactions: 8 transitions
+A11y: 94% WCAG · Score: 68/100 (D) · 4 issues
+
+→ 17 files written to ./design-extract-output/
+→ Run `designlang grade https://vercel.com` for a shareable report card
 ```
 
-## How It Works
+## 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, 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
+1. **Crawl** — Headless Chromium via Playwright, waits for network idle and fonts
+2. **Extract** — One `page.evaluate()` walks up to 5,000 DOM elements, collecting 25+ computed properties, inline SVGs, font sources, and image metadata
+3. **Process** — 17 extractor modules parse, deduplicate, cluster, and classify the raw data
+4. **Format** — 12+ formatter modules emit the output files
 5. **Score** — Accessibility extractor calculates WCAG contrast ratios for all color pairs
 6. **Capture** — Optional: screenshots, responsive viewport crawling, interaction state recording
 

package/bin/design-extract.js

@@ -45,6 +45,7 @@ import { generateClone } from '../src/clone.js';
 import { watchSite } from '../src/watch.js';
 import { diffDarkMode } from '../src/darkdiff.js';
 import { applyDesign } from '../src/apply.js';
+import { formatGrade, formatGradeMarkdown } from '../src/formatters/grade.js';
 import { nameFromUrl } from '../src/utils.js';
 
 function validateUrl(url) {
@@ -934,6 +935,81 @@ program
     }
   });
 
+// ── Grade command — shareable HTML report card ─────────────
+program
+  .command('grade <url>')
+  .description('Generate a shareable Design Report Card (HTML + JSON + Markdown)')
+  .option('-o, --out <dir>', 'output directory', './design-extract-output')
+  .option('-n, --name <name>', 'output file prefix (default: derived from URL)')
+  .option('--format <fmt>', 'output format: html, md, json, all', 'all')
+  .option('--open', 'open the HTML report in the default browser')
+  .action(async (url, opts) => {
+    if (!url.startsWith('http')) url = `https://${url}`;
+    validateUrl(url);
+
+    const spinner = ora('Auditing design system...').start();
+    try {
+      const design = await extractDesignLanguage(url);
+      const s = design.score;
+      if (!s) throw new Error('scoring failed — cannot grade');
+
+      const outDir = resolve(opts.out);
+      mkdirSync(outDir, { recursive: true });
+      const prefix = opts.name || nameFromUrl(url);
+      const written = [];
+
+      if (opts.format === 'all' || opts.format === 'html') {
+        const html = formatGrade(design, { version: PKG_VERSION });
+        const p = join(outDir, `${prefix}.grade.html`);
+        writeFileSync(p, html);
+        written.push(p);
+      }
+      if (opts.format === 'all' || opts.format === 'md') {
+        const md = formatGradeMarkdown(design);
+        const p = join(outDir, `${prefix}.grade.md`);
+        writeFileSync(p, md);
+        written.push(p);
+      }
+      if (opts.format === 'all' || opts.format === 'json') {
+        const p = join(outDir, `${prefix}.grade.json`);
+        writeFileSync(p, JSON.stringify({
+          url: design.meta?.url,
+          title: design.meta?.title,
+          timestamp: design.meta?.timestamp,
+          grade: s.grade,
+          overall: s.overall,
+          scores: s.scores,
+          strengths: s.strengths,
+          issues: s.issues,
+        }, null, 2));
+        written.push(p);
+      }
+
+      spinner.stop();
+      const gradeColor = s.grade === 'A' ? chalk.green : s.grade === 'B' ? chalk.cyan : s.grade === 'C' ? chalk.yellow : chalk.red;
+      console.log('');
+      console.log(`  ${gradeColor.bold(`Grade ${s.grade}`)} ${chalk.gray('·')} ${chalk.bold(`${s.overall}/100`)} ${chalk.gray('·')} ${chalk.gray(url)}`);
+      console.log('');
+      for (const f of written) console.log(`  ${chalk.green('✓')} ${chalk.gray(f)}`);
+      console.log('');
+      console.log(chalk.gray(`  Share: open the .grade.html in a browser, post the URL.`));
+      console.log('');
+
+      if (opts.open) {
+        const htmlPath = written.find(p => p.endsWith('.html'));
+        if (htmlPath) {
+          const { spawn } = await import('child_process');
+          const cmd = process.platform === 'darwin' ? 'open' : process.platform === 'win32' ? 'start' : 'xdg-open';
+          spawn(cmd, [htmlPath], { detached: true, stdio: 'ignore' }).unref();
+        }
+      }
+    } catch (err) {
+      spinner.fail('Grade failed');
+      console.error(chalk.red(`\n  ${err.message}\n`));
+      process.exit(1);
+    }
+  });
+
 // ── Apply command ──────────────────────────────────────────
 program
   .command('apply <url>')

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "designlang",
-  "version": "12.0.0",
+  "version": "12.1.0",
   "description": "Extract the complete design language from any website and ship it — clone to a working Next.js starter, guard tokens with a CI drift bot, or browse everything in a local studio. Outputs W3C DTCG tokens, motion tokens, typed anatomy stubs, Tailwind config, and ready-to-paste v0 / Lovable / Cursor / Claude-Artifacts prompts.",
   "type": "module",
   "bin": {

package/src/formatters/grade.js

@@ -0,0 +1,404 @@
+// designlang grade — standalone, shareable HTML "Design Report Card".
+// Renders the existing scoring output as an editorial-style audit page that
+// embeds the audited site's own design language (palette, type, spacing) as
+// visual evidence. Self-contained: no external assets except Google Fonts.
+
+const FONT_DISPLAY = 'Instrument Serif';
+const FONT_BODY = 'Inter';
+const FONT_MONO = 'JetBrains Mono';
+
+const DIMENSIONS = [
+  ['colorDiscipline',       'Color Discipline',     'Palette breadth, brand clarity, restraint.'],
+  ['typographyConsistency', 'Typography',           'Family count, weight discipline, scale length.'],
+  ['spacingSystem',         'Spacing System',       'Base unit fit, value count, rhythm.'],
+  ['shadowConsistency',     'Elevation',            'Shadow count and tier discipline.'],
+  ['radiusConsistency',     'Border Radii',         'Radius scale tightness.'],
+  ['accessibility',         'Accessibility',        'WCAG contrast pass rate.'],
+  ['tokenization',          'Tokenization',         'CSS variable depth.'],
+  ['cssHealth',             'CSS Health',           'Unused rules, !important, duplicates.'],
+];
+
+function esc(s) {
+  return String(s ?? '').replace(/[&<>"']/g, c => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' }[c]));
+}
+
+function gradeAccent(grade) {
+  return ({ A: '#0a8a52', B: '#1f6feb', C: '#b08400', D: '#d2691e', F: '#c43d3d' })[grade] || '#1f1f1f';
+}
+
+function describeScore(n) {
+  if (n >= 90) return 'Exemplary';
+  if (n >= 80) return 'Strong';
+  if (n >= 70) return 'Adequate';
+  if (n >= 60) return 'Below standard';
+  return 'Needs work';
+}
+
+function arcGauge(value, accent) {
+  const v = Math.max(0, Math.min(100, value));
+  const r = 36;
+  const c = 2 * Math.PI * r;
+  const offset = c * (1 - v / 100);
+  return `
+    <svg viewBox="0 0 88 88" class="gauge" aria-hidden="true">
+      <circle cx="44" cy="44" r="${r}" class="gauge-track" fill="none" stroke-width="4"/>
+      <circle cx="44" cy="44" r="${r}" class="gauge-fill" fill="none" stroke-width="4"
+              stroke="${accent}" stroke-linecap="round"
+              stroke-dasharray="${c.toFixed(2)}"
+              stroke-dashoffset="${offset.toFixed(2)}"
+              transform="rotate(-90 44 44)"/>
+    </svg>`;
+}
+
+function colorSwatches(design) {
+  const all = (design.colors?.all || []).slice(0, 18);
+  if (!all.length) return '';
+  return all.map(c => {
+    const hex = esc(c.hex || c);
+    return `<li class="swatch" style="--c:${hex}"><span class="swatch-chip"></span><code>${hex}</code></li>`;
+  }).join('');
+}
+
+function typeSpecimen(design) {
+  const families = (design.typography?.families || []).slice(0, 2).map(familyName).filter(Boolean);
+  const sizeOf = s => typeof s === 'number' ? s : (s?.size ?? 0);
+  const allScale = (design.typography?.scale || []).map(sizeOf).filter(n => n > 0).sort((a, b) => b - a);
+  const scale = allScale.slice(0, 5);
+  if (!families.length) return '';
+  const head = families[0];
+  const weights = (design.typography?.weights || []).map(w => typeof w === 'object' ? (w.value || w.weight) : w).filter(Boolean);
+  return `
+    <div class="specimen" style="font-family: ${esc(head)}, ${FONT_DISPLAY}, serif">
+      ${scale.map((s, i) => {
+        const lines = [
+          'The quiet authority of restraint.',
+          'How the page reads at rest.',
+          'Form follows feeling.',
+          'Calm hierarchy is a craft.',
+          'Notes from the audit.',
+        ];
+        return `<div class="spec-line" style="font-size:${Math.min(s, 72)}px">${lines[i] || lines[0]}</div>`;
+      }).join('')}
+    </div>
+    <div class="specimen-meta">
+      <span>Families · ${families.map(esc).join(' / ')}</span>
+      <span>Scale · ${(design.typography?.scale || []).length} sizes</span>
+      <span>Weights · ${weights.join(', ') || '—'}</span>
+    </div>`;
+}
+
+function spacingScale(design) {
+  const raw = (design.spacing?.scale || []).map(v => typeof v === 'number' ? v : (v?.value ?? v?.size ?? 0)).filter(n => n > 0);
+  const scale = raw.slice().sort((a, b) => a - b).slice(0, 10);
+  if (!scale.length) return '';
+  return scale.map(v => `<div class="rhythm-bar" style="width:${Math.min(v * 1.6, 220)}px"><span>${v}</span></div>`).join('');
+}
+
+function familyName(f) {
+  if (!f) return '';
+  if (typeof f === 'string') return f;
+  return f.name || f.family || '';
+}
+
+function fontHref(family) {
+  const name = familyName(family);
+  if (!name) return '';
+  const f = name.replace(/['"]/g, '').split(',')[0].trim();
+  if (!f) return '';
+  return `https://fonts.googleapis.com/css2?family=${encodeURIComponent(f).replace(/%20/g, '+')}:wght@400;500;700&display=swap`;
+}
+
+export function formatGrade(design, opts = {}) {
+  const s = design.score;
+  if (!s) throw new Error('grade: design.score missing — extract failed to score');
+
+  const accent = gradeAccent(s.grade);
+  const headFamily = (design.typography?.families || [])[0];
+  const headHref = fontHref(headFamily);
+  const url = design.meta?.url || '';
+  const title = design.meta?.title || url;
+  const host = (() => { try { return new URL(url).hostname; } catch { return url; } })();
+  const date = new Date(design.meta?.timestamp || Date.now()).toLocaleDateString('en-US', { month: 'long', day: 'numeric', year: 'numeric' });
+  const issues = s.issues || [];
+  const strengths = s.strengths || [];
+  const ogTitle = `${host} — Grade ${s.grade}`;
+  const ogDesc = `Design system audit by designlang. ${s.overall}/100 across 8 dimensions.`;
+
+  const dims = DIMENSIONS
+    .filter(([k]) => s.scores[k] !== undefined)
+    .map(([k, label, blurb]) => {
+      const score = Math.round(s.scores[k]);
+      const dimAccent = score >= 80 ? '#0a8a52' : score >= 60 ? '#b08400' : '#c43d3d';
+      return `
+        <article class="dim">
+          <div class="dim-gauge">${arcGauge(score, dimAccent)}<span class="dim-score">${score}</span></div>
+          <div class="dim-body">
+            <h3>${esc(label)}</h3>
+            <p class="dim-blurb">${esc(blurb)}</p>
+            <p class="dim-verdict" style="color:${dimAccent}">${describeScore(score)}</p>
+          </div>
+        </article>`;
+    }).join('');
+
+  return `<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width,initial-scale=1">
+<title>${esc(ogTitle)} · designlang</title>
+<meta name="description" content="${esc(ogDesc)}">
+<meta property="og:title" content="${esc(ogTitle)}">
+<meta property="og:description" content="${esc(ogDesc)}">
+<meta property="og:type" content="article">
+<meta name="twitter:card" content="summary_large_image">
+<link rel="preconnect" href="https://fonts.googleapis.com">
+<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
+<link href="https://fonts.googleapis.com/css2?family=${encodeURIComponent(FONT_DISPLAY)}&family=${encodeURIComponent(FONT_BODY)}:wght@400;500;600&family=${encodeURIComponent(FONT_MONO)}:wght@400;500&display=swap" rel="stylesheet">
+${headHref ? `<link href="${esc(headHref)}" rel="stylesheet">` : ''}
+<style>
+  :root {
+    --paper: #f7f5ef;
+    --ink: #141414;
+    --ink-soft: #555049;
+    --rule: #e5e1d6;
+    --accent: ${accent};
+    --display: '${FONT_DISPLAY}', 'Times New Roman', serif;
+    --body: '${FONT_BODY}', -apple-system, BlinkMacSystemFont, system-ui, sans-serif;
+    --mono: '${FONT_MONO}', ui-monospace, 'SF Mono', monospace;
+  }
+  [data-theme="dark"] {
+    --paper: #0e0d0b;
+    --ink: #f0ece2;
+    --ink-soft: #9b9589;
+    --rule: #2a2823;
+  }
+  * { box-sizing: border-box; }
+  html, body { margin: 0; padding: 0; }
+  body {
+    background: var(--paper);
+    color: var(--ink);
+    font-family: var(--body);
+    font-size: 16px;
+    line-height: 1.55;
+    -webkit-font-smoothing: antialiased;
+    -moz-osx-font-smoothing: grayscale;
+    transition: background .25s ease, color .25s ease;
+  }
+  .wrap { max-width: 920px; margin: 0 auto; padding: 56px 40px 96px; }
+  @media (max-width: 640px) { .wrap { padding: 32px 22px 64px; } }
+
+  /* — Top bar — */
+  .topbar { display:flex; justify-content:space-between; align-items:center; margin-bottom: 72px; font-size: 13px; }
+  .brand { font-family: var(--display); font-size: 22px; letter-spacing: .01em; }
+  .brand a { color: var(--ink); text-decoration: none; border-bottom: 1px solid var(--rule); padding-bottom: 1px; }
+  .topbar nav { display:flex; gap: 18px; align-items: center; color: var(--ink-soft); }
+  .theme-btn {
+    background: transparent; border: 1px solid var(--rule); color: var(--ink-soft);
+    font-family: var(--body); font-size: 12px; padding: 6px 12px; border-radius: 999px; cursor: pointer;
+    letter-spacing: .04em; text-transform: uppercase;
+  }
+  .theme-btn:hover { color: var(--ink); border-color: var(--ink); }
+
+  /* — Hero — */
+  .hero { display: grid; grid-template-columns: minmax(0, 1fr) auto; gap: 32px; align-items: end; padding-bottom: 56px; border-bottom: 1px solid var(--rule); }
+  .kicker { text-transform: uppercase; letter-spacing: .18em; font-size: 11px; color: var(--ink-soft); margin-bottom: 18px; }
+  .hero h1 { font-family: var(--display); font-weight: 400; font-size: clamp(40px, 6vw, 72px); line-height: 1.02; margin: 0 0 18px; letter-spacing: -.01em; }
+  .hero h1 em { font-style: italic; color: var(--accent); }
+  .hero h1 a { color: var(--ink); text-decoration: none; border-bottom: 2px solid var(--accent); padding-bottom: 2px; transition: color .15s; }
+  .hero h1 a:hover { color: var(--accent); }
+  .hero .subject { font-size: 15px; color: var(--ink-soft); margin: 0; }
+  .hero .subject a { color: var(--ink); text-decoration: none; border-bottom: 1px solid var(--rule); }
+  .hero .meta { display:flex; gap: 18px; margin-top: 22px; font-size: 12px; color: var(--ink-soft); font-family: var(--mono); text-transform: uppercase; letter-spacing: .08em; }
+  .grade-block { text-align: center; }
+  .grade-letter {
+    font-family: var(--display); font-size: clamp(180px, 26vw, 280px); line-height: .82; color: var(--accent);
+    font-weight: 400; letter-spacing: -.04em; margin: 0;
+    animation: gradeIn .9s cubic-bezier(.2,.8,.2,1);
+  }
+  .grade-score { font-family: var(--mono); font-size: 14px; color: var(--ink-soft); letter-spacing: .04em; margin-top: 8px; }
+  @keyframes gradeIn { from { opacity: 0; transform: translateY(12px) scale(.96); } to { opacity: 1; transform: none; } }
+  @media (max-width: 640px) { .hero { grid-template-columns: 1fr; gap: 0; } .grade-block { text-align: left; margin-top: 24px; } }
+
+  /* — Section frame — */
+  section { padding: 64px 0; border-bottom: 1px solid var(--rule); }
+  section:last-of-type { border-bottom: 0; }
+  section > h2 { font-family: var(--display); font-weight: 400; font-size: 32px; margin: 0 0 8px; letter-spacing: -.005em; }
+  section > h2 + .lead { color: var(--ink-soft); margin: 0 0 36px; max-width: 60ch; }
+
+  /* — Dimensions grid — */
+  .dims { display: grid; grid-template-columns: repeat(2, minmax(0, 1fr)); gap: 32px 48px; }
+  @media (max-width: 640px) { .dims { grid-template-columns: 1fr; gap: 28px; } }
+  .dim { display: grid; grid-template-columns: 88px 1fr; gap: 18px; align-items: start; }
+  .dim-gauge { position: relative; width: 88px; height: 88px; }
+  .gauge { width: 100%; height: 100%; }
+  .gauge-track { stroke: var(--rule); }
+  .gauge-fill { stroke-dasharray: var(--c, 226); animation: arc 1.1s cubic-bezier(.2,.8,.2,1) both; }
+  @keyframes arc { from { stroke-dashoffset: 226; } }
+  .dim-score { position: absolute; inset: 0; display: flex; align-items: center; justify-content: center; font-family: var(--mono); font-weight: 500; font-size: 18px; }
+  .dim h3 { font-family: var(--display); font-weight: 400; font-size: 22px; margin: 4px 0 6px; }
+  .dim-blurb { color: var(--ink-soft); font-size: 14px; margin: 0 0 8px; }
+  .dim-verdict { font-size: 12px; font-family: var(--mono); text-transform: uppercase; letter-spacing: .08em; margin: 0; }
+
+  /* — Lists — */
+  .ledger { display: grid; grid-template-columns: repeat(2, 1fr); gap: 48px; }
+  @media (max-width: 640px) { .ledger { grid-template-columns: 1fr; gap: 36px; } }
+  .ledger h3 { font-family: var(--display); font-weight: 400; font-size: 22px; margin: 0 0 16px; }
+  .ledger ul { list-style: none; padding: 0; margin: 0; }
+  .ledger li { padding: 14px 0; border-top: 1px solid var(--rule); display: flex; gap: 14px; align-items: baseline; }
+  .ledger li:last-child { border-bottom: 1px solid var(--rule); }
+  .ledger .marker { font-family: var(--mono); font-size: 11px; color: var(--ink-soft); flex: 0 0 24px; padding-top: 2px; letter-spacing: .04em; }
+  .ledger li p { margin: 0; font-size: 15px; line-height: 1.5; }
+  .ledger.empty p { color: var(--ink-soft); font-style: italic; font-family: var(--display); font-size: 16px; }
+
+  /* — Evidence — */
+  .swatches { list-style: none; padding: 0; margin: 0; display: grid; grid-template-columns: repeat(auto-fill, minmax(110px, 1fr)); gap: 10px; }
+  .swatch { display: flex; align-items: center; gap: 8px; padding: 6px 10px 6px 6px; background: rgba(0,0,0,.02); border: 1px solid var(--rule); border-radius: 6px; }
+  [data-theme="dark"] .swatch { background: rgba(255,255,255,.03); }
+  .swatch-chip { width: 22px; height: 22px; border-radius: 4px; background: var(--c); box-shadow: inset 0 0 0 1px rgba(0,0,0,.06); flex: 0 0 auto; }
+  .swatch code { font-family: var(--mono); font-size: 11px; color: var(--ink-soft); }
+
+  .specimen { padding: 24px 0; }
+  .spec-line { line-height: 1.05; margin: 0 0 14px; letter-spacing: -.01em; }
+  .spec-line:nth-child(2) { color: var(--ink-soft); font-style: italic; }
+  .specimen-meta { display: flex; flex-wrap: wrap; gap: 24px; font-family: var(--mono); font-size: 11px; color: var(--ink-soft); text-transform: uppercase; letter-spacing: .06em; padding-top: 18px; border-top: 1px solid var(--rule); }
+
+  .rhythm { display: flex; flex-direction: column; gap: 6px; padding: 12px 0; }
+  .rhythm-bar { height: 14px; background: var(--accent); opacity: .82; border-radius: 2px; display: flex; align-items: center; padding-left: 10px; transition: opacity .15s; }
+  .rhythm-bar span { font-family: var(--mono); font-size: 10px; color: var(--paper); mix-blend-mode: difference; filter: invert(1); }
+  .rhythm-bar:hover { opacity: 1; }
+
+  /* — Footer — */
+  footer { padding: 48px 0 0; font-size: 13px; color: var(--ink-soft); display: flex; justify-content: space-between; align-items: end; flex-wrap: wrap; gap: 16px; }
+  footer .sig { font-family: var(--display); font-size: 22px; color: var(--ink); }
+  footer a { color: var(--ink); text-decoration: none; border-bottom: 1px solid var(--rule); }
+  footer .stamp { font-family: var(--mono); font-size: 11px; text-transform: uppercase; letter-spacing: .08em; }
+
+  /* — Print — */
+  @media print {
+    body { background: white; color: black; }
+    .topbar nav, .theme-btn { display: none; }
+    section, .hero { page-break-inside: avoid; border-color: #ddd; }
+    .grade-letter { color: black; }
+  }
+</style>
+</head>
+<body>
+  <div class="wrap">
+    <header class="topbar">
+      <div class="brand"><a href="https://designlang.dev">designlang</a></div>
+      <nav>
+        <span>Report Card</span>
+        <button class="theme-btn" id="themeBtn" type="button">Theme</button>
+      </nav>
+    </header>
+
+    <div class="hero">
+      <div>
+        <p class="kicker">Design Audit · ${esc(date)}</p>
+        <h1>An <em>independent reading</em> of the design system at <a href="${esc(url)}" target="_blank" rel="noopener">${esc(host)}</a>.</h1>
+        <p class="subject">${esc(title)}</p>
+        <div class="meta">
+          <span>${(design.colors?.all || []).length} colors</span>
+          <span>${(design.typography?.scale || []).length} sizes</span>
+          <span>${(design.spacing?.scale || []).length} spacings</span>
+          <span>${(design.shadows?.values || []).length} shadows</span>
+        </div>
+      </div>
+      <div class="grade-block">
+        <div class="grade-letter">${esc(s.grade)}</div>
+        <div class="grade-score">${s.overall} / 100</div>
+      </div>
+    </div>
+
+    <section>
+      <h2>Eight dimensions, scored.</h2>
+      <p class="lead">Each dimension is graded against calibrated thresholds drawn from production design systems (Stripe, Linear, Vercel, GitHub, Apple). The number is the headline; the prose underneath is what to do next.</p>
+      <div class="dims">${dims}</div>
+    </section>
+
+    <section>
+      <h2>What's working. What to fix.</h2>
+      <div class="ledger">
+        <div class="${strengths.length ? '' : 'empty'}">
+          <h3>Strengths</h3>
+          ${strengths.length
+            ? `<ul>${strengths.map((str, i) => `<li><span class="marker">${String(i + 1).padStart(2, '0')}</span><p>${esc(str)}</p></li>`).join('')}</ul>`
+            : `<p>No standout strengths surfaced — the system is uniformly mid-tier.</p>`}
+        </div>
+        <div class="${issues.length ? '' : 'empty'}">
+          <h3>What to fix</h3>
+          ${issues.length
+            ? `<ul>${issues.map((iss, i) => `<li><span class="marker">${String(i + 1).padStart(2, '0')}</span><p>${esc(iss)}</p></li>`).join('')}</ul>`
+            : `<p>Nothing material flagged. Polish, then ship.</p>`}
+        </div>
+      </div>
+    </section>
+
+    <section>
+      <h2>Evidence.</h2>
+      <p class="lead">The audit reads from the page itself. Here is what the auditor saw — palette, type, rhythm — drawn straight from the live styles.</p>
+
+      <h3 style="font-family:var(--display);font-weight:400;font-size:18px;margin:24px 0 12px;color:var(--ink-soft)">Palette</h3>
+      <ul class="swatches">${colorSwatches(design)}</ul>
+
+      <h3 style="font-family:var(--display);font-weight:400;font-size:18px;margin:32px 0 0;color:var(--ink-soft)">Type</h3>
+      ${typeSpecimen(design)}
+
+      <h3 style="font-family:var(--display);font-weight:400;font-size:18px;margin:32px 0 0;color:var(--ink-soft)">Spacing rhythm</h3>
+      <div class="rhythm">${spacingScale(design)}</div>
+    </section>
+
+    <footer>
+      <div>
+        <div class="sig">designlang</div>
+        <div>Audit any site: <code style="font-family:var(--mono)">npx designlang grade ${esc(host)}</code></div>
+      </div>
+      <div class="stamp">${esc(date)} · v${esc(opts.version || '')}</div>
+    </footer>
+  </div>
+
+  <script>
+    (function () {
+      var btn = document.getElementById('themeBtn');
+      var saved = null;
+      try { saved = localStorage.getItem('dl-theme'); } catch (e) {}
+      if (saved) document.documentElement.setAttribute('data-theme', saved);
+      btn && btn.addEventListener('click', function () {
+        var cur = document.documentElement.getAttribute('data-theme') === 'dark' ? '' : 'dark';
+        if (cur) document.documentElement.setAttribute('data-theme', cur);
+        else document.documentElement.removeAttribute('data-theme');
+        try { localStorage.setItem('dl-theme', cur); } catch (e) {}
+      });
+    })();
+  </script>
+</body>
+</html>`;
+}
+
+export function formatGradeMarkdown(design) {
+  const s = design.score;
+  if (!s) throw new Error('grade: design.score missing');
+  const url = design.meta?.url || '';
+  const date = new Date(design.meta?.timestamp || Date.now()).toISOString().split('T')[0];
+  const lines = [
+    `# Design Report Card — ${url}`,
+    ``,
+    `**Grade ${s.grade}** · ${s.overall}/100 · _${date}_`,
+    ``,
+    `## Dimensions`,
+    ``,
+    `| Dimension | Score | Verdict |`,
+    `|---|---|---|`,
+    ...DIMENSIONS.filter(([k]) => s.scores[k] !== undefined).map(([k, label]) =>
+      `| ${label} | ${Math.round(s.scores[k])}/100 | ${describeScore(s.scores[k])} |`),
+    ``,
+  ];
+  if (s.strengths?.length) {
+    lines.push(`## Strengths`, ``, ...s.strengths.map(x => `- ${x}`), ``);
+  }
+  if (s.issues?.length) {
+    lines.push(`## What to fix`, ``, ...s.issues.map(x => `- ${x}`), ``);
+  }
+  lines.push(`---`, `_Audited by [designlang](https://designlang.dev) · \`npx designlang grade ${url}\`_`);
+  return lines.join('\n');
+}