stitch2 0.15.2 → 0.16.0

package/README.md

@@ -72,7 +72,8 @@ file that already exists. From there the agent spends its effort on the design.
   ```
 - **Versions, variants and approval**: a screen has versions (v1, v2, …), and each version has variants, its
   layouts for mobile and desktop (`mobile-v3.html`, `desktop-v3.html`). The canvas groups them; you approve a
-  version as a whole or one variant at a time, leave notes, and approving archives the previous approved layout.
+  version as a whole or one variant at a time, and leave notes. The approved version is the one current version:
+  approving it archives every earlier one, and only it gets implemented.
 - **DESIGN.md builder**: `stitch2 init` writes a complete DESIGN.md from a few choices (brand colour, modes,
   fonts, roundness, density), with colours checked for contrast; `stitch2 extract` measures one from an existing
   site or screens.
@@ -83,7 +84,7 @@ file that already exists. From there the agent spends its effort on the design.
 - **Skills** for agents (`skills/`): `stitch2` (the design workflow, principles, typography, components,
   versions), `stitch2-design-md` (building the design system), `stitch2-alternatives` (fresh-eyes versions and
   testing skill changes), `stitch2-consistency` (verifying and fixing
-  consistency), `stitch2-i18n` (screens in every language), `stitch2-app-sync` (keeping the app and the designs in step: design first, then the app) and,
+  consistency), `stitch2-i18n` (screens in every language), `stitch2-copy` (writing the text: a brief, plain words, the reader's outcome), `stitch2-translate` (translating by meaning, with a glossary from the product, a review by error type and a check in context), `stitch2-app-sync` (keeping the app and the designs in step: design first, then the app) and,
   optional, `stitch2-import-from-google-stitch` (drafting screens in Google Stitch through its MCP server).
 
 ## Setup
@@ -253,7 +254,8 @@ layout first, then a shorter natural word, never a smaller type size.
 | `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 |
