stitch2 0.0.0-stage → 0.7.2

package/dist/consistency.js

@@ -0,0 +1,336 @@
+/**
+ * Component consistency across screens. In each page it finds the shared elements (lab components by their
+ * data-<prefix> marker; in Stitch exports and hand-written markup by how they look: a fixed bottom bar with three or more
+ * buttons, the h1, buttons filled with the primary colour, pill chips, icon-only buttons, caps section labels) and takes a signature of
+ * each: size, radius, label font, icon size, and for the tab bar its centre circle. Screens of one family
+ * (the Stitch folder, an archive folder, or the lab's own screens) should share one signature per component; check reports
+ * the screens that differ from the majority, and lab screens that build a catalog component by hand.
+ */
+import { config } from './config.js';
+import { readDesign } from './design-md.js';
+/** The options for collectComponents from the config and DESIGN.md's primary colour. */
+export function collectOptions() {
+    const hex = (readDesign().colors.primary ?? '#000000').replace('#', '');
+    return { prefix: config.prefix, primary: [0, 2, 4].map((i) => Number.parseInt(hex.slice(i, i + 2), 16)) };
+}
+/** Runs in the page. Plain JS on purpose: Playwright sends its source to the browser. */
+export function collectComponents(opts) {
+    const sel = (el) => {
+        const parts = [];
+        for (let e = el; e && e !== document.body && parts.length < 6; e = e.parentElement) {
+            if (e.id) {
+                parts.unshift(`#${CSS.escape(e.id)}`);
+                break;
+            }
+            let p = e.tagName.toLowerCase();
+            const same = e.parentElement
+                ? [...e.parentElement.children].filter((c) => c.tagName === e.tagName)
+                : [];
+            if (same.length > 1)
+                p += `:nth-of-type(${same.indexOf(e) + 1})`;
+            parts.unshift(p);
+        }
+        return parts.join(' > ');
+    };
+    const px = (v) => String(Math.round(Number.parseFloat(v) || 0));
+    const ownText = (el) => [...el.childNodes]
+        .filter((n) => n.nodeType === 3)
+        .map((n) => n.textContent.trim())
+        .join(' ')
+        .trim();
+    const isIconFont = (el) => /material|symbols|icons/i.test(getComputedStyle(el).fontFamily);
+    const firstText = (root, match) => {
+        for (const el of [root, ...root.querySelectorAll('*')]) {
+            const t = ownText(el);
+            if (t && !isIconFont(el) && (!match || match.test(t)))
+                return el;
+        }
+        return null;
+    };
+    const font = (el) => {
+        if (!el)
+            return '';
+        const c = getComputedStyle(el);
+        const size = Number.parseFloat(c.fontSize);
+        const tr = c.letterSpacing === 'normal' ? 0 : Number.parseFloat(c.letterSpacing) / size;
+        return `${size}/${c.fontWeight}/${c.fontFamily.split(',')[0].replaceAll(/["']/g, '').trim()}${tr ? `/${tr.toFixed(2)}em` : ''}`;
+    };
+    const iconSize = (root) => {
+        const i = root.querySelector('svg, i, .material-symbols-outlined, [class*="material-symbols"]');
+        return i ? px(String(i.getBoundingClientRect().width)) : '';
+    };
+    // Which icon set and which glyphs: Lucide SVGs carry lucide-<name>, Material Symbols are ligature text.
+    const icons = (root) => [...root.querySelectorAll('svg, [data-lucide], [class*="material-symbols"], .material-icons')]
+        .filter((i) => !i.parentElement?.closest('svg'))
+        .map((i) => {
+        const cls = String(i.getAttribute('class') ?? '');
+        const lucide = /\blucide-([a-z0-9-]+)/.exec(cls)?.[1] ?? i.getAttribute('data-lucide');
+        if (lucide)
+            return ['lucide', lucide];
+        if (/material/.test(cls) || /material|symbols/i.test(getComputedStyle(i).fontFamily))
+            return ['material-symbols', (i.textContent ?? '').trim()];
+        return ['svg', ''];
+    });
+    const iconSet = (root) => [...new Set(icons(root).map(([s]) => s))].join('+');
+    const box = (el) => el.getBoundingClientRect();
+    const ember = (el) => getComputedStyle(el).backgroundColor.includes(opts.primary.join(', '));
+    const visible = (el) => {
+        const r = box(el);
+        const c = getComputedStyle(el);
+        return r.width > 0 && r.height > 0 && c.visibility !== 'hidden' && c.display !== 'none';
+    };
+    const sigOf = (kind, el) => {
+        const c = getComputedStyle(el);
+        const r = box(el);
+        const f = {};
+        const base = kind.split(':')[0];
+        if (base === 'tab-bar') {
+            f.height = px(String(r.height));
+            f.background = c.backgroundColor;
+            f.label = font(firstText(el));
+            f.icon = iconSize(el);
+            f.iconSet = iconSet(el);
+            f.icons = icons(el)
+                .map(([, n]) => n)
+                .filter(Boolean)
+                .join(',');
+            const circle = [...el.querySelectorAll('*')].find((e) => ember(e) && Math.abs(box(e).width - box(e).height) < 2);
+            if (circle) {
+                f.circle = px(String(box(circle).width));
+                f.lift = px(String(r.top - box(circle).top));
+            }
+            f.centreLabel = /\b(Start|Resume)\b/.test(el.textContent ?? '') ? 'yes' : 'no';
+        }
+        else if (base === 'header') {
+            f.title = font(el.matches('h1') ? el : (el.querySelector('h1') ?? firstText(el)));
+        }
+        else if (base === 'section') {
+            f.label = font(el.matches('h2, h3, p, span') ? el : (el.querySelector('h2, h3') ?? firstText(el)));
+        }
+        else if (base === 'card') {
+            f.radius = px(c.borderTopLeftRadius);
+            f.background = c.backgroundColor;
+        }
+        else if (base === 'button' || base === 'icon-button' || base === 'chip') {
+            f.height = px(String(r.height));
+            f.radius = px(c.borderTopLeftRadius);
+            f.font = font(firstText(el));
+            if (base === 'icon-button') {
+                f.icon = iconSize(el);
+                f.iconSet = iconSet(el);
+                f.width = px(String(r.width));
+                f.background = c.backgroundColor;
+            }
+        }
+        // Every other component (rows, sheets, charts, a sidebar, …) takes its size from its content, and its code
+        // guarantees the rest: only its presence is recorded, so screens are not flagged for holding other content.
+        for (const k of Object.keys(f))
+            if (!f[k])
+                delete f[k];
+        return {
+            selector: sel(el),
+            text: (el.textContent ?? '').trim().replace(/\s+/g, ' ').slice(0, 40),
+            fields: f,
+        };
+    };
+    const components = {};
+    const add = (kind, el) => {
+        const s = sigOf(kind, el);
+        components[kind] ??= [];
+        if (!components[kind].some((x) => JSON.stringify(x.fields) === JSON.stringify(s.fields)))
+            components[kind].push(s);
+    };
+    const handBuilt = [];
+    // 1. Lab components announce themselves.
+    const marker = `data-${opts.prefix}`;
+    for (const el of document.querySelectorAll(`[${marker}]`)) {
+        if (!visible(el))
+            continue;
+        const g = el.getAttribute(marker);
+        const kind = g === 'button' ? `button:${el.getAttribute('data-variant') ?? 'primary'}:${el.getAttribute('data-size') ?? 'md'}` : g;
+        if (!(g === 'button' && el.hasAttribute('disabled')))
+            add(kind, el);
+    }
+    // 2. Everything else is recognised by how it looks.
+    const H = window.innerHeight;
+    const W = document.documentElement.clientWidth;
+    const loose = (el) => !el.closest(`[${marker}]`);
+    const all = [...document.body.querySelectorAll('*')].filter((el) => visible(el) && loose(el));
+    const found = (kind, el) => {
+        add(kind, el);
+        handBuilt.push({
+            kind,
+            selector: sel(el),
+            text: (el.textContent ?? '').trim().replace(/\s+/g, ' ').slice(0, 40),
+        });
+    };
+    // A tab bar: a full-width bar fixed to the bottom with three or more buttons or links.
+    const bar = all.find((el) => {
+        const r = box(el);
+        return (getComputedStyle(el).position === 'fixed' &&
+            r.bottom >= H - 2 &&
+            r.width >= W * 0.9 &&
+            r.height < 140 &&
+            el.querySelectorAll('button, a').length >= 3);
+    });
+    if (bar)
+        found('tab-bar', bar);
+    const inBar = (el) => !!bar && bar.contains(el);
+    const h1 = all.find((el) => el.matches('h1'));
+    if (h1)
+        found('header', h1);
+    for (const el of all) {
+        if (inBar(el) || !el.matches('button, a, [role=button]'))
+            continue;
+        if (el.parentElement?.closest('button, a'))
+            continue;
+        const r = box(el);
+        const text = (el.textContent ?? '').trim();
+        const hasIcon = !!el.querySelector('svg, i, [class*="material-symbols"]');
+        const radius = Number.parseFloat(getComputedStyle(el).borderTopLeftRadius);
+        const textless = !firstText(el);
+        if (ember(el) && text && r.width > r.height * 1.5 && r.height >= 36)
+            found('button:primary:md', el);
+        // Header actions: icon-only buttons near the top (stars and steppers further down are other things).
+        else if (textless &&
+            hasIcon &&
+            r.width >= 32 &&
+            r.width <= 56 &&
+            Math.abs(r.width - r.height) < 4 &&
+            !ember(el) &&
+            r.top + window.scrollY < 140)
+            found('icon-button', el);
+        else if (!textless && radius >= r.height / 2 - 1 && r.height >= 26 && r.height <= 40 && text.length <= 24)
+            found('chip', el);
+    }
+    for (const el of all) {
+        if (inBar(el) || el.closest('button, a'))
+            continue;
+        const t = ownText(el);
+        const c = getComputedStyle(el);
+        // Caps labels: uppercased by CSS or typed in capitals, without digits ("RPE 8" is a value, not a label).
+        if (t.length >= 3 &&
+            !/\d/.test(t) &&
+            Number.parseFloat(c.fontSize) <= 13 &&
+            (c.textTransform === 'uppercase' || (t === t.toUpperCase() && /[A-Z]{4}/.test(t.replace(/\s/g, '')))) &&
+            el.matches('h2, h3, h4, p, span, div, label'))
+            found('section', el);
+    }
+    return { components, handBuilt };
+}
+/** The components whose look is measured and compared; the rest follow their content (see sigOf). */
+const MEASURED = new Set(['tab-bar', 'header', 'section', 'card', 'button', 'icon-button', 'chip']);
+export function familyOf(path) {
+    if (path.startsWith(`${config.stitchDir}/`))
+        return config.stitchDir;
+    return config.archiveDirs.find((d) => path.startsWith(`${d}/`)) ?? 'screens';
+}
+const p = config.prefix;
+const NAMES = {
+    'tab-bar': ['Tab bar', `${p}-tab-bar`],
+    header: ['Screen header', `${p}-header`],
+    section: ['Section label', `${p}-section`],
+    chip: ['Chip', `${p}-chip`],
+    'icon-button': ['Icon button', `${p}-icon-button`],
+    'button:primary:md': ['Primary button', `${p}-button`],
+};
+export const nameOf = (kind) => NAMES[kind]?.[0] ?? kind.replace(/:/g, ' ');
+const key = (s) => JSON.stringify(s.fields);
+/** Issues for the screens in `paths`, comparing with every screen whose components are known. */
+export function consistencyIssues(known, paths) {
+    const out = {};
+    const families = new Map();
+    const catalogs = Object.keys(known).filter((p) => p.startsWith(`${config.catalogDir}/`));
+    for (const p of Object.keys(known))
+        families.set(familyOf(p), [...(families.get(familyOf(p)) ?? []), p]);
+    for (const path of paths) {
+        const issues = [];
+        out[path] = issues;
+        const peers = (families.get(familyOf(path)) ?? []).filter((p) => p !== path);
+        for (const [kind, sigs] of Object.entries(known[path] ?? {})) {
+            if (sigs.length > 1 && MEASURED.has(kind.split(':')[0]))
+                issues.push({
+                    severity: 'warning',
+                    type: 'consistency',
+                    message: `${sigs.length} different versions of the ${nameOf(kind).toLowerCase()} on this screen`,
+                    selector: sigs[1].selector,
+                    text: sigs[1].text,
+                });
+            // The component catalog is the reference for every screen that is not an archived experiment.
+            const reference = familyOf(path) === config.stitchDir || familyOf(path) === 'screens'
+                ? catalogs.flatMap((c) => known[c]?.[kind] ?? [])
+                : [];
+            if (catalogs.includes(path))
+                continue;
+            if (reference.length) {
+                const mine = sigs[0];
+                if (reference.some((r) => key(r) === key(mine)))
+                    continue;
+                const ref = reference[0];
+                const diffs = Object.keys({ ...mine.fields, ...ref.fields })
+                    .filter((f) => mine.fields[f] !== ref.fields[f])
+                    .map((f) => `${f} ${mine.fields[f] ?? '–'} (catalog ${ref.fields[f] ?? '–'})`);
+                issues.push({
+                    severity: 'warning',
+                    type: 'consistency',
+                    message: `${nameOf(kind)} differs from the component catalog: ${diffs.join('; ')}`,
+                    selector: mine.selector,
+                    text: mine.text,
+                });
+                continue;
+            }
+            // The majority version among the other screens of the family.
+            const votes = new Map();
+            for (const p of peers) {
+                const first = known[p]?.[kind]?.[0];
+                if (!first)
+                    continue;
+                const v = votes.get(key(first)) ?? { n: 0, sig: first };
+                v.n++;
+                votes.set(key(first), v);
+            }
+            const ranked = [...votes.values()].sort((a, b) => b.n - a.n);
+            const top = ranked[0];
+            const mine = sigs[0];
+            if (!top)
+                continue;
+            // No majority: report when this screen matches none of its peers either.
+            if (top.n < 2 || ranked[1]?.n === top.n) {
+                if (!votes.has(key(mine)) && peers.filter((p) => known[p]?.[kind]).length >= 2)
+                    issues.push({
+                        severity: 'warning',
+                        type: 'consistency',
+                        message: `${nameOf(kind)} matches none of the other ${ranked.reduce((n, v) => n + v.n, 0)} screens (${ranked.length + 1} different versions in this family)`,
+                        selector: mine.selector,
+                        text: mine.text,
+                    });
+                continue;
+            }
+            if (key(mine) === key(top.sig))
+                continue;
+            const diffs = Object.keys({ ...mine.fields, ...top.sig.fields })
+                .filter((f) => mine.fields[f] !== top.sig.fields[f])
+                .map((f) => `${f} ${mine.fields[f] ?? '–'} (others ${top.sig.fields[f] ?? '–'})`);
+            issues.push({
+                severity: 'warning',
+                type: 'consistency',
+                message: `${nameOf(kind)} differs from ${top.n} other screens: ${diffs.join('; ')}`,
+                selector: mine.selector,
+                text: mine.text,
+            });
+        }
+    }
+    return out;
+}
+/** Lab screens build catalog components with the components, not by hand. */
+export function reuseIssues(path, page) {
+    if (familyOf(path) !== 'screens')
+        return [];
+    return page.handBuilt.slice(0, 10).map((h) => ({
+        severity: 'warning',
+        type: 'reuse',
+        message: `${nameOf(h.kind)} built by hand; use <${NAMES[h.kind]?.[1] ?? 'the catalog component'}> (see the component catalog, ${config.catalogDir})`,
+        selector: h.selector,
+        text: h.text,
+    }));
+}

