stitch2 0.8.0 → 0.9.1

package/README.md

@@ -40,7 +40,8 @@ file that already exists. From there the agent spends its effort on the design.
   Pick mode (`P`) highlights any element of a screen and copies a reference with its source line, such as
   `home mobile v1 (design/screens/home/mobile-v1.html:36) <gg-button> “Start Push”`; Shift-click collects
   several to copy at once or add to the version's note.
-- **Checks** (`stitch2 check`): content past the frame edge, labels that wrap, content under fixed bars, fixed bars that overlap each other, tap
+- **Checks** (`stitch2 check`): content past the frame edge or out of its card, labels that wrap, text running into
+  other text, labels cut short with an ellipsis, content under fixed bars, fixed bars that overlap each other, tap
   targets (WCAG 2.2), text contrast in every theme, text that is not one of DESIGN.md's type levels, capitals without tracking,
   large numbers in monospace, components built by hand, components that differ between screens, and colours
   written as values instead of DESIGN.md tokens.
@@ -164,6 +165,24 @@ put a page into the state the design shows (open a sheet, start a workout). The
 an error on that version and the run goes on. When it opens a modal, wait for something inside it (a marked
 component): dialog roots are often zero-sized wrappers, which Playwright reports as hidden.
 
+### In your own tests: every language, every width
+
+The layout rules are a plain function you can run on any page, so an app's own Playwright tests can check what
+mock-ups never show: long translations, right-to-left layouts, narrow phones.
+
+```ts
+import { audit } from 'stitch2/audit'
+
+for (const locale of ['de', 'ru', 'ar']) {
+  // …open the page in that language…
+  const issues = await page.evaluate(audit, { comfortable: 32 })
+  const errors = issues.filter((i) => i.severity === 'error') // overflow, text-overlap, label-wraps, …
+}
+```
+
+Warnings worth reading for translations: `truncated` (a label cut short with an ellipsis), `text-crowded` (two
+controls' labels nearly touching) and `clipped`.
+
 ## Commands
 
 | Command | What it does |

package/dist/audit.d.ts

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

package/dist/audit.js

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

package/package.json

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

package/skills/stitch2/SKILL.md

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