stitch2 0.18.0 → 0.19.0

package/README.md

@@ -48,18 +48,24 @@ file that already exists. From there the agent spends its effort on the design.
 - **Checks** (`stitch2 check`): content past the frame edge or out of its card, navigation whose links scroll or are cut (in any language), 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), all of it again at both ends of the window widths each layout covers (360 and 599 px for a
-  phone, 1024 and 1920 for desktop, or your own ranges), text contrast in every theme, text that is not one of DESIGN.md's type levels, capitals without tracking,
+  phone, 1024 and 1920 for desktop, or your own ranges) and at every breakpoint inside them (Tailwind's sm, md,
+  lg, xl, 2xl, or your own), a phone column left in a tablet-wide window, 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. Google's guidelines (Material 3, Android's app quality
   guidelines, web.dev, Lighthouse) add warnings for text under 11 px, text closer than 16 px (24 px from 600 px)
   to the edge, lines over 75 characters, targets under 48 px without room around them, placeholder-only labels,
   icon-only controls without a name, more than five bottom-navigation destinations and controls without visible
-  focus. Each screen is also run in long and right-to-left
+  focus. Motion: transitions whose length isn't one of DESIGN.md's motion tokens, and anything that still moves
+  with reduced motion on. Each screen is also run in long and right-to-left
   pseudo-languages and your locales (see below).
+- **States** (from `stitch2 check` on the component catalog): every control at rest, hovered, focused and
+  pressed, forced through Chromium so the components need nothing extra, side by side on one sheet; with
+  warnings for a control that gives no feedback and text that loses contrast in a state.
 - **Consistency report** (`stitch2 consistency`): every shared component (tab bar, header, buttons, chips, …)
   cropped from every screen, next to the catalog's version, with what differs (sizes, fonts, icon set, icons).
 - **Type audit** (`stitch2 type`): every text style a screen uses, and the level it matches.
-- **Tokens** (`stitch2 tokens`): CSS variables, one `.type-<level>` class per type level (with per-language
+- **Tokens** (`stitch2 tokens`): CSS variables, motion tokens (durations and easings, a stitch2 extension of
+  DESIGN.md), one `.type-<level>` class per type level (with per-language
   rules for scripts without capitals) and a Tailwind config, from DESIGN.md's front matter, plus Material 3
   colour roles from a seed colour. **Exports** write the same tokens for your app, so DESIGN.md drives the
   product as well as the screens: plain CSS variables, a Tailwind v4 theme (`@theme` plus `@utility type-*`), or

package/config.schema.json

@@ -67,6 +67,11 @@
       "description": "The window widths each variant covers, [narrowest, widest] in px, by device (mobile, tablet, desktop). check renders every variant at both ends; the canvas shows them. Defaults: mobile 360–599, tablet 600–1023, desktop 1024–1920.",
       "additionalProperties": { "type": "array", "items": { "type": "number" }, "minItems": 2, "maxItems": 2 }
     },
+    "breakpoints": {
+      "type": "object",
+      "description": "The window widths where the screens' layouts change (their responsive rules), in px by name. check also renders each variant at every breakpoint inside its range; the canvas can show every screen at one. Defaults to Tailwind's: sm 640, md 768, lg 1024, xl 1280, 2xl 1536.",
+      "additionalProperties": { "type": "number" }
+    },
     "themes": {
       "type": "array",
       "items": { "type": "string" },

package/dist/audit.d.ts

@@ -8,4 +8,10 @@ export declare const LAYOUT_ERRORS: string[];
 /** Runs inside the page. Plain JS on purpose: Playwright sends its source to the browser. */
 export declare function audit(opts: {
     comfortable: number;
+    durations?: number[];
 }): Promise<Issue[]>;
+/**
+ * Runs inside the page with prefers-reduced-motion: reduce. What still moves (an animation of transform,
+ * translate, scale, rotate or position) ignores the setting; fading and colour changes are fine.
+ */
+export declare function movingAnimations(): Issue[];

package/dist/audit.js

@@ -591,5 +591,81 @@ export async function audit(opts) {
     }
     before?.focus?.({ preventScroll: true });
     still.remove();
+    // 7. Motion uses DESIGN.md's durations (its motion: duration-* tokens): a transition of any other length is a
+    // value someone typed, and screens drift apart in how they move.
+    if (opts.durations?.length) {
+        const named = opts.durations.map((d) => Math.round(d));
+        for (const el of all) {
+            const cs = getComputedStyle(el);
+            if (cs.transitionProperty === 'none')
+                continue;
+            const odd = cs.transitionDuration
+                .split(',')
+                .map((v) => (v.trim().endsWith('ms') ? parseFloat(v) : parseFloat(v) * 1000))
+                .find((ms) => ms > 0 && !named.includes(Math.round(ms)));
+            if (odd !== undefined)
+                push('warning', 'motion-token', el, 'Moves for ' + Math.round(odd) + "ms, a duration DESIGN.md's motion doesn't name (" + named.join(', ') + 'ms): use a duration-* token');
+        }
+    }
+    // 6i. A medium window (600–1199 px: tablets, small laptops, Material's medium and expanded classes) is used: a
+    // phone column in the middle of it, with most of the window empty, is a layout that stopped adapting.
+    if (W >= 600 && W < 1200) {
+        const fixedBar = (el) => {
+            for (let e = el; e && e !== document.body; e = e.parentElement)
+                if (['fixed', 'sticky'].includes(getComputedStyle(e).position))
+                    return true;
+            return false;
+        };
+        let left = W, right = 0;
+        for (const el of all) {
+            if (!(ownText(el) || el.matches('img, svg, input, textarea, select, button, [role="button"]')) || fixedBar(el))
+                continue;
+            const r = el.getBoundingClientRect();
+            left = Math.min(left, r.left);
+            right = Math.max(right, r.right);
+        }
+        const used = right - left;
+        if (used > 0 && used < W * 0.6)
+            push('warning', 'narrow-layout', document.querySelector('main') ?? document.body, 'The content takes ' + Math.round(used) + ' of ' + W + 'px: a phone column in a wide window. Use the room (more columns, a side column) with the breakpoints, or give these widths to another variant');
+    }
     return out.sort((x, y) => (x.severity === y.severity ? 0 : x.severity === 'error' ? -1 : 1));
 }