package/dist/design-md.d.ts

@@ -0,0 +1,27 @@
+export interface TypeLevel {
+    fontFamily?: string;
+    fontSize?: string;
+    fontWeight?: number | string;
+    lineHeight?: string | number;
+    letterSpacing?: string;
+    fontFeature?: string;
+}
+export interface Design {
+    name: string;
+    colors: Record<string, string>;
+    typography: Record<string, TypeLevel>;
+    rounded: Record<string, string>;
+    spacing: Record<string, string>;
+    components: Record<string, Record<string, string>>;
+}
+export declare function readDesign(file?: string): Design;
+/** A type level in pixels, for comparing with computed styles. */
+export interface Level {
+    name: string;
+    mono: boolean;
+    size: number;
+    weight: number;
+    lineHeight: number;
+    tracking: number;
+}
+export declare function typeLevels(design?: Design): Level[];

package/dist/design-md.js

@@ -0,0 +1,49 @@
+/**
+ * Reads design/DESIGN.md's YAML front matter (the DESIGN.md format: colors, typography, rounded, spacing,
+ * components) and resolves {path.to.token} references.
+ */
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { parse } from 'yaml';
+import { ROOT } from './screens.js';
+export function readDesign(file = join(ROOT, 'DESIGN.md')) {
+    const text = readFileSync(file, 'utf8');
+    const front = /^---\n([\s\S]*?)\n---/.exec(text)?.[1];
+    if (!front)
+        throw new Error(`${file} has no YAML front matter`);
+    const raw = parse(front);
+    const resolve = (value, depth = 0) => {
+        if (typeof value !== 'string')
+            return value;
+        const ref = /^\{([\w.-]+)\}$/.exec(value)?.[1];
+        if (!ref || depth > 10)
+            return value;
+        const target = ref.split('.').reduce((o, k) => o?.[k], raw);
+        return resolve(target, depth + 1);
+    };
+    const colors = Object.fromEntries(Object.entries(raw.colors ?? {}).map(([k, v]) => [k, String(resolve(v))]));
+    return {
+        name: raw.name ?? '',
+        colors,
+        typography: raw.typography ?? {},
+        rounded: raw.rounded ?? {},
+        spacing: raw.spacing ?? {},
+        components: raw.components ?? {},
+    };
+}
+export function typeLevels(design = readDesign()) {
+    return Object.entries(design.typography).map(([name, t]) => {
+        const size = Number.parseFloat(String(t.fontSize));
+        const lh = String(t.lineHeight);
+        return {
+            name,
+            mono: /mono/i.test(t.fontFamily ?? ''),
+            size,
+            weight: Number(t.fontWeight ?? 400),
+            lineHeight: lh.endsWith('px') ? Number.parseFloat(lh) : Number.parseFloat(lh) * size,
+            tracking: t.letterSpacing?.endsWith('em')
+                ? Number.parseFloat(t.letterSpacing) * size
+                : Number.parseFloat(t.letterSpacing ?? '0') || 0,
+        };
+    });
+}

