stitch2 0.7.3 → 0.8.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,12 @@ 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,
+  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, …)
@@ -167,7 +172,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/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.8.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",

package/skills/stitch2/SKILL.md

@@ -47,6 +47,9 @@ 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`).
+   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