stitch2 0.0.0-stage → 0.7.2

package/skills/stitch2/SKILL.md

@@ -0,0 +1,80 @@
+---
+name: stitch2
+description: Design app screens as HTML with the stitch2 design lab — a canvas, layout and type checks, shared components, screen versions and the user's approval — on a project's DESIGN.md. Use when drafting or redesigning a screen or flow, fixing what the checks flag, comparing variants, or running a blind design trial.
+---
+
+# Designing screens with stitch2
+
+stitch2 is a design lab for agents. A screen is one HTML file (Tailwind from a CDN, the project's generated
+tokens, an icon set) at phone or desktop width. stitch2 renders it in Chromium, checks it, and shows every screen
+version on a canvas where the user approves, archives or comments on each one. The design system is the
+project's `DESIGN.md` in Google's DESIGN.md format: tokens in the YAML front matter, rules in the prose.
+
+The project tunes all of this in `stitch2.config.json` (folders, the prefix of its meta tags, components and
+CSS variables, screen order) and in a **project skill** with its specifics: brand, components, screen names,
+data. Read the project skill first when there is one; it wins over this one where they differ.
+
+A project without stitch2 yet: ask the user for the product name, brand colour and modes, then run
+`stitch2 setup --name "…" --primary "#…" --modes …` (config, DESIGN.md and tokens, template, catalog, starter
+components, and these skills linked). No DESIGN.md yet, or a new look: build it first with the
+**stitch2-design-md** skill (`stitch2 init` or `stitch2 extract`).
+
+References, read before the first screen:
+
+- [principles.md](references/principles.md): what makes a screen read well, and the review rubric.
+- [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.
+- [guides.md](references/guides.md): the public sources behind the rules.
+
+## Workflow
+
+1. **Read** the brief, DESIGN.md, the references, the project skill and the component catalog (on the canvas,
+   or its render under `<design>/renders/`). Run `stitch2 screens`: approved versions are the reference, notes
+   are the user's feedback. A systemic change (a colour, a type level, a component) goes into DESIGN.md first,
+   then `stitch2 lint` and `stitch2 tokens`.
+2. **Inventory.** List every element the brief names, in order, with its real data. That list is the screen:
+   add nothing (status bars, step labels, tips, helper text, extra buttons), drop nothing. Next to each element
+   write the catalog component that shows it; adapt or extend components rather than inventing markup.
+3. **Hierarchy before markup.** Name the one thing the user came for, the single primary action (the only
+   accent-filled element in its region), and what is secondary. Give every text element a type level and a
+   colour before writing markup.
+4. **Build** the next version, `<screens>/<screen>/<device>-v<N>.html`, from the project's template (status
+   `draft`; never edit an approved version). Assemble it from the components; plain markup only where none
+   applies, with token classes, `.type-<level>` classes for text, the spacing scale, and the states DESIGN.md
+   defines. 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
+   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`).
+6. **Look and critique.** View the render in `<design>/renders/` (crop the first screenful). Score it with the
+   rubric in principles.md, fix what fails, repeat 5–6 at most three times.
+7. **Hand over.** Set the version's status to `review`, point the user to it on the canvas, and report what
+   changed, how you answered their notes, and any rubric item you could not satisfy. The user approves.
+
+## Commands
+
+`stitch2 <command>` from the project (through its package manager when stitch2 is a dev dependency):
+
+| Command | What it does |
+|---|---|
+| `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]` | Layout, type, reuse and consistency checks; `--shots` saves renders |
+| `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 |
+| `screens [name] [--status s] [--json]` | Every version with its status and the user's note |
+| `compare [screen…]` | The live app against the approved versions: missing or extra components, order, looks; a side-by-side report |
+| `elements <entry>` | Bundles the app's components, turned into elements with `stitch2/elements`, for the screens |
+| `tokens` | `tokens.css` (colours, `.type-*` classes) and `tailwind.tokens.js` from DESIGN.md |
+| `lint` | Google's DESIGN.md linter |
+| `localize [filter]` | Copies remote images a screen uses into its `assets/` folder |
+| `init`, `extract` | Build DESIGN.md from choices, or measure it from an existing site (stitch2-design-md) |
+| `sandbox create <dir> <brief.md>…`, `sandbox import <dir>` | Fresh-eyes versions from agents that see no other versions (stitch2-variants) |
+
+## Alternatives and fresh eyes
+
+When the user wants options or a new direction, or a design is stuck, do not iterate on the existing versions:
+use the **stitch2-variants** skill. Fresh agents in sandboxes design from the brief without seeing the other
+versions, and their screens come back as new versions to compare on the canvas. The same skill tests changes to
+the skills or DESIGN.md.

