designlang 7.0.0 → 7.2.0

package/docs/superpowers/specs/2026-04-18-website-redesign-design.md

@@ -0,0 +1,120 @@
+# designlang website redesign — Wave 2
+
+**Date:** 2026-04-18
+**Status:** Approved for implementation
+**Direction:** Live Design DNA — the site embodies what designlang does.
+
+## Non-negotiables (from user)
+
+- No "AI slop" aesthetic. No purple/blue gradients. No glassmorphism. No floating hero cards.
+- **No emoji. No icon libraries** (Lucide, Heroicons, Phosphor). Iconography only as intent-drawn inline SVG, numerals, or letterforms.
+- No Framer Motion bloat, no fade-up-on-every-element scroll theatrics.
+- Copy must be earned, not templated.
+- Designer voice visible — marginalia, footnotes, document-feel.
+
+## Visual system
+
+**Base:** warm paper `#F3F1EA`, ink `#0A0908`, accent `#FF4800` (used once per screen, maximum).
+**Grays (warm):** `#D8D3C5`, `#8B8778`, `#403C34`.
+**Type:** Fraunces (display, optical 9pt, massive sizes), Instrument Sans (body), JetBrains Mono (mono/tokens).
+**Grid:** 12-col, 24px gutters, deliberately broken by marginalia and side notes.
+**Rules:** 1px solid ink hairlines everywhere (document feel), no soft dividers.
+**Shadow:** one hard offset shadow (`6px 6px 0 #FF4800`) on the primary CTA only.
+**Dark mode:** deferred. Paper-first matches design-system/archival feel.
+**Motion:** prefers-reduced-motion strict. All motion is content-matched (see §Signature Interactions).
+
+## Page structure
+
+Single-page scroll. Numbered sections like a monograph: `§00`…`§09`.
+
+- §00 `HERO` — URL input + live extraction stream; tokens paint on screen as they compute.
+- §01 `DTCG BROWSER` — interactive alias resolver. Click a semantic token, the line flies to its primitive.
+- §02 `MCP` — split: Cursor/Claude Code rule panel on left, real terminal transcript on right.
+- §03 `MULTI-PLATFORM` — tabs Web / iOS / Android / Flutter / WordPress; same token in 5 languages.
+- §04 `CSS HEALTH` — big numerals (unused %, `!important` count, duplicates) set against real specificity plot.
+- §05 `A11Y REMEDIATION` — before/after contrast slider with live ratio.
+- §06 `REGIONS + COMPONENTS` — annotated screenshot; button cluster animates into variants.
+- §07 `FEATURED SPECIMENS` — stripe / vercel / linear / github / figma / apple; each extracted and displayed like a museum specimen. Page accent shifts as you scroll between them.
+- §08 `COMPARISON` — transparent, opinionated table vs. v0, Builder.io, Style Dictionary, Subframe, Project Wallace.
+- §09 `INSTALL & FOOTER` — `npx designlang`, MCP config, Cursor rule install, GitHub/npm/Discussions/sponsor.
+
+## Signature interactions (motion only where content-matched)
+
+1. **Hero stream** — user submits URL, server streams back tokens in extraction order; swatches paint from left to right as server events arrive.
+2. **DTCG alias flight** — click `{primitive.color.brand.primary}` string, an SVG line animates from the semantic token to the primitive, primitive highlights, hex resolves inline.
+3. **Accent shift scroll** — as the Featured Specimens section scrolls, page accent CSS var transitions to each specimen's extracted primary.
+4. **A11y slider** — handle drag shows contrast ratio updating live above the color pair.
+5. **MCP terminal transcript** — real JSON-RPC lines, typed at realistic speed, showing `search_tokens` → result.
+6. **Component cluster unfold** — a single button card unfolds into its detected variants on scroll-into-view.
+
+No other motion.
+
+## Backend
+
+**Existing:** `/api/extract` route using `@sparticuz/chromium` + `playwright-core` + designlang `extractDesignLanguage`.
+
+**Changes required:**
+
+1. **v7.0 output parity** — currently the API returns v6 shape. Add DTCG tokens, agent rules, MCP companion JSON, multi-platform outputs.
+2. **Streaming response** — the extraction produces tokens progressively; stream them over an HTTP stream (Next.js 16 streaming response) so the hero demo paints live. If extraction is atomic today (single `page.evaluate`), we stream the *stages*: crawl → colors → typography → spacing → components → a11y → done.
+3. **Rate limiting** — Vercel Edge Config or in-memory map keyed by IP. 3 extractions per IP per day for anonymous, soft 429 with helpful copy. No login.
+4. **URL validation** — reject `localhost`, `127.x`, `169.254.x`, `10.x`, `172.16–31.x`, `192.168.x`, `file://`, non-http(s). Reject URLs whose DNS resolves to private ranges.
+5. **Timeout cap** — hard 45s; abort Playwright if exceeded.
+6. **Caching** — cache extraction result by URL in Vercel Blob for 24h. Collision: same URL within 24h returns cached zip + a small "cached" annotation.
+7. **Bot detection** — Vercel BotID (free, platform-native).
+8. **Output:** downloadable `.zip` of all generated files (same set the CLI would produce for `--platforms all --emit-agent-rules`) plus a JSON summary for the on-screen preview.
+
+**New/changed files:**
+- `website/app/api/extract/route.js` — streaming + rate limit + caching + v7.0 outputs
+- `website/lib/rate-limit.js` (new)
+- `website/lib/url-safety.js` (new)
+- `website/lib/cache.js` (new, Vercel Blob-backed)
+
+## Frontend components (new)
+
+Kept flat in `website/app/components/`. Each is a self-contained section:
+
+- `Hero.js` — URL input + live stream renderer
+- `TokenBrowser.js` — DTCG alias resolver
+- `McpSection.js` — split editor + terminal
+- `PlatformTabs.js` — multi-platform code viewer
+- `CssHealth.js` — numerals + specificity plot (hand-drawn SVG scatter)
+- `A11ySlider.js` — contrast before/after
+- `RegionsComponents.js` — annotated image + cluster unfold
+- `Specimens.js` — featured site grid; orchestrates accent shift
+- `Comparison.js` — opinionated feature matrix
+- `InstallFooter.js` — closing section
+- `Marginalia.js` — shared side-column component for footnotes and command labels
+- `Rule.js` — 1px hairline divider with section label
+
+New lib:
+- `website/lib/token-helpers.js` — DTCG alias resolution shared with components
+- `website/lib/specimens.json` — pre-extracted data for the featured section (generated at build time from the CLI so specimens are real)
+
+## Deferred (explicit non-goals for Wave 2)
+
+- Login / user accounts / saved extractions
+- Paid tiers
+- Dark mode
+- Blog / changelog page
+- i18n
+- Sharable `/x/<slug>` permalinks (nice-to-have but not Wave 2)
+
+## Test / verification plan
+
+- Lighthouse: LCP ≤ 2.0s on the hero at 3G-Fast, CLS 0, accessibility ≥ 95.
+- `prefers-reduced-motion: reduce` — verify all motion stops or substitutes with non-motion reveal.
+- Keyboard navigation through every interactive element.
+- Extractor end-to-end: submit real URL, receive streamed tokens, download zip, verify zip contains v7.0 shape.
+- Rate limit: 4th request from same IP returns 429 with copy.
+- URL safety: localhost, private IPs, `file://` all rejected with 400.
+
+## Implementation chunks (PR per chunk)
+
+Each chunk is one PR. Merge before starting the next, same pattern as v7.0 release.
+
+- **PR A: Foundation** — fonts, base CSS, grid primitives, `Rule`, `Marginalia`, new `globals.css`, `layout.js`, clean `page.js` scaffold.
+- **PR B: Hero + streaming extraction API** — hero component, API streaming, URL safety, rate limit, basic Blob cache.
+- **PR C: Core showcase sections** — DTCG browser, MCP section, multi-platform tabs.
+- **PR D: Analytics sections** — CSS health, a11y slider, regions + components.
+- **PR E: Specimens + comparison + install + footer + deploy** — pre-extract data at build time, accent-shift scroll, comparison table, final polish, Vercel deploy.

