diff --git a/DESIGN.json b/DESIGN.json
new file mode 100644
index 000000000..af72cd851
--- /dev/null
+++ b/DESIGN.json
@@ -0,0 +1,242 @@
+{
+ "schemaVersion": 1,
+ "generatedAt": "2026-04-15T00:00:00Z",
+ "title": "Design System: Impeccable",
+ "tokens": {
+ "colors": [
+ {
+ "role": "primary",
+ "name": "Editorial Magenta",
+ "value": "oklch(60% 0.25 350)",
+ "description": "The one vibrant voice. Primary CTAs, active navigation, live-state indicators.",
+ "tonalRamp": [
+ "oklch(22% 0.12 350)",
+ "oklch(32% 0.18 350)",
+ "oklch(42% 0.22 350)",
+ "oklch(52% 0.25 350)",
+ "oklch(60% 0.25 350)",
+ "oklch(72% 0.18 350)",
+ "oklch(84% 0.10 350)",
+ "oklch(94% 0.04 350)"
+ ]
+ },
+ {
+ "role": "neutral",
+ "name": "Warm Ash Cream",
+ "value": "oklch(96% 0.005 350)",
+ "description": "Primary page background. Almost-imperceptible magenta tint.",
+ "tonalRamp": [
+ "oklch(15% 0.005 350)",
+ "oklch(25% 0.005 350)",
+ "oklch(40% 0.005 350)",
+ "oklch(55% 0.005 350)",
+ "oklch(70% 0.005 350)",
+ "oklch(82% 0.005 350)",
+ "oklch(92% 0.005 350)",
+ "oklch(96% 0.005 350)"
+ ]
+ },
+ {
+ "role": "neutral",
+ "name": "Deep Graphite",
+ "value": "oklch(10% 0 0)",
+ "description": "Primary text, body CTAs. Softer than pure black.",
+ "tonalRamp": [
+ "oklch(10% 0 0)",
+ "oklch(25% 0 0)",
+ "oklch(40% 0 0)",
+ "oklch(55% 0 0)",
+ "oklch(70% 0 0)",
+ "oklch(85% 0 0)",
+ "oklch(92% 0 0)",
+ "oklch(98% 0 0)"
+ ]
+ }
+ ],
+ "typography": [
+ {
+ "role": "display",
+ "name": "Display",
+ "family": "Cormorant Garamond",
+ "fallback": "Georgia, serif",
+ "weight": 300,
+ "style": "italic",
+ "sampleSize": "4.5rem",
+ "lineHeight": "1",
+ "purpose": "Hero title. Light italic for an author-signature feel."
+ },
+ {
+ "role": "body",
+ "name": "Body",
+ "family": "Instrument Sans",
+ "fallback": "system-ui, sans-serif",
+ "weight": 400,
+ "style": "normal",
+ "sampleSize": "1rem",
+ "lineHeight": "1.6",
+ "purpose": "All paragraph copy. Capped at 65–75ch."
+ },
+ {
+ "role": "label",
+ "name": "Label",
+ "family": "Instrument Sans",
+ "fallback": "system-ui, sans-serif",
+ "weight": 500,
+ "style": "normal",
+ "sampleSize": "0.9rem",
+ "lineHeight": "1",
+ "letterSpacing": "0.05em",
+ "textTransform": "uppercase",
+ "purpose": "CTA labels. Short, declarative."
+ },
+ {
+ "role": "mono",
+ "name": "Mono",
+ "family": "Space Grotesk",
+ "fallback": "ui-monospace, monospace",
+ "weight": 500,
+ "style": "normal",
+ "sampleSize": "0.75rem",
+ "lineHeight": "1.4",
+ "letterSpacing": "0.1em",
+ "textTransform": "uppercase",
+ "purpose": "Micro-labels: 'What's included', 'v3.0 Changelog'."
+ }
+ ],
+ "radii": [
+ { "name": "sm", "value": "4px" },
+ { "name": "md", "value": "8px" },
+ { "name": "lg", "value": "12px" },
+ { "name": "xl", "value": "16px" }
+ ],
+ "shadows": [
+ {
+ "name": "Soft Hover Lift",
+ "value": "0 4px 24px -4px rgba(0,0,0,0.12), 0 1px 3px rgba(0,0,0,0.06)",
+ "purpose": "Default hover response on cards and interactive surfaces."
+ },
+ {
+ "name": "Lifted Card",
+ "value": "0 20px 40px rgba(0,0,0,0.08)",
+ "purpose": "Deliberately elevated content (featured cards, install blocks)."
+ },
+ {
+ "name": "Accent Glow",
+ "value": "0 20px 60px oklch(60% 0.25 350 / 0.15)",
+ "purpose": "Magenta-tinted ambient shadow. Used sparingly."
+ }
+ ],
+ "spacing": [
+ { "name": "xs", "value": "8px" },
+ { "name": "sm", "value": "16px" },
+ { "name": "md", "value": "24px" },
+ { "name": "lg", "value": "32px" },
+ { "name": "xl", "value": "48px" },
+ { "name": "2xl", "value": "80px" },
+ { "name": "3xl", "value": "120px" }
+ ]
+ },
+ "components": [
+ {
+ "name": "Primary CTA",
+ "kind": "button",
+ "description": "Sharp, squared, uppercase. The editorial signature.",
+ "html": "GET STARTED ",
+ "css": ".ds-btn-primary { display: inline-block; padding: 16px 48px; font-family: 'Instrument Sans', system-ui, sans-serif; font-size: 0.9rem; font-weight: 500; letter-spacing: 0.05em; text-transform: uppercase; color: oklch(98% 0 0); background: oklch(10% 0 0); border: none; border-radius: 0; cursor: pointer; transition: transform 0.2s ease, background 0.2s ease; } .ds-btn-primary:hover { transform: translateY(-2px); background: oklch(60% 0.25 350); }"
+ },
+ {
+ "name": "Inline Text Link",
+ "kind": "button",
+ "description": "Secondary action. No boxed secondary button exists in the system.",
+ "html": "Read the docs ",
+ "css": ".ds-link { color: oklch(10% 0 0); font-family: 'Instrument Sans', system-ui, sans-serif; font-weight: 500; text-decoration: underline; text-underline-offset: 3px; text-decoration-thickness: 1px; transition: color 0.2s ease; } .ds-link:hover { color: oklch(60% 0.25 350); }"
+ },
+ {
+ "name": "Email Input",
+ "kind": "input",
+ "description": "Hairline border, transparent background, magenta focus glow.",
+ "html": "What's included ",
+ "css": ".ds-microlabel { display: inline-block; font-family: 'Space Grotesk', ui-monospace, monospace; font-size: 0.6875rem; font-weight: 500; letter-spacing: 0.1em; text-transform: uppercase; color: oklch(55% 0 0); }"
+ },
+ {
+ "name": "Site Navigation",
+ "kind": "nav",
+ "description": "62px compact bar. No underline at rest; accent underline on active.",
+ "html": "/ Impeccable /impeccable polish Sweep a site for AI-tool tells and refine typography, spacing, color in one pass.
07 Po polish
",
+ "css": ".ds-tile { display: grid; grid-template-rows: auto 1fr auto; align-items: center; justify-items: center; width: 56px; height: 64px; padding: 4px; background: #fdf2f8; border: 1px solid #ec4899; border-radius: 6px; color: #be185d; cursor: pointer; transition: transform 0.2s ease, box-shadow 0.2s ease; } .ds-tile:hover { transform: translateY(-2px); box-shadow: 0 6px 16px rgba(236, 72, 153, 0.18); } .ds-tile-num { font-family: 'Space Grotesk', ui-monospace, monospace; font-size: 7px; font-weight: 500; letter-spacing: 0.05em; justify-self: start; } .ds-tile-sym { font-family: 'Cormorant Garamond', Georgia, serif; font-style: italic; font-size: 20px; font-weight: 500; line-height: 1; } .ds-tile-lbl { font-family: 'Space Grotesk', ui-monospace, monospace; font-size: 7px; font-weight: 500; letter-spacing: 0.05em; text-transform: lowercase; }"
+ }
+ ],
+ "narrative": {
+ "northStar": "The Editorial Sanctuary",
+ "overview": "The Impeccable site reads more like a printed design publication than a SaaS landing page. Committed typography, generous breathing room, a single decisive accent. The aesthetic philosophy is restraint in service of craft. Every element earns its place.",
+ "keyCharacteristics": [
+ "Warm off-white paper tones with an almost-imperceptible magenta tint.",
+ "A single decisive magenta accent used on ≤10% of any screen.",
+ "Italic serif for display type; clean neutral sans for body at 1.6 line-height.",
+ "Sharp, uppercase, letter-tracked primary CTAs.",
+ "Flat surfaces at rest. Shadows appear only on state change.",
+ "Magazine-scale spacing (8 / 16 / 24 / 32 / 48 / 80 / 120px)."
+ ],
+ "rules": [
+ { "name": "The One Voice Rule", "section": "colors", "body": "Editorial Magenta is the only vibrant color. No supporting accent, ever. If a second emphasis point is needed, use scale or weight, never a second hue." },
+ { "name": "The Paper-Not-White Rule", "section": "colors", "body": "Page background is Warm Ash Cream, never Crisp Paper White. Warmth is load-bearing." },
+ { "name": "The OKLCH-Only Rule", "section": "colors", "body": "All new colors declared in OKLCH. Hex is reserved for the fenced Command Category Tints." },
+ { "name": "The Italic-Is-Voice Rule", "section": "typography", "body": "Italic is a voice choice for display type, not emphasis inside body copy. Body emphasis is carried by weight." },
+ { "name": "The 1.6 Leading Rule", "section": "typography", "body": "Body line-height is 1.6 everywhere. Not 1.5, not 1.7. This is the load-bearing readability decision." },
+ { "name": "The Fluid-Headlines-Only Rule", "section": "typography", "body": "Headings use clamp() fluid sizing. Body copy uses fixed rem values." },
+ { "name": "The Flat-By-Default Rule", "section": "elevation", "body": "Surfaces are flat at rest. Reach for shadows only on hover or deliberate elevation." },
+ { "name": "The Low-Alpha Rule", "section": "elevation", "body": "Every shadow uses ≤0.15 alpha on its strongest blur. Higher alphas read as 2014 Material drop shadows." },
+ { "name": "The Tinted-Shadow-Only-For-Accent Rule", "section": "elevation", "body": "Neutral shadows for structure. Magenta-tinted shadows only for deliberate accent-glow moments." }
+ ],
+ "dos": [
+ "Do treat Warm Ash Cream as the default page background.",
+ "Do use Editorial Magenta on ≤10% of any given screen.",
+ "Do set all new colors in OKLCH.",
+ "Do use italic display type as a voice, not as emphasis inside paragraphs.",
+ "Do use clamp() fluid sizing for headings; use fixed rem for body.",
+ "Do keep the primary CTA sharp and squared. border-radius: 0, uppercase, letter-tracked.",
+ "Do use --ease-out (cubic-bezier(0.16, 1, 0.3, 1)) or --ease-out-quint on transitions.",
+ "Do leave surfaces flat at rest. Reach for shadows only on hover or deliberate elevation.",
+ "Do respect prefers-reduced-motion on every animation.",
+ "Do cap body line length at 65–75ch via max-width."
+ ],
+ "donts": [
+ "Don't use pure black (#000) or pure white (#fff).",
+ "Don't use border-left or border-right greater than 1px as a colored stripe. The AI-dashboard tell.",
+ "Don't use background-clip: text with a gradient. Gradient text is banned.",
+ "Don't default to dark mode.",
+ "Don't use glassmorphism.",
+ "Don't add a second accent color.",
+ "Don't use rounded rectangles with generic drop shadows.",
+ "Don't use bounce or elastic easing.",
+ "Don't animate layout properties (width, height, padding, margin). Use transform and opacity.",
+ "Don't nest cards inside cards.",
+ "Don't use identical card grids.",
+ "Don't use the hero-metric layout template.",
+ "Don't extend the Command Category Tints vocabulary.",
+ "Don't hedge in UI copy.",
+ "Don't introduce a new spacing token outside the 8/16/24/32/48/80/120 scale."
+ ]
+ }
+}
diff --git a/source/skills/impeccable/reference/document.md b/source/skills/impeccable/reference/document.md
index ec78c560c..73bbbaec7 100644
--- a/source/skills/impeccable/reference/document.md
+++ b/source/skills/impeccable/reference/document.md
@@ -166,11 +166,111 @@ Concrete, forceful guardrails. Lead each with "Do" or "Don't". Be specific — i
- **Don't** [...]
```
+### Step 4b: Write DESIGN.json sidecar
+
+After the Markdown is written, produce a machine-readable sidecar at `DESIGN.json` next to `DESIGN.md`. This powers the `/impeccable live` design-system panel, which renders a tile-based visualization of the system — color swatches with tonal ramps, Aa type specimens, live component previews. **The sidecar is how the panel shows *this project's* actual button/input/nav/card, not a generic approximation.**
+
+Regenerate the sidecar whenever you regenerate DESIGN.md. If the user only asks to refresh the sidecar (e.g., from the live panel's stale-hint), preserve DESIGN.md and write only DESIGN.json.
+
+#### Schema
+
+```json
+{
+ "schemaVersion": 1,
+ "generatedAt": "ISO-8601 string",
+ "title": "Design System: [Project Title]",
+ "tokens": {
+ "colors": [
+ {
+ "role": "primary | secondary | tertiary | neutral | accent",
+ "name": "Descriptive Name",
+ "value": "#HEX or oklch(...) or rgba(...)",
+ "description": "Short role explanation (one sentence).",
+ "tonalRamp": ["...", "...", "..."]
+ }
+ ],
+ "typography": [
+ {
+ "role": "display | headline | title | body | label | mono",
+ "name": "Display",
+ "family": "Cormorant Garamond",
+ "fallback": "Georgia, serif",
+ "weight": 300,
+ "style": "normal | italic",
+ "sampleSize": "clamp(2.5rem, 7vw, 4.5rem) or 1rem",
+ "lineHeight": "1 | 1.2 | 1.6",
+ "letterSpacing": "normal | 0.05em",
+ "textTransform": "none | uppercase",
+ "purpose": "Short description of where this role is used."
+ }
+ ],
+ "radii": [{ "name": "sm|md|lg|xl|full", "value": "4px" }],
+ "shadows": [{ "name": "Descriptive Name", "value": "0 4px 24px rgba(0,0,0,0.12)", "purpose": "..." }],
+ "spacing": [{ "name": "xs|sm|md|lg|xl|2xl|3xl", "value": "8px" }]
+ },
+ "components": [
+ {
+ "name": "Primary Button",
+ "kind": "button | input | nav | chip | card | custom",
+ "description": "One-line what and when.",
+ "html": "GET STARTED ",
+ "css": ".ds-btn-primary { background: #191c1d; color: #fff; padding: 16px 48px; letter-spacing: 0.05em; text-transform: uppercase; font-weight: 500; border: none; border-radius: 0; transition: background 0.2s, transform 0.2s; } .ds-btn-primary:hover { background: oklch(60% 0.25 350); transform: translateY(-2px); }"
+ }
+ ],
+ "narrative": {
+ "northStar": "The Editorial Sanctuary",
+ "overview": "2-3 paragraphs of the philosophy — pulled from DESIGN.md Overview section.",
+ "keyCharacteristics": ["...", "..."],
+ "rules": [{ "name": "The One Voice Rule", "body": "...", "section": "colors|typography|elevation" }],
+ "dos": ["Do use ..."],
+ "donts": ["Don't use ..."]
+ }
+}
+```
+
+#### Component translation rules
+
+The `html` and `css` fields must be **self-contained, drop-in snippets** that render correctly when injected into a shadow DOM. The panel applies them directly — no post-processing, no framework runtime.
+
+1. **Tailwind expansion.** If the source uses Tailwind (className="bg-primary text-white rounded-lg px-6 py-3"), expand every utility to literal CSS properties in the `css` string. Do **not** reference Tailwind classes; do **not** assume a Tailwind CSS bundle is loaded. Each component is self-contained.
+2. **Token resolution.** If the project exposes tokens as CSS custom properties on `:root` (e.g. `--color-primary`, `--radius-md`), reference them via `var(--color-primary)` — they inherit through the shadow DOM and stay live-bound. If tokens live only in JS theme objects (styled-components, CSS-in-JS), resolve to literal values at generation time.
+3. **Icons.** Inline as SVG. Do not reference Lucide/Heroicons packages, icon fonts, or `
+
+ Design
+ `;
+ fab.addEventListener('click', toggleDesignPanel);
+ root.appendChild(fab);
+
+ // Panel
+ const panel = document.createElement('aside');
+ panel.className = 'panel';
+ panel.setAttribute('data-open', designState.open ? 'true' : 'false');
+ panel.appendChild(buildDesignHeader());
+ const body = document.createElement('div');
+ body.className = 'panel-body';
+ body.id = 'panel-body';
+ panel.appendChild(body);
+ root.appendChild(panel);
+
+ renderDesignBody();
+ }
+
+ function buildDesignHeader() {
+ const header = document.createElement('div');
+ header.className = 'panel-header';
+
+ const title = document.createElement('div');
+ title.className = 'panel-title';
+ title.textContent = designState.model?.title
+ || designState.parsedMd?.title
+ || 'Design System';
+ header.appendChild(title);
+
+ const tabs = document.createElement('div');
+ tabs.className = 'tabs';
+ for (const t of [['visual', 'Visual'], ['raw', 'Raw']]) {
+ const btn = document.createElement('button');
+ btn.className = 'tab';
+ btn.textContent = t[1];
+ btn.setAttribute('data-active', designState.tab === t[0] ? 'true' : 'false');
+ btn.addEventListener('click', () => {
+ if (designState.tab === t[0]) return;
+ designState.tab = t[0];
+ saveDesignPrefs();
+ renderDesignChrome();
+ if (t[0] === 'raw' && designState.raw === null && !designState.loading) {
+ fetchDesignSystem(); // raw is part of the same fetch pair
+ }
+ });
+ tabs.appendChild(btn);
+ }
+ header.appendChild(tabs);
+
+ const close = document.createElement('button');
+ close.className = 'panel-close';
+ close.innerHTML = '✕';
+ close.setAttribute('aria-label', 'Close panel');
+ close.addEventListener('click', toggleDesignPanel);
+ header.appendChild(close);
+
+ return header;
+ }
+
+ function toggleDesignPanel() {
+ designState.open = !designState.open;
+ saveDesignPrefs();
+ renderDesignChrome();
+ if (designState.open && designState.present === null && !designState.loading) {
+ fetchDesignSystem();
+ }
+ }
+
+ async function fetchDesignSystem() {
+ designState.loading = true;
+ designState.error = null;
+ renderDesignBody();
+ try {
+ const [jsonRes, rawRes] = await Promise.all([
+ fetch(`http://localhost:${PORT}/design-system.json?token=${TOKEN}`, { cache: 'no-store' }),
+ fetch(`http://localhost:${PORT}/design-system/raw?token=${TOKEN}`, { cache: 'no-store' }),
+ ]);
+ const jsonData = await jsonRes.json();
+ designState.present = jsonData.present === true;
+ designState.mode = jsonData.mode || null;
+ designState.model = jsonData.model || null;
+ designState.parsedMd = jsonData.parsedMd || null;
+ designState.mdNewerThanJson = !!jsonData.mdNewerThanJson;
+ designState.raw = designState.present && rawRes.ok ? await rawRes.text() : null;
+ designState.error = jsonData.error || null;
+ } catch (err) {
+ designState.error = err?.message || 'Failed to load design system.';
+ } finally {
+ designState.loading = false;
+ renderDesignChrome(); // refresh title from data
+ }
+ }
+
+ function renderDesignBody() {
+ const body = designShadow.querySelector('#panel-body');
+ if (!body) return;
+ body.innerHTML = '';
+
+ if (designState.loading) {
+ body.appendChild(msgDiv('loading', 'Loading design system…'));
+ return;
+ }
+ if (designState.error) {
+ body.appendChild(msgDiv('error', designState.error));
+ return;
+ }
+ if (designState.present === false) {
+ const empty = document.createElement('div');
+ empty.className = 'empty';
+ empty.innerHTML = `No DESIGN.md yet Create one by running /impeccable document in your terminal, then re-open this panel.`;
+ body.appendChild(empty);
+ return;
+ }
+
+ if (designState.tab === 'raw') {
+ renderRawTab(body, designState.raw || '');
+ return;
+ }
+
+ // Visual tab
+ if (designState.mdNewerThanJson) body.appendChild(renderStaleHint());
+
+ if (designState.mode === 'sidecar' && designState.model) {
+ renderSidecarVisual(body, designState.model);
+ } else if (designState.mode === 'parsed-md' && designState.parsedMd) {
+ body.appendChild(renderParsedMdCta());
+ renderParsedMdVisual(body, designState.parsedMd);
+ } else {
+ body.appendChild(msgDiv('empty', 'No design system data available.'));
+ }
+ }
+
+ function msgDiv(cls, text) {
+ const d = document.createElement('div');
+ d.className = cls;
+ d.textContent = text;
+ return d;
+ }
+
+ function renderStaleHint() {
+ const box = document.createElement('div');
+ box.className = 'stale';
+ box.innerHTML = `
+ DESIGN.md is newer than DESIGN.json. Run /impeccable document to refresh the sidecar.Basic view Running /impeccable document generates DESIGN.json alongside your DESIGN.md, which lets this panel render your project's actual button, input, and nav primitives — not generic approximations.`;
+ return box;
+ }
+
+ // --- Sidecar (DESIGN.json) rendering --------------------------------------
+
+ function renderSidecarVisual(body, model) {
+ const tokens = model.tokens || {};
+ if (tokens.colors?.length) renderColorTiles(body, tokens.colors);
+ if (tokens.typography?.length) renderTypeTiles(body, tokens.typography);
+ if (tokens.radii?.length) renderRadiiTile(body, tokens.radii);
+ if (tokens.shadows?.length) renderShadowTiles(body, tokens.shadows);
+ if (Array.isArray(model.components) && model.components.length) {
+ renderComponentTiles(body, model.components);
+ }
+
+ // Narrative → collapsibles (closed by default)
+ const n = model.narrative || {};
+ if (n.rules?.length) body.appendChild(renderRulesCollapsible(n.rules));
+ if ((n.dos?.length || n.donts?.length)) body.appendChild(renderDosDontsCollapsible(n));
+ if (n.overview || n.northStar || n.keyCharacteristics?.length) {
+ body.appendChild(renderOverviewCollapsible(n));
+ }
+ }
+
+ function renderColorTiles(body, colors) {
+ for (const c of colors) {
+ const tile = document.createElement('div');
+ tile.className = 'tile c-tile';
+ tile.title = 'Click to copy';
+ tile.addEventListener('click', () => copyToClipboard(c.value));
+
+ const meta = document.createElement('div');
+ meta.className = 'tile-meta';
+ meta.innerHTML = `${escapeHtml(c.name || c.role || 'Color')} ${escapeHtml(c.value || '')} `;
+ tile.appendChild(meta);
+
+ const hero = document.createElement('div');
+ hero.className = 'c-hero';
+ hero.style.background = c.value;
+ tile.appendChild(hero);
+
+ const ramp = synthesizeRamp(c);
+ if (ramp.length) {
+ const r = document.createElement('div');
+ r.className = 'c-ramp';
+ r.innerHTML = ramp.map((v) => `${escapeHtml(t.role || '')} ${escapeHtml(t.weight || '')} ${escapeHtml(t.style === 'italic' ? 'italic' : '')} `;
+ tile.appendChild(meta);
+
+ const specimen = document.createElement('div');
+ specimen.className = 't-specimen';
+ specimen.textContent = 'Aa';
+ specimen.style.fontFamily = fontStack(t);
+ specimen.style.fontWeight = String(t.weight || 400);
+ specimen.style.fontStyle = t.style || 'normal';
+ specimen.style.fontSize = '56px'; // Fixed specimen size — compare faces, not scales.
+ specimen.style.letterSpacing = 'normal';
+ specimen.style.textTransform = 'none';
+ tile.appendChild(specimen);
+
+ // The system's actual sample size for this role, shown as small mono meta below.
+ if (t.sampleSize) {
+ const scale = document.createElement('div');
+ scale.style.cssText = 'font-family:' + MONO + '; font-size: 10px; color:' + DP.meta + '; margin-top: 2px;';
+ scale.textContent = t.sampleSize;
+ tile.appendChild(scale);
+ }
+
+ const family = document.createElement('div');
+ family.className = 't-family';
+ family.textContent = t.family || t.name || '';
+ tile.appendChild(family);
+
+ if (t.purpose) {
+ const p = document.createElement('div');
+ p.className = 't-purpose';
+ p.textContent = t.purpose;
+ tile.appendChild(p);
+ }
+ body.appendChild(tile);
+ }
+ }
+
+ function fontStack(t) {
+ const fam = t.family || '';
+ const fb = t.fallback || '';
+ if (fam && /[,\s]/.test(fam) && !fam.includes("'") && !fam.includes('"')) {
+ return `"${fam}", ${fb}`;
+ }
+ return fam && fb ? `"${fam}", ${fb}` : (fam || fb);
+ }
+
+ function renderRadiiTile(body, radii) {
+ const tile = document.createElement('div');
+ tile.className = 'tile';
+ const meta = document.createElement('div');
+ meta.className = 'tile-meta';
+ meta.innerHTML = `Corner Radii ${radii.length} `;
+ tile.appendChild(meta);
+
+ const strip = document.createElement('div');
+ strip.className = 'r-strip';
+ for (const r of radii) {
+ const item = document.createElement('div');
+ item.className = 'r-item';
+ const s = document.createElement('div');
+ s.className = 'r-sample';
+ s.style.borderRadius = r.value || '0';
+ item.appendChild(s);
+ const lbl = document.createElement('div');
+ lbl.className = 'r-label';
+ lbl.textContent = r.name || '';
+ item.appendChild(lbl);
+ const val = document.createElement('div');
+ val.className = 'r-val';
+ val.textContent = r.value || '';
+ item.appendChild(val);
+ strip.appendChild(item);
+ }
+ tile.appendChild(strip);
+ body.appendChild(tile);
+ }
+
+ function renderShadowTiles(body, shadows) {
+ for (const sh of shadows) {
+ const tile = document.createElement('div');
+ tile.className = 'tile s-tile';
+
+ const meta = document.createElement('div');
+ meta.className = 'tile-meta';
+ meta.innerHTML = `${escapeHtml(sh.name || 'Shadow')} Elevation `;
+ tile.appendChild(meta);
+
+ const surface = document.createElement('div');
+ surface.className = 's-surface';
+ surface.style.boxShadow = sh.value || 'none';
+ tile.appendChild(surface);
+
+ const val = document.createElement('div');
+ val.className = 's-value';
+ val.textContent = sh.value || '';
+ tile.appendChild(val);
+
+ if (sh.purpose) {
+ const p = document.createElement('div');
+ p.className = 's-purpose';
+ p.textContent = sh.purpose;
+ tile.appendChild(p);
+ }
+ body.appendChild(tile);
+ }
+ }
+
+ function renderComponentTiles(body, components) {
+ // Group consecutive components that share a kind into one tile. This avoids
+ // a pile of one-component tiles (e.g., three button variants = three tiles)
+ // and reads more like a proper category.
+ const groups = groupByKind(components);
+
+ for (const group of groups) {
+ const tile = document.createElement('div');
+ tile.className = 'tile cmp-tile';
+
+ const meta = document.createElement('div');
+ meta.className = 'tile-meta';
+ const groupTitle = group.length === 1
+ ? (group[0].name || group[0].kind || 'Component')
+ : titleForKind(group[0].kind, group.length);
+ meta.innerHTML = `${escapeHtml(groupTitle)} ${escapeHtml(group[0].kind || '')} `;
+ tile.appendChild(meta);
+
+ for (const c of group) {
+ const stage = document.createElement('div');
+ stage.className = 'cmp-stage';
+
+ // Render the component in its own shadow root so its CSS can't bleed.
+ const host = document.createElement('div');
+ const sub = host.attachShadow({ mode: 'open' });
+ const style = document.createElement('style');
+ style.textContent = c.css || '';
+ sub.appendChild(style);
+ const container = document.createElement('div');
+ container.innerHTML = c.html || '';
+ sub.appendChild(container);
+ stage.appendChild(host);
+
+ // Show component name as a sublabel only when the tile groups >1 item,
+ // or when the component's display name differs from its kind.
+ const showSublabel = group.length > 1;
+ if (showSublabel) {
+ const lbl = document.createElement('div');
+ lbl.className = 'cmp-sublabel';
+ lbl.textContent = c.name || '';
+ stage.appendChild(lbl);
+ }
+ tile.appendChild(stage);
+ }
+
+ // Single shared description if all items carry the same one; otherwise
+ // skip — per-item descriptions clutter a grouped tile.
+ if (group.length === 1 && group[0].description) {
+ const d = document.createElement('div');
+ d.className = 'c-desc';
+ d.textContent = group[0].description;
+ tile.appendChild(d);
+ }
+ body.appendChild(tile);
+ }
+ }
+
+ function groupByKind(components) {
+ const groups = [];
+ for (const c of components) {
+ const last = groups[groups.length - 1];
+ if (last && last[0].kind && c.kind === last[0].kind) {
+ last.push(c);
+ } else {
+ groups.push([c]);
+ }
+ }
+ return groups;
+ }
+
+ function titleForKind(kind, count) {
+ const labels = {
+ button: 'Buttons',
+ input: 'Inputs',
+ nav: 'Navigation',
+ chip: 'Chips',
+ card: 'Cards',
+ custom: 'Components',
+ };
+ return labels[kind] || (kind ? kind.charAt(0).toUpperCase() + kind.slice(1) + 's' : 'Components');
+ }
+
+ // --- Collapsibles ---------------------------------------------------------
+
+ function buildCollapsible(key, label, count) {
+ const wrap = document.createElement('div');
+ wrap.className = 'coll';
+ wrap.setAttribute('data-open', designState.collapsed[key] ? 'false' : 'true');
+
+ const head = document.createElement('button');
+ head.className = 'coll-head';
+ head.innerHTML = `
+ ${escapeHtml(label)}
+ ${count != null ? `${escapeHtml(String(count))} ` : ''}
+ `;
+ head.addEventListener('click', () => {
+ designState.collapsed[key] = !designState.collapsed[key];
+ saveDesignPrefs();
+ renderDesignBody();
+ });
+ wrap.appendChild(head);
+
+ const body = document.createElement('div');
+ body.className = 'coll-body';
+ wrap.appendChild(body);
+ return { wrap, body };
+ }
+
+ function renderRulesCollapsible(rules) {
+ const { wrap, body } = buildCollapsible('rules', 'Named Rules', rules.length);
+ for (const r of rules) {
+ const card = document.createElement('div');
+ card.className = 'rule-card';
+ const name = document.createElement('div');
+ name.className = 'name';
+ name.innerHTML = `${escapeHtml(r.name)}${r.section ? `${escapeHtml(r.section)} ` : ''}`;
+ card.appendChild(name);
+ const b = document.createElement('div');
+ b.className = 'body';
+ b.textContent = r.body || '';
+ card.appendChild(b);
+ body.appendChild(card);
+ }
+ return wrap;
+ }
+
+ function renderDosDontsCollapsible(n) {
+ const total = (n.dos?.length || 0) + (n.donts?.length || 0);
+ const { wrap, body } = buildCollapsible('dosdonts', "Do's and Don'ts", total);
+ const grid = document.createElement('div');
+ grid.className = 'dos';
+ for (const d of n.dos || []) {
+ const el = document.createElement('div');
+ el.className = 'do';
+ el.innerHTML = inlineMd(d);
+ grid.appendChild(el);
+ }
+ for (const d of n.donts || []) {
+ const el = document.createElement('div');
+ el.className = 'dont';
+ el.innerHTML = inlineMd(d);
+ grid.appendChild(el);
+ }
+ body.appendChild(grid);
+ return wrap;
+ }
+
+ function renderOverviewCollapsible(n) {
+ const { wrap, body } = buildCollapsible('overview', 'Overview', null);
+ const ov = document.createElement('div');
+ ov.className = 'overview-body';
+ if (n.northStar) {
+ const star = document.createElement('span');
+ star.className = 'north-star';
+ star.textContent = '“' + n.northStar + '”';
+ ov.appendChild(star);
+ }
+ if (n.overview) {
+ const p = document.createElement('p');
+ p.innerHTML = inlineMd(n.overview);
+ ov.appendChild(p);
+ }
+ if (n.keyCharacteristics?.length) {
+ const ul = document.createElement('ul');
+ ul.innerHTML = n.keyCharacteristics.map((k) => `${inlineMd(k)} `).join('');
+ ov.appendChild(ul);
+ }
+ body.appendChild(ov);
+ return wrap;
+ }
+
+ // --- Parsed-md fallback visual (limited view: no live components) ---------
+
+ function renderParsedMdVisual(body, md) {
+ // Reuse sidecar renderers by projecting parsed-md output into the model shape.
+ const pseudoColors = (md.colors?.groups || []).flatMap((g) =>
+ (g.colors || []).map((c) => ({ role: g.role, name: c.name, value: c.value, description: c.description }))
+ );
+ if (pseudoColors.length) renderColorTiles(body, pseudoColors);
+
+ const pseudoTypes = Object.entries(md.typography?.fonts || {}).map(([role, f]) => ({
+ role, name: f.family, family: f.family, fallback: f.fallback, weight: 400,
+ purpose: f.purpose,
+ }));
+ if (pseudoTypes.length) renderTypeTiles(body, pseudoTypes);
+
+ if (md.elevation?.shadows?.length) renderShadowTiles(body, md.elevation.shadows);
+
+ const n = {
+ northStar: md.overview?.creativeNorthStar,
+ overview: (md.overview?.philosophy || []).join(' '),
+ keyCharacteristics: md.overview?.keyCharacteristics || [],
+ rules: [
+ ...(md.colors?.rules || []).map((r) => ({ ...r, section: 'colors' })),
+ ...(md.typography?.rules || []).map((r) => ({ ...r, section: 'typography' })),
+ ...(md.elevation?.rules || []).map((r) => ({ ...r, section: 'elevation' })),
+ ],
+ dos: md.dosDonts?.dos || [],
+ donts: md.dosDonts?.donts || [],
+ };
+ if (n.rules.length) body.appendChild(renderRulesCollapsible(n.rules));
+ if (n.dos.length || n.donts.length) body.appendChild(renderDosDontsCollapsible(n));
+ if (n.overview || n.northStar || n.keyCharacteristics.length) {
+ body.appendChild(renderOverviewCollapsible(n));
+ }
+ }
+
+ function cssSafe(v) {
+ // Strip anything outside valid CSS value chars to prevent injection via
+ // DESIGN.json values rendered into inline style strings.
+ return String(v).replace(/[<>"'`\n]/g, '');
+ }
+
+ // --- Raw tab: minimal markdown renderer (subset) --------------------------
+
+ function renderRawTab(body, md) {
+ const wrap = document.createElement('div');
+ wrap.className = 'md';
+ wrap.innerHTML = renderMarkdown(md);
+ body.appendChild(wrap);
+ }
+
+ function renderMarkdown(md) {
+ const lines = md.split(/\r?\n/);
+ const out = [];
+ let i = 0;
+ let inCode = false;
+ let codeBuf = [];
+ let paraBuf = [];
+ let listBuf = []; // array of { indent, html }
+ let listType = null; // 'ul' | 'ol'
+
+ const flushPara = () => {
+ if (paraBuf.length) {
+ out.push(`${inlineMd(paraBuf.join(' '))}
`);
+ paraBuf = [];
+ }
+ };
+ const flushList = () => {
+ if (listBuf.length) {
+ out.push(buildListHtml(listBuf, listType));
+ listBuf = [];
+ listType = null;
+ }
+ };
+ const flushAll = () => { flushPara(); flushList(); };
+
+ for (; i < lines.length; i++) {
+ const line = lines[i];
+
+ // Code fence
+ const fence = line.match(/^```(\w*)\s*$/);
+ if (fence) {
+ if (!inCode) { flushAll(); inCode = true; codeBuf = []; }
+ else {
+ out.push(`${escapeHtml(codeBuf.join('\n'))}${inlineMd(heading[2])} `);
+ continue;
+ }
+
+ const bullet = line.match(/^(\s*)([-*])\s+(.+)$/);
+ const ordered = line.match(/^(\s*)(\d+)\.\s+(.+)$/);
+ if (bullet || ordered) {
+ flushPara();
+ const m = bullet || ordered;
+ const indent = Math.floor(m[1].length / 2);
+ const t = bullet ? 'ul' : 'ol';
+ if (listType && listType !== t) flushList();
+ listType = t;
+ listBuf.push({ indent, html: inlineMd(m[3]) });
+ continue;
+ }
+
+ paraBuf.push(line);
+ }
+ flushAll();
+ if (inCode && codeBuf.length) {
+ out.push(`${escapeHtml(codeBuf.join('\n'))}${it.html} `;
+ lastIndent = it.indent;
+ }
+ html += ``.repeat(lastIndent + 1);
+ return html;
+ }
+
+ function inlineMd(text) {
+ // Order matters: escape first, then re-inject tags.
+ let s = escapeHtml(text);
+ // Code spans
+ s = s.replace(/`([^`]+)`/g, (_, code) => `${code}`);
+ // Links [text](url)
+ s = s.replace(/\[([^\]]+)\]\(([^)]+)\)/g, (_, t, u) => `${t} `);
+ // Bold
+ s = s.replace(/\*\*([^*]+)\*\*/g, '$1 ');
+ // Italic (only single *…*, skip if inside bold already handled)
+ s = s.replace(/(^|[^*])\*([^*\n]+)\*(?!\*)/g, '$1$2 ');
+ return s;
+ }
+
+ function highlightBold(text) {
+ return inlineMd(text);
+ }
+
+ function escapeHtml(s) {
+ return String(s)
+ .replace(/&/g, '&')
+ .replace(//g, '>')
+ .replace(/"/g, '"')
+ .replace(/'/g, ''');
+ }
+
+ function copyToClipboard(text) {
+ if (!text) return;
+ try {
+ navigator.clipboard.writeText(text);
+ showToast('Copied: ' + text);
+ } catch { /* ignore */ }
+ }
+
// ---------------------------------------------------------------------------
// Init
// ---------------------------------------------------------------------------
@@ -1509,6 +2592,7 @@
initBar();
initActionPicker();
initGlobalBar();
+ initDesignPanel();
document.addEventListener('mousemove', handleMouseMove, true);
document.addEventListener('click', handleClick, true);
document.addEventListener('keydown', handleKeyDown, true);
diff --git a/source/skills/impeccable/scripts/live-server.mjs b/source/skills/impeccable/scripts/live-server.mjs
index 9fc581257..5df033aaa 100644
--- a/source/skills/impeccable/scripts/live-server.mjs
+++ b/source/skills/impeccable/scripts/live-server.mjs
@@ -20,6 +20,7 @@ import path from 'node:path';
import os from 'node:os';
import net from 'node:net';
import { fileURLToPath } from 'node:url';
+import { parseDesignMd } from './design-parser.mjs';
const __dirname = path.dirname(fileURLToPath(import.meta.url));
// PID file in the project root so both the server and agent can find it
@@ -107,6 +108,10 @@ function hasProjectContext() {
} catch { return false; }
}
+function statOrNull(filePath) {
+ try { return fs.statSync(filePath); } catch { return null; }
+}
+
// ---------------------------------------------------------------------------
// Validation (inline — no external import needed for self-contained script)
// ---------------------------------------------------------------------------
@@ -176,6 +181,62 @@ function createRequestHandler({ detectScript, liveScriptWithToken }) {
return;
}
+ // --- Design system sidecar + raw ---
+ // /design-system.json prefers DESIGN.json; falls back to parsed DESIGN.md
+ // returns { mode, model, mdNewerThanJson, ... }
+ // /design-system/raw returns DESIGN.md markdown verbatim
+ if (p === '/design-system.json' || p === '/design-system/raw') {
+ const token = url.searchParams.get('token');
+ if (token !== state.token) { res.writeHead(401); res.end('Unauthorized'); return; }
+
+ const mdPath = path.join(process.cwd(), 'DESIGN.md');
+ const jsonPath = path.join(process.cwd(), 'DESIGN.json');
+ const mdStat = statOrNull(mdPath);
+ const jsonStat = statOrNull(jsonPath);
+
+ if (p === '/design-system/raw') {
+ if (!mdStat) { res.writeHead(404); res.end('Not found'); return; }
+ res.writeHead(200, { 'Content-Type': 'text/markdown; charset=utf-8' });
+ res.end(fs.readFileSync(mdPath, 'utf-8'));
+ return;
+ }
+
+ if (!mdStat && !jsonStat) {
+ res.writeHead(404, { 'Content-Type': 'application/json' });
+ res.end(JSON.stringify({ present: false }));
+ return;
+ }
+
+ // Prefer DESIGN.json — it's the richer source (live component HTML).
+ if (jsonStat) {
+ let model;
+ try {
+ model = JSON.parse(fs.readFileSync(jsonPath, 'utf-8'));
+ } catch (err) {
+ res.writeHead(500, { 'Content-Type': 'application/json' });
+ res.end(JSON.stringify({ present: true, error: 'Failed to parse DESIGN.json: ' + err.message }));
+ return;
+ }
+ const mdNewerThanJson = !!(mdStat && mdStat.mtimeMs > jsonStat.mtimeMs + 1000);
+ res.writeHead(200, { 'Content-Type': 'application/json' });
+ res.end(JSON.stringify({ present: true, mode: 'sidecar', model, mdNewerThanJson }));
+ return;
+ }
+
+ // Fallback: DESIGN.md present but no sidecar. Panel shows a "basic mode"
+ // view + a CTA to run /impeccable document for the full visualization.
+ try {
+ const raw = fs.readFileSync(mdPath, 'utf-8');
+ const parsedMd = parseDesignMd(raw);
+ res.writeHead(200, { 'Content-Type': 'application/json' });
+ res.end(JSON.stringify({ present: true, mode: 'parsed-md', parsedMd }));
+ } catch (err) {
+ res.writeHead(500, { 'Content-Type': 'application/json' });
+ res.end(JSON.stringify({ present: true, error: err.message }));
+ }
+ return;
+ }
+
// --- Source file (no-HMR fallback) ---
if (p === '/source') {
const token = url.searchParams.get('token');