stitch2 0.25.1 → 0.27.0

package/README.md

@@ -283,7 +283,7 @@ layout first, then a shorter natural word, never a smaller type size.
 | `stitch2 init --name N --primary #hex [options]` | Writes a complete DESIGN.md from a few choices |
 | `stitch2 extract <url or file…>` | Writes a DESIGN.md measured from an existing site or screens |
 | `stitch2 canvas` | The canvas at http://localhost:4400 (`PORT` and `HOST` to change) |
-| `stitch2 check [filter] [--shots] [--strict] [--locales l,…]` | All checks, in every theme, app state and check language; `--shots` saves renders to `<design>/renders/` (`--light.png`, `--pseudo.png`, `--auth-user.png`…). Reruns visit only the screens that changed; after a change to stitch2, DESIGN.md, the tokens, the components or the catalog every screen is visited again, which takes minutes on a large project. Progress is printed to stderr, and `checks.json` is saved as screens finish and when the run is stopped (Ctrl-C), so the next run continues where it left off |
+| `stitch2 check [filter] [--shots] [--strict] [--archived] [--locales l,…]` | All checks, in every theme, app state and check language, on every version that is not archived (`--archived` adds the outdated ones); `--shots` saves renders to `<design>/renders/` (`--light.png`, `--pseudo.png`, `--auth-user.png`…). Reruns visit only the screens that changed; after a change to stitch2, DESIGN.md, the tokens, the components or the catalog every screen is visited again, which takes minutes on a large project. Progress is printed to stderr, and `checks.json` is saved as screens finish and when the run is stopped (Ctrl-C), so the next run continues where it left off |
 | `stitch2 i18n [filter] [--locale l] [--suggest] [--json]` | Message keys the source or a locale lacks, and screen text with no key |
 | `stitch2 consistency [kind…]` | The consistency report, `<design>/consistency/index.html` |
 | `stitch2 type [filter] [--json]` | The type audit |

package/dist/audit.d.ts