package/dist/design-page.d.ts

@@ -0,0 +1 @@
+export declare function designPage(): string;

package/dist/design-page.js

@@ -0,0 +1,127 @@
+/**
+ * The design system page (/design on the stitch2 server), with its own neutral styling: DESIGN.md's tokens drawn as swatches, live type
+ * samples, spacing bars, radii and component tokens, followed by its prose. Rendered on each request.
+ */
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { readDesign } from './design-md.js';
+import { ROOT } from './screens.js';
+const esc = (s) => String(s ?? '')
+    .replaceAll('&', '&')
+    .replaceAll('<', '&lt;')
+    .replaceAll('>', '&gt;')
+    .replaceAll('"', '&quot;');
+/** Enough Markdown for DESIGN.md's prose: headings, lists, paragraphs, bold, inline code. */
+function markdown(md) {
+    const inline = (s) => esc(s)
+        .replace(/`([^`]+)`/g, '<code>$1</code>')
+        .replace(/\*\*([^*]+)\*\*/g, '<strong>$1</strong>');
+    const out = [];
+    let list = false;
+    let para = [];
+    const flush = () => {
+        if (para.length)
+            out.push(`<p>${inline(para.join(' '))}</p>`);
+        para = [];
+    };
+    let item = null;
+    const endItem = () => {
+        if (item)
+            out.push(`<li>${inline(item.join(' '))}</li>`);
+        item = null;
+    };
+    for (const line of md.split('\n')) {
+        const h = /^(#{1,4})\s+(.*)$/.exec(line);
+        const li = /^-\s+(.*)$/.exec(line);
+        if (h) {
+            flush();
+            endItem();
+            if (list)
+                out.push('</ul>');
+            list = false;
+            out.push(`<h${h[1].length + 1}>${inline(h[2])}</h${h[1].length + 1}>`);
+        }
+        else if (li) {
+            flush();
+            endItem();
+            if (!list)
+                out.push('<ul>');
+            list = true;
+            item = [li[1]];
+        }
+        else if (!line.trim()) {
+            flush();
+            endItem();
+            if (list)
+                out.push('</ul>');
+            list = false;
+        }
+        else if (item)
+            item.push(line.trim());
+        else
+            para.push(line.trim());
+    }
+    flush();
+    endItem();
+    if (list)
+        out.push('</ul>');
+    return out.join('\n');
+}
+export function designPage() {
+    const d = readDesign();
+    const text = readFileSync(join(ROOT, 'DESIGN.md'), 'utf8');
+    const prose = text.replace(/^---\n[\s\S]*?\n---\n/, '');
+    const colours = Object.entries(d.colors).filter(([n, v]) => n !== 'primary' || !Object.entries(d.colors).some(([k, w]) => k !== n && w === v));
+    // Load the families DESIGN.md names from Google Fonts, so the type samples render in them.
+    const families = [
+        ...new Set(Object.values(d.typography)
+            .map((t) => t.fontFamily)
+            .filter(Boolean)),
+    ];
+    const fonts = `https://fonts.googleapis.com/css2?${families.map((f) => `family=${encodeURIComponent(f).replaceAll('%20', '+')}:wght@400;500;600;700`).join('&')}&display=swap`;
+    const swatch = ([name, value]) => `<div class="sw"><span style="background:${esc(value)}"></span><b>${esc(name)}</b><code>${esc(value)}</code></div>`;
+    const type = Object.entries(d.typography)
+        .map(([name, t]) => `<div class="ty"><div class="type-${esc(name)}">${/number|stat|timer/.test(name) ? '82.5 · 1:32 · 80.7' : name.endsWith('caps') ? 'Recent workouts' : 'Barbell Bench Press'}</div><code>${esc(name)} · ${esc(t.fontFamily)} ${esc(t.fontSize)}/${esc(t.lineHeight)} ${esc(t.fontWeight)}${t.letterSpacing && t.letterSpacing !== '0em' ? ` ${esc(t.letterSpacing)}` : ''}</code></div>`)
+        .join('');
+    const spacing = Object.entries(d.spacing)
+        .map(([n, v]) => `<div class="sp"><code>${esc(n)}</code><span style="width:${esc(v)}"></span><code>${esc(v)}</code></div>`)
+        .join('');
+    const radii = Object.entries(d.rounded)
+        .map(([n, v]) => `<div class="ra"><span style="border-radius:${esc(v)}"></span><code>${esc(n)} ${esc(v)}</code></div>`)
+        .join('');
+    const components = Object.entries(d.components)
+        .map(([n, props]) => `<tr><td><b>${esc(n)}</b></td><td>${Object.entries(props)
+        .map(([k, v]) => `<code>${esc(k)}: ${esc(v)}</code>`)
+        .join(' ')}</td></tr>`)
+        .join('');
+    return `<!doctype html>
+<html lang="en" data-theme="dark"><head><meta charset="utf-8" /><title>DESIGN.md — ${esc(d.name)}</title>
+<link href="${esc(fonts)}" rel="stylesheet" />
+<link rel="stylesheet" href="/tokens.css" />
+<style>
+  body { margin: 0; background: #0f0f11; color: #f4f4f5; font: 15px/1.55 Geist, system-ui, sans-serif; }
+  main { max-width: 980px; margin: 0 auto; padding: 32px 32px 96px; }
+  h1 { font-size: 32px; letter-spacing: -0.03em; margin: 0 0 4px; }
+  h2 { font-size: 13px; text-transform: uppercase; letter-spacing: .06em; color: #a1a1aa; margin: 40px 0 12px; }
+  h3, h4 { margin: 24px 0 8px; }
+  section.prose h2 { font-size: 20px; text-transform: none; letter-spacing: -0.02em; color: #f4f4f5; }
+  code { font: 12px/1.4 "Geist Mono", ui-monospace, monospace; color: #a1a1aa; }
+  .grid { display: grid; grid-template-columns: repeat(auto-fill, minmax(150px, 1fr)); gap: 12px; }
+  .sw { display: grid; gap: 4px; } .sw span { height: 56px; border-radius: 12px; border: 1px solid #2e2e33; }
+  .ty { padding: 14px 0; border-bottom: 1px solid #2e2e33; display: grid; gap: 6px; }
+  .sp { display: grid; grid-template-columns: 70px auto 1fr; gap: 12px; align-items: center; margin: 6px 0; }
+  .sp span { height: 12px; background: #a1a1aa; border-radius: 3px; }
+  .ra { display: grid; gap: 6px; justify-items: start; } .ra span { width: 72px; height: 72px; background: #232327; border: 1px solid #2e2e33; }
+  table { border-collapse: collapse; width: 100%; } td { border-bottom: 1px solid #2e2e33; padding: 8px 8px 8px 0; vertical-align: top; } td code { margin-right: 10px; display: inline-block; }
+  .prose li { margin: 4px 0; } .prose strong { color: #f4f4f5; } .prose { color: #d4d4d8; }
+</style></head>
+<body><main>
+<h1>${esc(d.name)} design system</h1><code>design/DESIGN.md · tokens in the front matter, rules below</code>
+<h2>Colours</h2><div class="grid">${colours.map(swatch).join('')}</div>
+<h2>Type levels</h2>${type}
+<h2>Spacing</h2>${spacing}
+<h2>Radii</h2><div class="grid">${radii}</div>
+<h2>Components</h2><table>${components}</table>
+<section class="prose">${markdown(prose)}</section>
+</main></body></html>`;
+}