package/docs/superpowers/specs/2026-04-19-designlang-v7-1-design.md

@@ -0,0 +1,111 @@
+# designlang v7.1 — Designer Toolkit
+
+**Date:** 2026-04-19
+**Status:** Approved for implementation
+
+## Theme
+
+*From extractor to designer's toolkit.* v7.0 shipped the full extraction surface. v7.1 makes the output composable, auditable, and complete — pull one component at a time, get every brand asset alongside the tokens, drop into any stack (Tailwind v4, Emotion, Stitches, Vanilla Extract, Panda), and fail your CI when production drifts from your design system.
+
+## Scope (7 features)
+
+### 1. Single-component extraction
+New flag: `designlang <url> --component <css-selector>`.
+- Playwright walks to the matched element, captures its own computed styles + its children's styles + its bounding box + its text content.
+- Emits a tiny extraction: `*-component.md` (a specimen-style card), `*-component.json` (the DTCG subset actually used by this component), `*-component.tsx` / `*-component.vue` / `*-component.svelte` based on `--framework` (or all three by default).
+- `--component` can be combined with `--platforms all` and `--emit-agent-rules`.
+
+### 2. Asset / brand-kit extraction
+New flag: `designlang <url> --assets` (also implied by `--full`).
+- Crawler enumerates every `<img>`, `<picture>`, `<source>`, `<svg>` (reuse existing icons work), `<link rel="icon">`, `<meta property="og:image">`, and CSS `background-image` URLs.
+- Downloads each asset with a timeout and size cap (50MB total per extraction).
+- Classifies: `logo`, `icon`, `illustration`, `photo`, `hero`, `og`, `favicon`, `avatar`, `screenshot`, `other`.
+- Emits to `<out>/assets/<kind>/<original-filename-or-hash.ext>` plus `assets-manifest.json` with the type, source URL, dimensions, byte size, and an `srcset`-style variant list for `<picture>` elements.
+- Size-aware: don't download a 20MB hero if it exceeds a per-asset cap (default 5MB). Log skipped assets in the manifest with a `skipped: reason` field.
+
+### 3. Illustration detection (folded into #2)
+- SVGs ≥ 200px or with >30 path elements → classified `illustration`, not `icon`.
+- Inline-SVG illustrations captured alongside external file references.
+- Raster illustrations (transparent PNG with flat-color regions) classified separately from photos via dominant-color entropy heuristic.
+
+### 4. Tailwind v4 `@theme` formatter
+New output file `<prefix>-tailwind.css` (separate from the existing `*-tailwind.config.js`, which stays for v3 users).
+- Uses the Tailwind v4 `@theme { … }` block syntax inside a `@import "tailwindcss"` wrapper.
+- Maps DTCG semantic tokens → Tailwind v4 CSS custom properties.
+- Respects `--tokens-legacy` (v4 file still emitted but from primitive-only JSON).
+
+### 5. CSS-in-JS emitters
+Four new formatters under `src/formatters/css-in-js/`:
+- `emotion.js` → `<prefix>-emotion.theme.ts`
+- `stitches.js` → `<prefix>-stitches.config.ts`
+- `vanilla-extract.js` → `<prefix>-vanilla.css.ts`
+- `panda.js` → `<prefix>-panda.config.ts`
+
+Selectable via new flag: `--framework emotion|stitches|vanilla-extract|panda|tailwind4`. Multi-select: `--framework emotion,stitches`. Default behavior unchanged: emit React theme + shadcn theme.
+
+### 6. Drift detection + GitHub Action
+New command: `designlang drift <url> <tokens-path> [--out <report-path>] [--fail-on <category>] [--tolerance <n>]`.
+- Extracts from `<url>`, loads DTCG JSON at `<tokens-path>`, walks both trees, and produces a report:
+  - `added` tokens (in extraction, not in file)
+  - `removed` (in file, not in extraction)
+  - `changed` (path matches, `$value` differs beyond tolerance)
+- Tolerance: colors use ΔE threshold (default 3), dimensions use px delta (default 1), others exact match.
+- `--fail-on color|dimension|typography|all` controls exit code (default exits 0 for a report-only run; exit 1 when any matching drift found with `--fail-on`).
+- Emits `drift-report.md` + `drift-report.json`.
+- **GitHub Action:** new `.github/workflows/designlang-drift.yml` template committed to this repo under `templates/github-action/designlang-drift.yml` with a README snippet. Runs on PR + daily cron, posts the report as a PR comment when drift is detected.
+
+### 7. Release
+- Bump to `7.1.0`, CHANGELOG entry, README updates, npm publish, git tag.
+
+## Non-goals (deferred to v7.2+)
+
+- **Remix Mode** / interactive web editor — substantial Next.js work; needs its own spec.
+- **Figma plugin**, **Chrome extension**, **VS Code extension** — each is a separate package with its own store/review cycle.
+- **Brand-voice extraction** (tone, reading level) — out of scope for a token release.
+- **Token marketplace / shared workspaces** — hosted SaaS territory.
+
+## Architecture
+
+### New files
+- `src/extractors/component.js` — selector-scoped extraction
+- `src/extractors/assets.js` — classifier + downloader for images and illustrations
+- `src/formatters/tailwind-v4.js`
+- `src/formatters/css-in-js/emotion.js`
+- `src/formatters/css-in-js/stitches.js`
+- `src/formatters/css-in-js/vanilla-extract.js`
+- `src/formatters/css-in-js/panda.js`
+- `src/formatters/component-snippet.js` — emits JSX / Vue / Svelte / HTML snippet from a component extraction
+- `src/formatters/drift.js` — produces drift-report.md + drift-report.json
+- `src/drift.js` — orchestrator for the `drift` subcommand
+- `templates/github-action/designlang-drift.yml`
+- `templates/github-action/README.md`
+
+### Modified files
+- `src/crawler.js` — add `fetchAssets()` with per-asset timeout + cap; add `page.$(selector).then(el => el.evaluate(...))` path for `--component`
+- `src/index.js` — wire new extractors + output files
+- `bin/design-extract.js` — new flags + `drift` subcommand
+- `src/config.js` — thread new options (`component`, `assets`, `framework`, driftTolerance)
+- `tests/extractors.test.js` + `tests/formatters.test.js` — new tests per extractor/formatter
+- `package.json` — version bump, potentially add `sharp` for optional raster resize (deferred decision — only if it stays zero-runtime-cost)
+- `README.md`
+- `CHANGELOG.md`
+
+### Dependencies
+- No new runtime deps. Image downloads use Node 20's native `fetch`. Classifier is heuristic only (no ML).
+
+### Security / safety
+- Asset downloader respects the same URL-safety layer as the website API (no private IPs, http(s) only, byte cap).
+- Same-origin preferred; cross-origin assets downloaded with an `Accept` header and a 10s timeout each.
+
+## Tests
+
+- Unit tests per extractor and formatter, snapshot-style for golden outputs.
+- Integration smoke: `designlang <url> --component "header nav" --assets --framework emotion,stitches,vanilla-extract,panda,tailwind4` produces all expected files.
+- Drift integration test: run against a fixture tokens file and a live URL, confirm report contents.
+
+## Release plan
+
+1. Implement via subagents in 3 parallel chunks (component+assets, emitters, drift+action).
+2. Tests green.
+3. README + CHANGELOG.
+4. Version bump → PR → merge → npm publish → tag.

package/package.json

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

package/src/config.js

@@ -27,7 +27,8 @@ export function mergeConfig(cliOpts, config) {
     screenshots: cliOpts.screenshots || config.screenshots || false,
     framework: cliOpts.framework || config.framework,
     responsive: cliOpts.responsive || config.responsive || false,
-    interactions: cliOpts.interactions || config.interactions || false,
+    interactions: cliOpts.interactions || cliOpts.deepInteract || config.interactions || false,
+    deepInteract: cliOpts.deepInteract || config.deepInteract || false,
     full: cliOpts.full || config.full || false,
     cookie: cliOpts.cookie || config.cookies,
     header: cliOpts.header || config.headers,
@@ -35,6 +36,9 @@ export function mergeConfig(cliOpts, config) {
     tokensLegacy: cliOpts.tokensLegacy || config.tokensLegacy || false,
     platforms: parsePlatforms(cliOpts.platforms ?? config.platforms ?? 'web'),
     emitAgentRules: cliOpts.emitAgentRules || config.emitAgentRules || false,
+    cookieFile: cliOpts.cookieFile || config.cookieFile,
+    insecure: cliOpts.insecure || config.insecure || false,
+    userAgent: cliOpts.userAgent || config.userAgent,
   };
 }