-| `stitch2 screens [name] [--status s] [--json]` | Versions, statuses and notes |
+| `stitch2 screens [name] [--status s] [--json] [--strict]` | Versions, statuses and notes; flags a screen whose current version is unclear |
+| `stitch2 approve <path or filter…>` | Approve variants (the user's decision); every earlier version is archived |
 | `stitch2 tokens` | Tokens from DESIGN.md |
 | `stitch2 compare [screen…]` | The live app against the approved screens (`app` in the config) |
 | `stitch2 elements <entry>` | Bundle your components (`stitch2/elements`) for the screens |

package/dist/approve.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/approve.js

@@ -0,0 +1,24 @@
+/**
+ * Approves screen variants, as the user does on the canvas: each becomes the current version of its screen on its
+ * device, and every earlier version there is archived. Agents run it when the user approves in words ("approve
+ * the v3 screens"), never on their own.
+ * Usage: stitch2 approve <path or filter…>   (a path under the design folder, or part of one: "connect/", "-v3")
+ */
+import { approve, listScreens } from './screens.js';
+const filters = process.argv.slice(2).filter((a) => !a.startsWith('--'));
+if (!filters.length) {
+    console.error('stitch2 approve <path or filter…>: which variants? ("home/mobile-v3", "connect/", "-v3")');
+    process.exit(1);
+}
+const targets = listScreens().filter((s) => s.kind === 'screen' && s.status !== 'archived' && filters.some((f) => s.path.includes(f)));
+if (!targets.length) {
+    console.error(`No screen variant matches ${filters.join(', ')}.`);
+    process.exit(1);
+}
+// Oldest first, so approving several versions of one screen leaves the latest current.
+targets.sort((a, b) => a.path.localeCompare(b.path, undefined, { numeric: true }));
+for (const t of targets) {
+    const archived = approve(t.path);
+    const note = archived.length ? `; archived ${archived.map((s) => s.version).join(', ')}` : '';
+    console.log(`approved ${t.screen} ${t.version} ${t.device}${note}`);
+}

package/dist/audit.js

@@ -36,6 +36,9 @@ export async function audit(opts) {
         if (closed && !closed.querySelector(':scope > summary')?.contains(el))
             return false;
         const r = el.getBoundingClientRect();
+        // Text kept for screen readers only (Tailwind's sr-only: a 1px box, clipped away) is not drawn.
+        if (r.width <= 1 && r.height <= 1 && cs.position === 'absolute')
+            return false;
         return r.width > 0 && r.height > 0;
     };
     const opacity = (el) => {

package/dist/cli.js

@@ -42,7 +42,8 @@ const COMMANDS = {
         'i18n-report.ts',
         '[filter] [--locale l] [--suggest] [--json]  Keys screens use that a locale lacks, and screen text with no key',
     ],
-    screens: ['list.ts', '[name] [--status s] [--json]  Screen versions, statuses and notes'],
+    screens: ['list.ts', '[name] [--status s] [--json] [--strict]  Screen versions, statuses, notes, and which version is current'],
+    approve: ['approve.ts', '<path or filter…>  Approve variants for the user; earlier versions are archived'],
     localize: ['assets.ts', '[filter]  Copy remote images a screen uses into its assets/ folder'],
     sandbox: [
         'sandbox.ts',

package/dist/list.js

@@ -1,9 +1,10 @@
 /**
  * Lists every screen version, variant by variant (mobile, desktop), with its status and the reviewer's note, for agents (and anyone without the
  * canvas open). Approved versions are the reference; review versions wait for the user; notes are feedback.
- * Usage: stitch2 screens [screen name] [--status approved|review|draft|archived] [--json]
+ * Ends with what makes the current version unclear (versionProblems); --strict fails on it.
+ * Usage: stitch2 screens [screen name] [--status approved|review|draft|archived] [--json] [--strict]
  */
-import { listScreens } from './screens.js';
+import { listScreens, versionProblems } from './screens.js';
 const args = process.argv.slice(2);
 const status = args.includes('--status') ? args[args.indexOf('--status') + 1] : undefined;
 const name = args.find((a, i) => !a.startsWith('--') && args[i - 1] !== '--status');
@@ -17,3 +18,11 @@ if (args.includes('--json'))
 else
     for (const s of rows)
         console.log(`${s.screen.padEnd(20)} ${s.version.padEnd(8)} ${s.device.padEnd(8)} ${s.status.padEnd(9)} ${s.path}${s.note ? `\n${' '.repeat(39)}note: ${s.note}` : ''}`);
+const problems = versionProblems().filter((p) => !name || p.startsWith(`${name} `));
+if (problems.length && !args.includes('--json')) {
+    console.log(`\nWhich version is current is unclear (${problems.length}):`);
+    for (const p of problems)
+        console.log(`  ${p}`);
+}
+if (problems.length && args.includes('--strict'))
+    process.exit(1);

package/dist/screens.d.ts

@@ -32,3 +32,17 @@ export declare const meta: (html: string, name: string) => string | undefined;
 export declare function listScreens(): Screen[];
 /** Sets (or removes, with undefined) <prefix>-* meta tags in a screen file, keeping the rest of it untouched. */
 export declare function writeMeta(path: string, values: Record<string, string | undefined>): void;
+/**
+ * Approves a variant. Approval makes it the one current version of its screen on its device: every earlier
+ * version there (approved, in review or a draft) and any other approved one become archived, so nobody can mistake
+ * an older one for what is implemented. Later versions (a newer proposal) keep their status.
+ * Returns the variants it archived.
+ */
+export declare function approve(path: string): Screen[];
+/**
+ * What makes it unclear which version of a screen is current: two approved on one device, or an earlier version
+ * still in review or a draft next to an approved later one. One line each; empty when every screen is clear.
+ */
+export declare function versionProblems(screens?: Screen[]): string[];
+/** A version's number: 3 for "v3"; NaN for one without (a Stitch export, a trial). */
+export declare const versionNumber: (s: Pick<Screen, 'version'>) => number;

package/dist/screens.js

@@ -83,3 +83,52 @@ export function writeMeta(path, values) {
     }
     writeFileSync(file, html);
 }
+/**
+ * Approves a variant. Approval makes it the one current version of its screen on its device: every earlier
+ * version there (approved, in review or a draft) and any other approved one become archived, so nobody can mistake
+ * an older one for what is implemented. Later versions (a newer proposal) keep their status.
+ * Returns the variants it archived.
+ */
+export function approve(path) {
+    const all = listScreens();
+    const target = all.find((s) => s.path === path);
+    if (!target || target.kind !== 'screen')
+        throw new Error(`not a screen: ${path}`);
+    writeMeta(path, { [tag('status')]: 'approved' });
+    const n = versionNumber(target);
+    const outdated = all.filter((s) => s.path !== path &&
+        s.kind === 'screen' &&
+        s.screen === target.screen &&
+        s.device === target.device &&
+        s.status !== 'archived' &&
+        (s.status === 'approved' || versionNumber(s) < n));
+    for (const s of outdated)
+        writeMeta(s.path, { [tag('status')]: 'archived' });
+    return outdated;
+}
+/**
+ * What makes it unclear which version of a screen is current: two approved on one device, or an earlier version
+ * still in review or a draft next to an approved later one. One line each; empty when every screen is clear.
+ */
+export function versionProblems(screens = listScreens()) {
+    const out = [];
+    const groups = new Map();
+    for (const s of screens) {
+        if (s.kind !== 'screen' || s.status === 'archived')
+            continue;
+        const key = `${s.screen} ${s.device}`;
+        groups.set(key, [...(groups.get(key) ?? []), s]);
+    }
+    for (const [key, list] of groups) {
+        const approved = list.filter((s) => s.status === 'approved');
+        if (approved.length > 1)
+            out.push(`${key}: ${approved.map((s) => s.version).join(' and ')} are all approved; approve the current one again`);
+        const current = Math.max(...approved.map(versionNumber).filter((n) => !Number.isNaN(n)));
+        for (const s of list)
+            if (s.status !== 'approved' && versionNumber(s) < current)
+                out.push(`${key}: ${s.version} is still ${s.status} although v${current} is approved; archive it (${s.path})`);
+    }
+    return out.sort();
+}
+/** A version's number: 3 for "v3"; NaN for one without (a Stitch export, a trial). */
+export const versionNumber = (s) => Number(/^v(\d+)$/.exec(s.version)?.[1] ?? Number.NaN);

package/dist/serve.js

@@ -28,7 +28,7 @@ function inlineTailwind(html, file) {
         return `<style type="text/tailwindcss">${readFileSync(css, 'utf8').replace(/\s*\n\s*/g, ' ')}</style>`;
     });
 }