package/skills/stitch2/references/components.md

@@ -0,0 +1,59 @@
+# Components: reuse before you create
+
+Screens are assembled from the project's shared components: light-DOM custom elements named
+`<prefix>-<name>` (the prefix from `stitch2.config.json`), each rendering the same markup with the type levels
+and every state, and marking itself `data-<prefix>="<name>"`. The **component catalog** (a screen in the
+config's `catalogDir`, first on the canvas) shows every component with its variants, and it is the reference
+`check` and `stitch2 consistency` compare every screen with. The project skill lists its components.
+
+Two screens that both show a tab bar, a header, a list or a button must show the same one: same size, type,
+colour, icons and states. Users learn an element once; every variant costs attention and looks like a mistake.
+
+## The ladder
+
+Go down only when the step above cannot work:
+
+1. **Use** a component as it is.
+2. **Use a variant** it already has (variant, size, selected, state…).
+3. **Adapt the content** to the component: a shorter label, an icon it supports, two rows instead of a custom
+   grid. A brief describes what to show, not which markup to invent.
+4. **Extend the component**: add the attribute or variant to the component, show it in the catalog, describe it
+   in DESIGN.md if it is a new look. Every screen gets it, and the change is reviewed once.
+5. **Create a component** only when nothing fits and the element appears on more than one screen; give it a
+   name, add it to the catalog and the project skill. A one-screen element may stay plain markup.
+
+Never restyle a component on one screen, copy its markup by hand, or build a near-twin ("a chip, but 30 px").
+
+## Components from the app
+
+When the project builds its elements from the app's own components (`stitch2/elements›, bundled with
+`stitch2 elements <entry>›), the catalog and every screen show exactly what the app renders. Then a change to
+a component is a change to the app's component: edit it there, rebuild the bundle, and look at the catalog;
+never patch the bundle or restyle the element on a screen. Props are the element's attributes (kebab-case,
+an empty attribute is true) and its content is children. A component the screens need but the app lacks is
+added to the app first, with the same name.
+
+## Colours come from DESIGN.md
+
+Every colour on a screen and in a component is one of DESIGN.md's: a token class (`bg-surface`,
+`text-muted`, …) or `var(--<prefix>-<name>)`, and for a shade a mix of those
+(`color-mix(in srgb, var(--<prefix>-accent) 30%, transparent)`). Then a colour changed in DESIGN.md and
+`stitch2 tokens` changes every screen at once. A colour DESIGN.md lacks (an illustration's backdrop, a chart
+series) is added to DESIGN.md first, with a line in the prose saying where it is used.
+
+## What the checks report
+
+- **reuse**: on a lab screen, an element that looks like a catalog component but was built by hand (a bottom
+  bar with three or more buttons, an h1, a primary-filled button, a pill chip, a header icon button, a caps
+  label).
+- **consistency**: a component whose size, radius, font, icon set or icons differ from the catalog's version
+  (or, without a catalog, from the majority of screens in its family), or that appears in two versions on one
+  screen. `stitch2 consistency` shows the same as cropped images; see the stitch2-consistency skill.
+- **color**: a hex, `rgb()` or `hsl()` value in a lab screen's markup, or (reported on the catalog) in the
+  component scripts it loads, with the file and line.
+
+## Generated drafts
+
+Generators such as Google Stitch produce each screen on its own and cannot share components, so their chrome
+drifts from screen to screen. Treat generated screens as drafts of layout and content; the catalog decides how
+shared components look. When a draft has a better element, adopt it by changing the component (step 4).

package/skills/stitch2/references/guides.md

@@ -0,0 +1,20 @@
+# Guides worth reading
+
+The skill works from principles.md and DESIGN.md; these are the sources behind them. Fetch the free ones when
+a question goes deeper than the principles (a component's anatomy, a platform convention, an accessibility
+rule). Paid books are listed for the humans on the team; an agent cannot read them, which is why their ideas
+are restated in principles.md.
+
+| Source | Free | Use it for |
+|---|---|---|
+| Material 3 (m3.material.io) | yes | Component anatomy and states, colour roles (stitch2 generates them as `md-*` tokens), type scale, motion durations |
+| Apple Human Interface Guidelines (developer.apple.com/design/human-interface-guidelines) | yes | iOS conventions, sheets, tab bars, watchOS |
+| WCAG 2.2 (w3.org/TR/WCAG22) | yes | Contrast (1.4.3), target size (2.5.8), focus, motion |
+| Laws of UX (lawsofux.com) | yes | Fitts, Hick, Jakob, proximity and similarity, with short explanations |
+| Refactoring UI, Adam Wathan & Steve Schoger (refactoringui.com) | no | The most practical book on hierarchy, spacing, colour and depth; principles.md restates its main ideas |
+| Google's material-color-utilities (github.com/material-foundation/material-color-utilities) | yes | Generating tonal palettes and roles from a seed (`tokens` uses it) |
+| DESIGN.md format (github.com/google-labs-code/design.md, npm `@google/design.md`) | yes | The file format of DESIGN.md (the one Stitch reads and writes); `stitch2 lint` runs its linter, and `design.md export css-tailwind` emits Tailwind v4 `@theme` for the app |
+| Stitch skills (github.com/google-labs-code/stitch-skills) | yes | How Google prompts Stitch: content and structure in prompts, all style in the design system |
+| 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 |

package/skills/stitch2/references/principles.md

@@ -0,0 +1,80 @@
+# Principles for screens that read well
+
+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`;
+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).
+
+## Hierarchy
+
+- Decide what matters before styling. Each screen has one focal point and one primary action; everything else
+  steps back.
+- Emphasise by de-emphasising: make secondary text the secondary colour and a lighter weight rather than making
+  the important thing bigger and louder. At most three text styles per region.
+- Weight and colour carry hierarchy better than size. A semibold primary-colour label over a smaller
+  secondary-colour line reads as a pair; two sizes of the same colour do not.
+- Labels are the last resort. A value needs no "Weight:" in front when its card is titled "Body weight"; when a
+  label is needed it is the quiet part and the value is the loud part.
+- Buttons follow the action's importance, not its existence: one filled primary, secondary on a surface step,
+  rare or destructive actions as text or icon buttons.
+
+## Layout and spacing
+
+- Start with too much space and remove it. Crowded is the common failure.
+- Use the spacing scale from DESIGN.md; never a value between two steps.
+- Spacing shows grouping: the gap inside a group is smaller than the gap between groups. Ambiguous spacing is
+  a bug.
+- 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.
+
+## Type
+
+The full guide is [typography.md](typography.md). In short: every text element is one of DESIGN.md's type
+levels **(check)**; hierarchy by weight and colour first; tabular figures on numbers, and large numbers in a
+proportional font **(check)**; tracking follows size **(check: capitals)**; wrapped text has room **(check)**;
+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.
+- 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.
+- Depth from surface steps, not shadows; an overlay (sheet, docked bar) may use one soft shadow.
+
+## Data and content
+
+- Real-looking data with irregular numbers. No round placeholders, no "Lorem", no John Doe.
+- Show only what the brief describes. Every invented chip, tip, badge, statistic or helper line is a defect.
+- Labels that make the described data readable belong in the screen even when the brief does not list them:
+  axis or month labels, a legend for a colour scale, captions under figures. They add no new facts.
+- Icons that stand for different things look different; one generic glyph repeated down a list says nothing.
+- Charts: one series in the accent, thin lines, few gridlines; label a single line directly instead of a legend.
+- Empty and loading states are designed too: one sentence and one action; skeletons the size of the content.
+
+## Touch and mobile
+
+- Tap targets at least 44 px for buttons; smaller ones only with spacing **(check)**.
+- 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)**.
+
+## Review rubric (step 6)
+
+Score each pass or fail from the render; done when all pass or the failures are explained.
+
+1. **Focal point:** squinting, the eye lands on the thing the user came for.
+2. **One primary:** exactly one accent-filled element per region.
+3. **Inventory:** everything the brief names is there, nothing it does not name was added, every chart or scale
+   carries the labels needed to read it.
+4. **Grouping:** spacing alone shows what belongs together.
+5. **Alignment:** text starts on a few shared vertical lines; numbers line up.
+6. **Type discipline:** every style is a type level (no `type-*` warnings); at most three per region.
+7. **Calm structure:** no card in a card, no redundant borders, no decoration without information.
+8. **Data realism:** names, numbers and dates look like a real person's data.
+9. **Consistency:** built from the catalog components; no `reuse` or `consistency` warnings.
+10. **Checks:** `stitch2 check --strict` reports no errors.

