stitch2 0.0.0-stage → 0.7.2

package/dist/audit.js

@@ -0,0 +1,259 @@
+/** Layout errors that mean the same bug wherever they appear; compare reports these for the app too. */
+export const LAYOUT_ERRORS = ['overflow', 'fixed-overlap', 'control-overlap'];
+/** Runs inside the page. Plain JS on purpose: Playwright sends its source to the browser. */
+export async function audit(opts) {
+    const W = document.documentElement.clientWidth;
+    const out = [];
+    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 text = (el) => (el.textContent ?? '').trim().replace(/\s+/g, ' ').slice(0, 60);
+    const push = (severity, type, el, message) => {
+        if (out.filter((i) => i.type === type).length >= 10)
+            return;
+        out.push({ severity, type, message, selector: sel(el), text: text(el) });
+    };
+    const shown = (el) => {
+        const cs = getComputedStyle(el);
+        if (cs.display === 'none' || cs.visibility === 'hidden')
+            return false;
+        const r = el.getBoundingClientRect();
+        return r.width > 0 && r.height > 0;
+    };
+    const opacity = (el) => {
+        let o = 1;
+        for (let e = el; e; e = e.parentElement)
+            o *= Number(getComputedStyle(e).opacity);
+        return o;
+    };
+    const ownText = (el) => [...el.childNodes].some((n) => n.nodeType === 3 && n.textContent.trim());
+    const inSvg = (el) => !!el.closest('svg') && el.tagName.toLowerCase() !== 'svg';
+    const all = [...document.body.querySelectorAll('*')].filter((el) => shown(el) && !inSvg(el));
+    const frame = () => new Promise((r) => requestAnimationFrame(() => requestAnimationFrame(r)));
+    // 1. Nothing past the screen edge, except inside deliberate horizontal scrollers (chip rows).
+    if (document.documentElement.scrollWidth > W + 1)
+        push('error', 'page-overflow', document.body, `The page scrolls sideways (${document.documentElement.scrollWidth}px wide)`);
+    const overflowing = new Set();
+    for (const el of all) {
+        const r = el.getBoundingClientRect();
+        if (r.right <= W + 1 && r.left >= -1)
+            continue;
+        let clip = null;
+        for (let p = el.parentElement; p && p !== document.body; p = p.parentElement) {
+            const ox = getComputedStyle(p).overflowX;
+            if (ox !== 'visible') {
+                clip = ox;
+                break;
+            }
+        }
+        if (clip === 'auto' || clip === 'scroll')
+            continue;
+        if (overflowing.has(el.parentElement)) {
+            overflowing.add(el);
+            continue;
+        }
+        overflowing.add(el);
+        if (clip) {
+            if (ownText(el))
+                push('warning', 'clipped', el, 'Text is cut off at the screen edge');
+        }
+        else
+            push('error', 'overflow', el, `Sticks out past the screen edge (${Math.round(r.right - W)}px)`);
+    }
+    // 2. Short labels (buttons, chips, tabs) stay on one line.
+    const isLabel = (el) => el.matches('button, a, label, [role=tab], [role=button], [role=switch], th') ||
+        /(^|\s)(chip|badge|pill|tag)|rounded-full/.test(String(el.className ?? ''));
+    for (const el of all) {
+        if (!isLabel(el) || text(el).length > 40 || el.querySelector('p, div, li, ul, br'))
+            continue;
+        // A wrap is one text node breaking across lines; an icon above its label is layout, not a wrap.
+        const walker = document.createTreeWalker(el, NodeFilter.SHOW_TEXT);
+        for (let n = walker.nextNode(); n; n = walker.nextNode()) {
+            if (!n.textContent.trim())
+                continue;
+            const range = document.createRange();
+            range.selectNodeContents(n);
+            const tops = [...range.getClientRects()].filter((r) => r.width > 1).map((r) => r.top + r.height / 2);
+            const lineHeight = parseFloat(getComputedStyle(n.parentElement).fontSize) || 14;
+            if (tops.length > 1 && Math.max(...tops) - Math.min(...tops) > lineHeight * 0.6) {
+                push('error', 'label-wraps', el, 'Label wraps onto two lines');
+                break;
+            }
+        }
+    }
+    // 3. Fixed bars (tab bar, rest timer, headers) never cover content: check at both scroll ends.
+    const bars = all.filter((el) => {
+        const p = getComputedStyle(el).position;
+        const r = el.getBoundingClientRect();
+        return (p === 'fixed' || p === 'sticky') && r.height <= 240 && r.width >= W * 0.6;
+    });
+    const outer = bars.filter((b) => !bars.some((o) => o !== b && o.contains(b)));
+    const content = all.filter((el) => !outer.some((b) => b.contains(el)) &&
+        (ownText(el) || el.matches('button, input, select, textarea, img, svg, canvas, video')) &&
+        opacity(el) > 0.5);
+    const covered = async (edge) => {
+        window.scrollTo(0, edge === 'bottom' ? document.documentElement.scrollHeight : 0);
+        await frame();
+        const H = window.innerHeight;
+        for (const bar of outer) {
+            const b = bar.getBoundingClientRect();
+            const atEdge = edge === 'bottom' ? b.bottom >= H - 4 && b.top > H / 2 : b.top <= 4 && b.bottom < H / 2;
+            if (!atEdge)
+                continue;
+            for (const el of content) {
+                if (el.contains(bar))
+                    continue;
+                const r = el.getBoundingClientRect();
+                const overlapY = Math.min(r.bottom, b.bottom) - Math.max(r.top, b.top);
+                const overlapX = Math.min(r.right, b.right) - Math.max(r.left, b.left);
+                if (overlapY > 4 && overlapX > 4)
+                    push('error', `under-${edge}-bar`, el, `Hidden under the fixed ${edge} bar when scrolled to the ${edge} (add padding)`);
+            }
+        }
+    };
+    // 3b. Fixed bars never overlap one another, including what sticks out of them (a raised tab-bar button
+    // reaching into a docked timer). Compares the painted parts: backgrounds, borders, text, icons, controls.
+    const painted = (el) => {
+        const cs = getComputedStyle(el);
+        return (ownText(el) ||
+            el.matches('svg, img, button, input') ||
+            !/rgba\(0, 0, 0, 0\)|transparent/.test(cs.backgroundColor) ||
+            Number.parseFloat(cs.borderTopWidth) > 0);
+    };
+    const fixedBars = outer.filter((b) => getComputedStyle(b).position === 'fixed' && b.getBoundingClientRect().height < window.innerHeight * 0.8);
+    const parts = (bar) => [bar, ...bar.querySelectorAll('*')].filter((e) => shown(e) && !inSvg(e) && painted(e)).map((e) => e.getBoundingClientRect());
+    for (const [i, a] of fixedBars.entries())
+        for (const b of fixedBars.slice(i + 1)) {
+            const hit = parts(a).some((r) => parts(b).some((q) => Math.min(r.right, q.right) - Math.max(r.left, q.left) > 2 && Math.min(r.bottom, q.bottom) - Math.max(r.top, q.top) > 2));
+            if (hit)
+                push('error', 'fixed-overlap', b, `Overlaps another fixed bar (“${text(a).slice(0, 30)}”): move one clear of the other`);
+        }
+    await covered('bottom');
+    await covered('top');
+    window.scrollTo(0, 0);
+    // 4. Tap targets: WCAG 2.2 asks for at least 24px; smaller than the config's comfortableTarget is a warning.
+    const interactive = all.filter((el) => el.matches('button, a[href], input:not([type=hidden]), select, textarea, [role=button], [role=tab], [role=switch], [role=checkbox]'));
+    for (const el of interactive) {
+        if (interactive.some((o) => o !== el && o.contains(el)))
+            continue;
+        if (el.matches('a') && el.closest('p'))
+            continue;
+        const r = el.getBoundingClientRect();
+        const min = Math.min(r.width, r.height);
+        // WCAG 2.2 spacing exception: a smaller target passes when a 24px circle on it touches no other target.
+        const cx = r.left + r.width / 2;
+        const cy = r.top + r.height / 2;
+        const crowded = interactive.some((o) => {
+            if (o === el || o.contains(el) || el.contains(o))
+                return false;
+            const q = o.getBoundingClientRect();
+            const dx = Math.max(q.left - cx, 0, cx - q.right);
+            const dy = Math.max(q.top - cy, 0, cy - q.bottom);
+            return Math.hypot(dx, dy) < 12;
+        });
+        if (min < 24 && crowded)
+            push('error', 'tap-target', el, 'Too small to tap and crowded (' +
+                Math.round(r.width) +
+                '×' +
+                Math.round(r.height) +
+                'px, minimum 24)');
+        else if (min < 24)
+            push('warning', 'tap-target', el, `Small tap target (${Math.round(r.width)}×${Math.round(r.height)}px)`);
+        else if (min < opts.comfortable)
+            push('warning', 'tap-target', el, `Small tap target (${Math.round(r.width)}×${Math.round(r.height)}px)`);
+    }
+    // 4b. Controls never overlap one another (a button squeezed over its neighbour). Controls inside one another
+    // and invisible overlays (a native picker laid over a row) are fine; fixed and sticky layers (a docked timer,
+    // a sticky Save bar floating over a list) are compared apart from the scrolling page.
+    const layer = (el) => {
+        for (let e = el; e; e = e.parentElement)
+            if (['fixed', 'sticky'].includes(getComputedStyle(e).position))
+                return e;
+        return null;
+    };
+    // Behind an open modal the page is inert and the modal covers it, so only the modal's own controls count.
+    const modal = [...document.querySelectorAll('[aria-modal="true"]')].find(shown);
+    const solid = interactive.filter((el) => opacity(el) > 0.05 && (!modal || modal.contains(el)));
+    for (const [i, a] of solid.entries())
+        for (const b of solid.slice(i + 1)) {
+            if (a.contains(b) || b.contains(a) || layer(a) !== layer(b))
+                continue;
+            const r = a.getBoundingClientRect();
+            const q = b.getBoundingClientRect();
+            if (Math.min(r.right, q.right) - Math.max(r.left, q.left) > 2 && Math.min(r.bottom, q.bottom) - Math.max(r.top, q.top) > 2)
+                push('error', 'control-overlap', b, `Overlaps another control (“${text(a).slice(0, 30) || a.getAttribute('aria-label') || a.tagName.toLowerCase()}”): give them room`);
+        }
+    // 5. Text contrast (WCAG AA): 4.5:1, or 3:1 for large text. Skips text over images and dimmed layers.
+    const rgba = (c) => {
+        const m = /rgba?\(([^)]+)\)/.exec(c);
+        if (!m)
+            return null;
+        const [r, g, b, a = '1'] = m[1].split(/[\s,/]+/).filter(Boolean);
+        return [Number(r), Number(g), Number(b), Number(a)];
+    };
+    const lum = (c) => {
+        const f = (v) => {
+            v /= 255;
+            return v <= 0.03928 ? v / 12.92 : ((v + 0.055) / 1.055) ** 2.4;
+        };
+        return 0.2126 * f(c[0]) + 0.7152 * f(c[1]) + 0.0722 * f(c[2]);
+    };
+    const over = (top, under) => {
+        const a = top[3];
+        return [0, 1, 2].map((i) => top[i] * a + under[i] * (1 - a)).concat(1);
+    };
+    for (const el of all) {
+        // WCAG exempts disabled controls from contrast.
+        if (!ownText(el) || opacity(el) < 0.6 || el.matches('input, textarea, select, option'))
+            continue;
+        if (el.closest('[disabled], [aria-disabled="true"]'))
+            continue;
+        const layers = [];
+        let image = false;
+        for (let e = el; e; e = e.parentElement) {
+            const cs = getComputedStyle(e);
+            if (cs.backgroundImage !== 'none') {
+                image = true;
+                break;
+            }
+            const c = rgba(cs.backgroundColor);
+            if (c && c[3] > 0) {
+                layers.push(c);
+                if (c[3] === 1)
+                    break;
+            }
+        }
+        if (image)
+            continue;
+        let bg = [255, 255, 255, 1];
+        for (const l of layers.reverse())
+            bg = over(l, bg);
+        const fgRaw = rgba(getComputedStyle(el).color);
+        if (!fgRaw)
+            continue;
+        const fg = over(fgRaw, bg);
+        const [a, b] = [lum(fg), lum(bg)].sort((x, y) => y - x);
+        const ratio = (a + 0.05) / (b + 0.05);
+        const cs = getComputedStyle(el);
+        const size = parseFloat(cs.fontSize);
+        const large = size >= 24 || (size >= 18.66 && Number(cs.fontWeight) >= 700);
+        const need = large ? 3 : 4.5;
+        if (ratio < need)
+            push(ratio < need - 1 ? 'error' : 'warning', 'contrast', el, `Low contrast ${ratio.toFixed(2)}:1 (needs ${need}:1)`);
+    }
+    return out.sort((x, y) => (x.severity === y.severity ? 0 : x.severity === 'error' ? -1 : 1));
+}