+/**
+ * Runs inside the page with prefers-reduced-motion: reduce. What still moves (an animation of transform,
+ * translate, scale, rotate or position) ignores the setting; fading and colour changes are fine.
+ */
+export function movingAnimations() {
+    const MOVES = ['transform', 'translate', 'scale', 'rotate', 'left', 'top', 'right', 'bottom', 'marginTop', 'marginLeft', 'offsetDistance'];
+    const sel = (el) => {
+        const parts = [];
+        for (let e = el; e && e !== document.body && parts.length < 6; e = e.parentElement) {
+            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 out = [];
+    const seen = new Set();
+    for (const a of document.getAnimations()) {
+        const effect = a.effect;
+        const el = effect?.target;
+        if (!el || seen.has(el) || a.playState !== 'running')
+            continue;
+        const moves = effect.getKeyframes().some((k) => MOVES.some((p) => p in k));
+        if (!moves)
+            continue;
+        seen.add(el);
+        if (out.length < 10)
+            out.push({
+                severity: 'warning',
+                type: 'reduced-motion',
+                selector: sel(el),
+                text: (el.textContent ?? '').trim().slice(0, 60),
+                message: 'Still moves with reduced motion on: wrap the animation in @media (prefers-reduced-motion: no-preference) (Tailwind motion-safe:), or fade instead',
+            });
+    }
+    return out;
+}

package/dist/build-design.js

@@ -253,6 +253,9 @@ export function buildDesignMd(c) {
     }
     y.push('rounded:', ...Object.entries(rounded).map(([k, v]) => `  ${k}: ${v}`));
     y.push('spacing:', ...Object.entries(spacing).map(([k, v]) => `  "${k}": ${v}`));
+    // stitch2's motion tokens (Material's durations and easings): tokens turns them into CSS variables, ease-*
+    // classes, duration-* utilities and Tailwind's default transition.
+    y.push('motion:', '  duration-short: 150ms', '  duration-medium: 250ms', '  duration-long: 400ms', '  ease-standard: cubic-bezier(0.2, 0, 0, 1)', '  ease-enter: cubic-bezier(0.05, 0.7, 0.1, 1)', '  ease-exit: cubic-bezier(0.3, 0, 0.8, 0.15)');
     y.push('components:');
     for (const [k, props] of Object.entries(components)) {
         y.push(`  ${k}:`);
@@ -319,6 +322,13 @@ ${Object.entries(rounded)
 - **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.
 
+## Motion & Interaction
+- Durations and easings are the motion tokens: short (150ms) for a control's own change (a press, a toggle),
+  medium (250ms) for something entering or opening (a sheet, a menu), long (400ms) only for a whole screen.
+  ease-standard inside the screen, ease-enter for what arrives, ease-exit for what leaves.
+- Animate transform and opacity only; nothing animates on its own except a skeleton's pulse.
+- With reduced motion, nothing moves: fade or switch instead.
+
 ## 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.

package/dist/canvas.html

@@ -85,6 +85,8 @@
   .frame.desktop .device { border-radius: 12px; }
   .frame.selected .device { outline: 3px solid var(--accent); }
   .frame.archived { opacity: .55; }
+  /* At a breakpoint (the width dropdown), a variant whose range doesn't cover it is drawn at its nearest edge, faded. */
+  .frame.outside { opacity: .35; }
   /* A frame shows its picture (rendered by the server) until its live page is ready; only frames in view are live. */
   .device iframe { background: #fff; border: 0; display: block; left: 0; position: absolute; top: 0; visibility: hidden; }
   .frame.ready .device iframe { visibility: visible; }
@@ -139,7 +141,7 @@
     <details id="versionFilter" class="multi" hidden title="Show only the versions you pick (several at once), or all of them"><summary>All versions</summary><div class="menu"></div></details>
     <details id="variantFilter" class="multi" hidden title="Show only the variants you pick: mobile, desktop (several at once), or all of them"><summary>All variants</summary><div class="menu"></div></details>
     <select id="themeFilter" class="pick" hidden title="Show every screen in this theme (T)" aria-label="Theme"></select>
-    <select id="widthFilter" class="pick" title="Show every screen at the narrowest or widest window its variant covers (W)" aria-label="Width"></select>
+    <select id="widthFilter" class="pick" title="Show every screen at the narrowest or widest window its variant covers, or at one breakpoint (W)" aria-label="Width"></select>
     <select id="langFilter" class="pick" title="Show every screen in this language (L)" aria-label="Language"></select>
   </header>
   <nav id="tree"></nav>
@@ -200,11 +202,22 @@ function setLang(l) {
   summary()
   scheduleSync()
 }
-// Widths: each variant covers a range of windows (config widths); frames show it drawn, at the narrowest or the widest.
+// Widths: each variant covers a range of windows (config widths); frames show it drawn, at the narrowest or the
+// widest, or at one breakpoint (config breakpoints): "at:768" puts every variant at 768 px, or the nearest edge of
+// its range when 768 is outside it (then the frame is faded: the app shows another variant there).
 let WIDTHS = {}
+let BREAKPOINTS = {}
 let widthMode = localStorage.getItem('stitch2-width') ?? 'drawn'
 const rangeOf = (s) => WIDTHS[s.device]
-const widthFor = (s) => { const r = rangeOf(s); return !r || widthMode === 'drawn' ? s.drawn : widthMode === 'narrow' ? r[0] : r[1] }
+const atWidth = () => (widthMode.startsWith('at:') ? Number(widthMode.slice(3)) : 0)
+const widthFor = (s) => {
+  const r = rangeOf(s), at = atWidth()
+  if (!r || widthMode === 'drawn') return s.drawn
+  if (at) return Math.min(r[1], Math.max(r[0], at))
+  return widthMode === 'narrow' ? r[0] : r[1]
+}
+const outside = (s) => { const r = rangeOf(s), at = atWidth(); return !!(r && at && (at < r[0] || at > r[1])) }
+const widthModes = () => ['drawn', 'narrow', 'wide', ...Object.values(BREAKPOINTS).sort((a, b) => a - b).map((w) => `at:${w}`)]
 const bigFrame = (s) => (s.drawn ?? s.width) > 700
 function setWidth(mode) {
   widthMode = mode
@@ -214,6 +227,7 @@ function setWidth(mode) {
     f.screen.width = widthFor(f.screen)
     f.el.style.width = `${f.screen.width}px`
     size(f)
+    f.el.classList.toggle('outside', outside(f.screen))
     setTimeout(() => measure(f), 300)
     setTimeout(() => measure(f), 1200)
   }
@@ -225,7 +239,9 @@ function widthOptions() {
   const used = [...new Set(screens.map((s) => s.device))].filter((d) => WIDTHS[d]).sort((a, b) => WIDTHS[a][0] - WIDTHS[b][0])
   const edge = (k) => used.map((d) => `${d} ${WIDTHS[d][k]}`).join(', ')
   const wsel = document.getElementById('widthFilter')
-  wsel.innerHTML = `<option value="drawn">Drawn width</option><option value="narrow">Narrowest: ${edge(0)}</option><option value="wide">Widest: ${edge(1)}</option>`
+  const at = Object.entries(BREAKPOINTS).sort((a, b) => a[1] - b[1]).map(([name, w]) => `<option value="at:${w}">At ${w} px (${name})</option>`).join('')
+  wsel.innerHTML = `<option value="drawn">Drawn width</option><option value="narrow">Narrowest: ${edge(0)}</option><option value="wide">Widest: ${edge(1)}</option>${at}`
+  if (!widthModes().includes(widthMode)) widthMode = 'drawn'
   wsel.value = widthMode
 }
 function applyTheme(f) {
@@ -277,7 +293,7 @@ const filters = JSON.parse(localStorage.getItem('stitch2-filters') ?? 'null') ??
 if (typeof filters.device === 'string') { filters.devices = filters.device === 'all' ? [] : [filters.device]; delete filters.device }
 let screens = []
 let checks = { screens: {} }
-let reports = { consistency: null, compare: null }
+let reports = { consistency: null, compare: null, states: null }
 let selected = null
 const frames = new Map() // path -> { el, device, img, iframe (while live), screen, height }
 // Heights measured before, so the layout doesn't jump while pictures and pages load.
@@ -432,7 +448,7 @@ function filterLabel() {
 var sentFilter = ''
 function sendFilter(force) {
   const doc = document.getElementById('doc')
-  if (!doc.classList.contains('open') || !['/consistency/index.html', '/compare/index.html', '/languages'].includes(docUrl)) return
+  if (!doc.classList.contains('open') || !['/consistency/index.html', '/compare/index.html', '/languages', '/states/index.html'].includes(docUrl)) return
   const message = { stitch2Filter: { paths: reportPaths(), label: filterLabel(), theme: themed() ? theme : '' } }
   const key = JSON.stringify(message)
   if (!force && key === sentFilter) return
@@ -485,6 +501,7 @@ function tree() {
       : `Made ${new Date(state.at).toLocaleString()}${n ? `. Changed since, run ${command} again:\n${changed.slice(0, 12).join('\n')}${n > 12 ? `\n… and ${n - 12} more` : ''}` : ', up to date'}`
   }
   report('Consistency report', '/consistency/index.html', reports.consistency, 'stitch2 consistency')
+  report('States', '/states/index.html', reports.states, 'stitch2 check on the catalog')
   report('App comparison', '/compare/index.html', reports.compare, 'stitch2 compare')
   item('Languages', 'screens × languages', docOpen('/languages'), () => openDoc('/languages'))
   const all = rows().filter((r) => r.key !== '~components' && r.visible.length)
@@ -695,6 +712,7 @@ function badge(f) {
 function paintLabel(f) {
   const s = f.screen
   const kept = ['ready', 'live', 'changed'].filter((c) => f.el.classList.contains(c))
+  if (outside(s)) kept.push('outside')
   f.el.className = ['frame', s.device, s.status, selected === f ? 'selected' : '', ...kept].filter(Boolean).join(' ')
   f.el.querySelector('.name').textContent = s.kind === 'components' ? 'Catalog' : s.device
   const pill = f.el.querySelector('.pill')
@@ -818,7 +836,7 @@ function inspector(f) {
     li.querySelector('code').textContent = i.selector
     li.onclick = () => {
       const r = rangeOf(s)
-      if (i.width && r && i.width !== s.width) { setWidth(i.width === r[0] ? 'narrow' : 'wide'); setTimeout(() => locate(f, i.selector), 900) }
+      if (i.width && r && i.width !== s.width) { setWidth(i.width === r[0] ? 'narrow' : i.width === r[1] ? 'wide' : `at:${i.width}`); setTimeout(() => locate(f, i.selector), 900) }
       else locate(f, i.selector)
     }
     ul.append(li)
@@ -1113,7 +1131,7 @@ addEventListener('keydown', (e) => {
   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 === 'l' || e.key === 'L') setLang(LANGS[(LANGS.indexOf(lang) + 1) % LANGS.length])
-  if (e.key === 'w' || e.key === 'W') setWidth(['drawn', 'narrow', 'wide'][(['drawn', 'narrow', 'wide'].indexOf(widthMode) + 1) % 3])
+  if (e.key === 'w' || e.key === 'W') { const m = widthModes(); setWidth(m[(m.indexOf(widthMode) + 1) % m.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)
@@ -1151,6 +1169,7 @@ fetch('/api/config').then((r) => r.json()).then((c) => {
   pick.onchange = () => setTheme(pick.value)
   setTheme(theme)
   WIDTHS = c.widths ?? {}
+  BREAKPOINTS = c.breakpoints ?? {}
   const wsel = document.getElementById('widthFilter')
   wsel.onchange = () => setWidth(wsel.value)
   SOURCE = c.sourceLocale ?? 'en'

package/dist/check.js

@@ -8,23 +8,25 @@
  * Then again in each check language (i18n.ts: the pseudo-languages and the config's): layout problems that
  * show only there (a label running into its neighbour, text cut off, a control drawn backwards right to left),
  * and keys a locale has no translation for, tagged with the locale. Last, each variant at both ends of the widths
- * it covers (config widths: mobile 360–599, desktop 1024–1920 by default), tagged with the width.
+ * it covers (config widths: mobile 360–599, desktop 1024–1920 by default) and at every breakpoint inside them
+ * (config breakpoints, Tailwind's by default), tagged with the width.
  * Usage: stitch2 check [path filter…] [--shots] [--strict] [--locales ru,ar | all | none]
- *   --shots   also save page-tall renders to design/renders/ (one per theme, language and width edge)
+ *   --shots   also save page-tall renders to design/renders/ (one per theme, language and width)
  *   --strict  exit 1 when any screen has errors (for CI and agent loops)
  */
 import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { chromium } from '@playwright/test';
 import { colourIssues } from './colours.js';
-import { config, widthRange } from './config.js';
+import { checkWidths, config } from './config.js';
 import { collectComponents, collectOptions, consistencyIssues, reuseIssues, } from './consistency.js';
-import { designThemes, typeLevels } from './design-md.js';
+import { designThemes, motionDurations, typeLevels } from './design-md.js';
 import { checkLocales } from './i18n.js';
 import { listScreens, ROOT } from './screens.js';
 import { startServer } from './serve.js';
+import { catalogStates, writeStatesSheet } from './states.js';
 import { collectText, typeIssues } from './typecheck.js';
-import { audit } from './audit.js';
+import { audit, movingAnimations } from './audit.js';
 const args = process.argv.slice(2);
 const shots = args.includes('--shots');
 const strict = args.includes('--strict');
@@ -35,6 +37,13 @@ const screens = listScreens().filter((s) => !filters.length || filters.some((f)
 const levels = typeLevels();
 const themes = designThemes();
 const collect = collectOptions();
+/** What the layout audit needs: the comfortable tap size and DESIGN.md's motion durations. */
+const auditOpts = { comfortable: config.comfortableTarget, durations: (() => { try {
+        return motionDurations();
+    }
+    catch {
+        return [];
+    } })() };
 const server = await startServer(0);
 /** The tallest render, in CSS px: a long landing page is shot whole (the canvas draws frames up to the same height). */
 const MAX_RENDER_HEIGHT = 20000;
@@ -42,6 +51,7 @@ const browser = await chromium.launch();
 const page = await browser.newPage({ viewport: { width: 390, height: 844 }, deviceScaleFactor: 2 });
 const results = {};
 const components = {};
+const stateRows = {};
 for (const s of screens) {
     await page.setViewportSize({ width: s.width, height: 844 });
     await page
@@ -53,7 +63,12 @@ for (const s of screens) {
     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 });
+    const layout = await page.evaluate(audit, auditOpts);
+    // With reduced motion asked for, nothing keeps moving (DESIGN.md motion, WCAG 2.3.3).
+    await page.emulateMedia({ reducedMotion: 'reduce' });
+    await page.waitForTimeout(100);
+    layout.push(...(await page.evaluate(movingAnimations)));
+    await page.emulateMedia({ reducedMotion: null });
     for (const i of layout)
         if (i.type === 'contrast')
             i.theme = base;
@@ -62,7 +77,7 @@ for (const s of screens) {
     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 }))
+        for (const i of await page.evaluate(audit, auditOpts))
             if (i.type === 'contrast' || !seen.has(`${i.type} ${i.selector}`))
                 themed.push({ ...i, theme, message: `${theme} theme: ${i.message}` });
         if (shots)
@@ -73,6 +88,19 @@ for (const s of screens) {
     const typed = typeIssues(levels, await page.evaluate(collectText));
     if (shots)
         await shoot(s);
+    // A catalog: every control at rest, hovered, focused and pressed (states.ts), then its contrast in each theme.
+    const states = [];
+    if (s.kind === 'components') {
+        const own = await catalogStates(page, s.path, { crop: true });
+        states.push(...own.issues);
+        stateRows[s.path] = own.rows;
+        for (const theme of themes.filter((t) => t !== base)) {
+            await setTheme(theme);
+            states.push(...(await catalogStates(page, s.path, { crop: false, theme })).issues.filter((i) => i.type === 'state-contrast'));
+        }
+        if (themes.length > 1)
+            await setTheme(base);
+    }
     // The other languages, in the screen's own theme. Reported once per element and kind, in the first locale.
     const unknownSeen = new Set();
     for (const locale of locales) {
@@ -80,7 +108,7 @@ for (const s of screens) {
             .goto(`http://127.0.0.1:${server.port}/${s.path}?lang=${encodeURIComponent(locale)}`, { waitUntil: 'networkidle', timeout: 30_000 })
             .catch(() => { });
         await page.waitForTimeout(600);
-        for (const i of await page.evaluate(audit, { comfortable: config.comfortableTarget })) {
+        for (const i of await page.evaluate(audit, auditOpts)) {
             const key = `${i.type} ${i.selector}`;
             if (i.type === 'contrast' || seen.has(key))
                 continue;
@@ -115,14 +143,13 @@ for (const s of screens) {
         if (shots)
             await shoot(s, undefined, locale);
     }
-    // The edges of the widths this variant covers (config widths), in its own theme and language: what breaks
-    // only when the window is narrower or wider than the frame it was drawn in.
-    const range = s.kind === 'screen' ? widthRange(s.device) : undefined;
-    for (const width of range ? [...new Set(range)].filter((w) => w !== s.width) : []) {
+    // The edges of the widths this variant covers (config widths) and the breakpoints inside them, in its own theme
+    // and language: what breaks only when the window is narrower or wider than the frame it was drawn in.
+    for (const width of s.kind === 'screen' ? checkWidths(s.device).filter((w) => w !== s.width) : []) {
         await page.setViewportSize({ width, height: 844 });
         await page.goto(`http://127.0.0.1:${server.port}/${s.path}`, { waitUntil: 'networkidle', timeout: 30_000 }).catch(() => { });
         await page.waitForTimeout(600);
-        for (const i of await page.evaluate(audit, { comfortable: config.comfortableTarget })) {
+        for (const i of await page.evaluate(audit, auditOpts)) {
             const key = `${i.type} ${i.selector}`;
             if (i.type === 'contrast' || seen.has(key))
                 continue;
@@ -139,9 +166,13 @@ for (const s of screens) {
         ...typed,
         ...reuseIssues(s.path, found),
         ...colourIssues(s.path),
+        ...states,
     ];
 }
 await browser.close();
+// The states sheet: the catalogs checked now, and the rows of the others from their last check.
+if (Object.keys(stateRows).length)
+    writeStatesSheet(stateRows, listScreens().filter((s) => s.kind === 'components').map((s) => s.path));
 server.close();
 async function setTheme(theme) {
     await page.evaluate((t) => {

package/dist/cli.js

@@ -62,12 +62,31 @@ if (command === 'lint') {
     const { ROOT } = await import('./config.js');
     // The linter's main entry is also its command line (the package only exports for import).
     const file = fileURLToPath(import.meta.resolve('@google/design.md'));
+    let out;
     try {
-        execFileSync(process.execPath, [file, 'lint', join(ROOT, 'DESIGN.md'), ...rest], { stdio: 'inherit' });
+        out = execFileSync(process.execPath, [file, 'lint', join(ROOT, 'DESIGN.md'), ...rest], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'inherit'] });
+    }
+    catch (e) {
+        out = String(e.stdout ?? '');
+    }
+    // motion is stitch2's extension of the format (duration-* and ease-* tokens): the linter only notes that it
+    // doesn't know the key, so that note is left out.
+    let report;
+    try {
+        report = JSON.parse(out);
     }
     catch {
+        process.stdout.write(out);
         process.exit(1);
     }
+    const ours = (f) => f.path === 'motion' && f.rule === 'token-like-ignored';
+    const dropped = (report.findings ?? []).filter(ours);
+    report.findings = (report.findings ?? []).filter((f) => !ours(f));
+    if (report.summary && dropped.length)
+        report.summary.warnings = (report.summary.warnings ?? 0) - dropped.length;
+    console.log(JSON.stringify(report, null, 2));
+    if ((report.summary?.errors ?? 0) > 0)
+        process.exit(1);
 }
 else {
     // Sources run as .ts (Node strips the types); the published build runs as .js.

package/dist/config.d.ts

@@ -31,6 +31,12 @@ export interface LabConfig {
      * follow Google's window size classes: mobile 360–599 (compact), tablet 600–1023 (medium), desktop 1024–1920.
      */
     widths?: Record<string, [number, number]>;
+    /**
+     * The window widths where the screens' layouts change (their responsive rules, Tailwind's sm: md: lg: …), in px.
+     * check renders each variant at every breakpoint inside its range besides the two ends, and the canvas can show
+     * every screen at one of them. Defaults to Tailwind's: sm 640, md 768, lg 1024, xl 1280, 2xl 1536.
+     */
+    breakpoints?: Record<string, number>;
     /** 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). */
@@ -78,5 +84,12 @@ export declare const config: LabConfig;
 export declare const WIDTH_DEFAULTS: Record<string, [number, number]>;
 export declare const widthRanges: () => Record<string, [number, number]>;
 export declare const widthRange: (device: string) => [number, number] | undefined;
+export declare const BREAKPOINT_DEFAULTS: Record<string, number>;
+export declare const breakpoints: () => Record<string, number>;
+/**
+ * The widths check renders a variant at: both ends of its range and every breakpoint inside it, where a responsive
+ * rule starts (each one is the narrowest window of its layout, where things are most likely to break).
+ */
+export declare function checkWidths(device: string): number[];
 /** The design folder, with a trailing slash. */
 export declare const ROOT: string;

package/dist/config.js

@@ -38,5 +38,18 @@ export const config = {
 export const WIDTH_DEFAULTS = { mobile: [360, 599], tablet: [600, 1023], desktop: [1024, 1920] };
 export const widthRanges = () => ({ ...WIDTH_DEFAULTS, ...config.widths });
 export const widthRange = (device) => widthRanges()[device];
+export const BREAKPOINT_DEFAULTS = { sm: 640, md: 768, lg: 1024, xl: 1280, '2xl': 1536 };
+export const breakpoints = () => config.breakpoints ?? BREAKPOINT_DEFAULTS;
+/**
+ * The widths check renders a variant at: both ends of its range and every breakpoint inside it, where a responsive
+ * rule starts (each one is the narrowest window of its layout, where things are most likely to break).
+ */
+export function checkWidths(device) {
+    const range = widthRange(device);
+    if (!range)
+        return [];
+    const inside = Object.values(breakpoints()).filter((b) => b > range[0] && b < range[1]);
+    return [...new Set([range[0], ...inside, range[1]])].sort((a, b) => a - b);
+}
 /** The design folder, with a trailing slash. */
 export const ROOT = join(resolve(BASE, config.designDir), '/');

package/dist/design-md.d.ts

@@ -13,8 +13,12 @@ export interface Design {
     rounded: Record<string, string>;
     spacing: Record<string, string>;
     components: Record<string, Record<string, string>>;
+    /** duration-<name>: "150ms", ease-<name>: "cubic-bezier(0.2, 0, 0, 1)". */
+    motion: Record<string, string>;
 }
 export declare function readDesign(file?: string): Design;
+/** The durations DESIGN.md's motion names, in ms (for check: a transition of any other length is a warning). */
+export declare function motionDurations(design?: Design): number[];
 /**
  * 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.

package/dist/design-md.js

@@ -1,6 +1,7 @@
 /**
  * Reads design/DESIGN.md's YAML front matter (the DESIGN.md format: colors, typography, rounded, spacing,
- * components) and resolves {path.to.token} references.
+ * components) and resolves {path.to.token} references. stitch2 adds motion: duration-<name> and ease-<name>
+ * tokens (Google's format has no motion yet; stitch2 lint leaves the linter's note about the key out).
  */
 import { readFileSync } from 'node:fs';
 import { join } from 'node:path';
@@ -30,8 +31,16 @@ export function readDesign(file = join(ROOT, 'DESIGN.md')) {
         rounded: raw.rounded ?? {},
         spacing: raw.spacing ?? {},
         components: raw.components ?? {},
+        motion: Object.fromEntries(Object.entries(raw.motion ?? {}).map(([k, v]) => [k, String(v)])),
     };
 }
+/** The durations DESIGN.md's motion names, in ms (for check: a transition of any other length is a warning). */
+export function motionDurations(design = readDesign()) {
+    return Object.entries(design.motion)
+        .filter(([k]) => k.startsWith('duration-'))
+        .map(([, v]) => (v.trim().endsWith('ms') ? parseFloat(v) : parseFloat(v) * 1000))
+        .filter((n) => Number.isFinite(n));
+}
 /**
  * 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.

package/dist/exports.js

@@ -5,6 +5,8 @@
  *   tailwind4  the same, plus an @theme block (bg-<colour>, rounded-<name>, font-sans) and the type levels as
  *              @utility type-<level>, for a Tailwind v4 stylesheet to @import. Spacing stays out of @theme:
  *              names like lg or 2xl would also resize max-w-lg and friends; it is --<prefix>-spacing-<name>.
+ *              Motion: ease-<name> classes, duration-<name> utilities, and Tailwind's default transition (the
+ *              plain transition, transition-colors…) set to the first duration and ease-standard.
  *   dtcg       W3C Design Tokens JSON, for Style Dictionary and other platforms (iOS, Android)
  * "aliases" maps the app's own variable names to DESIGN.md colours ({ "background": "floor" } writes
  * --background: var(--<prefix>-floor) in each theme), so an existing theme (shadcn's, say) keeps its names.
@@ -44,9 +46,25 @@ function tailwind4(t, e) {
         ...Object.entries(t.design.rounded).map(([k, v]) => `  --radius-${k}: ${v};`),
         ...(sans ? [`  --font-sans: "${sans}", var(--${p()}-font-sans-fallback);`] : []),
         ...(mono ? [`  --font-mono: "${mono}", var(--${p()}-font-mono-fallback);`] : []),
+        ...motionTheme(t.design.motion),
     ];
     const type = Object.entries(t.type).map(([n, d]) => `@utility type-${n} {\n${d.map((x) => `  ${x};`).join('\n')}\n}`);
-    return [t.header, ...themeBlocks(t, e), `@theme inline {\n${theme.join('\n')}\n}`, ...type, ''].join('\n\n');
+    const durations = Object.keys(t.design.motion)
+        .filter((k) => k.startsWith('duration-'))
+        .map((k) => `@utility ${k} {\n  transition-duration: var(--${p()}-${k});\n  animation-duration: var(--${p()}-${k});\n}`);
+    return [t.header, ...themeBlocks(t, e), `@theme inline {\n${theme.join('\n')}\n}`, ...type, ...durations, ''].join('\n\n');
+}
+/** @theme entries for motion: --ease-<name> (Tailwind's ease-* classes) and the default transition. */
+function motionTheme(motion) {
+    const keys = Object.keys(motion);
+    const eases = keys.filter((k) => k.startsWith('ease-'));
+    const first = keys.includes('duration-short') ? 'duration-short' : keys.find((k) => k.startsWith('duration-'));
+    const standard = eases.find((k) => k === 'ease-standard') ?? eases[0];
+    return [
+        ...eases.map((k) => `  --${k}: var(--${p()}-${k});`),
+        ...(first ? [`  --default-transition-duration: var(--${p()}-${first});`] : []),
+        ...(standard ? [`  --default-transition-timing-function: var(--${p()}-${standard});`] : []),
+    ];
 }
 function dtcg(t) {
     const group = (type, o) => Object.fromEntries(Object.entries(o).map(([k, v]) => [k, { $type: type, $value: v }]));
@@ -69,6 +87,14 @@ function dtcg(t) {
         'color-light': group('color', t.light),
         radius: group('dimension', t.design.rounded),
         spacing: group('dimension', t.design.spacing),
+        ...(Object.keys(t.design.motion).length
+            ? {
+                duration: group('duration', Object.fromEntries(Object.entries(t.design.motion).filter(([k]) => k.startsWith('duration-')).map(([k, v]) => [k.slice(9), v]))),
+                easing: Object.fromEntries(Object.entries(t.design.motion)
+                    .filter(([k]) => k.startsWith('ease-'))
+                    .map(([k, v]) => [k.slice(5), { $type: 'cubicBezier', $value: (v.match(/-?[\d.]+/g) ?? []).map(Number) }])),
+            }
+            : {}),
         typography,
     }, null, 2)}\n`;
 }

package/dist/serve.d.ts

@@ -11,6 +11,7 @@ export interface ReportState {
 export declare function reportStates(): {
     consistency: ReportState | null;
     compare: ReportState | null;
+    states: ReportState | null;
 };
 export declare function startServer(port: number): Promise<{
     port: number;

package/dist/serve.js

@@ -9,7 +9,7 @@ import { existsSync, readdirSync, readFileSync, statSync, watch } from 'node:fs'
 import { createServer } from 'node:http';
 import { dirname, extname, join, normalize } from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { CONFIG_FILE, config, widthRanges } from './config.js';
+import { breakpoints, CONFIG_FILE, checkWidths, config, widthRanges } from './config.js';
 import { designThemes } from './design-md.js';
 import { allLocales, localeScript, sourceLocale } from './i18n.js';
 import { designPage } from './design-page.js';
@@ -55,6 +55,8 @@ export function reportStates() {
     return {
         consistency: state('consistency/index.html', [...screens.filter((s) => s.status !== 'archived'), ...components]),
         compare: state('compare/index.html', screens.filter((s) => s.kind === 'screen' && s.status === 'approved')),
+        // The states sheet is made when check runs on a catalog: it covers the catalogs and the components.
+        states: state('states/index.html', [...screens.filter((s) => s.kind === 'components'), ...components]),
     };
 }
 const CANVAS = fileURLToPath(new URL('./canvas.html', import.meta.url));
@@ -118,6 +120,10 @@ export function startServer(port) {
             res.writeHead(200, { 'content-type': TYPES['.html'], 'cache-control': 'no-store' });
             return res.end('<body style="background:#0f0f11;color:#a1a1aa;font:15px system-ui;padding:32px">No consistency report yet: run <code>stitch2 consistency</code>.</body>');
         }
+        if (url.pathname === '/states/index.html' && !existsSync(join(ROOT, 'states/index.html'))) {
+            res.writeHead(200, { 'content-type': TYPES['.html'], 'cache-control': 'no-store' });
+            return res.end('<body style="background:#0f0f11;color:#a1a1aa;font:15px system-ui;padding:32px">No states sheet yet: run <code>stitch2 check</code> on the component catalog.</body>');
+        }
         if (url.pathname === '/api/screens/meta' && req.method === 'POST') {
             let body = '';
             req.on('data', (c) => {
@@ -149,7 +155,7 @@ export function startServer(port) {
             return;
         }
         if (url.pathname === '/api/config')
-            return json({ ...config, themes: designThemes(), locales: allLocales(), sourceLocale: sourceLocale(), widths: widthRanges() });
+            return json({ ...config, themes: designThemes(), locales: allLocales(), sourceLocale: sourceLocale(), widths: widthRanges(), breakpoints: breakpoints(), checkWidths: Object.fromEntries(Object.keys(widthRanges()).map((d) => [d, checkWidths(d)])) });
         if (url.pathname === '/api/screens')
             return json(listScreens());
         if (url.pathname === '/api/reports')

package/dist/shots.js

@@ -15,7 +15,7 @@ import { ROOT } from './screens.js';
 const MAX_HEIGHT = 20000;
 const DIR = join(tmpdir(), 'stitch2-shots');
 /** Folders under the design directory that hold outputs, not inputs: they never change a picture. */
-const OUTPUTS = new Set(['renders', 'consistency', 'compare', 'node_modules', '.git']);
+const OUTPUTS = new Set(['renders', 'consistency', 'compare', 'states', 'node_modules', '.git']);
 const REPORTS = new Set(['checks.json', 'compare.json', 'type-audit.json']);
 let shared;
 /** The newest of the files screens share: anything under the design directory that isn't a screen or an output. */

package/dist/states.d.ts

@@ -0,0 +1,28 @@
+import type { Page } from '@playwright/test';
+import type { Issue } from './typecheck.ts';
+export declare const STATES: readonly ['rest', 'hover', 'focus', 'pressed'];
+type State = (typeof STATES)[number];
+export interface StateRow {
+    name: string;
+    label: string;
+    selector: string;
+    /** The crop's width in CSS px (the picture is twice that on a 2x render). */
+    width?: number;
+    crops: Partial<Record<State, string>>;
+    notes: string[];
+}
+/**
+ * The states of every control in the catalog open in the page, in the current theme. With crop, saves a picture
+ * of each state under <design>/states/ and returns the rows of the sheet.
+ */
+export declare function catalogStates(page: Page, path: string, opts: {
+    crop: boolean;
+    theme?: string;
+}): Promise<{
+    issues: Issue[];
+    rows: StateRow[];
+}>;
+/** Writes the states sheet, keeping the rows of catalogs this run didn't check (states/states.json). */
+export declare function writeStatesSheet(fresh: Record<string, StateRow[]>, catalogs: string[]): void;
+export declare const statesSheetExists: () => boolean;
+export {};

package/dist/states.js

@@ -0,0 +1,203 @@
+/**
+ * Interactive states of the component catalog: every control in a catalog (a button, a chip, a row that opens
+ * something) drawn at rest, hovered, focused and pressed, forced through the DevTools protocol so the components
+ * need nothing extra. check runs it on each catalog: a control whose hover or press changes nothing gives no
+ * feedback, and text must keep its contrast in every state. The crops make <design>/states/index.html, the
+ * states sheet the canvas opens from its sidebar.
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { config } from './config.js';
+import { filterSnippet } from './report-filter.js';
+import { ROOT } from './screens.js';
+export const STATES = ['rest', 'hover', 'focus', 'pressed'];
+const FORCED = { rest: [], hover: ['hover'], focus: ['focus', 'focus-visible'], pressed: ['hover', 'active'] };
+/** Controls drawn per catalog, so a long catalog stays quick to check. */
+const MAX_CONTROLS = 80;
+/** Runs in the page: one control of each kind and look per component, marked data-s2-state. */
+function findControls(opts) {
+    const SEL = 'button, a[href], input:not([type="hidden"]), select, textarea, summary, [role="button"], [role="switch"], [role="tab"], [role="checkbox"], [role="radio"], [role="option"], [tabindex]:not([tabindex="-1"])';
+    const path = (el) => {
+        const parts = [];
+        for (let e = el; e && e !== document.body && parts.length < 6; e = e.parentElement) {
+            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 seen = new Set();
+    const out = [];
+    for (const root of document.querySelectorAll('[' + opts.attr + ']')) {
+        const name = root.getAttribute(opts.attr) || '';
+        const controls = root.matches(SEL) ? [root] : [...root.querySelectorAll(SEL)];
+        for (const c of controls) {
+            // The innermost component owns a control: a button inside a card belongs to the button.
+            if (c.closest('[' + opts.attr + ']') !== root && !c.matches('[' + opts.attr + ']'))
+                continue;
+            const h = c;
+            const r = h.getBoundingClientRect();
+            if (!r.width || !r.height || h.disabled || h.getAttribute('aria-disabled') === 'true')
+                continue;
+            const key = name + '|' + h.tagName + '|' + h.className + '|' + (h.getAttribute('aria-pressed') ?? '') + (h.getAttribute('aria-selected') ?? '');
+            if (seen.has(key) || out.length >= opts.max)
+                continue;
+            seen.add(key);
+            const label = (h.getAttribute('aria-label') || h.textContent || h.getAttribute('placeholder') || '').trim().replace(/\s+/g, ' ').slice(0, 40);
+            h.setAttribute('data-s2-state', String(out.length));
+            const field = h.matches('input:not([type="checkbox"]):not([type="radio"]):not([type="button"]):not([type="submit"]), textarea, select, [contenteditable="true"]');
+            const chosen = ['aria-pressed', 'aria-selected', 'aria-checked'].some((a) => h.getAttribute(a) === 'true') || (h.hasAttribute('aria-current') && h.getAttribute('aria-current') !== 'false');
+            out.push({ i: out.length, name, label, selector: path(h), field, chosen });
+        }
+    }
+    return out;
+}
+/** Runs in the page: how a control looks (itself and what it holds), and its text's contrast on its background. */
+function lookOf(i) {
+    const el = document.querySelector('[data-s2-state="' + i + '"]');
+    const props = (e) => {
+        const c = getComputedStyle(e);
+        // translate, scale and rotate are their own properties in Tailwind v4 (active:translate-y-px), apart from transform.
+        return [c.backgroundColor, c.color, c.borderColor, c.outlineStyle === 'none' ? '' : c.outlineColor + c.outlineWidth, c.boxShadow, c.transform, c.translate, c.scale, c.rotate, c.opacity, c.textDecorationLine, c.fill, c.stroke, c.filter].join('|');
+    };
+    const look = [el, ...el.querySelectorAll('*')].slice(0, 12).map(props).join('#');
+    const rgb = (s) => (s.match(/[\d.]+/g) ?? []).map(Number);
+    const lum = ([r, g, b]) => {
+        const f = (v) => ((v /= 255) <= 0.03928 ? v / 12.92 : ((v + 0.055) / 1.055) ** 2.4);
+        return 0.2126 * f(r) + 0.7152 * f(g) + 0.0722 * f(b);
+    };
+    let bg = [255, 255, 255];
+    for (let e = el; e; e = e.parentElement) {
+        const c = rgb(getComputedStyle(e).backgroundColor);
+        if (c.length >= 3 && (c[3] ?? 1) >= 0.95) {
+            bg = c;
+            break;
+        }
+    }
+    let worst = 21;
+    for (const t of [el, ...el.querySelectorAll('*')]) {
+        if (![...t.childNodes].some((n) => n.nodeType === 3 && n.textContent.trim()))
+            continue;
+        const cs = getComputedStyle(t);
+        const fg = rgb(cs.color);
+        if ((fg[3] ?? 1) < 0.5 || Number(cs.opacity) < 0.5)
+            continue;
+        const [a, b] = [lum(fg), lum(bg)];
+        const ratio = (Math.max(a, b) + 0.05) / (Math.min(a, b) + 0.05);
+        const large = parseFloat(cs.fontSize) >= 24 || (parseFloat(cs.fontSize) >= 18.66 && Number(cs.fontWeight) >= 700);
+        worst = Math.min(worst, ratio / (large ? 3 : 4.5));
+    }
+    return { look, contrast: worst };
+}
+/**
+ * The states of every control in the catalog open in the page, in the current theme. With crop, saves a picture
+ * of each state under <design>/states/ and returns the rows of the sheet.
+ */
+export async function catalogStates(page, path, opts) {
+    const controls = await page.evaluate(findControls, { attr: 'data-' + config.prefix, max: MAX_CONTROLS });
+    const still = await page.addStyleTag({ content: '*, *::before, *::after { transition: none !important; animation: none !important; caret-color: transparent !important; }' });
+    const cdp = await page.context().newCDPSession(page);
+    await cdp.send('DOM.enable');
+    await cdp.send('CSS.enable');
+    const { root } = await cdp.send('DOM.getDocument', { depth: 0 });
+    const issues = [];
+    const rows = [];
+    const tag = opts.theme ? opts.theme + ' theme: ' : '';
+    const dir = join(ROOT, 'states');
+    for (const c of controls) {
+        const { nodeId } = await cdp.send('DOM.querySelector', { nodeId: root.nodeId, selector: '[data-s2-state="' + c.i + '"]' });
+        if (!nodeId)
+            continue;
+        const looks = {};
+        const row = { name: c.name, label: c.label, selector: c.selector, crops: {}, notes: [] };
+        const el = page.locator('[data-s2-state="' + c.i + '"]');
+        await el.scrollIntoViewIfNeeded({ timeout: 2000 }).catch(() => { });
+        for (const state of STATES) {
+            await cdp.send('CSS.forcePseudoState', { nodeId, forcedPseudoClasses: FORCED[state] });
+            await page.evaluate(() => new Promise((r) => requestAnimationFrame(() => requestAnimationFrame(r))));
+            looks[state] = await page.evaluate(lookOf, c.i);
+            if (opts.crop) {
+                const box = await el.boundingBox();
+                if (box && box.width >= 1 && box.height >= 1) {
+                    const pad = 8;
+                    const file = path.replace(/[^a-z0-9]+/gi, '_') + '/' + c.i + '-' + state + '.png';
+                    mkdirSync(join(dir, file, '..'), { recursive: true });
+                    await page.screenshot({ path: join(dir, file), clip: { x: Math.max(0, box.x - pad), y: Math.max(0, box.y - pad), width: box.width + pad * 2, height: box.height + pad * 2 } });
+                    row.crops[state] = file;
+                    row.width = Math.round(box.width + pad * 2);
+                }
+            }
+        }
+        await cdp.send('CSS.forcePseudoState', { nodeId, forcedPseudoClasses: [] });
+        const who = c.name + (c.label ? ' “' + c.label + '”' : '');
+        const add = (type, message) => {
+            issues.push({ severity: 'warning', type, selector: c.selector, text: c.label, message: tag + message, ...(opts.theme ? { theme: opts.theme } : {}) });
+            row.notes.push(tag + message);
+        };
+        const noHover = looks.hover?.look === looks.rest?.look;
+        // Pressed is forced on top of hover: a press that adds nothing to hover shows nothing on a touch screen.
+        const noPress = looks.pressed?.look === looks.hover?.look;
+        if (!c.field && !c.chosen) {
+            if (noHover && noPress)
+                add('state-feedback', who + ': neither hovering nor pressing changes it, so a pointer or a tap gives no feedback (DESIGN.md, hover and pressed)');
+            else if (noHover)
+                add('state-hover', who + ': hovering changes nothing, so a pointer gives no feedback (DESIGN.md, hover)');
+            else if (noPress)
+                add('state-pressed', who + ': pressing adds nothing to hover, so a tap gives no feedback (DESIGN.md, pressed)');
+        }
+        for (const state of ['hover', 'focus', 'pressed'])
+            if ((looks[state]?.contrast ?? 21) < 1 && (looks.rest?.contrast ?? 21) >= 1) {
+                add('state-contrast', who + ': low text contrast when ' + (state === 'focus' ? 'focused' : state === 'hover' ? 'hovered' : 'pressed'));
+                break;
+            }
+        rows.push(row);
+    }
+    await cdp.detach();
+    await still.evaluate((n) => n.remove());
+    await page.evaluate(() => document.querySelectorAll('[data-s2-state]').forEach((n) => n.removeAttribute('data-s2-state')));
+    return { issues, rows };
+}
+const esc = (s) => String(s ?? '').replaceAll('&', '&amp;').replaceAll('<', '&lt;').replaceAll('>', '&gt;').replaceAll('"', '&quot;');
+/** Writes the states sheet, keeping the rows of catalogs this run didn't check (states/states.json). */
+export function writeStatesSheet(fresh, catalogs) {
+    const dir = join(ROOT, 'states');
+    mkdirSync(dir, { recursive: true });
+    const store = join(dir, 'states.json');
+    let all = {};
+    try {
+        all = JSON.parse(readFileSync(store, 'utf8'));
+    }
+    catch { }
+    all = Object.fromEntries(Object.entries({ ...all, ...fresh }).filter(([p]) => catalogs.includes(p)));
+    writeFileSync(store, JSON.stringify(all, null, 1));
+    const sections = Object.entries(all)
+        .map(([path, rows]) => {
+        const byName = new Map();
+        for (const r of rows)
+            byName.set(r.name, [...(byName.get(r.name) ?? []), r]);
+        const groups = [...byName.entries()]
+            .map(([name, list]) => '<h3>' + esc(name) + '</h3>' +
+            list
+                .map((r) => '<div class="row"><div class="who"><b>' + esc(r.label || name) + '</b><code>' + esc(r.selector) + '</code>' +
+                (r.notes.length ? r.notes.map((n) => '<p class="bad">' + esc(n) + '</p>').join('') : '<span class="ok">every state differs</span>') +
+                '</div><div class="imgs">' +
+                STATES.map((st) => '<figure>' + (r.crops[st] ? '<img src="' + esc(r.crops[st]) + '" alt=""' + (r.width ? ' width="' + Math.min(r.width, 360) + '"' : '') + ' />' : '<span class="none">—</span>') + '<figcaption>' + st + '</figcaption></figure>').join('') +
+                '</div></div>')
+                .join(''))
+            .join('');
+        return '<section data-path="' + esc(path) + '"><h2>' + esc(path) + '</h2>' + groups + '</section>';
+    })
+        .join('');
+    writeFileSync(join(dir, 'index.html'), '<!doctype html><html lang="en"><head><meta charset="utf-8" /><title>States</title><style>' +
+        'body { background: #0f0f11; color: #f4f4f5; font: 14px/1.5 system-ui, sans-serif; margin: 0; } main { margin: 0 auto; max-width: 1200px; padding: 32px; }' +
+        'h1 { font-size: 26px; margin: 0 0 4px; } h2 { font: 13px ui-monospace, monospace; color: #a1a1aa; margin: 40px 0 0; } h3 { font-size: 17px; margin: 28px 0 8px; } code { color: #71717a; font: 12px ui-monospace, monospace; }' +
+        '.row { border-top: 1px solid #2e2e33; display: grid; gap: 20px; grid-template-columns: 280px 1fr; padding: 12px 0; } .who { display: grid; gap: 4px; align-content: start; min-width: 0; overflow-wrap: anywhere; }' +
+        '.imgs { display: flex; flex-wrap: wrap; gap: 16px; align-items: flex-end; } figure { margin: 0; } figcaption { color: #71717a; font-size: 12px; margin-top: 4px; } img { background: #000; border: 1px solid #2e2e33; border-radius: 6px; display: block; max-width: 360px; }' +
+        '.ok { color: #3fb27f; } .bad { color: #e5b54a; margin: 0; font-size: 13px; } .none { color: #71717a; }' +
+        '</style></head><body><main><h1>States</h1><code>' + new Date().toISOString() + ' · every control in the component catalog at rest, hovered, focused and pressed</code><p id="stitch2-filter" hidden></p>' +
+        sections +
+        '</main>' + filterSnippet + '</body></html>\n');
+}
+export const statesSheetExists = () => existsSync(join(ROOT, 'states/index.html'));

package/dist/tokens.js

@@ -92,6 +92,10 @@ writeFileSync(join(ROOT, 'tokens.css'), [
     vars("[data-theme='light']", light, md.light),
     ":root { color-scheme: dark; } [data-theme='light'] { color-scheme: light; }",
     `:root { --${lab.prefix}-font-sans-fallback: ${FALLBACK}; --${lab.prefix}-font-mono-fallback: ui-monospace, monospace; }`,
+    // Motion (duration-* and ease-*), when DESIGN.md names it.
+    ...(Object.keys(design.motion).length
+        ? [`:root { ${Object.entries(design.motion).map(([k, v]) => `--${lab.prefix}-${k}: ${v};`).join(' ')} }`]
+        : []),
     '/* Typography levels: one class sets family, size, line height, weight, tracking and figures. */',
     typeCss.join('\n'),
     '',
@@ -122,6 +126,7 @@ const exported = writeExports({
     root: {
         [`${lab.prefix}-font-sans-fallback`]: FALLBACK,
         [`${lab.prefix}-font-mono-fallback`]: 'ui-monospace, monospace',
+        ...Object.fromEntries(Object.entries(design.motion).map(([k, v]) => [`${lab.prefix}-${k}`, v])),
     },
     header: `/* Generated by stitch2 tokens from DESIGN.md. Do not edit: change DESIGN.md and run stitch2 tokens. */`,
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "stitch2",
-  "version": "0.18.0",
+  "version": "0.19.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

@@ -27,6 +27,7 @@ References, read before the first screen:
 - [screens.md](references/screens.md): screen names, versions and their variants (mobile, desktop), the widths
   each variant covers, statuses, the user's approval and notes.
 - [google.md](references/google.md): Google's guidance (Material, Android, web.dev) as rules with numbers.
+- [motion.md](references/motion.md): motion tokens, what may move and how, reduced motion.
 - [guides.md](references/guides.md): the public sources behind the rules.
 
 ## Workflow
@@ -38,6 +39,9 @@ References, read before the first screen:
 2. **Inventory.** List every element the brief names, in order, with its real data. That list is the screen:
    add nothing (status bars, step labels, tips, helper text, extra buttons), drop nothing. Next to each element
    write the catalog component that shows it; adapt or extend components rather than inventing markup.
+   Then list the page's **states**. A page that shows data gets an empty screen and a loading screen, designed
+   with its main screen in the same version; a page that loads or saves data that can fail also gets an error
+   state. Build them with the main screen; they are part of the page (screens.md, Empty, loading and error).
 3. **Hierarchy before markup.** Name the one thing the user came for, the single primary action (the only
    accent-filled element in its region), and what is secondary. Give every text element a type level and a
    colour before writing markup.
@@ -63,10 +67,15 @@ References, read before the first screen:
    **stitch2-i18n** skill says.
    An issue tagged with a width ("at 1024px: …") breaks at an edge of the windows the variant covers: fix it with a
    responsive rule in the screen, or a new variant when the layout's structure has to change (screens.md, Widths).
+   Widths include the breakpoints inside the range; `narrow-layout` is a phone column left in a wide window.
+   Motion warnings: `motion-token` (a transition length DESIGN.md doesn't name) and `reduced-motion` (something
+   still moves when the person asked for less); see motion.md. On the catalog, `state-*` warnings come from the
+   States sheet (components.md, States).
 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
-   changed, how you answered their notes, and any rubric item you could not satisfy. The user approves; only then
+   changed, how you answered their notes, and any rubric item you could not satisfy. The page's empty and loading
+   screens go to review with it; for a page without them (a form, a static page), say why. The user approves; only then
    does it go into the app (the approved version is the one current version: see screens.md).
 
 ## Commands

package/skills/stitch2/references/components.md

@@ -24,6 +24,26 @@ Go down only when the step above cannot work:
 
 Never restyle a component on one screen, copy its markup by hand, or build a near-twin ("a chip, but 30 px").
 
+## States
+
+Every interactive component has its states, defined once in the component and described in DESIGN.md:
+
+| State | What changes (DESIGN.md says how) |
+|---|---|
+| Hover (pointer only) | the surface lightens or the text brightens one step |
+| Pressed | darkens one step and moves 1 px (or scales to 0.95); on a touch screen this is the only feedback |
+| Focus (keyboard) | a ring, never removed without a replacement |
+| Selected / current | shown by the accent or a raised surface; hover and press may stay as they are |
+| Disabled | faint, no hover or press change, the reason nearby |
+
+The catalog shows each component in each of its **data states** (selected, done, active, disabled, error, with
+and without an icon). Hover, focus and pressed are not drawn by hand: `stitch2 check` on the catalog forces them on
+every control and writes the **States** sheet (canvas sidebar), each control at rest, hovered, focused and
+pressed side by side. It reports a control that gives no feedback (**state-feedback**, **state-hover**,
+**state-pressed**: pressing adds nothing to hover, so a tap shows nothing) and text that loses contrast in a state
+(**state-contrast**). Fix them in the component, once. Selected and current controls and text fields are exempt
+from the feedback checks.
+
 ## Components from the app
 
 When the project builds its elements from the app's own components (`stitch2/elements›, bundled with
@@ -51,6 +71,7 @@ series) is added to DESIGN.md first, with a line in the prose saying where it is
   screen. `stitch2 consistency` shows the same as cropped images; see the stitch2-consistency skill.
 - **color**: a hex, `rgb()` or `hsl()` value in a lab screen's markup, or (reported on the catalog) in the
   component scripts it loads, with the file and line.
+- **state-***: from the catalog's States sheet, above.
 
 ## Generated drafts
 

package/skills/stitch2/references/motion.md

@@ -0,0 +1,48 @@
+# Motion: how screens move
+
+Motion confirms what just happened (a set ticked, a sheet opened) and shows where things come from. It is part
+of the design system, like colour: durations and easings are **motion tokens** in DESIGN.md, components use them,
+and screens get motion from their components. A static screen cannot show movement, so the rules live in
+DESIGN.md's prose and in the components, and the checks hold them.
+
+## Tokens
+
+stitch2 extends DESIGN.md's front matter with a `motion:` section (Google's format has none yet; `stitch2 lint`
+leaves out the linter's note about the key). `stitch2 init` writes Material's values:
+
+```yaml
+motion:
+  duration-short: 150ms    # a control's own change: press, toggle, tick
+  duration-medium: 250ms   # something entering or opening: a sheet, a menu, a toast
+  duration-long: 400ms     # a whole screen changing
+  ease-standard: cubic-bezier(0.2, 0, 0, 1)      # movement inside the screen
+  ease-enter: cubic-bezier(0.05, 0.7, 0.1, 1)    # what arrives (decelerates)
+  ease-exit: cubic-bezier(0.3, 0, 0.8, 0.15)     # what leaves (accelerates)
+```
+
+`stitch2 tokens` makes them `--<prefix>-duration-short` and `--<prefix>-ease-standard` variables, `ease-standard` and
+`duration-short` classes in the Tailwind 4 export, and sets Tailwind's plain `transition` (and `transition-colors`,
+…) to duration-short with ease-standard, so a component that only says `transition` already follows them.
+
+## Rules
+
+- **Animate transform and opacity.** Moving layout properties (width, top, margin) janks and reflows.
+- **One duration per kind of change** from the tokens; never a typed value (`duration-[180ms]`)
+  **(check: motion-token)**. Bigger or farther changes take the longer token; nothing over long except a
+  full-screen change.
+- **Enter with ease-enter, leave with ease-exit**, and leave faster than you entered (medium in, short out).
+- **Nothing moves on its own**, except a skeleton's pulse while content loads. No looping decoration, no
+  staggered list entrances in the app (speed matters more), no parallax.
+- **Reduced motion:** when the person asks for less motion, nothing moves: animations that move or scale are
+  wrapped in `@media (prefers-reduced-motion: no-preference)` (Tailwind `motion-safe:`), and a fade or an instant
+  change replaces them **(check: reduced-motion)**. Fades and colour changes may stay.
+- **Feedback is instant:** a press shows within one frame (the pressed state), and the motion that follows never
+  delays the next tap.
+- **Describe screen-level motion in DESIGN.md's Motion & Interaction section** (how a sheet opens, what a tick
+  does), in values: "slides up 250ms ease-enter", not "smoothly".
+
+## On the canvas
+
+Frames are pictures until you double-click one: then it is live, and its hover, press and transitions play.
+The **States** sheet shows every control of the catalog at rest, hovered, focused and pressed (see
+[components.md](components.md)).

package/skills/stitch2/references/principles.md

@@ -56,7 +56,8 @@ short labels never wrap **(check)**.
   axis or month labels, a legend for a colour scale, captions under figures. They add no new facts.
 - Icons that stand for different things look different; one generic glyph repeated down a list says nothing.
 - Charts: one series in the accent, thin lines, few gridlines; label a single line directly instead of a legend.
-- Empty and loading states are designed too: one sentence and one action; skeletons the size of the content.
+- Empty and loading states are designed with every page that shows data: one sentence and one action; skeletons
+  the size of the content (screens.md, Empty, loading and error).
 
 ## Touch and mobile
 
@@ -86,3 +87,5 @@ Score each pass or fail from the render; done when all pass or the failures are
 8. **Data realism:** names, numbers and dates look like a real person's data.
 9. **Consistency:** built from the catalog components; no `reuse` or `consistency` warnings.
 10. **Checks:** `stitch2 check --strict` reports no errors.
+11. **States:** the page has its empty and loading screens (and error when data can fail), built from the same
+    components and layout as the main screen; or the hand-over says why it needs none.

package/skills/stitch2/references/screens.md

@@ -30,6 +30,32 @@ together; `stitch2 screens <page>` lists them. A screen without `<p>-page` is a
   that page, not a new page.
 - Copy `<p>-page` along with the other tags into each new version; the latest version that has it decides the page.
 
+## Empty, loading and error
+
+Every page that shows data has these states, and the app shows them on most first visits: a new user sees the
+empty screen before any other, and every user sees the loading one. Design them with the page's main screen,
+not after it.
+
+- **Which pages:** any page that lists, counts or charts the user's data, or loads it from a server. A form, a
+  dialog, a static page (sign-in, a landing page) needs none; say so in the hand-over.
+- **Names:** `<page>-empty` and `<page>-loading` (`history-empty`, `history-loading`), `<page>-error` when it
+  has one, with the page's `<p>-page`. Same version number and same variants (mobile, desktop) as the main
+  screen. A page whose main screen is a new version gets new versions of its states when they change.
+- **Empty:** the page's header and navigation stay where they are. In place of the content: what this place is
+  for in one sentence, and the one action that fills it ("Create your first routine"). Use the page's own
+  components where they help (a suggested program as a list row), not a large illustration. An empty search or
+  filter result is a different empty: it says nothing matched and how to widen it (clear the filter), and keeps
+  the search field and filters.
+- **Loading:** the same layout as the main screen, with skeletons in place of the data: blocks the size and
+  shape of the rows, cards and numbers that will arrive (typography.md, Text in each state). The header,
+  navigation and buttons that need no data stay real and usable. No spinner in the middle of the page and no
+  "Loading…" text; a spinner belongs only inside a button or a row that is saving. Build skeletons from a
+  catalog component, so every page loads the same way.
+- **Error:** the page's frame stays; where the data would be, one sentence on what failed and a Retry action.
+  Data already shown stays on screen; a failed save says so next to what failed and keeps the user's input.
+- **Partial states** follow the same rules inside a section: an empty list in a page that has other data shows
+  one line and an action in that section only.
+
 ## New version or edit?
 
 - **New version** for every new attempt: a new direction, a regeneration, an export from a generator, a
@@ -105,6 +131,18 @@ Widths are a dimension like themes and languages, not more files: `stitch2 check
 both ends of its range and reports what breaks there ("at 1024px: …"), and the canvas shows every frame at its
 narrowest or widest (the width dropdown, W).
 
+Inside a range the layout changes at the project's **breakpoints** (`breakpoints` in the config, Tailwind's by
+default: sm 640, md 768, lg 1024, xl 1280, 2xl 1536). Each one starts a layout at its narrowest, where it is most
+likely to break, so check also renders every variant at each breakpoint inside its range (gymgym's mobile variant
+at 360, 640, 768 and 1023). On the canvas, "At 768 px (md)" shows every screen at that window; a variant that
+doesn't cover it is drawn at its nearest edge and faded, because the app shows another variant there.
+
+- Design for the whole range, not only the frame: a phone layout stretched to 1023 px with a 390 px column in the
+  middle of the window is a defect at that width. Let it use the room (two columns of cards, a wider measure
+  capped by the type rules) or give the range to a new variant.
+- Use the breakpoints the config names and no others (no `min-[700px]:`), so check covers every layout the
+  screen has.
+
 - A screen that breaks at an edge gets a **responsive rule inside the same variant**: a two-column grid that drops
   to one, three cards across that become two, a side column that moves under the main one. Use the project's
   breakpoints (Tailwind's `md:`, `lg:`, `xl:`), so the screen keeps one layout that adapts.

package/skills/stitch2-app-sync/SKILL.md

@@ -25,6 +25,11 @@ a component rebuilt by hand. The checks can only judge what the canvas draws, so
    single current version and the app matches it.
 4. **App**: the app picks the component up; wire it, then run `stitch2 compare <screen>`.
 
+A page in the app is its main screen and its states: implement its approved empty, loading and error screens with
+it. The app's loader is the loading screen's skeleton, shown until the data arrives, never a blank page or a lone
+spinner; data appearing all at once with no loading state is a bug. A page whose states were never designed goes
+back to the canvas for them first.
+
 Fixing a bug found in the app follows the same path: reproduce it on the canvas (a screen or catalog state that
 shows it), fix the component, check, then the app. If the canvas cannot show the bug, the canvas is missing a
 state: add it.
@@ -69,4 +74,3 @@ Read the findings as:
 2. `stitch2 check --strict` passes on the screens you touched (archived screens excepted).
 3. `stitch2 compare` has no errors for the screens you touched; warnings are explained (a kept feature) or fixed.
 4. The user has seen the canvas versions of anything that changed how a component looks.
-

package/skills/stitch2-design-md/SKILL.md

@@ -35,13 +35,18 @@ The generated prose is correct but generic. Make it the product's:
    surfaces and the primary with the user.
 3. **Typography**: keep the levels; adjust sizes only together with the user and only on the scale.
 4. **Components**: name the product's real components (its tab bar items, its core list row) and their states.
-5. **Content & voice** and **Do's and Don'ts**: add the product's data style, naming and banned patterns.
-6. Keep every rule checkable: values, not adjectives.
+   Each interactive one gets hover, pressed, focus, selected and disabled in the prose, in values ("darkens to
+   primary-pressed and moves 1px"); the States sheet then shows whether the components do it.
+5. **Motion**: keep the `motion:` tokens (duration-short, -medium, -long; ease-standard, -enter, -exit) and say in
+   Motion & Interaction what moves, with which token. See the stitch2 skill's motion.md.
+6. **Content & voice** and **Do's and Don'ts**: add the product's data style, naming and banned patterns.
+7. Keep every rule checkable: values, not adjectives.
 
 ## 3. Validate and show
 
 1. `stitch2 lint`: 0 errors. Warnings about disabled text contrast (WCAG exempts it), semi-transparent washes
    (the linter cannot measure them) and colours no component references are expected.
+   `motion:` is stitch2's extension of the format; the linter doesn't know it, and stitch2 lint leaves that note out.
 2. `stitch2 tokens`, then open the canvas: **DESIGN.md** in the sidebar draws the swatches, live type levels,
    radii and component tokens. Walk the user through it; change and repeat until they agree.
 3. Then build the component catalog and the first screens with the stitch2 skill, and run stitch2-consistency.