stitch2 0.7.3 → 0.9.0

package/README.md

@@ -7,6 +7,10 @@ agents skills that tell them how.
 > stitch2 is inspired by [Google Stitch](https://stitch.withgoogle.com) and works with it, but it is an
 > independent project, not affiliated with or endorsed by Google.
 
+[![Watch stitch2 in 80 seconds on YouTube: an agent's draft drifts from the design system, the checks catch it, and it is fixed and approved on the canvas](https://img.youtube.com/vi/mIhP_umyO3o/maxresdefault.jpg)](https://youtu.be/mIhP_umyO3o)
+
+▶ [Watch the 80-second demo on YouTube](https://youtu.be/mIhP_umyO3o)
+
 ## Quick start with an AI agent
 
 Paste this to your coding agent (Codex, Claude Code, Cursor or any agent that runs commands) in your project:
@@ -32,11 +36,13 @@ file that already exists. From there the agent spends its effort on the design.
 - **Canvas** (`stitch2 canvas`): every screen and its versions on a pan-and-zoom board, a sidebar with search
   and status filters, your DESIGN.md drawn as tokens and rules, the component catalog, and an inspector to
   approve, archive or leave a note on a version. Live reload; copyable references to paste to an agent.
+  With a light and a dark theme (DESIGN.md's `light-*` colours), a switch (`T`) shows every screen in either one.
   Pick mode (`P`) highlights any element of a screen and copies a reference with its source line, such as
   `home mobile v1 (design/screens/home/mobile-v1.html:36) <gg-button> “Start Push”`; Shift-click collects
   several to copy at once or add to the version's note.
-- **Checks** (`stitch2 check`): content past the frame edge, labels that wrap, content under fixed bars, fixed bars that overlap each other, tap
-  targets (WCAG 2.2), text contrast, text that is not one of DESIGN.md's type levels, capitals without tracking,
+- **Checks** (`stitch2 check`): content past the frame edge or out of its card, labels that wrap, text running into
+  other text, labels cut short with an ellipsis, content under fixed bars, fixed bars that overlap each other, tap
+  targets (WCAG 2.2), text contrast in every theme, text that is not one of DESIGN.md's type levels, capitals without tracking,
   large numbers in monospace, components built by hand, components that differ between screens, and colours
   written as values instead of DESIGN.md tokens.
 - **Consistency report** (`stitch2 consistency`): every shared component (tab bar, header, buttons, chips, …)
@@ -159,6 +165,24 @@ put a page into the state the design shows (open a sheet, start a workout). The
 an error on that version and the run goes on. When it opens a modal, wait for something inside it (a marked
 component): dialog roots are often zero-sized wrappers, which Playwright reports as hidden.
 
+### In your own tests: every language, every width
+
+The layout rules are a plain function you can run on any page, so an app's own Playwright tests can check what
+mock-ups never show: long translations, right-to-left layouts, narrow phones.
+
+```ts
+import { audit } from 'stitch2/audit'
+
+for (const locale of ['de', 'ru', 'ar']) {
+  // …open the page in that language…
+  const issues = await page.evaluate(audit, { comfortable: 32 })
+  const errors = issues.filter((i) => i.severity === 'error') // overflow, text-overlap, label-wraps, …
+}
+```
+
+Warnings worth reading for translations: `truncated` (a label cut short with an ellipsis), `text-crowded` (two
+controls' labels nearly touching) and `clipped`.
+
 ## Commands
 
 | Command | What it does |
@@ -167,7 +191,7 @@ component): dialog roots are often zero-sized wrappers, which Playwright reports
 | `stitch2 init --name N --primary #hex [options]` | Writes a complete DESIGN.md from a few choices |
 | `stitch2 extract <url or file…>` | Writes a DESIGN.md measured from an existing site or screens |
 | `stitch2 canvas` | The canvas at http://localhost:4400 (`PORT` and `HOST` to change) |
-| `stitch2 check [filter] [--shots] [--strict]` | All checks; `--shots` saves renders to `<design>/renders/` |
+| `stitch2 check [filter] [--shots] [--strict]` | All checks, in every theme; `--shots` saves renders to `<design>/renders/` (`--light.png` for the other theme) |
 | `stitch2 consistency [kind…]` | The consistency report, `<design>/consistency/index.html` |
 | `stitch2 type [filter] [--json]` | The type audit |
 | `stitch2 screens [name] [--status s] [--json]` | Versions, statuses and notes |

package/config.schema.json

@@ -62,6 +62,11 @@
       "description": "Tap targets smaller than this (px) get a warning.",
       "default": 32
     },
+    "themes": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "The themes every screen must work in, by their data-theme value. Defaults to DESIGN.md's: dark (the plain colours), plus light when it has light-* colours. The canvas switches between them and check runs in each."
+    },
     "skills": {
       "type": "array",
       "items": {

package/dist/audit.d.ts

@@ -1,5 +1,6 @@
 /**
- * The layout audit, shared by check (the design screens) and compare (the live app). Runs inside the page.
+ * The layout audit, shared by check (the design screens) and compare (the live app), and exported as
+ * stitch2/audit for projects' own tests. Runs inside the page.
  */
 import type { Issue } from './typecheck.ts';
 /** Layout errors that mean the same bug wherever they appear; compare reports these for the app too. */

package/dist/audit.js

@@ -1,5 +1,5 @@
 /** 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'];
+export const LAYOUT_ERRORS = ['overflow', 'fixed-overlap', 'control-overlap', 'text-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;
@@ -101,8 +101,15 @@ export async function audit(opts) {
         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)));
+    // Behind an open modal the page is inert and covered, so only the modal's own bars count.
+    // An open modal: the element may be 0px itself when everything in it is fixed (Headless UI's Dialog).
+    const modal = [...document.querySelectorAll('[aria-modal="true"]')].find((m) => {
+        const cs = getComputedStyle(m);
+        return cs.display !== 'none' && cs.visibility !== 'hidden' && [m, ...m.querySelectorAll('*')].some(shown);
+    });
+    const outer = bars.filter((b) => !bars.some((o) => o !== b && o.contains(b)) && (!modal || modal.contains(b)));
     const content = all.filter((el) => !outer.some((b) => b.contains(el)) &&
+        (!modal || modal.contains(el)) &&
         (ownText(el) || el.matches('button, input, select, textarea, img, svg, canvas, video')) &&
         opacity(el) > 0.5);
     const covered = async (edge) => {
@@ -121,7 +128,7 @@ export async function audit(opts) {
                 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)`);
+                    push('error', `under-${edge}-bar`, el, `Hidden under the fixed ${edge} bar (“${text(bar).slice(0, 30) || bar.tagName.toLowerCase()}”) when scrolled to the ${edge} (add padding)`);
             }
         }
     };
@@ -185,8 +192,7 @@ export async function audit(opts) {
                 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);
+    // Behind an open modal (found above) only the modal's own controls count.
     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)) {
@@ -197,6 +203,95 @@ export async function audit(opts) {
             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`);
         }
+    // 4c. Text never collides with other text: labels of two controls overlapping (a long translation spilling into
+    // its neighbour in a tab bar) are errors; labels of two controls closer than 4px are warnings.
+    const owner = (el) => el.closest('button, a, label, [role=tab], [role=button], [role=switch], [role=checkbox]') ?? el;
+    const runs = [];
+    {
+        const walker = document.createTreeWalker(document.body, NodeFilter.SHOW_TEXT);
+        for (let n = walker.nextNode(); n; n = walker.nextNode()) {
+            const el = n.parentElement;
+            if (!el || !n.textContent.trim() || !shown(el) || inSvg(el) || opacity(el) < 0.5)
+                continue;
+            if (modal && !modal.contains(el))
+                continue;
+            const range = document.createRange();
+            range.selectNodeContents(n);
+            // Only what shows: text cut off by a clipping parent (an ellipsis) still measures full width.
+            const clips = [];
+            for (let p = el; p && p !== document.body; p = p.parentElement)
+                if (getComputedStyle(p).overflowX !== 'visible')
+                    clips.push(p.getBoundingClientRect());
+            for (const raw of range.getClientRects()) {
+                let [l, t, r, b] = [raw.left, raw.top, raw.right, raw.bottom];
+                for (const c of clips)
+                    [l, t, r, b] = [Math.max(l, c.left), Math.max(t, c.top), Math.min(r, c.right), Math.min(b, c.bottom)];
+                if (r - l > 1 && b - t > 1)
+                    runs.push({ el, own: owner(el), r: new DOMRect(l, t, r - l, b - t) });
+            }
+        }
+    }
+    const collided = new Set();
+    for (const [i, a] of runs.entries())
+        for (const b of runs.slice(i + 1)) {
+            if (a.own === b.own || a.own.contains(b.own) || b.own.contains(a.own) || layer(a.el) !== layer(b.el))
+                continue;
+            if (collided.has(a.own) || collided.has(b.own))
+                continue;
+            const x = Math.min(a.r.right, b.r.right) - Math.max(a.r.left, b.r.left);
+            const y = Math.min(a.r.bottom, b.r.bottom) - Math.max(a.r.top, b.r.top);
+            // Same row: stacked lines of a tight heading touch at their glyph boxes and are not a collision.
+            const sameRow = y > Math.min(a.r.height, b.r.height) * 0.5;
+            if (x > 1 && sameRow) {
+                collided.add(b.own);
+                push('error', 'text-overlap', b.el, 'Text runs into “' + text(a.el).slice(0, 30) + '”: shorten it or give it room');
+            }
+            else if (sameRow && x > -4 && a.own !== a.el && b.own !== b.el) {
+                collided.add(b.own);
+                push('warning', 'text-crowded', b.el, 'Touches “' + text(a.el).slice(0, 30) + '” with no gap: a longer word will collide');
+            }
+        }
+    // 4c'. Labels cut short with an ellipsis: fine for a long exercise name in a row, a translation problem in a tab,
+    // a button or a short label. Reported as warnings, for the eye to judge.
+    for (const el of all) {
+        if (!ownText(el) || getComputedStyle(el).textOverflow !== 'ellipsis')
+            continue;
+        const h = el;
+        if (h.scrollWidth > h.clientWidth + 1)
+            push('warning', 'truncated', el, 'Cut short with an ellipsis (' + h.scrollWidth + 'px of text in ' + h.clientWidth + 'px)');
+    }
+    // 4d. Nothing sticks out sideways of the card or bar that holds it (a button pushed past its card's edge by a
+    // long label), even while still on screen. Clipping and scrolling containers end the search: what they hide
+    // is deliberate.
+    const paints = (el) => {
+        const cs = getComputedStyle(el);
+        return !/rgba\(0, 0, 0, 0\)|transparent/.test(cs.backgroundColor) || Number.parseFloat(cs.borderLeftWidth) > 0;
+    };
+    const outside = new Set();
+    for (const el of all) {
+        if (overflowing.has(el) || outside.has(el.parentElement))
+            continue;
+        if (['absolute', 'fixed'].includes(getComputedStyle(el).position))
+            continue;
+        let box = null;
+        for (let p = el.parentElement; p && p !== document.body; p = p.parentElement) {
+            if (getComputedStyle(p).overflowX !== 'visible')
+                break;
+            if (paints(p)) {
+                box = p;
+                break;
+            }
+        }
+        if (!box)
+            continue;
+        const r = el.getBoundingClientRect();
+        const b = box.getBoundingClientRect();
+        const out = Math.max(r.right - b.right, b.left - r.left);
+        if (out > 2) {
+            outside.add(el);
+            push('error', 'overflow', el, 'Sticks out of its container by ' + Math.round(out) + 'px');
+        }
+    }
     // 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);

package/dist/canvas.html

@@ -26,6 +26,7 @@
   .seg { background: var(--bg); border: 1px solid var(--edge); border-radius: 8px; display: flex; gap: 2px; padding: 2px; }
   .seg button { background: none; border: 0; border-radius: 6px; color: var(--muted); cursor: pointer; flex: 1; padding: 4px 6px; white-space: nowrap; }
   .seg button.on { background: var(--panel2); color: var(--text); }
+  .seg[hidden] { display: none; }
   #tree { flex: 1; overflow: auto; padding: 6px 8px 16px; }
   #tree h4 { color: var(--faint); font-size: 11px; letter-spacing: .06em; margin: 14px 6px 6px; text-transform: uppercase; }
   .item { align-items: center; background: none; border: 0; border-radius: 6px; color: var(--muted); cursor: pointer; display: flex; gap: 8px; padding: 6px 8px; text-align: left; width: 100%; }
@@ -105,6 +106,7 @@
     <input id="search" placeholder="Search screens… ( / )" />
     <div class="seg" id="statusFilter"><button type="button" data-v="active" class="on" title="Everything except archived versions">Active</button><button type="button" data-v="approved" title="The reference versions agents build on">Approved</button><button type="button" data-v="review" title="Finished by an agent, waiting for your decision">Needs review</button><button type="button" data-v="all" title="Including archived versions">All</button></div>
     <div class="seg" id="deviceFilter"><button type="button" data-v="all" class="on">All devices</button><button type="button" data-v="mobile">Mobile</button><button type="button" data-v="desktop">Desktop</button></div>
+    <div class="seg" id="themeFilter" hidden title="Show every screen in this theme (T)"></div>
   </header>
   <nav id="tree"></nav>
   <footer>
@@ -134,7 +136,26 @@ const STATUS_HINT = {
 }
 /** What to paste to an agent: the screen, device and version, and the file. */
 let designDir = 'design'
-const ref = (s) => (s.kind === 'components' ? `component catalog (${designDir}/${s.path})` : `${s.screen} ${s.device} ${s.version} (${designDir}/${s.path})`)
+// Themes: every screen is shown in the one picked here (data-theme on its document); checks follow it.
+let THEMES = ['dark']
+let theme = localStorage.getItem('stitch2-theme') ?? 'dark'
+const themed = () => THEMES.length > 1
+const themeNote = () => (themed() && theme !== THEMES[0] ? ` in the ${theme} theme` : '')
+const forTheme = (issues) => (issues ?? []).filter((i) => !i.theme || !themed() || i.theme === theme)
+function applyTheme(f) {
+  if (!themed()) return
+  try { f.iframe.contentDocument.documentElement.dataset.theme = theme } catch {}
+}
+function setTheme(t) {
+  theme = t
+  localStorage.setItem('stitch2-theme', t)
+  for (const b of document.querySelectorAll('#themeFilter button')) b.classList.toggle('on', b.dataset.v === t)
+  for (const f of frames.values()) applyTheme(f)
+  for (const f of frames.values()) badge(f)
+  if (selected) inspector(selected)
+  summary()
+}
+const ref = (s) => (s.kind === 'components' ? `component catalog (${designDir}/${s.path})` : `${s.screen} ${s.device} ${s.version}${themeNote()} (${designDir}/${s.path})`)
 let toastTimer
 async function copy(text) {
   try {
@@ -321,8 +342,8 @@ function measure(f) {
 
 function badge(f) {
   const b = f.el.querySelector('.badge')
-  const issues = checks.screens?.[f.screen.path]
-  if (!issues) { b.className = 'badge'; b.textContent = 'not checked'; return }
+  if (!checks.screens?.[f.screen.path]) { b.className = 'badge'; b.textContent = 'not checked'; return }
+  const issues = forTheme(checks.screens[f.screen.path])
   const errors = issues.filter((i) => i.severity === 'error').length
   const warnings = issues.length - errors
   b.className = `badge ${errors ? 'bad' : warnings ? 'warn' : 'ok'}`
@@ -346,7 +367,7 @@ function summary() {
   const review = versions.filter((s) => s.status === 'review').length
   const approved = new Set(versions.filter((s) => s.status === 'approved').map((s) => s.screen)).size
   const names = new Set(versions.map((s) => s.screen)).size
-  const bad = versions.filter((s) => checks.screens?.[s.path]?.some((i) => i.severity === 'error')).length
+  const bad = versions.filter((s) => forTheme(checks.screens?.[s.path]).some((i) => i.severity === 'error')).length
   document.getElementById('summary').textContent = `${names} screens · ${approved} approved · ${review} need review${bad ? ` · ${bad} with errors` : ''}`
 }
 
@@ -360,7 +381,7 @@ function frameFor(s) {
   iframe.style.height = `${s.width > 700 ? 800 : 844}px`
   iframe.src = `/${s.path}?pick`
   const f = { el, iframe, screen: s, height: s.width > 700 ? 800 : 844 }
-  iframe.addEventListener('load', () => { measure(f); setTimeout(() => measure(f), 800); setTimeout(() => measure(f), 2500) })
+  iframe.addEventListener('load', () => { applyTheme(f); measure(f); setTimeout(() => measure(f), 800); setTimeout(() => measure(f), 2500) })
   el.querySelector('.shield').addEventListener('click', () => select(f, false))
   el.querySelector('.shield').addEventListener('dblclick', () => { select(f, false); f.el.classList.add('live') })
   el.querySelector('.label').addEventListener('click', () => select(f, true))
@@ -387,7 +408,7 @@ function select(f, zoom) {
 function inspector(f) {
   const box = document.getElementById('inspector')
   const s = f.screen
-  const issues = checks.screens?.[s.path] ?? []
+  const issues = forTheme(checks.screens?.[s.path])
   box.innerHTML = `<h3><span class="dot ${s.status}"></span><span class="h"></span><button type="button" class="copy" title="Copy a reference to paste to an agent">Copy</button><button type="button" class="close" title="Close (Esc)">×</button></h3>
     <div class="facts"><span class="f"></span> · <a target="_blank"></a></div>
     ${s.kind === 'screen' ? `<div class="status">${['approved', 'review', 'draft', 'archived'].map((st) => `<button type="button" data-st="${st}" title="${STATUS_HINT[st]}" class="${s.status === st ? 'on' : ''}">${st === 'approved' ? 'Approve' : st === 'review' ? 'Needs review' : st === 'draft' ? 'Draft' : 'Archive'}</button>`).join('')}</div>
@@ -494,7 +515,7 @@ function elementRef(f, el) {
   const d = describe(el)
   const s = f.screen
   const who = s.kind === 'components' ? 'component catalog' : `${s.screen} ${s.device} ${s.version}`
-  return `${who} (${designDir}/${s.path}:${d.line}) <${d.tag}>${d.text ? ` “${d.text}”` : ''}`
+  return `${who}${themeNote()} (${designDir}/${s.path}:${d.line}) <${d.tag}>${d.text ? ` “${d.text}”` : ''}`
 }
 function drawBox(f, el, cls, label) {
   const r = el.getBoundingClientRect()
@@ -602,7 +623,9 @@ events.onmessage = async (e) => {
   const html = paths.filter((p) => p.endsWith('.html'))
   if (html.length) await load(false)
   if (paths.includes('DESIGN.md') && document.getElementById('doc').classList.contains('open')) document.querySelector('#doc iframe').contentWindow.location.reload()
-  const shared = paths.some((p) => /^(tokens\.css|tailwind\.tokens\.js|components\/)/.test(p))
+  // Stylesheets and scripts are shared: tokens.css, tailwind.tokens.js, token exports the screens link
+  // (tokens.tailwind.css), the components.
+  const shared = paths.some((p) => /\.(css|js|mjs)$/.test(p) || p.startsWith('components/'))
   for (const f of frames.values()) {
     if (shared || html.includes(f.screen.path)) {
       f.iframe.contentWindow?.location.reload()
@@ -658,6 +681,7 @@ addEventListener('keydown', (e) => {
   if (e.key === 'p' || e.key === 'P') setPicking(!picking)
   if (e.key === 'Escape') { closeDoc(); select(null) }
   if (e.key === 'f' || e.key === 'F') fit()
+  if ((e.key === 't' || e.key === 'T') && themed()) setTheme(THEMES[(THEMES.indexOf(theme) + 1) % THEMES.length])
   if (e.key === '0') zoomAt((innerWidth - SIDE) / 2, innerHeight / 2, 1)
   if (e.key === '+' || e.key === '=') zoomAt((innerWidth - SIDE) / 2, innerHeight / 2, view.z * 1.2)
   if (e.key === '-') zoomAt((innerWidth - SIDE) / 2, innerHeight / 2, view.z / 1.2)
@@ -681,6 +705,13 @@ fetch('/api/config').then((r) => r.json()).then((c) => {
   ORDER = c.order ?? []
   designDir = c.designDir ?? 'design'
   document.getElementById('labName').textContent = c.name
+  THEMES = c.themes?.length ? c.themes : ['dark']
+  if (!THEMES.includes(theme)) theme = THEMES[0]
+  const seg = document.getElementById('themeFilter')
+  seg.hidden = !themed()
+  seg.innerHTML = THEMES.map((t) => `<button type="button" data-v="${t}">${t[0].toUpperCase()}${t.slice(1)}</button>`).join('')
+  for (const b of seg.querySelectorAll('button')) b.onclick = () => setTheme(b.dataset.v)
+  setTheme(theme)
   document.title = c.name
   load(true)
 })

package/dist/check.js

@@ -3,8 +3,10 @@
  * edge, labels wrapping onto two lines, content hidden under fixed bars, tiny tap targets, low text
  * contrast, and text styles that are not one of DESIGN.md's type levels. Writes design/checks.json, which
  * the canvas shows as badges.
+ * Every screen is checked in its own theme, then again in each other theme DESIGN.md defines (designThemes):
+ * colours change there, so contrast is checked again, tagged with the theme.
  * Usage: stitch2 check [path filter…] [--shots] [--strict]
- *   --shots   also save page-tall renders to design/renders/
+ *   --shots   also save page-tall renders to design/renders/ (one per theme)
  *   --strict  exit 1 when any screen has errors (for CI and agent loops)
  */
 import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
@@ -13,7 +15,7 @@ import { chromium } from '@playwright/test';
 import { colourIssues } from './colours.js';
 import { config } from './config.js';
 import { collectComponents, collectOptions, consistencyIssues, reuseIssues, } from './consistency.js';
-import { typeLevels } from './design-md.js';
+import { designThemes, typeLevels } from './design-md.js';
 import { listScreens, ROOT } from './screens.js';
 import { startServer } from './serve.js';
 import { collectText, typeIssues } from './typecheck.js';
@@ -24,6 +26,7 @@ const strict = args.includes('--strict');
 const filters = args.filter((a) => !a.startsWith('--'));
 const screens = listScreens().filter((s) => !filters.length || filters.some((f) => s.path.includes(f)));
 const levels = typeLevels();
+const themes = designThemes();
 const collect = collectOptions();
 const server = await startServer(0);
 const browser = await chromium.launch();
@@ -39,23 +42,52 @@ for (const s of screens) {
     await page.waitForTimeout(600);
     const found = await page.evaluate(collectComponents, collect);
     components[s.path] = found.components;
+    const own = await page.evaluate(() => document.documentElement.dataset.theme || '');
+    const base = own || themes[0];
+    const layout = await page.evaluate(audit, { comfortable: config.comfortableTarget });
+    for (const i of layout)
+        if (i.type === 'contrast')
+            i.theme = base;
+    // The other themes: what the colours change (contrast), plus anything that only shows there.
+    const seen = new Set(layout.map((i) => `${i.type} ${i.selector}`));
+    const themed = [];
+    for (const theme of themes.filter((t) => t !== base)) {
+        await setTheme(theme);
+        for (const i of await page.evaluate(audit, { comfortable: config.comfortableTarget }))
+            if (i.type === 'contrast' || !seen.has(`${i.type} ${i.selector}`))
+                themed.push({ ...i, theme, message: `${theme} theme: ${i.message}` });
+        if (shots)
+            await shoot(s, theme);
+    }
+    if (themes.length > 1)
+        await setTheme(base);
     results[s.path] = [
-        ...(await page.evaluate(audit, { comfortable: config.comfortableTarget })),
+        ...layout,
+        ...themed,
         ...typeIssues(levels, await page.evaluate(collectText)),
         ...reuseIssues(s.path, found),
         ...colourIssues(s.path),
     ];
-    if (shots) {
-        const height = await page.evaluate(() => document.documentElement.scrollHeight);
-        await page.setViewportSize({ width: s.width, height: Math.max(844, Math.min(height, 6000)) });
-        mkdirSync(join(ROOT, 'renders'), { recursive: true });
-        await page.screenshot({
-            path: join(ROOT, 'renders', s.path.replaceAll('/', '__').replace(/\.html$/, '.png')),
-        });
-    }
+    if (shots)
+        await shoot(s);
 }
 await browser.close();
 server.close();
+async function setTheme(theme) {
+    await page.evaluate((t) => {
+        document.documentElement.dataset.theme = t;
+    }, theme);
+    await page.waitForTimeout(150);
+}
+/** A page-tall render; renders in another theme than the screen's own get a --<theme> suffix. */
+async function shoot(s, theme) {
+    const height = await page.evaluate(() => document.documentElement.scrollHeight);
+    await page.setViewportSize({ width: s.width, height: Math.max(844, Math.min(height, 6000)) });
+    mkdirSync(join(ROOT, 'renders'), { recursive: true });
+    const name = s.path.replaceAll('/', '__').replace(/\.html$/, theme ? `--${theme}.png` : '.png');
+    await page.screenshot({ path: join(ROOT, 'renders', name) });
+    await page.setViewportSize({ width: s.width, height: 844 });
+}
 // Merge with the last results, so a filtered run still compares components with every other screen.
 let previous = {};
 try {

package/dist/config.d.ts

@@ -20,6 +20,11 @@ export interface LabConfig {
     order: string[];
     /** Tap targets smaller than this (px) get a warning; under WCAG's 24px they are errors when crowded. */
     comfortableTarget: number;
+    /**
+     * The themes every screen must work in, by their data-theme value. Defaults to DESIGN.md's: "dark" (the plain
+     * colours) and "light" when it has light-* colours. The canvas switches between them; check runs in each.
+     */
+    themes?: string[];
     /** Skill folders a blind-trial sandbox copies. */
     skills: string[];
     /** Paths under designDir a sandbox leaves out besides screens (notes that would give the trial away). */

package/dist/design-md.d.ts

@@ -15,6 +15,11 @@ export interface Design {
     components: Record<string, Record<string, string>>;
 }
 export declare function readDesign(file?: string): Design;
+/**
+ * The themes screens must work in (their data-theme values): the config's, or DESIGN.md's own, where the plain
+ * colours are the dark theme and light-* colours make a light one.
+ */
+export declare function designThemes(): string[];
 /** A type level in pixels, for comparing with computed styles. */
 export interface Level {
     name: string;

package/dist/design-md.js

@@ -5,6 +5,7 @@
 import { readFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { parse } from 'yaml';
+import { config } from './config.js';
 import { ROOT } from './screens.js';
 export function readDesign(file = join(ROOT, 'DESIGN.md')) {
     const text = readFileSync(file, 'utf8');
@@ -31,6 +32,20 @@ export function readDesign(file = join(ROOT, 'DESIGN.md')) {
         components: raw.components ?? {},
     };
 }
+/**
+ * The themes screens must work in (their data-theme values): the config's, or DESIGN.md's own, where the plain
+ * colours are the dark theme and light-* colours make a light one.
+ */
+export function designThemes() {
+    if (config.themes?.length)
+        return config.themes;
+    try {
+        return Object.keys(readDesign().colors).some((k) => k.startsWith('light-')) ? ['dark', 'light'] : ['dark'];
+    }
+    catch {
+        return ['dark'];
+    }
+}
 export function typeLevels(design = readDesign()) {
     return Object.entries(design.typography).map(([name, t]) => {
         const size = Number.parseFloat(String(t.fontSize));

package/dist/serve.js

@@ -9,6 +9,7 @@ import { createServer } from 'node:http';
 import { dirname, extname, join, normalize } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { CONFIG_FILE, config } from './config.js';
+import { designThemes } from './design-md.js';
 import { designPage } from './design-page.js';
 import { annotate } from './pick.js';
 /**
@@ -114,7 +115,7 @@ export function startServer(port) {
             return;
         }
         if (url.pathname === '/api/config')
-            return json(config);
+            return json({ ...config, themes: designThemes() });
         if (url.pathname === '/api/screens')
             return json(listScreens());
         if (url.pathname === '/api/checks') {

package/dist/typecheck.d.ts

@@ -9,6 +9,8 @@ export interface Issue {
     message: string;
     selector: string;
     text: string;
+    /** Set when the issue depends on the theme (contrast): the data-theme it was found in. */
+    theme?: string;
 }
 export interface TextItem {
     selector: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "stitch2",
-  "version": "0.7.3",
+  "version": "0.9.0",
   "description": "A design canvas, layout and type checks, component consistency and screen versioning for agent-built UI, on Google's DESIGN.md format.",
   "license": "MIT",
   "author": "ifokeev",
@@ -17,6 +17,10 @@
       "types": "./dist/elements.d.ts",
       "default": "./dist/elements.js"
     },
+    "./audit": {
+      "types": "./dist/audit.d.ts",
+      "default": "./dist/audit.js"
+    },
     "./package.json": "./package.json"
   },
   "files": [

package/skills/stitch2/SKILL.md

@@ -47,6 +47,11 @@ References, read before the first screen:
 5. **Check** `stitch2 check <path> --shots --strict`. Fix every error (overflow, wrapped labels, content under
    fixed bars, fixed bars overlapping each other, tap targets, contrast, cramped text) and every warning about type (`type-*`), hand-built
    components (`reuse`), components that differ from the catalog (`consistency`) and colour values (`color`).
+   Text running into other text (`text-overlap`) or out of its card (`overflow`) is an error; a short label cut
+   short with an ellipsis (`truncated`) is a warning to fix with room, not a smaller size. When DESIGN.md has a
+   light and a dark theme, every screen is checked in both: an issue marked with a theme
+   ("light theme: Low contrast…") is fixed in DESIGN.md's colours for that theme when it shows on many
+   screens, or in the screen when it is one element. Look at both renders (`--light.png`).
 6. **Look and critique.** View the render in `<design>/renders/` (crop the first screenful). Score it with the
    rubric in principles.md, fix what fails, repeat 5–6 at most three times.
 7. **Hand over.** Set the version's status to `review`, point the user to it on the canvas, and report what