@@ -9,6 +9,7 @@ export declare const LAYOUT_ERRORS: string[];
 export declare function audit(opts: {
     comfortable: number;
     durations?: number[];
+    secondary?: string;
 }): Promise<Issue[]>;
 /**
  * Runs inside the page with prefers-reduced-motion: reduce. What still moves (an animation of transform,

package/dist/audit.js

@@ -772,6 +772,42 @@ export async function audit(opts) {
         if (longest > 80)
             push('warning', 'measure', el, 'Lines of up to ' + longest + ' characters: keep prose to 45–75 (a max width of about 32em)');
     }
+    // 6e. Text tiers: a sentence to read belongs in the body colour (skills/stitch2/references/typography.md, section 3). A block of reading
+    // copy, drawn in the secondary colour, is the usual reason a page reads dull although every contrast ratio passes: the strokes of small
+    // text reach only their own colour. A block is reading copy when it holds sixty characters and eight words of its own text and sits in
+    // the page's content: not in a bar, a table, a menu, a label, a control, a link or a code sample. It needs the secondary colour, which
+    // check takes from DESIGN.md's text-muted and passes as a CSS colour the page can resolve (var(--<prefix>-text-muted)).
+    if (opts.secondary) {
+        const canvas = document.createElement('canvas');
+        canvas.width = canvas.height = 1;
+        const g = canvas.getContext('2d', { willReadFrequently: true });
+        const rgba = (value) => {
+            g.clearRect(0, 0, 1, 1);
+            g.fillStyle = '#000';
+            g.fillStyle = value;
+            g.fillRect(0, 0, 1, 1);
+            const d = g.getImageData(0, 0, 1, 1).data;
+            return [d[0], d[1], d[2], d[3] / 255];
+        };
+        const probe = document.createElement('span');
+        probe.style.color = opts.secondary;
+        document.body.append(probe);
+        const want = rgba(getComputedStyle(probe).color);
+        probe.remove();
+        const quiet = (el) => {
+            const have = rgba(getComputedStyle(el).color);
+            return Math.abs(have[0] - want[0]) <= 2 && Math.abs(have[1] - want[1]) <= 2 && Math.abs(have[2] - want[2]) <= 2 && Math.abs(have[3] - want[3]) <= 0.02;
+        };
+        const apart = 'nav, footer, table, button, summary, label, a, code, pre, figcaption, caption, [role=navigation], [role=tablist], [role=tab], [role=menu], [role=listbox], [role=tooltip], [role=button], [aria-hidden=true]';
+        for (const el of all) {
+            if (!ownText(el) || opacity(el) < 0.1 || el.closest(apart))
+                continue;
+            const own = [...el.childNodes].filter((n) => n.nodeType === 3).map((n) => n.textContent).join(' ').replace(/\s+/g, ' ').trim();
+            if (own.length < 60 || own.split(' ').length < 8 || !quiet(el))
+                continue;
+            push('warning', 'text-tier', el, 'Reading copy in the secondary colour: a sentence to read takes the body colour, and the secondary one is for hints, captions and counts');
+        }
+    }
     // 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();

package/dist/check.js

@@ -16,6 +16,8 @@
  * Usage: stitch2 check [path filter…] [--shots] [--strict] [--locales ru,ar | all | none]
  *   --shots   also save page-tall renders to design/renders/ (one per theme, app state, language and width)
  *   --strict  exit 1 when any screen has errors (for CI and agent loops)
+ *   --archived  also check archived versions, which are left out otherwise: they are outdated (superseded or rejected),
+ *             hidden on the canvas, and nothing is built from them, so checking them costs time and reports errors in history
  * Screens run four at a time; reruns only visit screens that changed since design/checks.json (or
  * everything DESIGN.md, the tokens, the components, the catalog or stitch2 itself changed since: a first run after
  * that visits every screen and takes minutes on a large project). Progress goes to stderr, one line per screen
@@ -30,7 +32,7 @@ import { fingerprintPaths } from './cache.js';
 import { colourIssues } from './colours.js';
 import { CONFIG_FILE, checkWidths, config, modes } from './config.js';
 import { collectComponents, collectOptions, consistencyIssues, reuseIssues, } from './consistency.js';
-import { designThemes, motionDurations, typeLevels } from './design-md.js';
+import { designThemes, motionDurations, readDesign, typeLevels } from './design-md.js';
 import { checkLocales } from './i18n.js';
 import { listScreens, ROOT } from './screens.js';
 import { startServer } from './serve.js';
@@ -43,18 +45,33 @@ const strict = args.includes('--strict');
 const localesFlag = args.indexOf('--locales');
 const locales = checkLocales(localesFlag >= 0 ? args[localesFlag + 1] : undefined);
 const filters = args.filter((a, i) => !a.startsWith('--') && (localesFlag < 0 || i !== localesFlag + 1));
-const screens = listScreens().filter((s) => !filters.length || filters.some((f) => s.path.includes(f)));
+const matching = listScreens().filter((s) => !filters.length || filters.some((f) => s.path.includes(f)));
+const screens = args.includes('--archived') ? matching : matching.filter((s) => s.status !== 'archived');
+const archivedLeftOut = matching.length - screens.length;
+if (archivedLeftOut)
+    console.log(`${archivedLeftOut} archived screen${archivedLeftOut === 1 ? ' is' : 's are'} not checked (--archived includes ${archivedLeftOut === 1 ? 'it' : 'them'}).`);
+if (!screens.length && matching.length)
+    process.exit(0);
 const levels = typeLevels();
 const themes = designThemes();
 const appModes = modes();
 const collect = collectOptions();
-/** What the layout audit needs: the comfortable tap size and DESIGN.md's motion durations. */
-const auditOpts = { comfortable: config.comfortableTarget, durations: (() => { try {
+/** What the layout audit needs: the comfortable tap size, DESIGN.md's motion durations and its secondary text colour (text-muted, for text-tier). */
+const auditOpts = {
+    comfortable: config.comfortableTarget,
+    durations: (() => { try {
         return motionDurations();
     }
     catch {
         return [];
-    } })() };
+    } })(),
+    secondary: (() => { try {
+        return 'text-muted' in readDesign().colors ? 'var(--' + config.prefix + '-text-muted)' : undefined;
+    }
+    catch {
+        return undefined;
+    } })(),
+};
 const server = await startServer(0);
 /** The tallest render, in CSS px: a long landing page is shot whole (the canvas draws frames up to the same height). */
 const MAX_RENDER_HEIGHT = 20000;

package/package.json

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

@@ -53,7 +53,7 @@ References, read before the first screen:
    **stitch2-i18n**). Write the text as **stitch2-copy** says (the reader's outcome, plain words, the product's terms),
    and translate it with **stitch2-translate**. Never add classes to a component to change how it looks, and never write a colour value (hex,
    `rgb()`, `hsl()`): only DESIGN.md's colours, as token classes or `var(--<prefix>-<name>)`.
