@nusoft/nuos-build-catalogue 0.25.0 → 0.27.0

package/dist/render/design-system.js

@@ -0,0 +1,308 @@
+/**
+ * Render the `design-system/` register as an interactive companion gallery.
+ *
+ * What gets rendered:
+ *   - Colour tokens — as visual swatches with the hex value beside the name.
+ *   - Type scale — each step rendered at its declared px size with its line-height
+ *     and weight applied so the operator sees the real shape, not a description.
+ *   - Spacing scale — rendered as horizontal bars at the actual pixel widths.
+ *   - Radius & elevation — small boxes showing the corner radius applied.
+ *   - Motion — table only (no animation; would push complexity past MVP scope).
+ *   - Components + patterns — name list with first-paragraph summary.
+ *   - Voice + accessibility — first-paragraph summary blocks.
+ *
+ * Token files use GFM tables with a `Token` column and a value column. The parser
+ * looks for either a `Hex` / `Value` / `Size` / `Used for` column shape and falls
+ * back to "list the table verbatim" when the shape isn't recognised.
+ */
+import { readdir, readFile, writeFile, mkdir } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import path from 'node:path';
+import { parseSections, parseTable, firstParagraph, isPlaceholder, extractHexColours, } from './parser.js';
+import { pageWrapper, card, emptyState, escapeHtml, renderInlineMarkdown, renderProse, } from './html.js';
+export async function renderDesignSystem(opts) {
+    const dir = path.join(opts.buildRoot, 'design-system');
+    const outPath = path.join(dir, '_view.html');
+    if (!existsSync(dir)) {
+        return { written: false, outPath };
+    }
+    const blocks = [];
+    blocks.push(await renderTokenFile(dir, 'tokens-colour.md', renderColourTokens));
+    blocks.push(await renderTokenFile(dir, 'tokens-typography.md', renderTypeTokens));
+    blocks.push(await renderTokenFile(dir, 'tokens-spacing.md', renderSpacingTokens));
+    blocks.push(await renderTokenFile(dir, 'tokens-radius-elevation.md', renderRadiusTokens));
+    blocks.push(await renderTokenFile(dir, 'tokens-motion.md', renderMotionTokens));
+    blocks.push(await renderListing(path.join(dir, 'components'), 'Components'));
+    blocks.push(await renderListing(path.join(dir, 'patterns'), 'Patterns'));
+    blocks.push(await renderPlainFile(dir, 'voice.md', 'Voice'));
+    blocks.push(await renderPlainFile(dir, 'accessibility.md', 'Accessibility'));
+    const body = blocks.filter(Boolean).join('\n');
+    const html = pageWrapper({
+        title: 'Design system',
+        projectName: opts.projectName,
+        generatedAt: opts.generatedAt,
+        sourceNote: '<code>docs/build/design-system/</code>',
+        body: body || card('Design system not yet populated', emptyState('Phase C of planning populates this register.')),
+    });
+    await mkdir(dir, { recursive: true });
+    await writeFile(outPath, html, 'utf8');
+    return { written: true, outPath };
+}
+async function renderTokenFile(dir, filename, renderer) {
+    const filePath = path.join(dir, filename);
+    if (!existsSync(filePath))
+        return '';
+    const md = await readFile(filePath, 'utf8');
+    if (isPlaceholder(md)) {
+        return card(prettyTitle(filename), emptyState(`Not yet filled in (${filename}).`), { tone: 'muted' });
+    }
+    const sections = parseSections(md);
+    return renderer(sections, md);
+}
+function renderColourTokens(sections, md) {
+    const swatchBlocks = [];
+    for (const [heading, body] of sections) {
+        if (heading === '')
+            continue;
+        const table = parseTable(body);
+        if (!table)
+            continue;
+        const tokenColumn = findColumn(table, ['Token', 'Name']);
+        const hexColumn = findColumn(table, ['Hex', 'Value']);
+        const useColumn = findColumn(table, ['Used for', 'Role', 'Description']);
+        if (tokenColumn === -1)
+            continue;
+        const swatches = table.rows
+            .map((row) => {
+            const token = stripInline(row[tokenColumn] ?? '');
+            const value = stripInline(row[hexColumn === -1 ? 1 : hexColumn] ?? '');
+            const purpose = useColumn === -1 ? '' : row[useColumn] ?? '';
+            const hexes = extractHexColours(value);
+            const hex = hexes[0];
+            if (!hex)
+                return '';
+            return `<div class="swatch">
+          <div class="swatch__chip" style="background:${escapeHtml(hex)}"></div>
+          <div class="swatch__meta">
+            <code>${escapeHtml(token)}</code>
+            <small>${escapeHtml(hex)}${purpose ? ` · ${escapeHtml(stripInline(purpose))}` : ''}</small>
+          </div>
+        </div>`;
+        })
+            .filter(Boolean)
+            .join('');
+        if (swatches) {
+            swatchBlocks.push(`<h4>${escapeHtml(heading)}</h4>${swatches}`);
+        }
+    }
+    if (swatchBlocks.length === 0) {
+        return card('Colour tokens', renderProse(md));
+    }
+    return card('Colour tokens', swatchBlocks.join(''));
+}
+function renderTypeTokens(sections, md) {
+    const blocks = [];
+    for (const [heading, body] of sections) {
+        if (heading === '')
+            continue;
+        const table = parseTable(body);
+        if (!table)
+            continue;
+        const tokenCol = findColumn(table, ['Token', 'Name']);
+        const sizeCol = findColumn(table, ['Size']);
+        const lineCol = findColumn(table, ['Line height']);
+        const weightCol = findColumn(table, ['Weight']);
+        const useCol = findColumn(table, ['Used for']);
+        if (tokenCol === -1)
+            continue;
+        if (sizeCol !== -1) {
+            const samples = table.rows
+                .map((row) => {
+                const token = stripInline(row[tokenCol] ?? '');
+                const size = stripInline(row[sizeCol] ?? '');
+                const line = lineCol === -1 ? '' : stripInline(row[lineCol] ?? '');
+                const weight = weightCol === -1 ? '' : stripInline(row[weightCol] ?? '');
+                const use = useCol === -1 ? '' : stripInline(row[useCol] ?? '');
+                const cssSize = parsePxOrRem(size) ?? '16px';
+                const cssLine = parseUnitless(line) ?? '1.4';
+                const cssWeight = parseWeight(weight) ?? '400';
+                return `<div class="type-row">
+            <span class="type-sample" style="font-size:${cssSize};line-height:${cssLine};font-weight:${cssWeight}">The quick brown fox</span>
+            <small><code>${escapeHtml(token)}</code> · ${escapeHtml([size, weight, use].filter(Boolean).join(' · '))}</small>
+          </div>`;
+            })
+                .join('');
+            blocks.push(`<h4>${escapeHtml(heading)}</h4>${samples}`);
+        }
+        else {
+            blocks.push(`<h4>${escapeHtml(heading)}</h4>${renderTableAsTokens(table)}`);
+        }
+    }
+    if (blocks.length === 0)
+        return card('Typography', renderProse(md));
+    return card('Typography', blocks.join(''));
+}
+function renderSpacingTokens(sections, md) {
+    const blocks = [];
+    for (const [heading, body] of sections) {
+        if (heading === '')
+            continue;
+        const table = parseTable(body);
+        if (!table)
+            continue;
+        const tokenCol = findColumn(table, ['Token', 'Name', 'Step']);
+        const valCol = findColumn(table, ['Value', 'Size', 'px']);
+        if (tokenCol === -1 || valCol === -1) {
+            blocks.push(`<h4>${escapeHtml(heading)}</h4>${renderTableAsTokens(table)}`);
+            continue;
+        }
+        const bars = table.rows
+            .map((row) => {
+            const token = stripInline(row[tokenCol] ?? '');
+            const value = stripInline(row[valCol] ?? '');
+            const px = parsePx(value);
+            if (!px)
+                return '';
+            return `<div class="spacing-row">
+          <small><code>${escapeHtml(token)}</code> · ${escapeHtml(value)}</small>
+          <div class="spacing-bar" style="width:${px}px;max-width:100%"></div>
+        </div>`;
+        })
+            .filter(Boolean)
+            .join('');
+        blocks.push(`<h4>${escapeHtml(heading)}</h4>${bars || renderTableAsTokens(table)}`);
+    }
+    if (blocks.length === 0)
+        return card('Spacing', renderProse(md));
+    return card('Spacing', blocks.join(''));
+}
+function renderRadiusTokens(sections, md) {
+    const blocks = [];
+    for (const [heading, body] of sections) {
+        if (heading === '')
+            continue;
+        const table = parseTable(body);
+        if (!table)
+            continue;
+        const tokenCol = findColumn(table, ['Token', 'Name']);
+        const valCol = findColumn(table, ['Value', 'Radius', 'Size']);
+        if (tokenCol === -1 || valCol === -1) {
+            blocks.push(`<h4>${escapeHtml(heading)}</h4>${renderTableAsTokens(table)}`);
+            continue;
+        }
+        const examples = table.rows
+            .map((row) => {
+            const token = stripInline(row[tokenCol] ?? '');
+            const value = stripInline(row[valCol] ?? '');
+            const px = parsePx(value);
+            return `<div class="radius-row">
+          <div class="radius-chip" style="border-radius:${px ?? 0}px"></div>
+          <small><code>${escapeHtml(token)}</code> · ${escapeHtml(value)}</small>
+        </div>`;
+        })
+            .join('');
+        blocks.push(`<h4>${escapeHtml(heading)}</h4>${examples}`);
+    }
+    if (blocks.length === 0)
+        return card('Radius & elevation', renderProse(md));
+    return card('Radius & elevation', blocks.join(''));
+}
+function renderMotionTokens(sections, md) {
+    const blocks = [];
+    for (const [heading, body] of sections) {
+        if (heading === '')
+            continue;
+        const table = parseTable(body);
+        if (table)
+            blocks.push(`<h4>${escapeHtml(heading)}</h4>${renderTableAsTokens(table)}`);
+    }
+    if (blocks.length === 0)
+        return card('Motion', renderProse(md));
+    return card('Motion', blocks.join(''));
+}
+// ---------------------------------------------------------------------------
+// Components / patterns listing
+// ---------------------------------------------------------------------------
+async function renderListing(dir, title) {
+    if (!existsSync(dir))
+        return '';
+    const entries = await readdir(dir, { withFileTypes: true });
+    const items = [];
+    for (const entry of entries) {
+        if (!entry.isFile() || !entry.name.endsWith('.md'))
+            continue;
+        if (entry.name === '_index.md' || entry.name === '_template.md')
+            continue;
+        const md = await readFile(path.join(dir, entry.name), 'utf8');
+        if (isPlaceholder(md))
+            continue;
+        const titleMatch = md.match(/^#\s+(.+)$/m);
+        const name = titleMatch ? titleMatch[1].trim() : entry.name;
+        const summary = firstParagraph(md);
+        items.push(`<div class="listing-item">
+        <strong>${escapeHtml(name)}</strong>
+        ${summary ? `<p>${renderInlineMarkdown(summary)}</p>` : ''}
+        <small><code>${escapeHtml(entry.name)}</code></small>
+      </div>`);
+    }
+    if (items.length === 0)
+        return card(title, emptyState('None filed yet.'), { tone: 'muted' });
+    return card(title, items.join(''));
+}
+async function renderPlainFile(dir, filename, title) {
+    const filePath = path.join(dir, filename);
+    if (!existsSync(filePath))
+        return '';
+    const md = await readFile(filePath, 'utf8');
+    if (isPlaceholder(md)) {
+        return card(title, emptyState(`Not yet filled in (${filename}).`), { tone: 'muted' });
+    }
+    const summary = firstParagraph(md);
+    return card(title, summary ? `<p>${renderInlineMarkdown(summary)}</p>` : renderProse(md));
+}
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+function prettyTitle(filename) {
+    return filename
+        .replace(/\.md$/, '')
+        .replace(/^tokens-/, '')
+        .replace(/-/g, ' ')
+        .replace(/^./, (c) => c.toUpperCase());
+}
+function findColumn(table, candidates) {
+    const lower = table.headers.map((h) => h.toLowerCase());
+    for (const c of candidates) {
+        const idx = lower.indexOf(c.toLowerCase());
+        if (idx >= 0)
+            return idx;
+    }
+    return -1;
+}
+function stripInline(s) {
+    return s.replace(/^`(.+)`$/, '$1').replace(/\\\|/g, '|').trim();
+}
+function renderTableAsTokens(table) {
+    const head = table.headers.map((h) => `<th>${escapeHtml(h)}</th>`).join('');
+    const rows = table.rows
+        .map((row) => row.map((cell) => `<td>${renderInlineMarkdown(cell)}</td>`).join(''))
+        .map((r) => `<tr>${r}</tr>`)
+        .join('');
+    return `<table class="tokens-table"><thead><tr>${head}</tr></thead><tbody>${rows}</tbody></table>`;
+}
+function parsePxOrRem(s) {
+    const m = s.match(/(\d+(?:\.\d+)?)(px|rem|em)/);
+    return m ? `${m[1]}${m[2]}` : null;
+}
+function parsePx(s) {
+    const m = s.match(/(\d+(?:\.\d+)?)\s*px/i);
+    return m ? Number(m[1]) : null;
+}
+function parseUnitless(s) {
+    const m = s.match(/^(\d+(?:\.\d+)?)$/);
+    return m ? m[1] : null;
+}
+function parseWeight(s) {
+    const m = s.match(/\b(100|200|300|400|500|600|700|800|900)\b/);
+    return m ? m[1] : null;
+}

package/dist/render/html.d.ts

@@ -0,0 +1,47 @@
+/**
+ * HTML primitives shared across the per-register renderers.
+ *
+ * Design notes:
+ *   - Pure static HTML. No JS, no framework, no external CSS or fonts.
+ *   - One self-contained file per register so the operator can open it directly
+ *     in a browser or share it without a build step.
+ *   - Inline styles in a single `<style>` block; CSS variables for the few values
+ *     the renderers care about (token swatches, type previews) so they can be
+ *     overridden per-block without restating the rule set.
+ *   - The visual language is deliberately neutral — cards, restrained spacing,
+ *     system fonts. Consumer projects with strong design opinions can post-process
+ *     or skip companion rendering; the default isn't trying to be a brand.
+ */
+export declare function escapeHtml(s: string): string;
+/**
+ * Convert a single line of markdown to inline HTML — `code`, **bold**, *italic*,
+ * and [text](url) links. Block-level constructs (headings, lists, tables) are not
+ * processed; callers parse those structurally and use this helper on the cells.
+ */
+export declare function renderInlineMarkdown(s: string): string;
+/**
+ * Render a multi-line markdown block as paragraphs. Lists become `<ul>`/`<ol>`.
+ * Sub-headings (### / ####) become `<h4>`. Tables are skipped — the renderer should
+ * have parsed those structurally before getting here.
+ */
+export declare function renderProse(md: string): string;
+export declare function card(title: string, body: string, opts?: {
+    tone?: 'default' | 'muted';
+}): string;
+export declare function grid(items: string[], opts?: {
+    columns?: 'auto' | 'wide';
+}): string;
+export declare function emptyState(message: string): string;
+/**
+ * Wrap rendered fragments into a self-contained HTML document.
+ *
+ * The doc carries an explicit "generated, do not edit" banner so the operator
+ * doesn't try to hand-edit the file — the source of truth is the markdown.
+ */
+export declare function pageWrapper(opts: {
+    title: string;
+    projectName: string;
+    generatedAt: string;
+    sourceNote: string;
+    body: string;
+}): string;

package/dist/render/html.js

@@ -0,0 +1,258 @@
+/**
+ * HTML primitives shared across the per-register renderers.
+ *
+ * Design notes:
+ *   - Pure static HTML. No JS, no framework, no external CSS or fonts.
+ *   - One self-contained file per register so the operator can open it directly
+ *     in a browser or share it without a build step.
+ *   - Inline styles in a single `<style>` block; CSS variables for the few values
+ *     the renderers care about (token swatches, type previews) so they can be
+ *     overridden per-block without restating the rule set.
+ *   - The visual language is deliberately neutral — cards, restrained spacing,
+ *     system fonts. Consumer projects with strong design opinions can post-process
+ *     or skip companion rendering; the default isn't trying to be a brand.
+ */
+export function escapeHtml(s) {
+    return s
+        .replace(/&/g, '&amp;')
+        .replace(/</g, '&lt;')
+        .replace(/>/g, '&gt;')
+        .replace(/"/g, '&quot;')
+        .replace(/'/g, '&#39;');
+}
+/**
+ * Convert a single line of markdown to inline HTML — `code`, **bold**, *italic*,
+ * and [text](url) links. Block-level constructs (headings, lists, tables) are not
+ * processed; callers parse those structurally and use this helper on the cells.
+ */
+export function renderInlineMarkdown(s) {
+    let out = escapeHtml(s);
+    out = out.replace(/`([^`]+)`/g, '<code>$1</code>');
+    out = out.replace(/\*\*([^*]+)\*\*/g, '<strong>$1</strong>');
+    out = out.replace(/(?<!\*)\*([^*]+)\*(?!\*)/g, '<em>$1</em>');
+    out = out.replace(/\[([^\]]+)\]\(([^)]+)\)/g, (_m, text, href) => `<a href="${escapeHtml(href)}">${text}</a>`);
+    return out;
+}
+/**
+ * Render a multi-line markdown block as paragraphs. Lists become `<ul>`/`<ol>`.
+ * Sub-headings (### / ####) become `<h4>`. Tables are skipped — the renderer should
+ * have parsed those structurally before getting here.
+ */
+export function renderProse(md) {
+    const lines = md.split('\n');
+    const blocks = [];
+    let para = [];
+    let list = null;
+    let inTable = false;
+    const flushPara = () => {
+        if (para.length === 0)
+            return;
+        blocks.push(`<p>${renderInlineMarkdown(para.join(' '))}</p>`);
+        para = [];
+    };
+    const flushList = () => {
+        if (!list)
+            return;
+        const items = list.items.map((it) => `<li>${renderInlineMarkdown(it)}</li>`).join('');
+        blocks.push(`<${list.kind}>${items}</${list.kind}>`);
+        list = null;
+    };
+    for (const raw of lines) {
+        const line = raw.trim();
+        // Skip GFM tables — those are parsed structurally.
+        if (line.includes('|') && lines.indexOf(raw) + 1 < lines.length) {
+            const next = lines[lines.indexOf(raw) + 1]?.trim() ?? '';
+            if (/^\|?\s*:?-+:?(\s*\|\s*:?-+:?)+\s*\|?\s*$/.test(next))
+                inTable = true;
+        }
+        if (inTable) {
+            if (!line.includes('|'))
+                inTable = false;
+            else
+                continue;
+        }
+        if (inTable)
+            continue;
+        if (!line) {
+            flushPara();
+            flushList();
+            continue;
+        }
+        if (line.startsWith('> *') && line.endsWith('*'))
+            continue; // hint blockquote
+        if (line.startsWith('#### ')) {
+            flushPara();
+            flushList();
+            blocks.push(`<h5>${renderInlineMarkdown(line.slice(5))}</h5>`);
+            continue;
+        }
+        if (line.startsWith('### ')) {
+            flushPara();
+            flushList();
+            blocks.push(`<h4>${renderInlineMarkdown(line.slice(4))}</h4>`);
+            continue;
+        }
+        const ulMatch = line.match(/^[-*]\s+(.+)$/);
+        if (ulMatch) {
+            flushPara();
+            if (list?.kind !== 'ul') {
+                flushList();
+                list = { kind: 'ul', items: [] };
+            }
+            list.items.push(ulMatch[1]);
+            continue;
+        }
+        const olMatch = line.match(/^\d+\.\s+(.+)$/);
+        if (olMatch) {
+            flushPara();
+            if (list?.kind !== 'ol') {
+                flushList();
+                list = { kind: 'ol', items: [] };
+            }
+            list.items.push(olMatch[1]);
+            continue;
+        }
+        if (line.startsWith('>'))
+            continue; // generic blockquotes are usually template hints
+        para.push(line);
+    }
+    flushPara();
+    flushList();
+    return blocks.join('\n');
+}
+export function card(title, body, opts = {}) {
+    const cls = opts.tone === 'muted' ? 'card card--muted' : 'card';
+    return `<section class="${cls}"><h3>${escapeHtml(title)}</h3><div class="card__body">${body}</div></section>`;
+}
+export function grid(items, opts = {}) {
+    const cls = opts.columns === 'wide' ? 'grid grid--wide' : 'grid';
+    return `<div class="${cls}">${items.join('')}</div>`;
+}
+export function emptyState(message) {
+    return `<div class="empty">${escapeHtml(message)}</div>`;
+}
+/**
+ * Wrap rendered fragments into a self-contained HTML document.
+ *
+ * The doc carries an explicit "generated, do not edit" banner so the operator
+ * doesn't try to hand-edit the file — the source of truth is the markdown.
+ */
+export function pageWrapper(opts) {
+    return `<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width,initial-scale=1">
+<title>${escapeHtml(opts.title)} — ${escapeHtml(opts.projectName)}</title>
+<style>${BASE_CSS}</style>
+</head>
+<body>
+<header class="page-header">
+  <div class="page-header__title">
+    <small>${escapeHtml(opts.projectName)} catalogue companion</small>
+    <h1>${escapeHtml(opts.title)}</h1>
+  </div>
+  <div class="page-header__meta">
+    <p>Generated ${escapeHtml(opts.generatedAt)} from ${opts.sourceNote}. Do not hand-edit — the markdown is the source of truth.</p>
+  </div>
+</header>
+<main>
+${opts.body}
+</main>
+<footer class="page-footer">
+  <p>Regenerate with <code>npx @nusoft/nuos-build-catalogue render</code>.</p>
+</footer>
+</body>
+</html>
+`;
+}
+const BASE_CSS = `
+:root {
+  --bg: #fafaf9;
+  --surface: #ffffff;
+  --surface-muted: #f4f4f3;
+  --border: #e5e5e2;
+  --text: #1a1a1a;
+  --text-muted: #666;
+  --accent: #2a5cdc;
+  --shadow: 0 1px 2px rgba(0,0,0,0.04), 0 1px 6px rgba(0,0,0,0.03);
+  --radius: 8px;
+  --gap: 16px;
+}
+* { box-sizing: border-box; }
+body {
+  margin: 0;
+  background: var(--bg);
+  color: var(--text);
+  font: 15px/1.55 -apple-system, BlinkMacSystemFont, "Segoe UI", system-ui, sans-serif;
+}
+.page-header {
+  display: flex;
+  flex-wrap: wrap;
+  justify-content: space-between;
+  align-items: end;
+  gap: var(--gap);
+  padding: 32px max(24px, 4vw) 24px;
+  border-bottom: 1px solid var(--border);
+  background: var(--surface);
+}
+.page-header__title small { color: var(--text-muted); text-transform: uppercase; letter-spacing: 0.04em; font-size: 12px; }
+.page-header__title h1 { margin: 4px 0 0; font-size: 28px; font-weight: 600; }
+.page-header__meta { color: var(--text-muted); font-size: 13px; max-width: 50ch; }
+.page-header__meta p { margin: 0; }
+main { padding: 32px max(24px, 4vw); display: flex; flex-direction: column; gap: 28px; }
+.page-footer { padding: 24px max(24px, 4vw); color: var(--text-muted); font-size: 12px; border-top: 1px solid var(--border); }
+h2 { margin: 8px 0 4px; font-size: 18px; font-weight: 600; }
+h2 small { color: var(--text-muted); font-weight: 400; font-size: 13px; margin-left: 8px; }
+h3 { margin: 0 0 8px; font-size: 16px; font-weight: 600; }
+h4 { margin: 16px 0 4px; font-size: 14px; font-weight: 600; }
+h5 { margin: 12px 0 4px; font-size: 13px; font-weight: 600; color: var(--text-muted); text-transform: uppercase; letter-spacing: 0.04em; }
+p { margin: 0 0 8px; }
+p:last-child { margin-bottom: 0; }
+ul, ol { margin: 0 0 8px; padding-left: 22px; }
+li { margin-bottom: 4px; }
+code { background: var(--surface-muted); padding: 1px 6px; border-radius: 4px; font-family: ui-monospace, "SF Mono", Consolas, monospace; font-size: 0.92em; }
+a { color: var(--accent); text-decoration: none; }
+a:hover { text-decoration: underline; }
+.card { background: var(--surface); border: 1px solid var(--border); border-radius: var(--radius); padding: 18px 20px; box-shadow: var(--shadow); }
+.card--muted { background: var(--surface-muted); box-shadow: none; }
+.card__body { color: var(--text); font-size: 14px; line-height: 1.55; }
+.grid { display: grid; grid-template-columns: repeat(auto-fit, minmax(280px, 1fr)); gap: var(--gap); }
+.grid--wide { grid-template-columns: repeat(auto-fit, minmax(380px, 1fr)); }
+.empty { color: var(--text-muted); font-style: italic; font-size: 14px; padding: 12px 0; }
+.swatch { display: flex; gap: 12px; align-items: center; margin-bottom: 8px; }
+.swatch__chip { width: 36px; height: 36px; border-radius: 6px; border: 1px solid var(--border); flex-shrink: 0; }
+.swatch__meta { display: flex; flex-direction: column; min-width: 0; }
+.swatch__meta code { background: transparent; padding: 0; font-size: 13px; }
+.swatch__meta small { color: var(--text-muted); font-size: 12px; }
+.tokens-table { width: 100%; border-collapse: collapse; font-size: 13px; }
+.tokens-table th { text-align: left; padding: 6px 8px; border-bottom: 1px solid var(--border); font-weight: 600; color: var(--text-muted); }
+.tokens-table td { padding: 8px; border-bottom: 1px solid var(--border); vertical-align: top; }
+.type-sample { display: block; margin: 4px 0 12px; line-height: 1.2; }
+.spacing-bar { height: 14px; background: var(--accent); border-radius: 3px; }
+.tag { display: inline-block; padding: 2px 8px; border-radius: 999px; background: var(--surface-muted); font-size: 11px; color: var(--text-muted); margin-right: 4px; }
+.tag--status { background: #e5f0ff; color: #0b3da1; }
+.timeline { display: flex; flex-direction: column; gap: 12px; position: relative; padding-left: 24px; border-left: 2px solid var(--border); }
+.timeline .card { position: relative; }
+.timeline .card::before { content: ""; position: absolute; width: 10px; height: 10px; background: var(--accent); border-radius: 50%; left: -29px; top: 22px; }
+.sitemap-list { columns: 2 320px; column-gap: 24px; padding-left: 18px; }
+.sitemap-list li { break-inside: avoid; margin-bottom: 4px; }
+.card__tags { display: flex; flex-wrap: wrap; gap: 6px; margin: -4px 0 12px; }
+.wireframe { border: 1.5px dashed var(--border); border-radius: 6px; padding: 18px 16px; margin: 4px 0 12px; background: linear-gradient(135deg, var(--surface-muted) 25%, transparent 25%, transparent 50%, var(--surface-muted) 50%, var(--surface-muted) 75%, transparent 75%); background-size: 14px 14px; color: var(--text-muted); font-size: 13px; font-style: italic; }
+.wireframe__label { background: var(--surface); padding: 6px 10px; border-radius: 4px; display: inline-block; }
+.listing-item { padding: 10px 0; border-bottom: 1px solid var(--border); }
+.listing-item:last-child { border-bottom: none; }
+.listing-item p { margin: 4px 0; }
+.listing-item small { color: var(--text-muted); }
+.type-row { margin-bottom: 12px; }
+.type-row small { color: var(--text-muted); font-size: 12px; }
+.spacing-row { margin-bottom: 10px; display: flex; flex-direction: column; gap: 4px; }
+.spacing-row small { color: var(--text-muted); font-size: 12px; }
+.radius-row { display: flex; align-items: center; gap: 12px; margin-bottom: 8px; }
+.radius-chip { width: 48px; height: 32px; background: var(--accent); flex-shrink: 0; }
+.radius-row small { color: var(--text-muted); font-size: 12px; }
+@media (max-width: 720px) {
+  .page-header { flex-direction: column; align-items: flex-start; }
+  .sitemap-list { columns: 1; }
+}
+`;

package/dist/render/maps.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Render the `maps/` register as a single companion HTML page.
+ *
+ * Each map file (`01-the-horizon.md`, `02-phases.md`, `03-near-term.md`, etc.)
+ * is parsed by its `## Section` structure and rendered as a card with the
+ * section contents underneath. Multiple maps become a vertical timeline so the
+ * operator sees them in their intended order (numeric prefix).
+ */
+export interface MapsRenderResult {
+    written: boolean;
+    outPath: string;
+    mapCount: number;
+}
+export declare function renderMaps(opts: {
+    buildRoot: string;
+    projectName: string;
+    generatedAt: string;
+}): Promise<MapsRenderResult>;