stitch2 0.12.1 → 0.13.0

package/README.md

@@ -46,7 +46,11 @@ file that already exists. From there the agent spends its effort on the design.
   other text, labels cut short with an ellipsis, content under fixed bars, fixed bars that overlap each other, tap
   targets (WCAG 2.2), text contrast in every theme, text that is not one of DESIGN.md's type levels, capitals without tracking,
   large numbers in monospace, components built by hand, components that differ between screens, and colours
-  written as values instead of DESIGN.md tokens. Each screen is also run in long and right-to-left
+  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
   pseudo-languages and your locales (see below).
 - **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).

package/dist/audit.js

@@ -370,5 +370,164 @@ export async function audit(opts) {
         if (ratio < need)
             push(ratio < need - 1 ? 'error' : 'warning', 'contrast', el, `Low contrast ${ratio.toFixed(2)}:1 (needs ${need}:1)`);
     }
+    // 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 scrollsSideways = (el) => {
+        for (let e = el.parentElement; e && e !== document.body; e = e.parentElement) {
+            const ox = getComputedStyle(e).overflowX;
+            if (ox === 'auto' || ox === 'scroll')
+                return true;
+        }
+        return false;
+    };
+    const margin = W < 600 ? 16 : 24;
+    for (const el of all) {
+        if (!ownText(el) || opacity(el) < 0.1)
+            continue;
+        const cs = getComputedStyle(el);
+        const size = parseFloat(cs.fontSize);
+        // 6a. Material's smallest type level is 11 (label small); body text starts at 12, which Lighthouse asks of
+        // most text on a page.
+        if (size < 11)
+            push('warning', 'text-small', el, 'Text at ' + size + "px: Material's smallest level is 11px, and body text starts at 12px");
+        const rects = textRects(el);
+        if (!rects.length)
+            continue;
+        // 6b. Margins: Material keeps content 16dp from the edge of a compact window, 24dp from medium ones up.
+        // Navigation bars and tab strips spread their items across the full width; the margin is for content.
+        if (!scrollsSideways(el) && !el.closest('nav, [role=navigation], [role=tablist]')) {
+            const left = Math.min(...rects.map((r) => r.left));
+            const right = Math.max(...rects.map((r) => r.right));
+            const gap = Math.min(left, W - right);
+            if (gap >= 0 && gap < margin - 0.5)
+                push('warning', 'edge-margin', el, 'Text ' + Math.round(gap) + "px from the screen edge (Material's margin is " + margin + 'px at this width)');
+        }
+        // 6c. Line length: 45–75 characters a line, in every language (Android's app quality guidelines, web.dev).
+        if (el.querySelector('p, div, li, ul, ol, section, article, br, h1, h2, h3, h4'))
+            continue;
+        // Measured word by word: each word's line, then the longest full line (the last one may be short).
+        if (rects.length < 2)
+            continue;
+        const lineChars = [];
+        const walker = document.createTreeWalker(el, NodeFilter.SHOW_TEXT);
+        for (let t = walker.nextNode(); t; t = walker.nextNode())
+            for (const m of t.textContent.matchAll(/\S+\s*/g)) {
+                const range = document.createRange();
+                range.setStart(t, m.index);
+                range.setEnd(t, m.index + m[0].trimEnd().length);
+                const top = range.getBoundingClientRect().top;
+                const line = lineChars.find((l) => Math.abs(l.top - top) < size * 0.6);
+                if (line)
+                    line.n += m[0].replace(/\s+/g, ' ').length;
+                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));
+        if (longest > 80)
+            push('warning', 'measure', el, 'Lines of up to ' + longest + ' characters: keep prose to 45–75 (a max width of about 32em)');
+    }
+    // 6d. Touch targets: Material and Lighthouse want 48×48; a smaller one fails when the 48px square around its
+    // centre covers a quarter of its area of another target (about 8px apart is enough). Touch-sized windows only.
+    const named = (el) => text(el) || el.getAttribute('aria-label') || el.tagName.toLowerCase();
+    // Compared like overlaps (4b): behind an open modal only its own controls, and within one layer.
+    if (W < 600)
+        for (const el of solid) {
+            if (solid.some((o) => o !== el && o.contains(el)) || (el.matches('a') && el.closest('p')))
+                continue;
+            const r = el.getBoundingClientRect();
+            if (r.width >= 48 && r.height >= 48)
+                continue;
+            if (out.some((i) => i.type === 'tap-target' && i.selector === sel(el)))
+                continue;
+            const cx = r.left + r.width / 2;
+            const cy = r.top + r.height / 2;
+            const hit = solid.find((o) => {
+                if (o === el || o.contains(el) || el.contains(o) || layer(o) !== layer(el))
+                    return false;
+                const q = o.getBoundingClientRect();
+                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;
+            });
+            if (hit)
+                push('warning', 'tap-spacing', el, Math.round(r.width) + '×' + Math.round(r.height) + 'px and close to “' + named(hit).slice(0, 24) + '”: make it 48px or leave about 8px around it (Material, Lighthouse)');
+        }
+    // 6e. Forms (web.dev): a placeholder is a hint, not a label; it disappears as soon as someone types.
+    const visibleText = (n) => !!n && shown(n) && !!(n.textContent ?? '').trim();
+    for (const el of all) {
+        if (!el.matches('input, textarea'))
+            continue;
+        if (el.matches('[type=hidden], [type=checkbox], [type=radio], [type=submit], [type=button], [type=range], [type=search], [role=searchbox]'))
+            continue;
+        if (el.closest('[role=search], search'))
+            continue;
+        const f = el;
+        if (!f.placeholder)
+            continue;
+        const labelled = [...(f.labels ?? [])].some(visibleText) ||
+            (f.getAttribute('aria-labelledby') ?? '').split(/\s+/).some((id) => visibleText(document.getElementById(id)));
+        if (!labelled)
+            push('warning', 'placeholder-label', el, 'Its placeholder is its only label, and it disappears while typing: add a visible label (web.dev)');
+    }
+    // 6f. Every control has a name (Android's content descriptions, WCAG 4.1.2): an icon-only button needs a label.
+    for (const el of interactive) {
+        if (el.matches('input, select, textarea'))
+            continue;
+        const name = (el.textContent ?? '').trim() ||
+            el.getAttribute('aria-label') ||
+            el.getAttribute('title') ||
+            [...el.querySelectorAll('img[alt], svg title')].map((i) => i.getAttribute('alt') ?? i.textContent).join('').trim() ||
+            (el.getAttribute('aria-labelledby') ?? '').split(/\s+/).map((id) => document.getElementById(id)?.textContent ?? '').join('').trim();
+        if (!name)
+            push('warning', 'unnamed-control', el, 'An icon-only control with no name: screen readers announce nothing (add aria-label)');
+    }
+    // 6g. Material's navigation bar holds three to five destinations; more belong in a rail, a drawer or a page.
+    for (const el of all) {
+        if (!['fixed', 'sticky'].includes(getComputedStyle(el).position))
+            continue;
+        const r = el.getBoundingClientRect();
+        if (r.bottom < innerHeight - 2 || r.width < W * 0.8)
+            continue;
+        if (!el.matches('nav, [role=navigation], [role=tablist]') && !el.querySelector('nav, [role=navigation], [role=tablist]'))
+            continue;
+        const items = [...el.querySelectorAll('a[href], button, [role=tab]')].filter((i) => shown(i) && !i.parentElement?.closest('a[href], button, [role=tab]'));
+        if (items.length > 5)
+            push('warning', 'nav-destinations', el, items.length + " destinations in the bottom navigation: Material's navigation bar holds 3–5");
+    }
+    // 6h. Keyboard focus is visible (Material's focus state, web.dev, WCAG 2.4.7): focusing a control changes how
+    // it or its frame looks. Transitions are paused so a ring that fades in still counts.
+    const still = document.createElement('style');
+    still.textContent = '*, *::before, *::after { transition: none !important; animation: none !important }';
+    document.head.append(still);
+    const look = (e) => {
+        if (!e)
+            return '';
+        const c = getComputedStyle(e);
+        return [c.outlineStyle === 'none' ? '' : c.outlineStyle + c.outlineWidth + c.outlineColor, c.boxShadow, c.backgroundColor, c.borderColor, c.color, c.textDecorationLine].join('|');
+    };
+    const frameOf = (e) => [e, e.parentElement, e.parentElement?.parentElement ?? null].map(look).join('#');
+    const before = document.activeElement;
+    for (const el of interactive) {
+        const h = el;
+        if (h.disabled || opacity(h) < 0.05)
+            continue;
+        const was = frameOf(h);
+        h.focus({ preventScroll: true, focusVisible: true });
+        if (document.activeElement !== h)
+            continue;
+        const now = frameOf(h);
+        h.blur();
+        if (was === now)
+            push('warning', 'focus-visible', el, 'No visible focus: someone using a keyboard cannot see where they are (add a :focus-visible ring)');
+    }
+    before?.focus?.({ preventScroll: true });
+    still.remove();
     return out.sort((x, y) => (x.severity === y.severity ? 0 : x.severity === 'error' ? -1 : 1));
 }