-import { listScreens, ROOT, STATUSES, tag, writeMeta } from './screens.js';
+import { listScreens, ROOT, STATUSES, tag, writeMeta, approve } from './screens.js';
 /**
  * The consistency report covers every screen that is not archived and the components; the app comparison covers
  * the approved screens. A report is stale once one of those files is newer than it (a status change counts: it
@@ -131,14 +131,9 @@ export function startServer(port) {
                     if (note !== undefined)
                         values[tag('note')] = note.trim() || undefined;
                     writeMeta(path, values);
-                    // One approved version per screen and device: approving archives the previous one.
-                    if (status === 'approved')
-                        for (const s of all)
-                            if (s.path !== path &&
-                                s.screen === target.screen &&
-                                s.device === target.device &&
-                                s.status === 'approved')
-                                writeMeta(s.path, { [tag('status')]: 'archived' });
+                    // One current version per screen and device: approving archives every earlier one (screens.ts).
+                    if (status === 'approved' && target.kind === 'screen')
+                        approve(path);
                     json(listScreens());
                 }
                 catch (e) {

package/dist/typecheck.js

@@ -30,6 +30,9 @@ export function collectText() {
         const r = el.getBoundingClientRect();
         if (!r.width || !r.height)
             continue;
+        // Text for screen readers only (Tailwind's sr-only: a 1px box, clipped away) is not drawn.
+        if (r.width <= 1 && r.height <= 1 && cs.position === 'absolute')
+            continue;
         let opacity = 1;
         for (let e = el; e; e = e.parentElement)
             opacity *= Number(getComputedStyle(e).opacity);

package/package.json

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

@@ -46,7 +46,8 @@ References, read before the first screen:
    variant). 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. When the config has `i18n`, mark every product string with its message key (`data-t`, see
-   **stitch2-i18n**). Never add classes to a component to change how it looks, and never write a colour value (hex,
+   **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
    fixed bars, fixed bars overlapping each other, tap targets, contrast, cramped text) and every warning about type (`type-*`), hand-built
@@ -65,7 +66,8 @@ References, read before the first screen:
 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.
+   changed, how you answered their notes, and any rubric item you could not satisfy. The user approves; only then
+   does it go into the app (the approved version is the one current version: see screens.md).
 
 ## Commands
 
@@ -79,7 +81,8 @@ References, read before the first screen:
 | `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 |
-| `screens [name] [--status s] [--json]` | Every version with its status and the user's note |
+| `screens [name] [--status s] [--json] [--strict]` | Every version with its status and the user's note, and anything that makes the current version unclear |
+| `approve <path or filter…>` | Approves variants for the user (only on their word); every earlier version of the screen on that device is archived |
 | `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 |

package/skills/stitch2/references/screens.md

@@ -35,8 +35,13 @@ 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 variant archives the previously approved variant of the same device |
+| `approved` | The current version: the reference to build on and match, and the only one the app implements | The user only (on the canvas, or in words: then the agent runs `stitch2 approve`) |
+| `archived` | Outdated: superseded or rejected; hidden on the canvas | Approval: approving a variant archives every earlier version of that screen on that device, whatever its status |
+
+**One current version.** For each screen and device there is at most one approved variant, and it is what the app
+shows. Approving one archives every earlier version there (approved, in review or a draft), so nothing older can be
+mistaken for the current one; a later version, a newer proposal, keeps its status. `stitch2 screens` ends with
+anything that breaks this (two approved, an older version still in review); `--strict` fails on it.
 
 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
@@ -47,8 +52,12 @@ variant can still be approved, archived or noted on its own.
 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.
+3. Never approve on your own and never build on an archived version unless asked. When the user approves in words
+   ("approve the v3 screens"), run `stitch2 approve <path or filter…>` rather than editing status tags: it archives the
+   earlier versions as the canvas does.
+4. **Implement only approved versions.** A version in review or a draft is not built in the app, not even partly. If
+   the user asks to implement one that is not approved yet, that request is their approval: run `stitch2 approve` on it
+   first and say so. If the app needs something no approved version shows, design it and hand it over first.
 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
@@ -59,7 +68,7 @@ variant can still be approved, archived or noted on its own.
 
 ## 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
+Check first with `stitch2 screens <screen>` that the version is approved and is the only approved one on its device. 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

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

@@ -19,7 +19,10 @@ a component rebuilt by hand. The checks can only judge what the canvas draws, so
    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.
+3. **Approval**: the user approves the new versions (or the catalog change) as for any design. Nothing goes into
+   the app before this: a version in review is not implemented, not even partly. When the user asks to implement
+   one in review, run `stitch2 approve` on it first; that archives the earlier versions, so the approved one is the
+   single current version and the app matches it.
 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
@@ -62,7 +65,8 @@ Read the findings as:
 
 ## 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.
+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).
+3. `stitch2 compare` has no errors for the screens you touched; warnings are explained (a kept feature) or fixed.
+4. The user has seen the canvas versions of anything that changed how a component looks.
 

package/skills/stitch2-copy/SKILL.md

@@ -0,0 +1,93 @@
+---
+name: stitch2-copy
+description: Write the words on screens and landing pages so they say what the product does for the reader, in plain language a translator can carry into any language. Use when writing or rewriting a screen's text, a landing page, onboarding, empty states or buttons, when the user says the copy is weak, generic, too technical or "not selling", and before translating (stitch2-translate starts from this source).
+---
+
+# Copy with stitch2
+
+The words are part of the design. A screen can pass every layout check and still fail because its text is vague,
+written for the wrong reader, or impossible to translate well. This skill writes the **source** text; translating
+it is stitch2-translate.
+
+## 1. The brief: design/COPY.md
+
+Write it once per product, before the text, and keep it next to DESIGN.md. It is short:
+
+- **Reader.** Who opens this page and what they want done today, in their words ("know what to lift and log it
+  without fuss"), not in the product's ("a training management platform"). A page has one main reader; others
+  (developers, self-hosters, partners) get their own section further down, written for them.
+- **Promise.** One sentence: what the product does for that reader. Every headline on the page serves it.
+- **Proof.** Real, specific facts that back the promise: numbers, names, what happens on screen. No round fake
+  numbers.
+- **Voice.** Three words for how it sounds, and what it is not ("calm, direct, practical; never hype, never
+  slang").
+- **Words.** The product's terms, one per concept, as the UI uses them (*set*, *routine*, *program*), and the words
+  it never uses. stitch2-translate turns this into a glossary per language.
+- **Section intents.** For a landing page, one line per section: what the reader should understand or do after
+  it. The intent travels with the strings to the translators.
+
+## 2. Writing rules
+
+Sources: Google developer style guide (*Write for a global audience*), Nielsen Norman Group (people scan: 79% of
+users scan, 16% read word by word), Mozilla's marketing style guides, Material and Apple writing guidance.
+
+- **Lead with the reader's outcome**, then how the product gets there. "Know what to lift today" before "a
+  progression engine".
+- **Concrete beats clever.** Name the thing on the screen ("last time's weight sits next to every set") instead of
+  an abstraction ("data-driven insights"). A headline should still make sense with the page's design removed.
+- **One idea per sentence; short sentences.** They scan better and translate better.
+- **Plain words.** *use*, not *leverage*; *start*, not *commence*. No idioms, puns, phrasal verbs or cultural
+  references in the source: the translator has to rebuild them, and usually cannot.
+- **Second person, active voice, present tense.** "You log a set", "gymgym fills in the weight".
+- **Sentence case** for headings and buttons. A button is a verb and its object ("Start training", "Send
+  answers").
+- **No hype.** Not *seamless, powerful, ultimate, revolutionary, effortless, journey, unlock, supercharge*; no
+  exclamation marks. Proof replaces adjectives.
+- **Technical words only for the reader who uses them.** Licences, hosting, protocols and stack belong in the
+  section for developers, and even there say what they mean for the reader ("your data stays in your database")
+  before naming the technology.
+- **Write for translation.** Keep each sentence whole in one string (never split a sentence across keys or build
+  it by concatenation); use placeholders for numbers and names, with plural forms; avoid words with two meanings
+  in context (*set* the noun vs the verb). See stitch2-i18n for keys and placeholders.
+
+### A landing page
+
+- **Hero**: an eyebrow (what it is, or its strongest fact), a title of up to about eight words with the outcome,
+  a lead of one or two sentences with how and why to trust it, one primary action and at most one secondary.
+- **Sections**: eyebrow = the topic (one or two words); title = the benefit; lead = how it works, in product
+  terms. Feature cards: title = what the reader gets, text = what happens on screen.
+- **Lists** (checklists, "also included"): parallel grammar, each item a short claim the reader can check.
+- **Calls to action** repeat the same verb for the same action across the page.
+
+### In the product
+
+Labels are nouns, buttons are verbs, hints say what happens next, empty states say what this place is for and
+offer the first action, errors say what happened and what to do. Reuse the app's existing words before inventing
+new ones.
+
+## 3. Process
+
+1. Write or update the brief.
+2. **Read the strings in order.** `stitch2 i18n <screen> --json` lists a screen's keys; read the source text top
+   to bottom as one story, without the design. Mark every sentence that is vague, technical for the reader,
+   repeats another, or would not survive translation.
+3. Rewrite in the source messages (the app's files: one copy of every string). Keep keys whose meaning stays;
+   a string whose meaning changes gets its new text under the same key only if every place that uses it wants
+   the new meaning.
+4. Self-review with the checklist below, then `stitch2 check <screen> --shots` for fit.
+5. **Cold read.** Give a fresh agent only the page's strings (no brief, no design) and ask: what is this product,
+   who is it for, what would you do next? If the answer misses the promise, the page does not say it yet. A
+   `stitch2 sandbox` folder keeps the fresh agent from seeing your reasoning.
+6. Then translate with stitch2-translate: the brief's section intents are its context.
+
+## Checklist
+
+- [ ] The hero says what the product does for the main reader, in their words.
+- [ ] Every section title is a benefit; every lead says how, concretely.
+- [ ] No hype words, no exclamation marks, no idioms or puns.
+- [ ] Technical terms only in the section for the readers who use them.
+- [ ] One term per concept, the same as the UI.
+- [ ] Sentences short, whole in one string, with placeholders for numbers.
+- [ ] Buttons are verb + object, the same verb for the same action.
+- [ ] The cold read names the promise.
+

package/skills/stitch2-i18n/SKILL.md

@@ -110,6 +110,12 @@ Use logical properties so layouts flip by themselves: `ms-*`/`me-*`, `ps-*`/`pe-
 `text-start`, `rounded-s-*`. Icons that point (back, next, chevrons, progress) get `rtl:-scale-x-100`;
 icons that show objects (a dumbbell, a clock) and numbers, charts and media controls do not flip.
 
+## Writing and translating the words
+
+This skill makes every language fit. What the text says, and how well each language says it, is
+**stitch2-copy** (the source) and **stitch2-translate** (meaning, not words: a glossary from the app, the
+language's conventions, a review pass by error type, then this skill's check in context).
+
 ## Hand over
 
 Tell the user which languages you checked, what you changed to make each fit (layout, word, component), and

package/skills/stitch2-translate/SKILL.md

@@ -0,0 +1,91 @@
+---
+name: stitch2-translate
+description: Translate a product's screens and landing pages by meaning, as a native writer of each language would put it, not word for word — with a glossary taken from the product, the language's own conventions, a review pass that marks errors by type and severity, and a check in context. Use when adding or updating translations, when a language reads like a translation (calques, wrong terms, odd tone), when the user complains about a language, or after stitch2-copy changes the source.
+---
+
+# Translating with stitch2
+
+A good translation says what the source *means* and has the effect it is meant to have, in words a native
+speaker would choose. "Avoid literal translation at all costs" (Mozilla's localization style guide). For product
+UI that means the product's own terms, every time; for marketing it means transcreation: the headline may change
+its words entirely to keep its point.
+
+Machine and model translation in one pass is fluent but literal. It does better when it prepares like a human
+translator does and then revises against named errors: preparing keywords, topic and examples first (MAPS, He et
+al. 2023, arXiv:2305.04118), translating, then estimating errors and refining (TEaR, Feng et al. 2024,
+arXiv:2402.16379), with errors marked by MQM type and severity (GEMBA-MQM, Kocmi & Federmann 2023,
+arXiv:2310.13988), and with separate roles for translator, localizer and reviewer (TransAgents, Wu et al. 2024,
+arXiv:2405.11804). This skill is that process.
+
+## 0. Before translating
+
+- **The source is good.** If the source is vague or full of idioms, fix it first (stitch2-copy): a translation
+  cannot be better than what it says.
+- **The brief** (design/COPY.md): reader, promise, voice, section intents. Every string is translated knowing
+  what it is for.
+
+## 1. Prepare, per language
+
+1. **Glossary from the product.** Before writing a word, read how the app already says the core concepts in this
+   language (the locale's messages: set, rep, rest, workout, routine, program, history…; search the message files
+   for the source terms). Write them into design/COPY.md under the language. The landing page uses the app's
+   words; when the app's own terms collide (one word for two concepts), fix the collision in the app first and
+   note the decision.
+2. **Language conventions** (references/locales.md): form of address used by the app (detect it from existing
+   strings: *du*/*Sie*, *tu*/*vous*, *ты*/*вы*), quotation marks, spaces before punctuation, dashes, number
+   formatting, capitalization.
+3. **Context per string.** Where it appears (hero title, button, chip, checklist item), how much room it has
+   (`stitch2 i18n <screen> --json` lists keys per screen; the renders show the space), and the intent from the
+   brief.
+
+## 2. Draft as a native writer
+
+- Read the whole section in the source first; translate the section, not string by string.
+- Ask, as Mozilla's guide does: what does this mean, what is the author trying to say, how would I say that in my
+  language? Then write it the way a good local fitness, finance or tech site (whatever the product is) would.
+- Headlines and slogans: transcreate. Keep the point and the length class (short stays short), drop the source's
+  wording when it does not work. Write two or three options and keep the best.
+- UI strings: the glossary term, the language's usual verb for the action ("Войти", "Anmelden"), the same form of
+  address everywhere.
+- Keep placeholders, plural categories (CLDR) and markup slots; never concatenate.
+- Units, numbers and dates come from the locale; product names, brands and code stay as written.
+
+## 3. Review: mark errors, then fix
+
+Review as a **separate pass**, ideally a separate agent that sees the source, the draft, the glossary and the
+conventions, but not the drafter's reasoning. Mark every problem with an MQM category and severity
+(references/review.md), for example:
+
+```
+site.hero.title  ru  "Знайте, что поднимать."  fluency/unnatural (calque of "Know what to lift")  major
+```
+
+The questions that catch most errors:
+
+- Would a native copywriter ever write this sentence? If it only makes sense to someone who knows the English, it
+  is a calque.
+- Does it say exactly what the source means, nothing added, nothing lost?
+- Is every product concept the glossary term? Is the form of address the app's?
+- Punctuation, quotes, spaces and numbers as the language writes them?
+
+Fix every critical and major error and review again, until a pass finds none. A back-translation can confirm the
+meaning; it is never a target for style.
+
+## 4. In context
+
+1. `stitch2 check <screen> --locales <l> --shots`: nothing cut, wrapped badly or overlapping (stitch2-i18n has the
+   fixes, in order).
+2. Read the render top to bottom in the language. Headlines that broke onto an orphan word, a term that changed
+   between two sections, a tone that changed: fix in the messages.
+
+## 5. Hand over
+
+Say which languages you reviewed in context, the terminology decisions (with the collisions you fixed), and which
+strings deserve a native speaker's read before a launch: headlines and anything legal. Be honest about the
+languages you are less sure of.
+
+## References
+
+- references/locales.md: conventions per language.
+- references/review.md: the error types and severities, and the review output.
+

