stitch2 0.13.1 → 0.15.0

package/skills/stitch2/references/screens.md

@@ -1,14 +1,18 @@
 # 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
+The canvas and the agents share one model: an app **screen** (home, settings, …) has **versions**, design
+iterations numbered v1, v2, v3…, and each version has **variants**, its layouts for each device (mobile,
+desktop, later tablet). Each variant 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.
+- A variant is one file, `<screens dir>/<screen>/<device>-v<N>.html`; the variants of a version share N
+  (`mobile-v3.html` and `desktop-v3.html` are v3). A new version takes the next free N across the screen's
+  variants; a variant added to an existing version takes that version's N (a desktop for v3 is
+  `desktop-v3.html`, never v4). A version may start with one variant and get the others later.
   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.
@@ -17,9 +21,13 @@ and build on it. Meta tag names below use the project's prefix (`<p>`, from `sti
 
 - **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`.
+- **New variant** for a device the version lacks (its desktop, its tablet): a new file with the version's N,
+  `draft` then `review`, even when the version's other variants are approved.
 - **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.
+- **Never edit** an `approved` or `archived` variant: copy the version to the next number and change the copy.
+  The exception is the user's own request: a fix they ask for on a version they name ("it had to be on v3")
+  goes into that version, which keeps its status; say what changed.
 
 ## Statuses
 
@@ -28,7 +36,11 @@ and build on it. Meta tag names below use the project's prefix (`<p>`, from `sti
 | `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 |
+| `archived` | History: superseded or rejected; hidden on the canvas | The user; approving a variant archives the previously approved variant of the same device |
+
+The canvas shows each version with its variants side by side under one heading, and one status for the version:
+needs review while any variant does. **Approve version** approves every variant in review at once; a single
+variant can still be approved, archived or noted on its own.
 
 ## How to use them
 
@@ -55,21 +67,37 @@ the page needs a state first (an open sheet, a running workout), add a `prepare`
 
 ## 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
+Desktop is a variant of a version, designed after the version's mobile variant is approved: `desktop-v<N>.html`
+with the mobile's N, 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.
 
-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.
+## Widths
+
+A variant is drawn at one frame width but covers a range of windows: `widths` in `stitch2.config.json`, by
+device, `[narrowest, widest]` in px. The defaults follow Google's window size classes ([google.md](google.md)):
+mobile 360–599 (compact), tablet 600–1023 (medium), desktop 1024–1920 (expanded and up); a project sets the
+width where its app actually changes layout (gymgym: mobile up to 1023, desktop from 1024).
+
+Widths are a dimension like themes and languages, not more files: `stitch2 check` also renders every variant at
+both ends of its range and reports what breaks there ("at 1024px: …"), and the canvas shows every frame at its
+narrowest or widest (the width dropdown, W).
+
+- A screen that breaks at an edge gets a **responsive rule inside the same variant**: a two-column grid that drops
+  to one, three cards across that become two, a side column that moves under the main one. Use the project's
+  breakpoints (Tailwind's `md:`, `lg:`, `xl:`), so the screen keeps one layout that adapts.
+- Only when the **structure** has to change (a bar becomes a side navigation, one pane becomes list-detail) is it a
+  new variant: `tablet-v<N>` for 600–1023, with its own frame width (768) and range, the same N as the version.
+- A desktop screen is a layout for its range, not a stretched phone: a side navigation instead of the bar,
+  list-detail with both panes, extra columns for feeds.
 
 ## 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
+`stitch2 canvas` → http://localhost:4400. The sidebar lists DESIGN.md (drawn as tokens and rules), Components
+(the catalog for the variants the filter shows; a click steps through them), the consistency report and app
+comparison (each with when it last ran, or how many covered screens changed since), Languages, and every screen
+with its versions. Filters: status (active, approved, needs review, all), versions, variants, theme, width and
+language. The reports and Languages follow the filters too: they show only the screens the canvas shows. Selecting a version opens the inspector: status, note, checks, and
 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-variants → stitch2-alternatives}/SKILL.md

@@ -1,9 +1,9 @@
 ---
-name: stitch2-variants
+name: stitch2-alternatives
 description: Get fresh-eyes versions of a screen from agents that see no other versions (stitch2 sandbox), so alternatives are not anchored to what exists; or test a change to the skills on output only the rules produced. Use when the user wants alternatives or a new direction, feels stuck with a design, wants several options to choose from, or when a skill or DESIGN.md rule changed and you need evidence it helps.
 ---
 
-# Fresh-eyes variants with stitch2 sandboxes
+# Fresh-eyes alternatives with stitch2 sandboxes
 
 An agent that can see a screen's existing versions copies them, even when asked for something new. A sandbox
 is a folder with the project's design system, components, catalog, template and skills, and none of its screens,
@@ -16,8 +16,8 @@ the user to compare on the canvas.
    and structure only: colours, fonts and shapes come from DESIGN.md. Name the file after the screen
    (`history.md` designs `history`). For several directions, write one brief per direction with one sentence
    on what differs (`history.md` in sandbox A: "a calendar first"; in sandbox B: "a list first").
-2. **Create one sandbox per variant**: `stitch2 sandbox create /tmp/<project>-<screen>-a <brief.md>`.
-   `--context home stats` adds the approved versions of other screens, so the variant stays consistent with
+2. **Create one sandbox per alternative**: `stitch2 sandbox create /tmp/<project>-<screen>-a <brief.md>`.
+   `--context home stats` adds the approved versions of other screens, so the alternative stays consistent with
    them; `--device desktop` for desktop.
 3. **Run a fresh agent in each**, with no shared conversation: a sub-agent started without forked history,
    working only in that folder, told to read its AGENTS.md and follow the skills there. Without sub-agents, give

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

@@ -44,7 +44,10 @@ Slots are for wiring. If what goes into a slot changes how the component looks,
   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.
+  control-overlap), so a control squeezed in the app shows up even when no screen drew it. Each version runs at
+  its drawn width and at both edges of its width range; a finding seen only at an edge starts with "at <width>px:".
+- Both reports are snapshots that run only when called. The canvas sidebar says "N changed since" once the
+  screens they cover have changed; run them again before relying on them.
 - 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.
 

package/skills/stitch2-i18n/SKILL.md

@@ -44,7 +44,8 @@ Use the app's own files. Never copy messages into the design folder: two copies
 ```
 
 A value with braces is a **template**: each `{key}` or `{key|name=value;name=value}` becomes its message and
-the rest stays as written. Use it for lines the app builds from several messages and data (a meta line, a
+the rest stays as written. Templates nest, innermost first, for a message that takes another as an argument:
+`data-t-title="{site.screens.title|workout={nav.workout};history={nav.history}}"`. Use it for lines the app builds from several messages and data (a meta line, a
 list of `label=url` links: `data-t-links="{site.features}=#features,{site.docs}=/docs"`); sample data inside
 it stays literal. Without braces, `data-t-<attr>` on a comma list takes one key per item.