-5. **Check** `stitch2 check <path> --shots --strict`. Fix every error (overflow, wrapped labels, content under
+5. **Check** `stitch2 check <path> --shots --strict` (archived versions are outdated and are not visited; `--archived` includes them). Fix every error (overflow, wrapped labels, content under
    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`).
@@ -68,7 +68,7 @@ References, read before the first screen:
    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`,
-   `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
+   `nav-destinations`, `focus-visible`, `text-tier`; see google.md): `text-tier` is a block of reading copy (sixty characters, eight words, in the page's content and not in a bar, table, control or link) drawn in DESIGN.md's `text-muted`; give it the body colour (typography.md, section 3): 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
@@ -132,7 +132,7 @@ References, read before the first screen:
 |---|---|
 | `setup [--name N --primary #hex] [options]` | Sets a project up in one step; keeps every file that exists |
 | `canvas` | The canvas at http://localhost:4400: screens and versions, DESIGN.md, the consistency report, approval and notes |
-| `check [filter] [--shots] [--strict] [--locales l,…]` | Layout, type, reuse and consistency checks, in every theme, app state and check language, and at both ends of each variant's widths; `--shots` saves renders |
+| `check [filter] [--shots] [--strict] [--archived] [--locales l,…]` | Layout, type, reuse and consistency checks, in every theme, app state and check language, and at both ends of each variant's widths; `--shots` saves renders; archived versions are left out unless `--archived` asks for them |
 | `i18n [filter] [--locale l] [--suggest]` | Message keys screens use that the source or a locale lacks, and text with no key (stitch2-i18n) |
 | `consistency [kind…]` | Every shared component cropped from every screen, next to the catalog's version |
 | `type [filter] [--json]` | Every text style a screen uses and the type level it matches |

package/skills/stitch2/references/google.md

@@ -34,6 +34,11 @@ the rest are judged from the render. Where Google and DESIGN.md disagree, DESIGN
   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.
+- **Reading copy is a body, not a caption.** A sentence a person reads (an introduction, a card's description, an
+  answer) is Material's body: 14/20 at the smallest (body medium), 16/24 for long passages (body large). Material 3
+  gives the 12 and 11 sizes to labels and captions: buttons, chips, the unit under a number, "very small text in the
+  content body, such as captions". The Lighthouse font-size audit (12 px for 60% of a page's text; retired in
+  Lighthouse 13) is a floor, not a recommendation. Body line height is about 1.5 times the size.
 - **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,
@@ -61,6 +66,12 @@ the rest are judged from the render. Where Google and DESIGN.md disagree, DESIGN
   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.
+- **Text tiers on a dark theme:** the default text colour is "on surface", and "on surface variant" is the lower-emphasis
+  alternative (Material 3). In its baseline dark scheme they are #E6E1E5 and #CAC4D0 on #1C1B1F: about 89% and 77%
+  of white. Material 2's dark theme used 87% (high emphasis), 60% (medium emphasis and hints) and 38% (disabled); the
+  60% tier reads dim for anything a person reads. Neither uses pure white for text, which vibrates and bleeds on a
+  dark surface. A secondary text colour below about 75% of white is a defect for text that carries meaning, and a
+  sentence of reading copy in the secondary colour is flagged by `check` **(check: text-tier)**.
 - **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
@@ -121,3 +132,6 @@ the rest are judged from the render. Where Google and DESIGN.md disagree, DESIGN
 - 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
+- Material 3 typography, applying type (body, label, line height): m3.material.io/styles/typography/applying-type
+- Material 2 dark theme (text emphasis, no pure white): m2.material.io/design/color/dark-theme.html and
+  codelabs.developers.google.com/codelabs/design-material-darktheme/

package/skills/stitch2/references/principles.md

@@ -42,7 +42,8 @@ short labels never wrap **(check)**.
 ## Colour and depth
 
 - One accent with one meaning ("act here"). Two accent-filled elements in one region: one of them is wrong.
-- Greys carry the structure: a few surface steps and two text colours do almost all the work.
+- Greys carry the structure: a few surface steps and two text colours do almost all the work, and the reading copy
+  is in the stronger of the two (typography.md, section 3).
 - Status colours appear as small text, icons or thin bars, never as large fills.
 - Text contrast at least 4.5:1, 3:1 for large text **(check)**. Secondary text on raised surfaces is where this
   fails.

package/skills/stitch2/references/typography.md

@@ -36,6 +36,9 @@ together. A typical app set (sizes for a 390 px phone):
 - 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).
+- A meta or caption level (12–13 px) is for counts, dates, units and hints. A sentence a person reads (an
+  introduction, a card's description, an answer) takes a body level, 14 px at the smallest: a caption size that
+  carries a sentence is the usual cause of a page that reads small.
 
 ## 2. Hierarchy recipes
 
@@ -53,8 +56,34 @@ To make something stand out inside a row, change its weight or colour, not its s
 
 ## 3. Text colour
 
-- Primary text for what the user reads first or acts on; secondary for everything else; a third, faint grey
-  only for disabled text and separators (it usually fails 4.5:1, so it never carries information).
+- Three tiers, by what the text does and not by how it looks: **strong** for headings and values, **body** for reading
+  copy, **secondary** for what the eye may skip (hints, captions, counts, dates, labels); a faint grey only for
+  disabled text and separators (it usually fails 4.5:1, so it never carries information).
+- Reading copy takes the body colour, whatever its size. On a dark theme a good set is about 95%, 85–90% and 75–80%
+  of white for the three tiers (Material 3's two text roles are about 89% and 77%; see [google.md](google.md)); on a
+  light theme the same steps in the ink colour.
+- **A contrast ratio does not show a dull page.** Every tier can pass 4.5:1 and a page still read grey, because the
+  strokes of small text reach only their own colour: a thin 13 px stroke in a 70% grey is what the eye sees, not the
+  ratio. The glyph edges are not the problem either (they render as sharp as a clean page); the colour and the tier
+  are. Measure the share of characters in each tier: when most of a page's characters are in the secondary colour,
+  or a paragraph of two sentences is, the copy is in the wrong tier. `check` warns about the second case **(check: text-tier)**: a block of
+  reading copy (sixty characters and eight words of its own text, in the page's content and not in a bar, table, menu,
+  label, control or link) drawn in DESIGN.md's `text-muted`. It needs that colour in DESIGN.md and is silent without it.
+
+  ```js
+  // characters per computed colour and size, from the rendered page (run it with Playwright's page.evaluate)
+  const share = () => {
+    const tally = {}; let total = 0;
+    const walker = document.createTreeWalker(document.body, NodeFilter.SHOW_TEXT);
+    for (let node = walker.nextNode(); node; node = walker.nextNode()) {
+      const text = node.textContent.trim(), element = node.parentElement;
+      if (!text || !element.checkVisibility()) continue;
+      const style = getComputedStyle(element), key = style.color + ' ' + style.fontSize;
+      tally[key] = (tally[key] ?? 0) + text.length; total += text.length;
+    }
+    return Object.entries(tally).map(([key, count]) => [key, Math.round(100 * count / total) + '%']).sort((a, b) => parseInt(b[1]) - parseInt(a[1]));
+  };
+  ```
 - Accent-coloured text means "active" or "act here". Check its contrast on every surface it sits on: accent text
   on a tinted accent background over a raised surface is a common failure.
 - Status colours colour short values and words, never sentences.
@@ -110,3 +139,5 @@ Devanagari; `tokens.css` falls back to Noto and system fonts.
 3. Secondary text differs by colour and weight, not just size.
 4. Numbers are tabular; large ones proportional; units smaller and secondary.
 5. At most three levels per region; capitals only in section labels; nothing wraps that should not.
+6. `check` shows no `text-tier` warning: reading copy is in the body colour and at 14 px or more, and most of the page's
+   characters are not in the secondary colour (section 3).

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

@@ -82,7 +82,7 @@ Read the findings as:
 ## Before you call it done
 
 1. Every screen you implemented is approved, and `stitch2 screens --strict` passes: one current version each.
-2. `stitch2 check --strict` passes on the screens you touched (archived screens excepted).
+2. `stitch2 check --strict` passes on the screens you touched (it leaves archived screens out).
 3. `stitch2 compare` has no errors for the screens you touched; warnings are explained (a kept feature) or fixed.
 4. `stitch2 look` and `stitch2 geometry` report nothing on the screens you touched, except differences you can
    name as data.

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

@@ -32,7 +32,9 @@ The generated prose is correct but generic. Make it the product's:
 1. **Overview**: the product, its users, the mood, in two or three sentences.
 2. **Colors**: keep the role names (other skills and the components use them); give each a short brand name in
    the prose if the team has one. Extracted colours are guesses where the page was ambiguous: confirm text,
-   surfaces and the primary with the user.
+   surfaces and the primary with the user. Define three text colours (strong, body, secondary) and write which text
+   takes which: reading copy is the body colour, the secondary one is for hints, captions, counts and dates (on a
+   dark theme about 95%, 85–90% and 75–80% of white; typography.md, section 3 of the stitch2 skill).
 3. **Typography**: keep the levels; adjust sizes only together with the user and only on the scale.
 4. **Components**: name the product's real components (its tab bar items, its core list row) and their states.
    Each interactive one gets hover, pressed, focus, selected and disabled in the prose, in values ("darkens to