package/skills/stitch2-translate/references/locales.md

@@ -0,0 +1,40 @@
+# Conventions per language
+
+The defaults for consumer products; when the product already uses another form of address, keep the product's.
+Numbers, dates and units come from `Intl` in the app; in prose, write them the way the language does.
+
+| Language | Address | Quotes | Punctuation and spacing | Numbers | Notes |
+|---|---|---|---|---|---|
+| English (en) | you | “ ” | sentence case; serial comma by house style | 1,324.5 | the source: plain, no idioms |
+| German (de) | du in consumer apps, Sie in banking and B2B | „ “ | nouns capitalised; compounds closed (Pausentimer) | 1.324,5 | avoid Denglisch where a German word is usual; keep accepted loanwords (Coach, Workout) |
+| French (fr) | tu or vous by product; be consistent | « » with narrow no-break spaces | narrow no-break space before ; : ! ? and inside « » | 1 324,5 | sentence case; avoid anglicismes (séance, série, répétition) |
+| Spanish (es) | tú | « » or “ ” | ¿ ¡ open questions and exclamations | 1324,5 / 1.324,5 | neutral Spanish for Spain and Latin America; avoid regional slang |
+| Italian (it) | tu | « » or “ ” | sentence case | 1.324,5 | allenamento, serie, ripetizioni, recupero |
+| Portuguese, Portugal (pt) | tu (or você) by product | « » or “ ” | sentence case | 1324,5 | ginásio, ecrã, telemóvel, registar — never the Brazilian forms |
+| Portuguese, Brazil (pt-BR) | você | “ ” | sentence case | 1.324,5 | academia, tela, celular, registrar |
+| Polish (pl) | ty (imperative 2nd person singular) | „ ” | sentence case | 1324,5 | seria, powtórzenia, przerwa; avoid noun chains |
+| Turkish (tr) | sen (or siz) by product | “ ” | sentence case; suffixes after numbers and names with an apostrophe (Strong’dan) | 1.324,5 | vowel harmony in suffixes after placeholders needs care: prefer phrasing without a suffix on {name} |
+| Russian (ru) | вы (lowercase) | «ёлочки», „лапки“ inside | spaced em dash —; no Title Case; ё where it matters | 1 324,5 (no-break space) | lifter vocabulary: подход, повторение (повтор), отдых, разминка, жим лёжа; no calques (see below) |
+| Ukrainian (uk) | ви | « » | apostrophe ’ inside words (м’язи) | 1 324,5 | not Russian with Ukrainian letters: own vocabulary (підхід, повторення, відпочинок, тренування) |
+| Hungarian (hu) | te in consumer apps | „ ” | sentence case | 1 324,5 | word order differs a lot: rebuild the sentence |
+| Arabic (ar) | neutral second person, masculine as default where unavoidable | « » or ” “ | Arabic comma ، and question mark ؟; right to left | Western digits by product choice | Modern Standard Arabic, plain; mirror arrows |
+| Hindi (hi) | आप | “ ” | । as full stop | 1,324.5 (Indian grouping for large numbers) | gym words are often English in Devanagari (सेट, रेप्स, वर्कआउट): use what Indian fitness apps use |
+| Thai (th) | neutral, no polite particles in UI | “ ” | no spaces between words; a space ends a phrase | 1,324.5 | short; avoid long noun phrases |
+| Korean (ko) | 해요체 (polite informal) in consumer apps | “ ” | spaces between words (띄어쓰기) | 1,324.5 | consistent ending style across the product |
+| Chinese, Simplified (zh) | 你 | “ ” | full-width punctuation ，。：；？！ | 1,324.5 | a space between Chinese and Latin letters or numbers is house style: keep the product's |
+
+## Calques to catch (Russian examples; every language has its own)
+
+| Source | Literal (wrong) | Natural |
+|---|---|---|
+| Know what to lift. | Знайте, что поднимать. | Всегда знаете, какой вес брать. |
+| Keep every rep. | Сохраните каждое повторение. | Ни один подход не потеряется. |
+| A coach that reads your training. | Тренер, который читает ваши тренировки. | Тренер, который знает ваши тренировки. |
+| Get gymgym | Получить gymgym | Как начать |
+| Use ours, or run your own. | Пользуйтесь нашим или запустите свой. | Пользуйтесь нашим сервером или разверните свой. |
+| at a glance | с первого взгляда | всё на одном экране |
+
+Signs of a calque: the sentence keeps English word order; a possessive on every noun (ваши, ваш, вашего); a verb
+that only makes sense in English (*read* training, *keep* reps); nouns where the language prefers a verb; an
+English idiom kept word for word.
+