package/dist/elements.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Shared components for screens: turns a project's own components (React, Preact, Vue, Solid, …) into the
+ * <prefix>-<name> elements stitch2 screens use, so a screen shows exactly the markup the app renders. Each
+ * element renders once into plain markup in the page (no shadow DOM, so the checks, pick mode and Tailwind
+ * see it), marks its root data-<prefix>="<name>" (plus data-variant and data-size from those props), and
+ * keeps the screen's source line for pick mode.
+ *
+ *   import { createElement } from 'react'
+ *   import { renderToStaticMarkup } from 'react-dom/server'
+ *   import { defineElements } from 'stitch2/elements'
+ *   import { Button, Row } from './ui'
+ *   defineElements({ button: Button, row: Row }, {
+ *     prefix: 'gg',
+ *     render: (C, props) => renderToStaticMarkup(createElement(C, props)),
+ *   })
+ *
+ * Attributes become props: kebab-case to camelCase, an empty attribute (<gg-row chevron>) is true, other
+ * values stay strings. The element's content becomes children, rendered where the component puts them.
+ * Bundle the entry with `stitch2 elements <entry>› and load the bundle in the screens and the template.
+ */
+export interface ElementsOptions<C> {
+    /** The project's prefix (stitch2.config.json): elements are <prefix>-<name>. */
+    prefix: string;
+    /**
+     * Renders one component with its props to static HTML; props.children is a placeholder string. Synchronous
+     * (React, Preact, Solid) or a promise (Vue's renderToString).
+     */
+    render: (component: C, props: Record<string, unknown>) => string | Promise<string>;
+    /** Runs after every element has rendered, e.g. to draw icon placeholders (lucide.createIcons). */
+    after?: () => void;
+}
+export declare function defineElements<C>(components: Record<string, C>, options: ElementsOptions<C>): void;

package/dist/elements.js

@@ -0,0 +1,69 @@
+/**
+ * Shared components for screens: turns a project's own components (React, Preact, Vue, Solid, …) into the
+ * <prefix>-<name> elements stitch2 screens use, so a screen shows exactly the markup the app renders. Each
+ * element renders once into plain markup in the page (no shadow DOM, so the checks, pick mode and Tailwind
+ * see it), marks its root data-<prefix>="<name>" (plus data-variant and data-size from those props), and
+ * keeps the screen's source line for pick mode.
+ *
+ *   import { createElement } from 'react'
+ *   import { renderToStaticMarkup } from 'react-dom/server'
+ *   import { defineElements } from 'stitch2/elements'
+ *   import { Button, Row } from './ui'
+ *   defineElements({ button: Button, row: Row }, {
+ *     prefix: 'gg',
+ *     render: (C, props) => renderToStaticMarkup(createElement(C, props)),
+ *   })
+ *
+ * Attributes become props: kebab-case to camelCase, an empty attribute (<gg-row chevron>) is true, other
+ * values stay strings. The element's content becomes children, rendered where the component puts them.
+ * Bundle the entry with `stitch2 elements <entry>› and load the bundle in the screens and the template.
+ */
+const camel = (s) => s.replace(/-([a-z])/g, (_, c) => c.toUpperCase());
+export function defineElements(components, options) {
+    const { prefix, render } = options;
+    let pending = 0;
+    for (const [name, component] of Object.entries(components)) {
+        const tag = `${prefix}-${name}`;
+        if (customElements.get(tag))
+            continue;
+        customElements.define(tag, class extends HTMLElement {
+            connectedCallback() {
+                const props = {};
+                for (const a of Array.from(this.attributes)) {
+                    if (a.name.startsWith('data-s2-'))
+                        continue;
+                    props[camel(a.name)] = a.value === '' ? true : a.value;
+                }
+                const inner = this.innerHTML.trim();
+                const token = `s2children${Math.random().toString(36).slice(2)}`;
+                if (inner)
+                    props.children = token;
+                const out = render(component, props);
+                if (typeof out === 'string')
+                    this.mount(out, inner, token, props);
+                else
+                    void out.then((html) => this.mount(html, inner, token, props));
+            }
+            mount(html, inner, token, props) {
+                if (inner)
+                    html = html.replace(token, inner);
+                const t = document.createElement('template');
+                t.innerHTML = html;
+                const root = t.content.firstElementChild;
+                if (root) {
+                    if (!root.hasAttribute(`data-${prefix}`))
+                        root.setAttribute(`data-${prefix}`, name);
+                    for (const key of ['variant', 'size'])
+                        if (typeof props[key] === 'string' && !root.hasAttribute(`data-${key}`))
+                            root.setAttribute(`data-${key}`, props[key]);
+                }
+                this.replaceWith(t.content);
+                if (options.after && !pending++)
+                    queueMicrotask(() => {
+                        pending = 0;
+                        options.after?.();
+                    });
+            }
+        });
+    }
+}

package/dist/exports.d.ts

@@ -0,0 +1,25 @@
+import type { Design } from './design-md.ts';
+export interface TokenExport {
+    format: 'css' | 'tailwind4' | 'dtcg';
+    /** Output file, relative to stitch2.config.json. */
+    path: string;
+    /** App variable name → DESIGN.md colour name (or any CSS value). */
+    aliases?: Record<string, string>;
+    /** Theme selectors; default the lab's: :root, [data-theme='dark'] and [data-theme='light']. */
+    themes?: {
+        dark?: string;
+        light?: string;
+    };
+}
+export interface Tokens {
+    design: Design;
+    dark: Record<string, string>;
+    light: Record<string, string>;
+    /** Declarations per type level, e.g. ["font: 600 28px/34px \"Geist\", …", "letter-spacing: -0.03em"]. */
+    type: Record<string, string[]>;
+    /** Extra variables for :root (font fallbacks). */
+    root: Record<string, string>;
+    header: string;
+}
+/** Writes every export in the config; returns their paths. */
+export declare function writeExports(t: Tokens, list?: TokenExport[]): string[];