stitch2 0.22.11 → 0.23.0

package/README.md

@@ -42,6 +42,8 @@ file that already exists. From there the agent spends its effort on the design.
   A width switch (`W`) shows every screen at the narrowest or widest window its layout covers.
   With languages configured, a Language switch (`L`) shows every screen in one of them, and the Languages page
   shows a screen side by side in each.
+  With app states configured (`modes`: signed in or out, a plan, a role), a dropdown for each (`M` cycles the first)
+  shows every screen in one of them, live pages and pictures alike, or as drawn.
   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.

package/config.schema.json

@@ -77,6 +77,31 @@
       "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."
     },
+    "modes": {
+      "type": "array",
+      "description": "App states every screen can be shown in, picked from the canvas sidebar: signed in or out, a plan, a role. The pick is an attribute on each screen's <html>, so the screens' own CSS and scripts answer to it. The dropdown also offers the screens as drawn, which leaves each one as its file has it.",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["name", "values"],
+        "properties": {
+          "name": { "type": "string", "pattern": "^[a-z][a-z0-9-]*$", "description": "The id: lowercase letters, digits and hyphens. The canvas remembers the pick under it." },
+          "label": { "type": "string", "description": "Shown before each value in the dropdown. Defaults to the name, capitalized." },
+          "attribute": { "type": "string", "pattern": "^[a-z][a-z0-9-]*$", "description": "The attribute on the screen's <html> that carries the value. Defaults to data-<name>." },
+          "values": {
+            "type": "array",
+            "minItems": 1,
+            "description": "What the canvas can show every screen as: a value, or a value with its label.",
+            "items": {
+              "oneOf": [
+                { "type": "string" },
+                { "type": "object", "additionalProperties": false, "required": ["value"], "properties": { "value": { "type": "string" }, "label": { "type": "string" } } }
+              ]
+            }
+          }
+        }
+      }
+    },
     "i18n": {
       "type": "object",
       "additionalProperties": false,

package/dist/audit.js

@@ -145,15 +145,13 @@ export async function audit(opts) {
             (c.display.includes('flex') && c.flexDirection.startsWith('column')) ||
             (c.display.includes('grid') && c.gridTemplateColumns.split(/\s+/).length === 1);
     };
-    const disclosureTextFits = (el) => {
-        if (!el.matches('button[aria-expanded]:not([aria-haspopup])'))
-            return false;
+    const contentTextFits = (el) => {
         const c = getComputedStyle(el);
-        if (!['left', 'start'].includes(c.textAlign))
-            return false;
         const r = el.getBoundingClientRect();
         const top = r.top + parseFloat(c.borderTopWidth) + parseFloat(c.paddingTop);
         const bottom = r.bottom - parseFloat(c.borderBottomWidth) - parseFloat(c.paddingBottom);
+        const left = r.left + parseFloat(c.borderLeftWidth) + parseFloat(c.paddingLeft);
+        const right = r.right - parseFloat(c.borderRightWidth) - parseFloat(c.paddingRight);
         const walker = document.createTreeWalker(el, NodeFilter.SHOW_TEXT);
         let found = false;
         for (let n = walker.nextNode(); n; n = walker.nextNode()) {
@@ -163,12 +161,23 @@ export async function audit(opts) {
             range.selectNodeContents(n);
             for (const q of range.getClientRects()) {
                 found = true;
-                if (q.top < top - 1 || q.bottom > bottom + 1)
+                if (q.top < top - 1 || q.bottom > bottom + 1 || q.left < left - 1 || q.right > right + 1)
                     return false;
             }
         }
         return found;
     };
+    const disclosureTextFits = (el) => el.matches('button[aria-expanded]:not([aria-haspopup])') &&
+        ['left', 'start'].includes(getComputedStyle(el).textAlign) && contentTextFits(el);
+    const readableContentControl = (el) => {
+        if (el.closest('nav, [role=navigation], [role=menu], [role=tablist], [role=toolbar]'))
+            return false;
+        const c = getComputedStyle(el);
+        // Pretty/balanced wrapping explicitly authors a content title, not a
+        // compact action label. It still has to fit without clipping or crowding.
+        return ['pretty', 'balance'].includes(c.textWrapStyle) &&
+            parseFloat(c.lineHeight) >= parseFloat(c.fontSize) * 1.3 && contentTextFits(el);
+    };
     // 1. Nothing past the screen edge, except inside deliberate horizontal scrollers (chip rows).
     if (document.documentElement.scrollWidth > W + 1)
         push('error', 'page-overflow', document.body, `The page scrolls sideways (${document.documentElement.scrollWidth}px wide)`);
@@ -177,6 +186,10 @@ export async function audit(opts) {
         const r = el.getBoundingClientRect();
         if (r.right <= W + 1 && r.left >= -1)
             continue;
+        // A nested clip (for example a title's ellipsis) must not hide the fact
+        // that its whole card belongs to a deliberate horizontal scroller.
+        if (visibleRects(el).every((q) => q.right <= 0 || q.left >= W))
+            continue;
         let clip = null;
         for (let p = el.parentElement; p && p !== document.body; p = p.parentElement) {
             const ox = getComputedStyle(p).overflowX;
@@ -227,26 +240,29 @@ export async function audit(opts) {
     const isLabel = (el) => el.matches('button, a, label, [role=tab], [role=button], [role=switch], th') ||
         /(^|\s)(chip|badge|pill|tag)|rounded-full/.test(String(el.className ?? ''));
     for (const el of all) {
-        if (!isLabel(el) || text(el).length > 40 || el.querySelector('p, div, li, ul, br'))
+        if (!isLabel(el) || el.querySelector('p, div, li, ul, br'))
+            continue;
+        // A tooltip describes its trigger but is not its painted control label,
+        // even when hovered. Hidden hints cannot create a wrap or conceal a real
+        // wrapped label by pushing its text beyond the short-label length limit.
+        const labelNodes = [];
+        const textWalker = document.createTreeWalker(el, NodeFilter.SHOW_TEXT);
+        for (let n = textWalker.nextNode(); n; n = textWalker.nextNode())
+            if (n.textContent.trim() && n.parentElement && shown(n.parentElement) && !n.parentElement.closest('[role=tooltip]'))
+                labelNodes.push(n);
+        if (!labelNodes.length || labelNodes.map((n) => n.textContent).join(' ').trim().length > 40)
             continue;
         // Prose links flow with their sentence; vertical contents titles and fitted disclosure headings can
         // also wrap. Horizontal navigation, tabs and ordinary button labels retain their one-line rule.
-        if (proseLink(el) || verticalNavigationLink(el) || disclosureTextFits(el))
+        if (proseLink(el) || verticalNavigationLink(el) || disclosureTextFits(el) || readableContentControl(el))
             continue;
         // A control whose text sits in two or more elements (a list row's title and its meta line) is a composite
         // control, not a label: its lines are laid out on purpose.
-        const holders = new Set();
-        const textWalker = document.createTreeWalker(el, NodeFilter.SHOW_TEXT);
-        for (let n = textWalker.nextNode(); n; n = textWalker.nextNode())
-            if (n.textContent.trim() && n.parentElement)
-                holders.add(n.parentElement);
+        const holders = new Set(labelNodes.map((n) => n.parentElement));
         if (holders.size > 1)
             continue;
         // A wrap is one text node breaking across lines; an icon above its label is layout, not a wrap.
-        const walker = document.createTreeWalker(el, NodeFilter.SHOW_TEXT);
-        for (let n = walker.nextNode(); n; n = walker.nextNode()) {
-            if (!n.textContent.trim())
-                continue;
+        for (const n of labelNodes) {
             // A label allowed two lines on purpose (line-clamp-2: a navigation rail's, under its icon) may wrap.
             if ((parseInt(getComputedStyle(n.parentElement).getPropertyValue('-webkit-line-clamp')) || 0) > 1)
                 continue;
@@ -338,7 +354,7 @@ export async function audit(opts) {
             const atEdge = edge === 'bottom' ? b.bottom >= H - 4 && b.top > H / 2 : b.top <= 4 && b.bottom < H / 2;
             if (!atEdge)
                 continue;
-            const drawn = paintedParts(bar).flatMap(visibleRects);
+            const drawn = paintedParts(bar).flatMap((part) => visibleRects(part));
             for (const el of content) {
                 if (el.contains(bar))
                     continue;
@@ -354,7 +370,7 @@ export async function audit(opts) {
     // 3b. Fixed bars never overlap one another, including what sticks out of them (a raised tab-bar button
     // reaching into a docked timer). Compares the painted parts: backgrounds, borders, text, icons, controls.
     const fixedBars = outer.filter((b) => getComputedStyle(b).position === 'fixed' && b.getBoundingClientRect().height < window.innerHeight * 0.8);
-    const parts = (bar) => paintedParts(bar).flatMap(visibleRects);
+    const parts = (bar) => paintedParts(bar).flatMap((part) => visibleRects(part));
     for (const [i, a] of fixedBars.entries())
         for (const b of fixedBars.slice(i + 1)) {
             const hit = parts(a).some((r) => parts(b).some((q) => Math.min(r.right, q.right) - Math.max(r.left, q.left) > 2 && Math.min(r.bottom, q.bottom) - Math.max(r.top, q.top) > 2));
@@ -385,12 +401,58 @@ export async function audit(opts) {
                 return e;
         return null;
     };
+    const tapRect = (el) => {
+        if (el instanceof HTMLInputElement && /^(checkbox|radio)$/.test(el.type))
+            for (const label of el.labels ?? []) {
+                if (!shown(label) || label.control !== el || getComputedStyle(label).pointerEvents === 'none')
+                    continue;
+                const sized = (box) => box.right - box.left >= opts.comfortable && box.bottom - box.top >= opts.comfortable;
+                let r = visibleRects(label).find(sized);
+                // A row at a scrollport edge can be fully revealed even inside an
+                // overflow-hidden dialog frame. Prove that by scrolling, measuring the
+                // actually exposed area, then restoring every scroll position.
+                if (!r) {
+                    const original = label.getBoundingClientRect();
+                    const scrolls = [];
+                    for (let p = label.parentElement; p; p = p.parentElement) {
+                        const c = getComputedStyle(p);
+                        if ((/auto|scroll/.test(c.overflowX) && p.scrollWidth > p.clientWidth) || (/auto|scroll/.test(c.overflowY) && p.scrollHeight > p.clientHeight))
+                            scrolls.push({ el: p, left: p.scrollLeft, top: p.scrollTop });
+                    }
+                    if (scrolls.length && original.width >= opts.comfortable && original.height >= opts.comfortable) {
+                        const before = { x: scrollX, y: scrollY };
+                        try {
+                            label.scrollIntoView({ block: 'nearest', inline: 'nearest', behavior: 'instant' });
+                            const revealed = visibleRects(label).find(sized);
+                            if (revealed)
+                                r = { left: original.left, top: original.top, right: original.left + revealed.right - revealed.left, bottom: original.top + revealed.bottom - revealed.top };
+                        }
+                        finally {
+                            for (const s of scrolls) {
+                                s.el.scrollLeft = s.left;
+                                s.el.scrollTop = s.top;
+                            }
+                            window.scrollTo({ left: before.x, top: before.y, behavior: 'instant' });
+                        }
+                    }
+                }
+                // Associated native labels are part of the hit area, not checkbox artwork.
+                if (r)
+                    return { left: r.left, top: r.top, right: r.right, bottom: r.bottom, width: r.right - r.left, height: r.bottom - r.top };
+            }
+        return el.getBoundingClientRect();
+    };
     for (const el of interactive) {
         if (interactive.some((o) => o !== el && o.contains(el)))
             continue;
         if (proseLink(el))
             continue;
-        const r = el.getBoundingClientRect();
+        // Scrolling containers can fully clip an otherwise laid-out control. It
+        // has no current hit area to measure; being below the window alone does
+        // not clip it, and the control is checked after scrolling it into view.
+        if (!visibleRects(el).length)
+            continue;
+        const r = tapRect(el);
         const min = Math.min(r.width, r.height);
         // WCAG 2.2 spacing exception: a smaller target passes when a 24px circle on it touches no other target.
         const cx = r.left + r.width / 2;
@@ -398,7 +460,7 @@ export async function audit(opts) {
         const crowded = interactive.some((o) => {
             if (o === el || o.contains(el) || el.contains(o) || layerOf(o) !== layerOf(el))
                 return false;
-            const q = o.getBoundingClientRect();
+            const q = tapRect(o);
             const dx = Math.max(q.left - cx, 0, cx - q.right);
             const dy = Math.max(q.top - cy, 0, cy - q.bottom);
             return Math.hypot(dx, dy) < 12;
@@ -478,7 +540,7 @@ export async function audit(opts) {
         return q.right <= left + 1 || q.left >= right - 1;
     };
     // Behind an open modal (found above) only the modal's own controls count.
-    const solid = interactive.filter((el) => opacity(el) > 0.05 && (!modal || modal.contains(el)));
+    const solid = interactive.filter((el) => opacity(el) > 0.05 && visibleRects(el).length > 0 && (!modal || modal.contains(el)));
     const emptyOverlays = new Set(solid.filter(isEmptyOverlay));
     const controlRects = new Map(solid.map((el) => [el, visibleRects(el)]));
     for (const [i, a] of solid.entries())
@@ -640,9 +702,16 @@ export async function audit(opts) {
     // 6. Google's guidelines (Material 3, Android's app quality guidelines, web.dev, Lighthouse). Warnings: each names
     // the rule it comes from, so a screen can break one on purpose (see skills/stitch2/references/google.md).
     const textRects = (el) => {
-        const range = document.createRange();
-        range.selectNodeContents(el);
-        return [...range.getClientRects()].filter((r) => r.width > 1 && r.height > 1);
+        const rects = [];
+        const walker = document.createTreeWalker(el, NodeFilter.SHOW_TEXT);
+        for (let node = walker.nextNode(); node; node = walker.nextNode()) {
+            if (!node.textContent.trim() || !node.parentElement || !shown(node.parentElement) || opacity(node.parentElement) < 0.1)
+                continue;
+            const range = document.createRange();
+            range.selectNodeContents(node);
+            rects.push(...range.getClientRects());
+        }
+        return rects.filter((r) => r.width > 1 && r.height > 1);
     };
     const scrollsSideways = (el) => {
         for (let e = el.parentElement; e && e !== document.body; e = e.parentElement) {
@@ -682,7 +751,9 @@ export async function audit(opts) {
             continue;
         const lineChars = [];
         const walker = document.createTreeWalker(el, NodeFilter.SHOW_TEXT);
-        for (let t = walker.nextNode(); t; t = walker.nextNode())
+        for (let t = walker.nextNode(); t; t = walker.nextNode()) {
+            if (!t.parentElement || !shown(t.parentElement) || opacity(t.parentElement) < 0.1)
+                continue;
             for (const m of t.textContent.matchAll(/\S+\s*/g)) {
                 const range = document.createRange();
                 range.setStart(t, m.index);
@@ -694,6 +765,7 @@ export async function audit(opts) {
                 else
                     lineChars.push({ top, n: m[0].replace(/\s+/g, ' ').length });
             }
+        }
         if (lineChars.length < 2)
             continue;
         const longest = Math.max(...lineChars.sort((a, b) => a.top - b.top).slice(0, -1).map((l) => l.n));
@@ -708,7 +780,7 @@ export async function audit(opts) {
         for (const el of solid) {
             if (solid.some((o) => o !== el && o.contains(el)) || proseLink(el))
                 continue;
-            const r = el.getBoundingClientRect();
+            const r = tapRect(el);
             if (r.width >= 48 && r.height >= 48)
                 continue;
             if (out.some((i) => i.type === 'tap-target' && i.selector === sel(el)))
@@ -718,7 +790,12 @@ export async function audit(opts) {
             const hit = solid.find((o) => {
                 if (o === el || o.contains(el) || el.contains(o) || layer(o) !== layer(el))
                     return false;
-                const q = o.getBoundingClientRect();
+                // A compound input's clear/reveal/list button occupies reserved padding,
+                // not a neighbouring target. The same geometry as overlap checks keeps
+                // insufficient padding and unrelated adjacent controls checked.
+                if (reservedInputAction(el, o) || reservedInputAction(o, el) || emptyOverlay(el, o) || emptyOverlay(o, el))
+                    return false;
+                const q = tapRect(o);
                 const ox = Math.max(0, Math.min(cx + 24, q.right) - Math.max(cx - 24, q.left));
                 const oy = Math.max(0, Math.min(cy + 24, q.bottom) - Math.max(cy - 24, q.top));
                 return ox * oy > 48;

package/dist/canvas.html

@@ -44,6 +44,7 @@
   /* Theme and language: native dropdowns drawn like the versions and variants ones. */
   .pick { appearance: none; background: var(--bg) url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='12' height='8' viewBox='0 0 12 8'%3E%3Cpath d='M1 1.5l5 5 5-5' fill='none' stroke='%23a1a1aa' stroke-width='1.5' stroke-linecap='round' stroke-linejoin='round'/%3E%3C/svg%3E") no-repeat right 10px center / 12px 8px; border: 1px solid var(--edge); border-radius: 8px; color: var(--text); cursor: pointer; font: inherit; padding: 5px 30px 5px 8px; width: 100%; }
   .pick[hidden] { display: none; }
+  #modeFilters { display: contents; }
   #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%; }
@@ -142,6 +143,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, tablet, 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>
+    <div id="modeFilters"></div>
     <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>
@@ -179,13 +181,20 @@ let designDir = 'design'
 let THEMES = ['dark']
 let theme = localStorage.getItem('stitch2-theme') ?? 'dark'
 const themed = () => THEMES.length > 1
+// Modes: app states (signed in or out, a plan, a role) every screen can be shown in. Each sets an attribute on the
+// screen's document, like the theme; "As drawn" leaves a screen as its file has it. Pictures of the screens that are
+// not live ask the server for the same states (?mode=name:value).
+let MODES = []
+const modePick = {} // mode name -> picked value, '' for as drawn
+const modeValueLabel = (m, v) => (v ? (m.values.find((x) => x.value === v)?.label ?? v) : 'As drawn')
+const modeNotes = () => MODES.filter((m) => modePick[m.name]).map((m) => `${m.label}: ${modeValueLabel(m, modePick[m.name])}`)
 // Languages: screens reload in the one picked (?lang=…); the source language shows them as written.
 let LANGS = ['en']
 let SOURCE = 'en'
 let lang = localStorage.getItem('stitch2-lang') ?? 'en'
 const langQuery = () => (lang === SOURCE ? '' : `&lang=${encodeURIComponent(lang)}`)
 const themeNote = () =>
-  [themed() && theme !== THEMES[0] ? `in the ${theme} theme` : '', lang !== SOURCE ? `in ${lang}` : '']
+  [themed() && theme !== THEMES[0] ? `in the ${theme} theme` : '', lang !== SOURCE ? `in ${lang}` : '', ...modeNotes()]
     .filter(Boolean)
     .map((s) => ' ' + s)
     .join(',')
@@ -245,6 +254,33 @@ function widthOptions() {
   if (!widthModes().includes(widthMode)) widthMode = 'drawn'
   wsel.value = widthMode
 }
+// The document's own value is kept the first time, so "As drawn" puts it back.
+const authored = new WeakMap()
+function applyModes(f) {
+  if (!f.iframe) return
+  let root
+  try { root = f.iframe.contentDocument.documentElement } catch { return }
+  if (!root) return
+  const was = authored.get(root) ?? authored.set(root, {}).get(root)
+  for (const m of MODES) {
+    if (!(m.attribute in was)) was[m.attribute] = root.getAttribute(m.attribute)
+    const value = modePick[m.name] || was[m.attribute]
+    if (value == null) root.removeAttribute(m.attribute)
+    else root.setAttribute(m.attribute, value)
+  }
+}
+function setMode(name, value) {
+  const m = MODES.find((x) => x.name === name)
+  if (!m) return
+  modePick[name] = m.values.some((x) => x.value === value) ? value : ''
+  localStorage.setItem(`stitch2-mode-${name}`, modePick[name])
+  const sel = document.querySelector(`#modeFilters [data-mode="${name}"]`)
+  if (sel) sel.value = modePick[name]
+  for (const f of frames.values()) applyModes(f)
+  if (selected) inspector(selected)
+  summary()
+  scheduleSync()
+}
 function applyTheme(f) {
   if (!themed() || !f.iframe) return
   try { f.iframe.contentDocument.documentElement.dataset.theme = theme } catch {}
@@ -640,6 +676,7 @@ function shotUrl(s) {
   const q = new URLSearchParams({ path: s.path, width: String(s.width), m: String(Math.round(s.mtime)), r: String(shotRev) })
   if (themed()) q.set('theme', theme)
   if (lang !== SOURCE) q.set('lang', lang)
+  for (const m of MODES) if (modePick[m.name]) q.append('mode', `${m.name}:${modePick[m.name]}`)
   return `/api/shot?${q}`
 }
 const pinned = (f) => f === selected || f.el.classList.contains('live') || picked.some((p) => p.f === f)
@@ -670,6 +707,7 @@ function mount(f) {
     void (async () => {
       if (!(await waitForStyles()) || f.iframe !== iframe) return
       applyTheme(f)
+      applyModes(f)
       measure(f)
       clearTimeout(f.reveal)
       // The picture stays until the complete, styled page has been measured.
@@ -1176,6 +1214,7 @@ addEventListener('keydown', (e) => {
   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 === 'm' || e.key === 'M') && MODES.length) { const m = MODES[0], all = ['', ...m.values.map((v) => v.value)]; setMode(m.name, all[(all.indexOf(modePick[m.name]) + 1) % all.length]) }
   if (e.key === 'l' || e.key === 'L') setLang(LANGS[(LANGS.indexOf(lang) + 1) % LANGS.length])
   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)
@@ -1214,6 +1253,20 @@ fetch('/api/config').then((r) => r.json()).then((c) => {
   pick.innerHTML = THEMES.map((t) => `<option value="${t}">${t[0].toUpperCase()}${t.slice(1)} theme</option>`).join('')
   pick.onchange = () => setTheme(pick.value)
   setTheme(theme)
+  MODES = c.modes ?? []
+  MODES.forEach((m, i) => {
+    const stored = localStorage.getItem(`stitch2-mode-${m.name}`) ?? ''
+    modePick[m.name] = m.values.some((v) => v.value === stored) ? stored : ''
+    const sel = document.createElement('select')
+    sel.className = 'pick'
+    sel.dataset.mode = m.name
+    sel.setAttribute('aria-label', m.label)
+    sel.title = `Show every screen with ${m.label.toLowerCase()} set to one of these, or as drawn${i === 0 ? ' (M)' : ''}`
+    for (const v of ['', ...m.values.map((x) => x.value)]) sel.add(new Option(`${m.label}: ${modeValueLabel(m, v)}`, v))
+    sel.value = modePick[m.name]
+    sel.onchange = () => setMode(m.name, sel.value)
+    document.getElementById('modeFilters').append(sel)
+  })
   WIDTHS = c.widths ?? {}
   BREAKPOINTS = c.breakpoints ?? {}
   const wsel = document.getElementById('widthFilter')

package/dist/colours.js

@@ -9,15 +9,31 @@ import { existsSync, readFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { config } from './config.js';
 import { familyOf } from './consistency.js';
-import { ROOT } from './screens.js';
+import { ROOT, meta, tag } from './screens.js';
 const LITERAL = /(?<![\w&/=-])#(?:[0-9a-fA-F]{8}|[0-9a-fA-F]{6}|[0-9a-fA-F]{3,4})\b|(?<![a-zA-Z])(?:rgba?|hsla?)\(\s*[\d.][^)]*\)/g;
 /** Lines with a literal colour, comments blanked out (keeping line numbers). */
 function literals(source, js) {
     let s = source.replace(/<!--[\s\S]*?-->/g, (m) => m.replace(/[^\n]/g, ' '));
     if (js)
         s = s.replace(/\/\*[\s\S]*?\*\//g, (m) => m.replace(/[^\n]/g, ' ')).replace(/^\s*\/\/.*$/gm, '');
-    else
+    else {
         s = s.replace(/<head[\s>][\s\S]*?<\/head>/i, (m) => m.replace(/[^\n]/g, ' '));
+        // Code examples and syntax highlighting are content. Keep the outer tag's
+        // styles so an actual code-container background still follows the theme.
+        s = s.replace(/(<(pre|code)\b[^>]*>)([\s\S]*?)(<\/\2\s*>)/gi, (_, open, _tag, body, close) => open + body.replace(/[^\n]/g, ' ') + close);
+        // SVG drawing colours belong to an asset; the outer SVG's class/style
+        // still follows UI tokens (for example a muted search icon).
+        s = s.replace(/(<svg\b[^>]*>)([\s\S]*?)(<\/svg\s*>)/gi, (_, open, body, close) => open + body.replace(/[^\n]/g, ' ') + close);
+        // Documentation can describe a literal colour without painting it. Only
+        // markup attributes are authored styling, not prose or example values.
+        const tags = [...s.matchAll(/<(?:[^>"']|"[^"]*"|'[^']*')*>/g)];
+        let styled = s.replace(/[^\n]/g, ' ');
+        for (const match of tags) {
+            const tag = match[0].replace(/\s(?:data-[\w-]+|on[\w]+)\s*=\s*("[^"]*"|'[^']*')/gi, (attribute) => attribute.replace(/[^\n]/g, ' '));
+            styled = styled.slice(0, match.index) + tag + styled.slice(match.index + match[0].length);
+        }
+        s = styled;
+    }
     const out = [];
     s.split('\n').forEach((text, i) => {
         for (const m of text.matchAll(LITERAL)) {
@@ -34,6 +50,9 @@ export function colourIssues(path) {
     if (familyOf(path) !== 'screens')
         return [];
     const html = readFileSync(join(ROOT, path), 'utf8');
+    // Imported captures document the app as it is, not an editable token source.
+    if (meta(html, tag('source')) === 'app')
+        return [];
     const found = literals(html, false).map((l) => ({ ...l, file: `${config.designDir}/${path}` }));
     if (path.startsWith(`${config.catalogDir}/`))
         for (const [, src] of html.matchAll(/<script[^>]*\bsrc="\/([^"]+\.js)"/g)) {

package/dist/config.d.ts

@@ -1,3 +1,20 @@
+/**
+ * An app state every screen can be shown in, picked from the canvas sidebar: signed in or out, a plan, a role. The pick
+ * is an attribute on each screen's <html> (data-auth="user"), so the screens' own CSS and scripts answer to it.
+ */
+export interface ModeConfig {
+    /** The id: lowercase letters, digits and hyphens. The canvas remembers the pick under it. */
+    name: string;
+    /** Shown before each value in the dropdown; defaults to the name, capitalized. */
+    label?: string;
+    /** The attribute on the screen's <html> that carries the value; defaults to data-<name>. */
+    attribute?: string;
+    /** What the canvas can show every screen as: a value, or a value with its label. "As drawn" is always offered too. */
+    values: (string | {
+        value: string;
+        label?: string;
+    })[];
+}
 export interface LabConfig {
     /** Shown on the canvas. */
     name: string;
@@ -41,6 +58,11 @@ export interface LabConfig {
     skills: string[];
     /** Paths under designDir a sandbox leaves out besides screens (notes that would give the trial away). */
     sandboxExclude?: string[];
+    /**
+     * App states shown across all screens (see ModeConfig). The canvas has a dropdown for each, with the screens as drawn
+     * first; picking a value sets its attribute on every screen, live ones and the pictures of the rest.
+     */
+    modes?: ModeConfig[];
     /** The live app, for stitch2 compare (see compare.ts): its URL, a sign-in script and a route per screen. */
     app?: {
         url: string;
@@ -91,5 +113,21 @@ export declare const breakpoints: () => Record<string, number>;
  * 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[];
+export interface Mode {
+    name: string;
+    label: string;
+    attribute: string;
+    values: {
+        value: string;
+        label: string;
+    }[];
+}
+/** The configured modes, checked: a name or attribute that isn't plain, a repeat, or a mode without values is left out. */
+export declare function modes(): Mode[];
+/**
+ * The attributes a request asks for, from its "name:value" pairs; a pair that isn't a configured mode and value is
+ * ignored, so an address can only set what the config offers.
+ */
+export declare function modeAttributes(pairs: string[]): Record<string, string>;
 /** The design folder, with a trailing slash. */
 export declare const ROOT: string;

package/dist/config.js

@@ -51,5 +51,43 @@ export function checkWidths(device) {
     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);
 }
+const MODE_NAME = /^[a-z][a-z0-9-]*$/;
+const capitalize = (s) => s.charAt(0).toUpperCase() + s.slice(1);
+/** The configured modes, checked: a name or attribute that isn't plain, a repeat, or a mode without values is left out. */
+export function modes() {
+    const out = [];
+    for (const m of Array.isArray(config.modes) ? config.modes : []) {
+        if (typeof m?.name !== 'string' || !MODE_NAME.test(m.name) || out.some((o) => o.name === m.name))
+            continue;
+        const attribute = m.attribute ?? `data-${m.name}`;
+        if (!MODE_NAME.test(attribute))
+            continue;
+        const values = [];
+        for (const v of Array.isArray(m.values) ? m.values : []) {
+            const value = typeof v === 'string' ? v : v?.value;
+            if (typeof value !== 'string' || !value || /[\s"'<>=&:]/.test(value) || values.some((x) => x.value === value))
+                continue;
+            values.push({ value, label: (typeof v === 'object' && v.label) || capitalize(value) });
+        }
+        if (values.length)
+            out.push({ name: m.name, label: m.label ?? capitalize(m.name), attribute, values });
+    }
+    return out;
+}
+/**
+ * The attributes a request asks for, from its "name:value" pairs; a pair that isn't a configured mode and value is
+ * ignored, so an address can only set what the config offers.
+ */
+export function modeAttributes(pairs) {
+    const picked = {};
+    for (const pair of pairs) {
+        const at = pair.indexOf(':');
+        const mode = modes().find((m) => m.name === pair.slice(0, at));
+        const value = pair.slice(at + 1);
+        if (at > 0 && mode?.values.some((v) => v.value === value))
+            picked[mode.attribute] = value;
+    }
+    return picked;
+}
 /** The design folder, with a trailing slash. */
 export const ROOT = join(resolve(BASE, config.designDir), '/');

package/dist/consistency.js

@@ -201,9 +201,11 @@ export function collectComponents(opts) {
         const variant = el.getAttribute('data-variant');
         const kind = g === 'button'
             ? `button:${variant ?? 'primary'}:${el.getAttribute('data-size') ?? 'md'}`
-            : variant
-                ? `${g}:${variant}`
-                : g;
+            : g === 'card'
+                ? `card:${variant ?? 'default'}:${el.getAttribute('data-layout') ?? 'default'}:${el.getAttribute('data-size') ?? 'default'}`
+                : variant
+                    ? `${g}:${variant}`
+                    : g;
         if (!(g === 'button' && el.hasAttribute('disabled')))
             add(kind, el);
     }
@@ -293,6 +295,11 @@ const NAMES = {
 };
 export const nameOf = (kind) => NAMES[kind]?.[0] ?? kind.replace(/:/g, ' ');
 const key = (s) => JSON.stringify(s.fields);
+// An icon/thumb-only control has no painted typography to compare with a
+// labelled example. Its geometry still matches, and two actual fonts must match.
+const differences = (a, b) => Object.keys({ ...a.fields, ...b.fields })
+    .filter((f) => !(f === 'font' && (!a.fields.font || !b.fields.font)) && a.fields[f] !== b.fields[f]);
+const matches = (a, b) => differences(a, b).length === 0;
 /** Issues for the screens in `paths`, comparing with every screen whose components are known. */
 export function consistencyIssues(known, paths) {
     const out = {};
@@ -306,7 +313,7 @@ export function consistencyIssues(known, paths) {
         const peers = (families.get(familyOf(path)) ?? []).filter((p) => p !== path);
         for (const [kind, sigs] of Object.entries(known[path] ?? {})) {
             // The catalog shows every variant of a component side by side; a screen shows one.
-            if (sigs.length > 1 && MEASURED.has(kind.split(':')[0]) && !catalogs.includes(path))
+            if (sigs.some((a, i) => sigs.slice(i + 1).some((b) => !matches(a, b))) && MEASURED.has(kind.split(':')[0]) && !catalogs.includes(path))
                 issues.push({
                     severity: 'warning',
                     type: 'consistency',
@@ -322,11 +329,10 @@ export function consistencyIssues(known, paths) {
                 continue;
             if (reference.length) {
                 const mine = sigs[0];
-                if (reference.some((r) => key(r) === key(mine)))
+                if (reference.some((r) => matches(r, mine)))
                     continue;
                 const ref = reference[0];
-                const diffs = Object.keys({ ...mine.fields, ...ref.fields })
-                    .filter((f) => mine.fields[f] !== ref.fields[f])
+                const diffs = differences(mine, ref)
                     .map((f) => `${f} ${mine.fields[f] ?? '–'} (catalog ${ref.fields[f] ?? '–'})`);
                 issues.push({
                     severity: 'warning',
@@ -354,7 +360,7 @@ export function consistencyIssues(known, paths) {
                 continue;
             // No majority: report when this screen matches none of its peers either.
             if (top.n < 2 || ranked[1]?.n === top.n) {
-                if (!votes.has(key(mine)) && peers.filter((p) => known[p]?.[kind]).length >= 2)
+                if (![...votes.values()].some((v) => matches(mine, v.sig)) && peers.filter((p) => known[p]?.[kind]).length >= 2)
                     issues.push({
                         severity: 'warning',
                         type: 'consistency',
@@ -364,10 +370,9 @@ export function consistencyIssues(known, paths) {
                     });
                 continue;
             }
-            if (key(mine) === key(top.sig))
+            if (matches(mine, top.sig))
                 continue;
-            const diffs = Object.keys({ ...mine.fields, ...top.sig.fields })
-                .filter((f) => mine.fields[f] !== top.sig.fields[f])
+            const diffs = differences(mine, top.sig)
                 .map((f) => `${f} ${mine.fields[f] ?? '–'} (others ${top.sig.fields[f] ?? '–'})`);
             issues.push({
                 severity: 'warning',

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 { breakpoints, CONFIG_FILE, checkWidths, config, widthRanges } from './config.js';
+import { breakpoints, CONFIG_FILE, checkWidths, config, modeAttributes, modes, widthRanges } from './config.js';
 import { designThemes } from './design-md.js';
 import { allLocales, localeScript, sourceLocale } from './i18n.js';
 import { designPage } from './design-page.js';
@@ -156,7 +156,7 @@ export function startServer(port) {
             return;
         }
         if (url.pathname === '/api/config')
-            return json({ ...config, themes: designThemes(), locales: allLocales(), sourceLocale: sourceLocale(), widths: widthRanges(), breakpoints: breakpoints(), checkWidths: Object.fromEntries(Object.keys(widthRanges()).map((d) => [d, checkWidths(d)])) });
+            return json({ ...config, modes: modes(), 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')
@@ -169,6 +169,7 @@ export function startServer(port) {
                 width: Math.min(4000, Math.max(200, Number(q.get('width')) || 390)),
                 theme: q.get('theme') || undefined,
                 lang: q.get('lang') || undefined,
+                modes: modeAttributes(q.getAll('mode')),
             });
             if (!job) {
                 res.writeHead(404, { 'content-type': 'text/plain' });

package/dist/shots.d.ts

@@ -3,6 +3,8 @@ export interface ShotRequest {
     width: number;
     theme?: string;
     lang?: string;
+    /** Attributes set on the page's <html> before the picture: the app states picked in the canvas (config modes). */
+    modes?: Record<string, string>;
 }
 /** The server's file watcher calls this: the next picture looks at the shared files again. */
 export declare function sharedChanged(): void;

package/dist/shots.js

@@ -3,7 +3,7 @@
  * components), so a canvas with a hundred of them stalls the browser; the canvas keeps only the screens in view live
  * and draws the rest from these. One headless Chromium renders them, three at a time, and they are kept on disk
  * (os.tmpdir()/stitch2-shots), keyed by everything that changes the picture: the screen file, the files screens
- * share (tokens, components, stylesheets), the theme, the language and its messages, and the width.
+ * share (tokens, components, stylesheets), the theme, the modes, the language and its messages, and the width.
  */
 import { createHash } from 'node:crypto';
 import { existsSync, mkdirSync, readdirSync, readFileSync, statSync, writeFileSync } from 'node:fs';
@@ -53,6 +53,7 @@ function keyOf(r) {
         statSync(file).mtimeMs,
         sharedStamp(),
         r.theme ?? '',
+        JSON.stringify(Object.entries(r.modes ?? {}).sort(([a], [b]) => a.localeCompare(b))),
         r.lang ?? '',
         messages && existsSync(messages) ? statSync(messages).mtimeMs : '',
         r.width,
@@ -98,6 +99,10 @@ export function shot(base, r) {
             await page.goto(`${base}/${r.path}?${query}`, { waitUntil: 'networkidle', timeout: 30_000 }).catch(() => { });
             if (r.theme)
                 await page.evaluate((t) => { document.documentElement.dataset.theme = t; }, r.theme);
+            const attributes = Object.entries(r.modes ?? {});
+            if (attributes.length)
+                await page.evaluate((list) => { for (const [name, value] of list)
+                    document.documentElement.setAttribute(name, value); }, attributes);
             await page.evaluate(() => document.fonts.ready);
             // Tailwind's browser build and the components settle after load.
             await page.waitForTimeout(400);

package/dist/states.js

@@ -140,7 +140,7 @@ export async function catalogStates(page, path, opts) {
         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 (c.clickable && !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)
@@ -148,6 +148,8 @@ export async function catalogStates(page, path, opts) {
             else if (noPress)
                 add('state-pressed', who + ': pressing adds nothing to hover, so a tap gives no feedback (DESIGN.md, pressed)');
         }
+        if (!c.clickable && !c.field && looks.focus?.look === looks.rest?.look)
+            add('state-focus', who + ': this keyboard-focusable region needs a visible focus indicator, not hover or pressed feedback');
         // The hand says "this does something" before the click; the arrow over a button reads as plain text.
         const cursor = looks.hover?.cursor;
         if (c.clickable && cursor && cursor !== 'pointer')

package/dist/typecheck.d.ts

@@ -31,6 +31,8 @@ export interface TextItem {
     upper: boolean;
     numeric: boolean;
     lines: number;
+    /** Literal code uses its language's case and monospace conventions, not UI labels. */
+    code?: boolean;
 }
 /** Runs in the page. Plain JS on purpose: Playwright sends its source to the browser. */
 export declare function collectText(): TextItem[];

package/dist/typecheck.js

@@ -66,9 +66,10 @@ export function collectText() {
             color: `#${hex(m[0])}${hex(m[1])}${hex(m[2])}${alpha < 0.99 ? ` ${Math.round(alpha * 100)}%` : ''}`,
             // Set in capitals: uppercased by CSS, or typed in capitals (6+ letters, so "RPE" and "PR" don't count).
             upper: cs.textTransform === 'uppercase' ||
-                (own === own.toUpperCase() && own.replace(/[^A-Z]/g, '').length >= 6),
+                (!el.closest('td, dd, output') && own === own.toUpperCase() && own.replace(/[^A-Z]/g, '').length >= 6),
             numeric: /^[\d\s.,:×x+\-−–/%]+[a-z]{0,4}$/i.test(own) && /\d/.test(own),
             lines,
+            code: Boolean(el.closest('pre, code')),
         });
     }
     return out;
@@ -97,7 +98,7 @@ export function typeIssues(levels, items) {
         out.push({ severity, type, message, selector: t.selector, text: t.text });
     };
     for (const t of items) {
-        if (levels.length && !matchLevel(levels, t)) {
+        if (!t.code && levels.length && !matchLevel(levels, t)) {
             const key = describe(t);
             if (!seen.has(key)) {
                 seen.add(key);
@@ -106,9 +107,9 @@ export function typeIssues(levels, items) {
         }
         if (t.lines > 1 && t.lineHeight < t.size * 1.15)
             push('error', 'type-leading', t, `Wrapped text with cramped line height (${Math.round(t.lineHeight)}px for ${t.size}px type)`);
-        if (t.upper && t.text.length > 2 && t.tracking < 0.03 * t.size)
+        if (!t.code && t.upper && t.text.length > 2 && t.tracking < 0.03 * t.size)
             push('warning', 'type-caps', t, 'Capitals without letter-spacing (use label-caps, +0.06em)');
-        if (t.mono && t.size >= 18 && /\d[.,:]\d/.test(t.text))
+        if (!t.code && t.mono && t.size >= 18 && /\d[.,:]\d/.test(t.text))
             push('warning', 'type-mono-number', t, 'Large number in a monospace font: its point, comma or colon gets a full-width gap; use Geist with tabular figures');
     }
     return out;

package/package.json

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

@@ -57,6 +57,14 @@ References, read before the first screen:
    fixed bars, fixed bars overlapping each other, tap targets, contrast, cramped text), a hand-built copy of a
    catalog component (`reuse`: use the component or extend it, never rebuild it), and every warning about type
    (`type-*`), components that differ from the catalog (`consistency`) and colour values (`color`).
+   Native checkbox and radio targets include their visible, associated label; the glyph need not be 44px.
+   Hidden or noninteractive labels do not enlarge a hit area. Offscreen content in a deliberate horizontal
+   rail is not viewport clipping, while a partially visible cut label still needs correction.
+   Literal `<pre>`/`<code>` content keeps its language's case and syntax colours, not UI-label typography.
+   Native table-data, definition values and output values keep their supplied case too. Explicit CSS uppercase
+   and column headings still receive the caps-label tracking check.
+   The code container's own authored colours still follow DESIGN.md. Unchanged `source=app` captures are
+   not token-migration targets.
    Text running into other text (`text-overlap`) or out of its card (`overflow`) is an error; a short label cut
    short with an ellipsis (`truncated`) is a warning to fix with room, not a smaller size. Google's rules are
    warnings too (`text-small`, `edge-margin`, `measure`, `tap-spacing`, `placeholder-label`, `unnamed-control`,
@@ -78,11 +86,24 @@ References, read before the first screen:
    An empty, transparent stretched row/card action may sit under a secondary link; painted controls or
    partially colliding neighbours still fail. Do not silence an overlap by hiding content or removing its
    accessible label: inspect the visible state and fix actual collisions in the shared component.
+   Content-title controls may explicitly use `text-wrap: pretty` or `balance` when their full text fits
+   inside the control with readable line height. This does not exempt navigation, menus, tabs or toolbars,
+   clipped titles, or ordinary compact action labels. Do not shrink or truncate content to force one line.
    Inline links within a prose sentence may wrap and receive WCAG's inline-target exception, including
    sentences inside list items; standalone links do not. Titles in vertical contents/menu lists may wrap,
    unlike horizontal navigation labels. An in-page disclosure (`aria-expanded`, without `aria-haspopup`)
    may have a multiline heading when its height and padding fit the complete text. A text input's clear,
    reveal or list-toggle button may overlap only padding reserved for it, never the editable text area.
+   Such a geometrically contained action is one compound input, not a close neighbour for `tap-spacing`;
+   a button intruding into editable text or an unrelated adjacent control still fails the checks.
+   A transparent stretched row action below its own secondary link is not a competing touch target when
+   browser hit-testing proves that link is reachable; painted, blocking or merely adjacent controls still fail.
+   Fully clipped controls inside scrolling containers have no painted hit area until scrolled into view;
+   this does not exempt visible small controls or content merely below the window.
+   A partly scroll-clipped native choice label retains its full hit-area size only when the scrollport can
+   reveal the minimum target. Permanent clipping and scrollports too small to reveal it still fail.
+   Tooltip copy is reading text, not its trigger's compact label: it may wrap when visible and does not
+   create or hide a `label-wraps` issue on the trigger. The actual painted control label is still checked.
    Cached checks are invalidated when shared components, the catalog or the checker change. A filtered
    rerun refreshes only those screens; it must not make unrelated screens' older checks appear current.
    Motion warnings: `motion-token` (a transition length DESIGN.md doesn't name) and `reduced-motion` (something

package/skills/stitch2/references/components.md

@@ -45,7 +45,9 @@ clickable element that is not a button or a link gets `role="button"` (and a key
 it the hand. Override the cursor only with a reason (`cursor-grab` on a drag handle).
 
 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
+and without an icon). Keyboard-focusable reading or scrolling regions are not click actions and need no hover
+or pressed feedback, but must show a visible focus indicator (`state-focus`). Actual actions retain those checks.
+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

package/skills/stitch2/references/screens.md

@@ -171,13 +171,31 @@ doesn't cover it is drawn at its nearest edge and faded, because the app shows a
 - A desktop screen is a layout for its range, not a stretched phone: a side navigation instead of the bar,
   list-detail with both panes, extra columns for feeds.
 
+## App states
+
+When the product looks different signed in or out, on another plan or for another role, do not draw a copy of each
+screen per state. Draw it once, let its CSS and scripts answer to an attribute on `<html>`, and list the states as
+`modes` in `stitch2.config.json`:
+
+```json
+"modes": [
+  { "name": "auth", "label": "Account", "values": [{ "value": "guest", "label": "Guest" }, { "value": "user", "label": "Signed in" }] }
+]
+```
+
+The canvas sidebar then has a dropdown for each mode. A value sets the attribute (`data-auth="user"`; `attribute`
+names another) on every screen, live frames and the pictures of the rest, and "As drawn" puts each screen back to what
+its file says. `m` cycles the first mode. A screen is still written for the state it shows (a signed-in account page has
+`data-auth="user"` in its file); modes show the other states of the same screen. `stitch2 check` runs on the screens as
+drawn, not in each state, so open the other states on the canvas and look at them before hand-over.
+
 ## The canvas
 
 `stitch2 canvas` → http://localhost:4400. The sidebar lists DESIGN.md (drawn as tokens and rules), Components
 (the catalog for the variants the filter shows; a click steps through them), the consistency report and app
 comparison (each with when it last ran, or how many covered screens changed since), Languages, and every screen
-with its versions. Filters: status (active, approved, needs review, all), versions, variants, theme, width and
-language. The reports and Languages follow the filters too: they show only the screens the canvas shows. Selecting a version opens the inspector: status, note, checks, and
+with its versions. Filters: status (active, approved, needs review, all), versions, variants, theme, width,
+language and each app state (`modes`). The reports and Languages follow the filters too: they show only the screens the canvas shows. Selecting a version opens the inspector: status, note, checks, and
 Copy for its reference. Pick mode (`p`) highlights the element under the pointer; a click copies its reference,
 Shift-click collects several (Copy all, Add to note). Keys: `/` search, `j`/`k` next and previous, `a` approve,
-`p` pick, `f` fit, `0` actual size, double-click to use a frame, `Esc` to leave.
+`p` pick, `f` fit, `m` next app state, `0` actual size, double-click to use a frame, `Esc` to leave.

package/skills/stitch2-consistency/SKILL.md

@@ -6,6 +6,8 @@ description: Verify that shared elements (tab bar, header, buttons, chips, icon
 # Verifying design consistency with stitch2
 
 A shared element must be the same everywhere: same size, radius, type, colour, icon set, icons and states.
+Declared card layout and size variants are compared separately: a horizontal row and a media showcase
+have different geometry by design. Each variant still has to match its own catalog reference or peers.
 stitch2 measures this; your job is to read the evidence, decide what is wrong, and fix it at the source. The
 reference is the **component catalog** (the screen in the config's `catalogDir`); without a catalog, the
 majority of screens in the same family.
@@ -28,6 +30,8 @@ majority of screens in the same family.
    - `reuse`: a lab screen built a catalog component by hand instead of using it.
 4. Look at the crops yourself. Numbers say what differs; the images say whether it matters. A 1 px height
    difference from a border is noise; another icon set, label size or button shape is not.
+   Font comparisons apply when both controls paint a label. An icon/thumb-only control has no label font;
+   its geometry remains checked, and genuine font differences between labelled controls still fail.
 
 ## 2. Decide, per difference