package/skills/stitch2-translate/references/review.md

@@ -0,0 +1,30 @@
+# Review: error types and severity
+
+Based on the MQM (Multidimensional Quality Metrics) typology, cut down to what product text needs. Mark each
+error on the string it is in.
+
+| Category | Subtypes | Example |
+|---|---|---|
+| Accuracy | mistranslation, omission, addition, untranslated | "rest timer" as "остаток времени" |
+| Fluency | grammar, spelling, unnatural (calque), inconsistency within the string | "Знайте, что поднимать" |
+| Terminology | not the glossary term, two terms for one concept | routine as "программа" here and "тренировка" there |
+| Style | register or form of address unlike the product, tone unlike the brief, wordy | "вы" in a "ты" product; marketing hype |
+| Locale conventions | punctuation, quotes, spacing, numbers, dates, capitalization | "Hello : world" spacing in fr, Title Case in ru |
+| Design | does not fit, breaks a line badly, wrong plural form | (stitch2 check finds most) |
+
+Severity:
+
+- **critical**: says something false or harmful (wrong price, wrong action on a button, legal or medical
+  mistake), or unreadable.
+- **major**: a reader notices: unnatural, wrong term, wrong tone, meaning shifted.
+- **minor**: a careful reader notices: punctuation, a slightly better word exists.
+
+Output, one line per error, then a verdict:
+
+```
+<key>  <locale>  "<text>"  <category>/<subtype>  <severity>  <why, and the fix>
+verdict: <locale> n critical, n major, n minor
+```
+
+A language ships when its last pass has no critical or major errors.
+