package/dist/build-design.d.ts

@@ -0,0 +1,39 @@
+export type Mode = 'dark' | 'light';
+export interface Choices {
+    name: string;
+    /** One line on the product and its mood, for the Overview. */
+    mood: string;
+    primary: string;
+    modes: Mode[];
+    sans: string;
+    mono?: string;
+    /** Body text size in px (14 compact, 15 default, 16 comfortable). */
+    base: number;
+    /** Corner radius of a card-sized element in px; 0 for square, 999 for pill-shaped controls. */
+    roundness: number;
+    /** Side padding of a phone screen in px. */
+    page: number;
+    icons: string;
+    scheme: string;
+    /** Measured type levels (extract); otherwise generated from base. */
+    levels?: Record<string, Level>;
+    /** Measured colours (extract) to use instead of generated ones, by role. */
+    colorOverrides?: Partial<Record<Mode, Partial<Palette>>>;
+}
+export interface Level {
+    fontFamily: string;
+    fontSize: string;
+    fontWeight: number;
+    lineHeight: string;
+    letterSpacing: string;
+    fontFeature?: string;
+}
+export declare const ROLES: readonly ['background', 'surface', 'raised', 'border', 'text', 'text-muted', 'text-faint', 'primary', 'primary-pressed', 'on-primary', 'primary-wash', 'success', 'warning', 'danger'];
+export type Palette = Record<(typeof ROLES)[number], string>;
+export declare const contrast: (a: string, b: string) => number;
+export declare function palette(c: Choices, mode: Mode): Palette;
+/** Tracking that follows size (fonts without optical sizes): tight titles, zero for reading sizes, open small text. */
+export declare const tracking: (size: number, caps?: boolean) => -0.04 | -0.03 | -0.02 | 0 | 0.01 | 0.02 | 0.06;
+export declare function typeScale(c: Choices): Record<string, Level>;
+export declare function radii(r: number): Record<string, string>;
+export declare function buildDesignMd(c: Choices): string;