package/dist/elements.js

@@ -30,6 +30,31 @@ export function translate(key, fallback, args) {
 }
 /** The locale the screen is shown in ("en", "ru", "ar-XB" for the right-to-left pseudo-language), or undefined. */
 export const screenLocale = () => globalThis.__stitch2?.lang;
+/**
+ * Each element renders on its own, so ids a framework generates (React's useId) repeat from one element to the
+ * next, and a label's for= finds the first field on the page. An id already on the page is renamed, with the
+ * attributes inside the element that point to it.
+ */
+let idCount = 0;
+const ID_REFS = ['for', 'aria-labelledby', 'aria-describedby', 'aria-controls', 'aria-owns', 'aria-activedescendant', 'list'];
+function uniqueIds(content) {
+    const renamed = new Map();
+    for (const el of Array.from(content.querySelectorAll('[id]'))) {
+        if (!document.getElementById(el.id))
+            continue;
+        const next = el.id + '-s2-' + ++idCount;
+        renamed.set(el.id, next);
+        el.id = next;
+    }
+    if (!renamed.size)
+        return;
+    for (const el of Array.from(content.querySelectorAll('*')))
+        for (const attr of ID_REFS) {
+            const v = el.getAttribute(attr);
+            if (v)
+                el.setAttribute(attr, v.split(/\s+/).map((id) => renamed.get(id) ?? id).join(' '));
+        }
+}
 const camel = (s) => s.replace(/-([a-z])/g, (_, c) => c.toUpperCase());
 export function defineElements(components, options) {
     const { prefix, render } = options;
@@ -70,6 +95,7 @@ export function defineElements(components, options) {
                         if (typeof props[key] === 'string' && !root.hasAttribute(`data-${key}`))
                             root.setAttribute(`data-${key}`, props[key]);
                 }
+                uniqueIds(t.content);
                 this.replaceWith(t.content);
                 if (options.after && !pending++)
                     queueMicrotask(() => {

package/package.json

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

@@ -25,6 +25,7 @@ References, read before the first screen:
 - [typography.md](references/typography.md): type levels and how to combine them; most polish is here.
 - [components.md](references/components.md): build from the shared components; the reuse ladder.
 - [screens.md](references/screens.md): screen names, versions, statuses, the user's approval and notes, desktop.
+- [google.md](references/google.md): Google's guidance (Material, Android, web.dev) as rules with numbers.
 - [guides.md](references/guides.md): the public sources behind the rules.
 
 ## Workflow
@@ -49,7 +50,9 @@ References, read before the first screen:
    fixed bars, fixed bars overlapping each other, tap targets, contrast, cramped text) and every warning about type (`type-*`), hand-built
    components (`reuse`), components that differ from the catalog (`consistency`) and colour values (`color`).
    Text running into other text (`text-overlap`) or out of its card (`overflow`) is an error; a short label cut
-   short with an ellipsis (`truncated`) is a warning to fix with room, not a smaller size. When DESIGN.md has a
+   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`,
+   `nav-destinations`, `focus-visible`; see google.md): fix them, or say in the hand-over why the screen breaks one. When DESIGN.md has a
    light and a dark theme, every screen is checked in both: an issue marked with a theme
    ("light theme: Low contrast…") is fixed in DESIGN.md's colours for that theme when it shows on many
    screens, or in the screen when it is one element. Look at both renders (`--light.png`). With `i18n`, check

package/skills/stitch2/references/google.md

@@ -0,0 +1,122 @@
+# Google's design guidance, as rules
+
+Google publishes its app and web design guidance in several places: Material Design 3 and its component
+libraries, Android's app quality guidelines, web.dev's Learn Design and Learn Forms courses, and Lighthouse's
+audits. This file restates what applies to screens in our own words, with Google's numbers. Rules marked
+**(check: name)** are measured by `stitch2 check` (warnings, so a screen can break one on purpose and say why);
+the rest are judged from the render. Where Google and DESIGN.md disagree, DESIGN.md wins for the project.
+
+## Layout and window sizes
+
+- **Design for width classes, not devices.** Material and Android group available width into classes:
+  compact under 600 px (phones), medium 600–839 (tablets in portrait, unfolded foldables), expanded 840–1199
+  (tablets in landscape, small laptops), large 1200–1599 and extra large from 1600 (desktops). A window can
+  change class while open (rotation, split screen, a resized browser), so a layout follows the width it has.
+- **Order of work:** the compact layout first, then expanded (the most room for change), then decide whether
+  medium needs its own layout or takes one of the two.
+- **A small screen is not a shrunk large one, and a large screen is not a blown-up small one** (web.dev). On a
+  wide window, add columns, panes or a side navigation; do not just widen the phone column.
+- **Navigation follows the class:** a bottom navigation bar in compact windows, a navigation rail at the side
+  in medium and expanded ones, a drawer (persistent) when there is room for labels and the app has many places.
+- **Canonical layouts** (Material): *list-detail* shows both panes side by side from expanded widths and one
+  pane at a time below that (narrowing keeps the detail that was open); *supporting pane* puts secondary
+  content beside the main one when there is room; *feed* is a grid of cards that adds columns as width grows.
+- **Margins:** content keeps 16 px from the window edge in compact windows and 24 px from medium up
+  **(check: edge-margin)**. Only deliberate horizontal scrollers (chip rows, carousels) run to the edge.
+- **Spacing on a 4 px grid** (Material's 4dp increments): the spacing scale in DESIGN.md should be multiples
+  of 4, with 2 px only inside small components.
+
+## Type
+
+- **Material's scale** has fifteen levels in five roles, each in three sizes: display 57 / 45 / 36, headline
+  32 / 28 / 24, title 22 / 16 / 14, body 16 / 14 / 12, label 14 / 12 / 11 (sp, at 1x). Titles and labels are
+  medium weight, the rest regular. An *emphasized* set adds weight, never size, for selection and headlines.
+  Map DESIGN.md's levels onto these roles when choosing sizes; the names can stay the project's.
+- **Smallest sizes:** nothing under 11 px (Material's label small), and body text from 12 px up; Lighthouse
+  wants at least 12 px for most of a page's text **(check: text-small)**. Prefer 14–16 for reading text.
+- **Line length 45–75 characters, in every language the app ships** (Android's app quality guidelines; about
+  66 is ideal, per web.dev). Cap prose with a max width in a relative unit, never in pixels: about `32em` lands on
+  45–75 characters in most fonts. `ch` is the width of the font's zero, which is wider than an average letter,
+  so `66ch` holds 80–90 characters in many sans-serifs **(check: measure)**.
+- **Line height** is unitless and follows line length: short lines can take more, long lines less (web.dev).
+  Material pairs 16/24 and 14/20 for body.
+- **Text resizes:** sizes in rem so the user's font size setting works; the layout still holds at 200%.
+- **Few fonts:** every web font file delays text; load what the type levels use and nothing else.
+
+## Touch, pointer and keyboard
+
+- **Touch targets 48 × 48 px** (Material, Android's quality guidelines, web.dev), about 9 mm; an icon of 24 px
+  gets padding up to 48. A smaller target needs about 8 px of space to its neighbours: Lighthouse fails a
+  target under 48 px when the 48 px square around its centre covers another target **(check: tap-spacing)**.
+  WCAG's 24 px floor is checked separately **(check: tap-target)**.
+- **Fine pointers** may take smaller targets, but Fitts's law still applies: shrink with care.
+- **Do not hide information behind hover.** Hover is optional (touch has none, keyboards focus instead); what
+  shows on hover must be reachable without it.
+- **Visible focus** on every control, styled with `:focus-visible`, in the order the screen reads
+  **(check: focus-visible)**. Material's focus state is a ring plus a light state layer.
+
+## Colour, states and themes
+
+- **Roles in pairs:** text on a colour uses that colour's "on" partner (on-primary on primary, on-surface on
+  surface). Depth comes from tonal surface containers (lowest to highest) rather than shadows.
+- **Contrast:** 4.5:1 for text under 18 px (14 px bold), 3:1 above **(check: contrast)**. Never colour alone:
+  a link also has an underline or weight; a status also has an icon or word.
+- **Light and dark:** Android's quality guidelines ask for both themes, and for web content shown in the app
+  to follow them (stitch2 checks every theme DESIGN.md defines).
+- **States as layers:** hover 8%, focus 10%, pressed 10%, dragged 16% of the content colour over the
+  container; disabled content at 38% and its container at 12%. Every interactive component defines them.
+- **Shape scale:** corners from a short scale (Material: 4, 8, 12, 16, 20, 28, 32, 48, full). Pick each
+  component's corner from DESIGN.md's `rounded` and keep it the same everywhere.
+
+## Components
+
+- **Navigation bar:** three to five destinations, each an icon with a one-line label; more destinations go to a
+  rail, a drawer or a page **(check: nav-destinations; label-wraps)**.
+- **Button emphasis:** filled for the one main action, tonal or outlined for secondary, text buttons for
+  low-emphasis; one floating action button at most.
+- **Icon-only controls have a name** that says what they do ("Share", not "Share button"); repeated items in a
+  list have different names; decorative icons are hidden from screen readers **(check: unnamed-control)**.
+- **Navigation on small screens** (web.dev): with a few links, show them; with many, let them scroll sideways
+  (the overflow pattern); hide them behind a toggle only as a last resort, and then label the toggle with a
+  word, not only an icon.
+- **Carousels** hide content: on small screens show a part of the next item so it reads as scrollable; on
+  large screens show a grid. No autoplay.
+
+## Forms (web.dev)
+
+- **Visible labels.** A placeholder is a hint about the format and vanishes while typing; it is never the
+  label **(check: placeholder-label)**. Search fields with a search icon are the accepted exception.
+- **The right control and keyboard:** `textarea` for several lines, `type="email"`, `tel`, `inputmode="decimal"`
+  so phones show the matching keyboard; a control looks like what it does (a link navigates, a button acts).
+- **One column, in reading order,** with related fields grouped and 48 px controls with room between them.
+
+## Motion
+
+- **Durations** (Material): short 50–200 ms for small changes (a switch, a ripple), medium 250–400 ms for
+  elements entering or expanding, long 450–600 ms for large transitions, up to 1000 ms only for full-screen
+  ones. Longer distance or area, longer duration.
+- **Easing:** standard `cubic-bezier(0.2, 0, 0, 1)` for movement within the screen; emphasized decelerate
+  `(0.05, 0.7, 0.1, 1)` for things entering, accelerate `(0.3, 0, 0.8, 0.15)` for things leaving.
+
+## Responsiveness of the product (for the app, beyond the screens)
+
+- Feedback within about two seconds: a progress indicator or skeleton when content takes longer.
+- State survives leaving and coming back (a half-filled form, a running timer); back navigation never loses work.
+- Logical properties (start/end) so right-to-left languages mirror; see the stitch2-i18n skill.
+
+## Sources
+
+- Material Components for Android, theming docs (type scale, shape, colour, motion):
+  github.com/material-components/material-components-android/tree/master/docs
+- Material Design 3: m3.material.io (layout, window size classes, canonical layouts, states, accessibility)
+- Android window size classes: developer.android.com/develop/ui/compose/layouts/adaptive/use-window-size-classes
+- Android canonical layouts: developer.android.com/develop/ui/compose/layouts/adaptive/canonical-layouts
+- Android core app quality: developer.android.com/docs/quality-guidelines/core-app-quality
+- Android adaptive app quality: developer.android.com/docs/quality-guidelines/large-screen-app-quality
+- Android accessibility: developer.android.com/guide/topics/ui/accessibility/apps
+- web.dev Learn Design (typography, macro layouts, UI patterns, interaction, accessibility, theming,
+  internationalization): web.dev/learn/design
+- web.dev Learn Forms, design basics: web.dev/learn/forms/design-basics
+- web.dev accessible tap targets: web.dev/articles/accessible-tap-targets
+- Lighthouse tap targets and font size audits: developer.chrome.com/docs/lighthouse/seo/tap-targets,
+  developer.chrome.com/docs/lighthouse/seo/font-size

package/skills/stitch2/references/guides.md

@@ -18,3 +18,7 @@ are restated in principles.md.
 | Vercel Geist typography (vercel.com/geist/typography) | yes | The type scale made for Geist by its authors: sizes, line heights and the tracking that suits it (and fonts like it) |
 | Apple HIG, Typography (developer.apple.com/design/human-interface-guidelines/typography) | yes | iOS Dynamic Type sizes, the SF Pro tracking table, minimum sizes (11pt), watchOS sizes |
 | Material 3 type scale (m3.material.io/styles/typography/type-scale-tokens) | yes | Role names (display, headline, title, body, label) and how labels open up at small sizes |
+| Google's guidance, restated as rules ([google.md](google.md)) | — | Window size classes, canonical layouts, Material's type, shape, state and motion numbers, 48 px targets, line length, forms |
+| Android app quality guidelines (developer.android.com/docs/quality-guidelines) | yes | What Google Play calls a quality app: 48dp targets, contrast, line length 45–75, light and dark, adaptive layouts |
+| web.dev Learn Design and Learn Forms (web.dev/learn/design, web.dev/learn/forms) | yes | Responsive layout, typography, navigation patterns, interaction (pointer, hover), accessibility, forms |
+| Lighthouse audits (developer.chrome.com/docs/lighthouse) | yes | The exact rules behind tap target spacing and legible font sizes |

package/skills/stitch2/references/principles.md

@@ -2,7 +2,8 @@
 
 In our own words; the ideas are common practice in interface design, drawn from Refactoring UI (Wathan &
 Schoger), Material 3, Apple's Human Interface Guidelines, WCAG 2.2 and the Laws of UX (see
-[guides.md](guides.md)); no text is copied from them. Items marked **(check)** are measured by `stitch2 check`;
+[guides.md](guides.md)); no text is copied from them. Google's guidance (Material, Android's app quality
+guidelines, web.dev, Lighthouse) is gathered with its numbers in [google.md](google.md). Items marked **(check)** are measured by `stitch2 check`;
 the rest are judged from the render. Colour names below are roles: the project's DESIGN.md names the actual
 colours (its accent, its primary and secondary text, its surface steps).
 
@@ -28,7 +29,8 @@ colours (its accent, its primary and secondary text, its surface steps).
 - Align to a few vertical lines: the page edge, the card's inner edge, one column for numbers. Numbers in lists
   are right-aligned so their digits line up.
 - Fewer borders. Separate with spacing or a surface step first, a hairline second, never a card inside a card.
-- Do not fill the width because it is there; prose reads best at about 60 characters a line.
+- Do not fill the width because it is there; prose reads best at 45–75 characters a line, in every language
+  the product ships (**check: measure**).
 
 ## Type
 
@@ -58,7 +60,11 @@ short labels never wrap **(check)**.
 
 ## Touch and mobile
 
-- Tap targets at least 44 px for buttons; smaller ones only with spacing **(check)**.
+- Tap targets 48 px (Google: Material, Android, Lighthouse; Apple's minimum is 44); smaller ones only with
+  about 8 px of space around them **(check: tap-target, tap-spacing)**.
+- Content keeps 16 px from the screen edge on phones, 24 px from 600 px up **(check: edge-margin)**.
+- Every control shows keyboard focus and every icon-only control has a name **(check: focus-visible,
+  unnamed-control)**; form fields have visible labels, not placeholders **(check: placeholder-label)**.
 - The primary action sits in the thumb zone (lower half or a docked bar); destructive actions far from it.
 - Fixed bars never cover content: the scroll ends with enough bottom padding **(check)**.
 - Nothing wider than the frame; only chip rows and tab strips scroll sideways **(check)**.

package/skills/stitch2/references/screens.md

@@ -60,6 +60,11 @@ frame width 1280, the same components and type levels, the layout from DESIGN.md
 of a tab bar, a content max width, two columns where it helps). Shared components get their desktop form in the
 component, before the first desktop screen.
 
+Widths follow Google's window size classes ([google.md](google.md)): compact under 600 px (the phone frame),
+medium 600–839, expanded 840–1199, large from 1200 (the desktop frame). A desktop screen is a layout for the
+width class, not a stretched phone: a side navigation instead of the bar, list-detail with both panes, extra
+columns for feeds. When a project needs a tablet, it is a medium-width device of the same screen.
+
 ## The canvas
 
 `stitch2 canvas` → http://localhost:4400. The sidebar lists DESIGN.md (drawn as tokens and rules), the

package/skills/stitch2/references/typography.md

@@ -30,6 +30,9 @@ together. A typical app set (sizes for a 390 px phone):
   utilities on text: that is how screens drift into twenty slightly different styles.
 - Add a level only when a real use appears on two screens and nothing fits. Never solve a one-off with an
   in-between size.
+- Nothing under 11 px, body text from 12 px, reading text 14–16 px **(check: text-small)**; prose at 45–75
+  characters a line, a max width of about `32em` **(check: measure)**. Material's fifteen-level scale and its sizes are in
+  [google.md](google.md).
 
 ## 2. Hierarchy recipes