package/skills/stitch2/references/screens.md

@@ -0,0 +1,70 @@
+# Screens, versions and approval
+
+The canvas and the agents share one model: an app **screen** (home, settings, …) has **versions**, each for a
+**device** (mobile or desktop), and each version has a **status**. The user decides; agents read the decision
+and build on it. Meta tag names below use the project's prefix (`<p>`, from `stitch2.config.json`).
+
+## Names and files
+
+- Screen names are lowercase with hyphens and name what the user sees; one per step of a flow
+  (`checkout-1`, `checkout-2`). Reuse existing names (`stitch2 screens` lists them).
+- A version is one file, `<screens dir>/<screen>/<device>-v<N>.html`, N the next free number for that device.
+  Its head carries `<p>-screen`, `<p>-device` (mobile | desktop), `<p>-status`, `<p>-source` (stitch | lab),
+  `<p>-frame-width` (390 mobile, 1280 desktop) and, written by the user, `<p>-note`. Older files elsewhere
+  carry the same tags.
+
+## New version or edit?
+
+- **New version** for every new attempt: a new direction, a regeneration, an export from a generator, a
+  redesign after feedback on an approved screen. It starts as `draft` and ends as `review`.
+- **Edit in place** only to finish your own draft, or to answer a note on a version still in `review` or
+  `draft`.
+- **Never edit** an `approved` or `archived` version: copy it to the next number and change the copy.
+
+## Statuses
+
+| Status | Meaning | Who sets it |
+|---|---|---|
+| `draft` | Work in progress | The agent, while working |
+| `review` | Finished, waiting for the user ("Needs review") | The agent, when done |
+| `approved` | The reference: build on it, match it, implement it | The user only |
+| `archived` | History: superseded or rejected; hidden on the canvas | The user; approving a version archives the previously approved one |
+
+## How to use them
+
+1. Before designing, run `stitch2 screens` (a name or `--status approved` narrows it) and open the approved
+   versions of the screens next to yours.
+2. A note is the user's feedback: address every point in your next version or edit, and say how.
+3. Never set `approved` yourself; never build on an archived version unless asked.
+4. Only approved versions get implemented in the product.
+5. When the user pastes a reference copied from the canvas, such as `home mobile v2
+   (design/screens/home/mobile-v2.html)`, open that file: it names exactly the version they mean.
+6. A reference to an element adds its source line, its tag and its text: `home mobile v1
+   (design/screens/home/mobile-v1.html:36) <gg-button> “Start Push”`. The element is the one with that tag
+   starting on that line (the text tells apart two on one line); a component's tag stands for everything it
+   renders. Change that element, or the component itself when the change belongs on every screen. Several
+   references in one message are numbered in the order the user picked them.
+
+## Implementing an approved version
+
+Build the screen in the app from the same components the screens use, in the version's order, with the app's
+own data, strings and behaviour; keep the app's tests passing. Then run `stitch2 compare <screen>` with the app
+running: fix every `missing` component and look at the side-by-side report. `extra` and `order` warnings are
+fine when the app needs them (a desktop-only control, a frame drawn by layout); say so when you hand over. When
+the page needs a state first (an open sheet, a running workout), add a `prepare` module for its route.
+
+## Desktop
+
+Desktop is a device of the same screen, designed after the mobile version is approved: `desktop-v<N>.html`,
+frame width 1280, the same components and type levels, the layout from DESIGN.md (typically a sidebar instead
+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.
+
+## The canvas
+
+`stitch2 canvas` → http://localhost:4400. The sidebar lists DESIGN.md (drawn as tokens and rules), the
+consistency report, the component catalog and every screen with its versions; filters for active, approved,
+needs review or all, and mobile or desktop. 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.

package/skills/stitch2/references/typography.md

@@ -0,0 +1,106 @@
+# Typography for app screens
+
+Most of what makes a dense app screen look finished is type: a small set of text styles used the same way
+everywhere, hierarchy carried by weight and colour, tracking that follows size, quiet secondary text. The
+project's DESIGN.md defines the levels (front matter `typography`); `stitch2 tokens` turns each into a
+`.type-<level>` class, `stitch2 check` warns about text that is not one of them, and `stitch2 type` lists every
+style a screen uses.
+
+## 1. A type scale is a short list of levels
+
+Google's DESIGN.md format suggests 9–15 levels, each fixing family, size, line height, weight and tracking
+together. A typical app set (sizes for a 390 px phone):
+
+| Role | Typical size / line | Weight | Tracking |
+|---|---|---|---|
+| Display (a timer, a hero number) | 40–56 / 1.0–1.1 | 600 | −0.04em |
+| Screen title | 28 / 34 | 600 | −0.03em |
+| Sheet or dialog title | 22 / 28 | 600 | −0.02em |
+| Card title | 18 / 24 | 600 | −0.02em |
+| Body | 15–16 / 22–24 | 400 | 0 |
+| Body strong (list names) | 15 / 20 | 500 | 0 |
+| Button label | 15 / 20 | 600 | 0 |
+| Meta (secondary lines) | 13 / 18 | 400 | 0 |
+| Chip or tab label | 13 / 16 | 500 | 0 |
+| Caps label (sections) | 12 / 16 | 600 | +0.06em, uppercase |
+| Caption (units, axes) | 12 / 16 | 400 | +0.01em |
+| Tab bar label | 11 / 14 | 500 | +0.02em |
+
+- One `.type-<level>` class per text element plus a colour class. No size, weight, tracking or line-height
+  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.
+
+## 2. Hierarchy recipes
+
+| Element | Recipe |
+|---|---|
+| Screen header | meta line in the secondary colour above the screen title |
+| Section | caps label, 8 px above its block |
+| Card header | data cards: a caps label; cards whose title is the content: a card title |
+| List row | body-strong name over a meta line; a trailing value as meta, or body-strong when it matters |
+| Stat | caps label, a large value with its unit at about half its size in the secondary colour, a meta note |
+| Controls | button label on buttons, chip label on chips and segments, tab label in the tab bar |
+
+At most three levels and two text colours per region. Most of a screen is 13–15 px; one or two things are big.
+To make something stand out inside a row, change its weight or colour, not its size.
+
+## 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).
+- 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.
+
+## 4. Numbers
+
+- Tabular figures for every number, so columns line up and timers do not jitter.
+- Large values in a proportional font with tabular figures: monospace fonts give the decimal point, comma and
+  colon a full-width cell ("80 . 7"); `check` warns about large monospace numbers. Monospace, if the brand uses
+  it, is for small standalone metadata, never mid-sentence.
+- Units follow their value at about half its size in the secondary colour.
+- Real typography: minus "−" for negatives, "×" for multiplication, en dash for ranges, "·" between facts.
+- Locales write numbers differently ("82,5"): leave room and never hard-code the decimal point.
+
+## 5. Tracking and line height
+
+- Tracking follows size: tight for titles (tighter the bigger), zero for reading sizes, open for small text and
+  capitals. For fonts without optical sizes (Geist, Inter and most web fonts) the font's own scale is the best
+  guide; Apple's SF Pro table follows the same curve below 24 pt.
+- Line height comes with the level. Wrapped text needs at least 1.3× its size; `check` reports wrapped text under
+  1.15× as an error. A line height equal to the size is only for single-line display numbers.
+- Titles, labels and metadata stay on one line: truncate with an ellipsis rather than wrap.
+
+## 6. Capitals
+
+Only the caps-label level: one to three words, never buttons, titles or sentences. Chinese, Korean, Thai, Hindi
+and Arabic have no capitals; `tokens.css` removes the uppercase and tracking for those languages.
+
+## 7. Text in each state
+
+| State | Text |
+|---|---|
+| Hover (pointer only) | secondary → primary colour |
+| Pressed | unchanged; the surface darkens and moves 1 px |
+| Focus | unchanged; a visible ring around the control |
+| Selected | the accent (chips, tabs) or primary text on a raised surface (segments) |
+| Disabled | the faint colour, with the reason nearby when it is not obvious |
+| Error | one meta line in the danger colour under the field, saying how to fix it |
+| Placeholder | secondary colour, an example of the input, not an instruction |
+| Loading | skeleton bars the height of the level's line |
+
+## 8. Length and languages
+
+Translations run up to 30% longer (German, Russian, Polish, Hungarian): every label has room or truncates.
+Right-to-left scripts align to start and end, never left and right, and are never letter-spaced (it breaks
+Arabic joining). Thai and Hindi need line height of at least 1.5. Latin web fonts lack Arabic, CJK, Thai and
+Devanagari; `tokens.css` falls back to Noto and system fonts.
+
+## 9. Type review
+
+1. `check` shows no `type-*` warnings.
+2. Squint: the title and the screen's main number are the only big things.
+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.

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

@@ -0,0 +1,65 @@
+---
+name: stitch2-app-sync
+description: Keep the live app and the approved designs in step when both are built from the same components. Use when changing a shared component the app uses, building or fixing an app screen from an approved design, adding a state or control the app needs (a paused timer, an error, an empty list), or when stitch2 compare reports missing components or layout errors in the app.
+---
+
+# Keeping the app and the designs in step
+
+The screens on the canvas and the app use **the same components** (one definition each, rendered by both). The
+canvas is where a component's look is decided and checked; the app wires the component to real data. Drift starts
+when the app draws something the canvas never showed: a control added only in the app, a state no screen has,
+a component rebuilt by hand. The checks can only judge what the canvas draws, so those slip through.
+
+## The direction of change
+
+**Design first, then the app.** A visible change to a shared component goes:
+
+1. **Component**: change it (or add the variant) in the component library, never in the app's copy of a screen.
+2. **Canvas**: rebuild the elements bundle, show the change on the screens that use it (a new version of each
+   approved screen if the change is visible there; a catalog entry for a new variant or state), and run
+   `stitch2 check <screens> --strict`. Look at the screens yourself: the check finds overlaps and overflow, not
+   ugliness.
+3. **Approval**: the user approves the new versions (or the catalog change) as for any design.
+4. **App**: the app picks the component up; wire it, then run `stitch2 compare <screen>`.
+
+Fixing a bug found in the app follows the same path: reproduce it on the canvas (a screen or catalog state that
+shows it), fix the component, check, then the app. If the canvas cannot show the bug, the canvas is missing a
+state: add it.
+
+## What the app may and may not add
+
+| The app needs | Do |
+|---|---|
+| Real data, handlers, routing, test ids | Props on the component (`onClick`, `onSelect`, `testId`); no change in look |
+| Its own control where the screen shows a value (an input where the design shows a number) | A slot that keeps the component's look: same size, type and colour as the value it replaces |
+| A new visible part (a pause button, a badge, a second line) | Add it to the component with its own props, and show it on a screen first. Never through a generic "extra" slot |
+| A state the screens do not have (loading, empty, error, paused, ready) | A screen version or catalog entry for that state first |
+| A whole new screen or sheet | Design it on the canvas first; until then it is unfinished, and the user should know |
+
+Slots are for wiring. If what goes into a slot changes how the component looks, it belongs in the component.
+
+## Checks that keep them honest
+
+- `stitch2 check` (screens): overflow, labels that wrap, content under fixed bars, fixed bars overlapping each
+  other, **controls overlapping each other**, small tap targets, contrast, type levels, reuse and consistency.
+- `stitch2 compare` (the live app, against every approved version with a route): which components appear, in
+  what order, how the measured ones look, **and the same layout errors as check** (overflow, fixed-overlap,
+  control-overlap), so a control squeezed in the app shows up even when no screen drew it.
+- Give every approved screen a route, and every state a `prepare` module that puts the app into it (a sheet
+  open, a timer running, a form half filled). An unrouted screen is not compared at all.
+
+Read the findings as:
+
+| Finding | Meaning | Fix |
+|---|---|---|
+| `missing` in compare | The app does not use a component the design shows | Build that part from the component; if the data is missing, fix the `prepare` |
+| `extra` in compare | The app shows a component the design does not | Fine if it is a kept feature the design leaves out; otherwise design it first |
+| `control-overlap` / `overflow` in compare only | The app draws a state or control the canvas never showed | Show it on the canvas, fix the component there, then re-run both |
+| `look` differences | The component is styled differently in the app | The app is overriding the component: remove the override, or change the component |
+
+## Before you call it done
+
+1. `stitch2 check --strict` passes on the screens you touched (archived screens excepted).
+2. `stitch2 compare` has no errors for the screens you touched; warnings are explained (a kept feature) or fixed.
+3. The user has seen the canvas versions of anything that changed how a component looks.
+

package/skills/stitch2-consistency/SKILL.md

@@ -0,0 +1,59 @@
+---
+name: stitch2-consistency
+description: Verify that shared elements (tab bar, header, buttons, chips, icon buttons, section labels, rows…) look the same on every screen, and fix drift the right way. Use when screens look inconsistent, after generating or importing screens (Stitch exports, a new flow), before asking the user to approve, or when check reports reuse or consistency warnings.
+---
+
+# Verifying design consistency with stitch2
+
+A shared element must be the same everywhere: same size, radius, type, colour, icon set, icons and states.
+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.
+
+## 1. Measure
+
+1. `stitch2 check` over **all** screens (no filter), so every screen's components are known; later filtered runs
+   compare with them.
+2. `stitch2 consistency` (or `stitch2 consistency tab-bar header` for some kinds): crops every shared component
+   from every active screen into one page, next to the catalog's version, with what differs. Open it from the
+   canvas sidebar (Consistency report) or view the crops under `<design>/consistency/<kind>/`.
+3. Read the warnings, per screen (`<design>/checks.json`, or the canvas inspector):
+   - `consistency`: "Tab bar differs from the component catalog: label 13/500 (catalog 11/500); iconSet
+     material-symbols (catalog lucide); icons home,… (catalog house,…)". Every field is a fact:
+     `height`/`width`/`radius` in px, `font` and `label` as size/weight/family/tracking, `icon` size,
+     `iconSet` and `icons` (the glyph names), and for a tab bar its centre `circle` and `lift`.
+     Measured are the tab bar, header, section label, card, buttons, icon buttons and chips; every other
+     component takes its size from its content, so compare those by eye in the report.
+   - `… different versions … on this screen`: the same component styled two ways on one screen.
+   - `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.
+
+## 2. Decide, per difference
+
+| What you see | Fix |
+|---|---|
+| A lab screen rebuilt a component by hand (`reuse`) | Replace the markup with the component, in a new version if the screen is approved |
+| A lab screen restyled a component (extra classes) | Remove the overrides; if the change was wanted, extend the component (step 4 of the ladder) |
+| A generated draft (Stitch) has its own chrome | Rebuild the draft from components as a new lab version, keeping its layout and content; or leave it and record it, because drafts are not implemented |
+| The draft's element is better than the catalog's | Change the component and the catalog (and DESIGN.md if it is a new look), then re-run the checks: every screen follows |
+| Two versions of one component on a screen | Pick the catalog's; if both are needed, they are two variants: add the variant to the component |
+| The catalog itself is missing the variant a screen needs | Add it to the component and the catalog first, then use it |
+
+Never fix consistency by editing one screen to imitate another by hand, and never edit an approved version:
+make the next version.
+
+## 3. Verify and report
+
+1. Re-run `stitch2 check` and `stitch2 consistency`: the fixed screens show "matches" in the report and no
+   `reuse`/`consistency` warnings.
+2. Tell the user, per component, which screens matched, which you fixed (and how: component used, component
+   extended, new version), and which differ on purpose (drafts you left, with the reason). Point to the report
+   on the canvas so they can see it.
+
+## Rules for every screen you build
+
+- Build from the catalog; check the catalog before writing any shared element.
+- One icon set (DESIGN.md names it); the same glyph for the same meaning on every screen.
+- Same chrome in the same place: header, tab bar or sidebar, safe-area padding.
+- Changes to shared elements happen in the component, never per screen.

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

@@ -0,0 +1,64 @@
+---
+name: stitch2-design-md
+description: Create or update a project's DESIGN.md (Google's DESIGN.md format) with stitch2 — from a short interview (stitch2 init) or measured from an existing site or screens (stitch2 extract) — then refine it with the user. Use when a project has no design system yet, when the user wants a new look or a rebrand, or wants to capture an existing product's design.
+---
+
+# Building a DESIGN.md
+
+DESIGN.md is the design system every other stitch2 skill and check reads: tokens (colours, type levels, radii,
+spacing, components with states) in the YAML front matter, rules in the prose. Google Stitch builds one from a
+theme or a website; stitch2 does the same with two commands, and you refine the result with the user.
+
+## 1. Choose the starting point
+
+- **From choices** (`stitch2 init`), when there is no product yet or the user wants a new look. Ask, in one
+  message, only what you cannot infer: the product in one sentence and its mood; the brand colour (a hex, or a
+  description you turn into one); dark, light or both; the font (default Inter; offer one or two that fit the
+  mood); a monospace font for numbers, if any; corner style (square, gently rounded, rounded, pill); density
+  (compact, balanced, spacious). Then run:
+  `stitch2 init --name "…" --mood "…" --primary "#…" --modes dark,light --sans "…" [--mono "…"]
+  --roundness 0|8|12|16|999 --base 14|15|16 --icons Lucide [--scheme tonal_spot|neutral|vibrant|…]`.
+- **From an existing product** (`stitch2 extract <url or .html files…>`), when the user has a site, an app's web
+  build or exported screens. Use several representative pages (a list, a detail, a form). It measures colours,
+  fonts, text styles, radii and padding and generates what it cannot measure.
+
+Both write `<design>/DESIGN.md` (`--out` elsewhere, `--force` to replace) and print the contrast of the pairs
+that matter; when a brand colour had to move to reach 4.5:1, they say so. Tell the user about every adjustment.
+
+## 2. Refine
+
+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.
+3. **Typography**: keep the levels; adjust sizes only together with the user and only on the scale.
+4. **Components**: name the product's real components (its tab bar items, its core list row) and their states.
+5. **Content & voice** and **Do's and Don'ts**: add the product's data style, naming and banned patterns.
+6. Keep every rule checkable: values, not adjectives.
+
+## 3. Validate and show
+
+1. `stitch2 lint`: 0 errors. Warnings about disabled text contrast (WCAG exempts it), semi-transparent washes
+   (the linter cannot measure them) and colours no component references are expected.
+2. `stitch2 tokens`, then open the canvas: **DESIGN.md** in the sidebar draws the swatches, live type levels,
+   radii and component tokens. Walk the user through it; change and repeat until they agree.
+3. Then build the component catalog and the first screens with the stitch2 skill, and run stitch2-consistency.
+
+## Updating an existing DESIGN.md
+
+Edit the front matter and prose directly for small changes. For a rebrand, generate a new file with `--out`,
+compare it with the current one (`npx @google/design.md diff old new`), and merge what the user approves;
+run `stitch2 tokens`, and every screen re-renders from the new tokens: screens and components use only token
+colours, and `stitch2 check` reports any colour value written into them (`color`).
+
+## The app uses the same tokens
+
+DESIGN.md is the one source of the product's look, not only the screens'. `stitch2 tokens` also writes every
+entry of `exports` in `stitch2.config.json` (format `css`, `tailwind4` or `dtcg`; `path` relative to the config).
+When the app already has its own theme variables (shadcn's `--background`, `--primary`, …), map each one to a
+DESIGN.md colour in `aliases` and import the generated file in place of the hand-written values, so nothing in
+the app sets a colour, radius or font of its own. `themes` sets the selectors when the app switches themes
+another way than `data-theme` (`{ "dark": ".dark", "light": ":root" }`). A colour the app needs and DESIGN.md
+lacks goes into DESIGN.md first. Commit the generated files; never edit them.