package/dist/build-design.js

@@ -0,0 +1,337 @@
+/**
+ * Builds a complete DESIGN.md (Google's DESIGN.md format) from a few choices or from measurements: colours from
+ * one primary colour with Material 3 tonal palettes (text and status colours adjusted until they reach 4.5:1),
+ * a 15-level type scale with tracking that follows size, radius and spacing scales, component tokens with
+ * states, and prose sections that state the rules with the real values. Used by `stitch2 init` and
+ * `stitch2 extract`.
+ */
+import { argbFromHex, Contrast, Hct, hexFromArgb, SchemeContent, SchemeExpressive, SchemeFidelity, SchemeMonochrome, SchemeNeutral, SchemeTonalSpot, SchemeVibrant, } from '@material/material-color-utilities';
+export const ROLES = [
+    'background',
+    'surface',
+    'raised',
+    'border',
+    'text',
+    'text-muted',
+    'text-faint',
+    'primary',
+    'primary-pressed',
+    'on-primary',
+    'primary-wash',
+    'success',
+    'warning',
+    'danger',
+];
+const SCHEMES = {
+    tonal_spot: SchemeTonalSpot,
+    neutral: SchemeNeutral,
+    fidelity: SchemeFidelity,
+    vibrant: SchemeVibrant,
+    expressive: SchemeExpressive,
+    content: SchemeContent,
+    monochrome: SchemeMonochrome,
+};
+const tone = (hex) => Hct.fromInt(argbFromHex(hex)).tone;
+export const contrast = (a, b) => Contrast.ratioOfTones(tone(a), tone(b));
+const withTone = (hex, t) => {
+    const h = Hct.fromInt(argbFromHex(hex));
+    return hexFromArgb(Hct.from(h.hue, h.chroma, Math.max(0, Math.min(100, t))).toInt());
+};
+/** Moves a colour's tone away from the background until it reaches the ratio (or the end of the range). */
+function readable(hex, against, ratio, dark) {
+    let t = tone(hex);
+    let out = hex;
+    while (against.some((b) => contrast(out, b) < ratio) && t >= 0 && t <= 100) {
+        t += dark ? 1 : -1;
+        out = withTone(hex, t);
+    }
+    return out;
+}
+export function palette(c, mode) {
+    const dark = mode === 'dark';
+    const Scheme = SCHEMES[c.scheme] ?? SchemeTonalSpot;
+    const scheme = new Scheme(Hct.fromInt(argbFromHex(c.primary)), dark, 0);
+    const n = (t) => hexFromArgb(scheme.neutralPalette.tone(t));
+    const nv = (t) => hexFromArgb(scheme.neutralVariantPalette.tone(t));
+    const surfaces = dark
+        ? { background: n(6), surface: n(10), raised: n(17), border: nv(25), text: n(95) }
+        : { background: n(98), surface: n(100), raised: n(94), border: nv(87), text: n(10) };
+    const on = [surfaces.surface, surfaces.raised];
+    // The accent is text too (active tabs, links): 4.5:1 on surfaces. Its label (on-primary) needs 4.5:1 on it:
+    // when neither near-black nor white gets there, move the accent's tone further the same way.
+    let primary = readable(c.primary, on, 4.5, dark);
+    const ink = n(6);
+    const white = '#ffffff';
+    const label = (p) => (contrast(p, ink) >= contrast(p, white) ? ink : white);
+    for (let t = tone(primary); contrast(label(primary), primary) < 4.5 && t > 0 && t < 100;) {
+        t += label(primary) === ink ? 1 : -1;
+        primary = withTone(primary, t);
+    }
+    const onPrimary = label(primary);
+    const status = (hue) => {
+        const base = hexFromArgb(Hct.from(hue, 60, dark ? 70 : 40).toInt());
+        return readable(base, on, 4.5, dark);
+    };
+    const rgb = Hct.fromInt(argbFromHex(primary)).toInt();
+    const wash = `rgba(${(rgb >> 16) & 255}, ${(rgb >> 8) & 255}, ${rgb & 255}, ${dark ? 0.14 : 0.12})`;
+    const p = {
+        ...surfaces,
+        'text-muted': readable(nv(dark ? 75 : 40), on, 4.5, dark),
+        'text-faint': nv(dark ? 55 : 60),
+        primary,
+        'primary-pressed': withTone(primary, tone(primary) - 8),
+        'on-primary': onPrimary,
+        'primary-wash': wash,
+        success: status(150),
+        warning: status(80),
+        danger: status(25),
+    };
+    return { ...p, ...(c.colorOverrides?.[mode] ?? {}) };
+}
+const em = (v) => (v ? `${v}em` : '0em');
+/** Tracking that follows size (fonts without optical sizes): tight titles, zero for reading sizes, open small text. */
+export const tracking = (size, caps = false) => caps
+    ? 0.06
+    : size >= 40
+        ? -0.04
+        : size >= 26
+            ? -0.03
+            : size >= 18
+                ? -0.02
+                : size <= 11
+                    ? 0.02
+                    : size <= 12
+                        ? 0.01
+                        : 0;
+export function typeScale(c) {
+    if (c.levels)
+        return c.levels;
+    const k = c.base / 15;
+    const s = (px) => Math.round(px * k);
+    const lh = (px) => Math.round(px / 2) * 2;
+    const level = (size, weight, line, opts = {}) => ({
+        fontFamily: opts.mono && c.mono ? c.mono : c.sans,
+        fontSize: `${size}px`,
+        fontWeight: weight,
+        lineHeight: `${line}px`,
+        letterSpacing: em(tracking(size, opts.caps)),
+        ...(opts.tnum || opts.mono ? { fontFeature: '"tnum" 1' } : {}),
+    });
+    const b = c.base;
+    return {
+        'display-number': level(s(48), 600, lh(s(52)), { tnum: true }),
+        'display-stat': level(s(40), 600, lh(s(44)), { tnum: true }),
+        'title-screen': level(s(28), 600, lh(s(34))),
+        'title-sheet': level(s(22), 600, lh(s(28))),
+        'number-lg': level(s(22), 500, lh(s(28)), { tnum: true }),
+        'title-card': level(s(18), 600, lh(s(24))),
+        body: level(b, 400, lh(b * 1.47)),
+        'body-strong': level(b, 500, lh(b + 5)),
+        'label-button': level(b, 600, lh(b + 5)),
+        meta: level(s(13), 400, lh(s(18))),
+        'meta-number': level(s(13), 400, lh(s(18)), { mono: true, tnum: true }),
+        'label-chip': level(s(13), 500, lh(s(16))),
+        'label-caps': level(s(12), 600, lh(s(16)), { caps: true }),
+        caption: level(s(12), 400, lh(s(16))),
+        'label-tab': level(s(11), 500, lh(s(14))),
+    };
+}
+export function radii(r) {
+    const px = (v) => `${Math.round(v)}px`;
+    if (r >= 999)
+        return {
+            sm: '8px',
+            input: '9999px',
+            btn: '9999px',
+            row: '16px',
+            card: '20px',
+            sheet: '24px',
+            full: '9999px',
+        };
+    return {
+        sm: px(r * 0.5),
+        input: px(r * 0.75),
+        btn: px(r * 0.875),
+        row: px(r),
+        card: px(r * 1.25),
+        sheet: px(r * 1.5),
+        full: '9999px',
+    };
+}
+const yamlString = (v) => (/^[\w#.-]+$/.test(v) && !/^\d/.test(v) ? v : JSON.stringify(v));
+export function buildDesignMd(c) {
+    const pal = Object.fromEntries(c.modes.map((m) => [m, palette(c, m)]));
+    const main = c.modes[0];
+    const levels = typeScale(c);
+    const rounded = radii(c.roundness);
+    const spacing = {
+        xs: '4px',
+        sm: '8px',
+        md: '12px',
+        lg: '16px',
+        xl: '24px',
+        '2xl': '32px',
+        '3xl': '48px',
+        page: `${c.page}px`,
+    };
+    const colors = { ...pal[main] };
+    for (const m of c.modes.slice(1))
+        for (const [k, v] of Object.entries(pal[m]))
+            colors[`${m}-${k}`] = v;
+    const ref = (g, k) => `"{${g}.${k}}"`;
+    const components = {
+        'button-primary': {
+            backgroundColor: ref('colors', 'primary'),
+            textColor: ref('colors', 'on-primary'),
+            typography: ref('typography', 'label-button'),
+            rounded: ref('rounded', 'btn'),
+            height: '48px',
+            padding: '20px',
+        },
+        'button-primary-pressed': { backgroundColor: ref('colors', 'primary-pressed') },
+        'button-primary-disabled': {
+            backgroundColor: ref('colors', 'raised'),
+            textColor: ref('colors', 'text-faint'),
+        },
+        'button-secondary': {
+            backgroundColor: ref('colors', 'raised'),
+            textColor: ref('colors', 'text'),
+            typography: ref('typography', 'label-button'),
+            rounded: ref('rounded', 'btn'),
+            height: '48px',
+            padding: '20px',
+        },
+        'button-secondary-pressed': { backgroundColor: ref('colors', 'border') },
+        chip: {
+            backgroundColor: ref('colors', 'raised'),
+            textColor: ref('colors', 'text-muted'),
+            typography: ref('typography', 'label-chip'),
+            rounded: ref('rounded', 'full'),
+            height: '32px',
+            padding: '12px',
+        },
+        'chip-selected': { backgroundColor: ref('colors', 'primary-wash'), textColor: ref('colors', 'primary') },
+        segment: {
+            backgroundColor: ref('colors', 'background'),
+            textColor: ref('colors', 'text-muted'),
+            typography: ref('typography', 'label-chip'),
+            rounded: ref('rounded', 'sm'),
+            height: '36px',
+        },
+        'segment-selected': { backgroundColor: ref('colors', 'raised'), textColor: ref('colors', 'text') },
+        'tab-item': { textColor: ref('colors', 'text-muted'), typography: ref('typography', 'label-tab') },
+        'tab-item-active': { textColor: ref('colors', 'primary') },
+        input: {
+            backgroundColor: ref('colors', 'raised'),
+            textColor: ref('colors', 'text'),
+            typography: ref('typography', 'body'),
+            rounded: ref('rounded', 'input'),
+            height: '48px',
+            padding: '14px',
+        },
+        card: {
+            backgroundColor: ref('colors', 'surface'),
+            textColor: ref('colors', 'text'),
+            rounded: ref('rounded', 'card'),
+            padding: '16px',
+        },
+    };
+    const y = [
+        '---',
+        'version: alpha',
+        `name: ${yamlString(c.name)}`,
+        `description: ${JSON.stringify(c.mood)}`,
+        'colors:',
+    ];
+    for (const [k, v] of Object.entries(colors))
+        y.push(`  ${k}: "${v}"`);
+    y.push('typography:');
+    for (const [k, l] of Object.entries(levels)) {
+        y.push(`  ${k}:`, `    fontFamily: ${yamlString(l.fontFamily)}`, `    fontSize: ${l.fontSize}`, `    fontWeight: ${l.fontWeight}`, `    lineHeight: ${l.lineHeight}`, `    letterSpacing: ${l.letterSpacing}`);
+        if (l.fontFeature)
+            y.push(`    fontFeature: '${l.fontFeature}'`);
+    }
+    y.push('rounded:', ...Object.entries(rounded).map(([k, v]) => `  ${k}: ${v}`));
+    y.push('spacing:', ...Object.entries(spacing).map(([k, v]) => `  "${k}": ${v}`));
+    y.push('components:');
+    for (const [k, props] of Object.entries(components)) {
+        y.push(`  ${k}:`);
+        for (const [p, v] of Object.entries(props))
+            y.push(`    ${p}: ${v}`);
+    }
+    y.push('---', '');
+    const p = pal[main];
+    const ratio = (a, b) => contrast(a, b).toFixed(1);
+    const lv = (k) => levels[k];
+    const sizeOf = (k) => `${lv(k).fontSize.replace('px', '')}/${lv(k).lineHeight.replace('px', '')} ${lv(k).fontWeight}`;
+    const prose = `# Design System: ${c.name}
+
+## Overview
+${c.mood} ${c.base <= 14 ? 'Dense' : c.base >= 16 ? 'Spacious' : 'Balanced'} density: one clear job per screen and the next action always obvious. ${c.roundness === 0 ? 'Square, precise corners.' : c.roundness >= 999 ? 'Pill-shaped controls and soft cards.' : c.roundness >= 16 ? 'Rounded but firm shapes.' : 'Gently rounded shapes.'} ${c.modes.length > 1 ? `${main === 'dark' ? 'Dark' : 'Light'} first, with a ${c.modes[1]} theme.` : `${main === 'dark' ? 'Dark' : 'Light'} theme.`}
+
+## Colors
+- **Surfaces:** background (${p.background}) for the screen, surface (${p.surface}) for cards and bars, raised (${p.raised}) for inputs, chips and pressed rows, border (${p.border}) for 1px dividers.
+- **Text in three levels:** text (${p.text}, ${ratio(p.text, p.surface)}:1 on surface) for titles, values and anything the user acts on; text-muted (${p['text-muted']}, ${ratio(p['text-muted'], p.raised)}:1 on raised) for secondary lines and labels; text-faint (${p['text-faint']}) only for disabled controls and separators, never for information.
+- **Primary** (${p.primary}): the single accent, for the main action, the active tab, selection and focus rings. At most one primary-filled element per screen region. Text on it is on-primary (${p['on-primary']}, ${ratio(p['on-primary'], p.primary)}:1); pressed is ${p['primary-pressed']}; primary-wash tints selected chips.
+- **Status:** success (${p.success}), warning (${p.warning}), danger (${p.danger}), each at least 4.5:1 on surface and raised. They colour small text, icons and thin bars, never large fills.${c.modes.length > 1 ? `\n- The ${c.modes[1]} theme uses the \`${c.modes[1]}-*\` colours with the same roles.` : ''}
+
+## Typography
+${c.sans} everywhere${c.mono ? `, with ${c.mono} only for small standalone numbers (meta-number)` : ''}, at three weights: 400 for reading, 500 for names and values, 600 for titles, buttons and caps labels. The fifteen levels in the front matter are the only text styles; each fixes size, line height, weight and tracking together, so pick a level, never a size.
+
+- **Hierarchy comes from weight and colour before size.** Most of a screen is ${sizeOf('meta').split('/')[0]}–${sizeOf('body').split('/')[0]}px; one or two elements per screen are large (the title, and the number the screen is about).
+- **Tracking follows size:** titles tightened (−0.02em at 18–22px, −0.03em at 28px, −0.04em at 40px and up), reading sizes 0, small text opened slightly (caption +0.01em, tab labels +0.02em, caps labels +0.06em).
+- **Numbers** use tabular figures. Large values use ${c.sans} with tabular figures so decimal points stay narrow${c.mono ? `; ${c.mono} is for small metadata that stands on its own, never mid-sentence` : ''}. Units sit next to their value at about half its size in text-muted.
+- **Capitals** only in label-caps section labels, never in titles or buttons, and never for scripts without case (Chinese, Korean, Thai, Hindi, Arabic).
+- **Languages:** no letter-spacing for Arabic, Thai, Hindi, Chinese or Korean; Thai and Hindi need at least 1.5 line height; labels survive German and Russian text about 30% longer than English.
+- Body lines stay under 60 characters. No gradient text, no weights below 400 or above 600.
+
+## Layout
+- Mobile first at 390px wide (desktop frames 1280px). ${c.page}px side padding, 24px between sections, 12px between items inside a card, 16px card padding; the spacing scale is 4, 8, 12, 16, 24, 32, 48.
+- Screen structure: a title row (title left, one or two icon buttons right), a vertical stack of sections, and a fixed bottom tab bar with safe-area padding.
+- Desktop (1024px and up): a left sidebar replaces the tab bar; content up to 960px wide.
+- Touch targets at least 44px. Nothing overlaps, nothing scrolls sideways except chip rows.
+
+## Elevation & Depth
+Depth comes from tonal layering: background recedes, surface cards step forward, raised controls sit on top, with 1px borders where two surfaces meet. No drop shadows on cards; a sheet or docked bar may cast one soft shadow.
+
+## Shapes
+${Object.entries(rounded)
+        .filter(([k]) => k !== 'full')
+        .map(([k, v]) => `${v} ${k === 'sm' ? 'small controls' : k === 'input' ? 'inputs' : k === 'btn' ? 'buttons' : k === 'row' ? 'list rows' : k === 'card' ? 'cards' : 'sheet tops'}`)
+        .join(', ')}, and pills for chips. Never mix sharp and rounded corners in one view.
+
+## Components
+- **Buttons:** 48px tall, label-button. Primary: primary fill, on-primary text. Secondary: raised fill, text. Danger: transparent with danger text and a border.
+- **Cards:** surface, card radius, 1px border, no shadow; hairline dividers inside, never cards in cards.
+- **Chips:** 32px pills on raised, text-muted label-chip; a selected filter is primary-wash with primary text.
+- **Segmented controls:** a background track with raised for the selected segment, text-muted turning text when selected.
+- **Bottom tab bar:** surface with a top border, up to five items, each a ${c.icons} icon over a label-tab label; the active item is primary.
+- **Inputs:** label above, raised fill, input radius, text-muted placeholder, a 2px primary focus ring.
+- **Sheets:** bottom sheets with a grab handle and sheet-radius top corners.
+- **Empty states:** one sentence of guidance and one action.
+- Icons: ${c.icons}, one set everywhere, the same glyph for the same meaning on every screen.
+
+### States (every interactive element shows them)
+- **Pressed:** moves down 1px and darkens one step (primary → primary-pressed, raised → border); circular buttons scale to 0.95.
+- **Hover (pointer devices only):** text-muted turns text; surfaces lighten one step.
+- **Focus (keyboard):** 2px primary ring with a 2px offset.
+- **Selected:** chips primary-wash with primary text; segments raised with text; the active tab primary.
+- **Disabled:** text-faint on raised, no pressed or hover change, the reason shown nearby when not obvious.
+- **Error:** danger border and one meta line in danger under the field, saying how to fix it.
+
+## Do's and Don'ts
+- Do build every screen from the shared components; adapt the content or extend the component rather than build a near-copy.
+- Do use primary only for the single most important action in each region.
+- Do pick text styles from the type levels; don't invent sizes between them.
+- Don't use more than one accent colour, gradients behind text, glows or glassmorphism.
+- Don't use placeholder names (John Doe, Acme) or fake round numbers in mock-ups.
+- Don't use circular spinners: show skeletons the size of the content.
+
+## Layout Guardrails
+- Fixed bars never cover content: the scroll ends with enough bottom padding for the tab bar.
+- Titles and metadata stay on one line; chips, segments and buttons never wrap their labels.
+- Every element fits the frame: no clipping, no overlap, no horizontal page scroll (chip rows may scroll).
+- Mock-ups show only what the app shows: no phone status bar, no step labels, no tip or promo cards, no helper text or features the screen's description does not ask for.
+`;
+    return `${y.join('\n')}${prose}`;
+}

package/dist/build-elements.d.ts

@@ -0,0 +1 @@
+export {};