stitch2 0.15.2 → 0.15.3

package/README.md

@@ -83,7 +83,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

package/package.json

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

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.
+