stitch2 0.0.0-stage → 0.7.2

package/skills/stitch2-import-from-google-stitch/SKILL.md

@@ -0,0 +1,47 @@
+---
+name: stitch2-import-from-google-stitch
+description: Optional, only for projects that use Google Stitch (Google's product) — draft screens there through its MCP server and bring them into stitch2 as reviewable versions. Use when the user wants Stitch to generate a screen, design variants, or to push the project's DESIGN.md to a Stitch design system. (stitch2 is inspired by Google Stitch and is not affiliated with Google.)
+---
+
+# Drafting screens in Google Stitch
+
+Google Stitch generates screens (HTML and a screenshot) from prompts against a design system. stitch2 treats
+each export as a **draft version**: it lands next to the other versions of its screen on the canvas, gets
+checked, and waits for the user's decision. The project skill names the Stitch project, its design system and
+the data to use in prompts. How Stitch builds its screens: [references/how-stitch-works.md](references/how-stitch-works.md).
+
+## Access
+
+- The MCP server is `https://stitch.googleapis.com/mcp` with the header `X-Goog-Api-Key` (configure it in the
+  agent's MCP settings; never commit or print the key).
+- Without the MCP tools in the session, call it over HTTP: it is stateless JSON-RPC, one POST per call
+  (`{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"…","arguments":{…}}}`, headers
+  `content-type: application/json` and `accept: application/json, text/event-stream`).
+
+## Workflow
+
+1. **Design system first.** Systemic changes go into DESIGN.md (Google's DESIGN.md format, which Stitch reads
+   directly). Push it with `upload_design_md` (base64 of the file), then `create_design_system_from_design_md`
+   with the returned screen instance; `list_design_systems` gives the asset id. Read it back: Stitch's fonts
+   come from a fixed list of about 65 Google Fonts and it silently substitutes the others.
+2. **Prompts carry content and structure**: the screen's sections, controls and realistic data, the shared
+   chrome in the same words on every prompt (taken from DESIGN.md's Components), and what must not appear (no
+   phone status bar, step labels, tip cards, extra helper text or buttons; Stitch adds them otherwise). Colours,
+   fonts and radii come from the design system.
+3. **One screen at a time**, `generate_screen_from_text` with `designSystem` set. Parallel calls caused
+   "service unavailable", screens never placed on the canvas and screens stuck on "Preparing…". Never resend a
+   running call. Empty `downloadUrl`s: poll `get_screen` for a few minutes, then generate once more.
+4. **Known quirks.** `edit_screens` reports success but does not persist through the API; fix a screen by
+   generating again with a corrected prompt. There is no API to delete a screen (the user removes it in the
+   Stitch UI). `list_screens` lags. A prompt resembling an existing screen makes Stitch edit that one
+   (unsaved): start it with "Create a NEW, separate screen (do not edit or replace any existing screen) titled
+   '…'". `update_design_system` rewrites the design system's DESIGN.md text. Each reply carries follow-up
+   suggestions (`outputComponents[].suggestion`): pass them on to the user.
+5. **Bring it in as a version**: save the HTML as `<screens>/<screen>/<device>-v<N>.html` with the meta tags
+   `<p>-screen`, `<p>-device`, `<p>-source` = `stitch`, `<p>-status` = `review` (see stitch2's screens.md),
+   then `stitch2 localize <path>` (Stitch links images to Google URLs that can fail elsewhere or expire),
+   `stitch2 check <path> --shots`, and look at it on the canvas.
+6. **Consistency.** Stitch cannot share components between screens, so its chrome drifts (one project's first
+   six screens had six different tab bars). Run the stitch2-consistency skill; the component catalog, not
+   Stitch, decides how shared components look. Stitch screens are drafts: the product implements approved
+   versions built from the project's components, never pasted Stitch HTML.

package/skills/stitch2-import-from-google-stitch/references/how-stitch-works.md

@@ -0,0 +1,36 @@
+# How Stitch builds its screens
+
+Observed through Stitch's MCP API, the HTML it generated for one project (ten screens, 341 text elements
+measured with `stitch2 type`), and Google's public material: the DESIGN.md format (github.com/google-labs-code/
+design.md, npm `@google/design.md`) and the stitch-skills repository (github.com/google-labs-code/stitch-skills).
+
+## The pipeline
+
+1. **A structured theme.** A Stitch design system is a typed object: headline, body and label fonts from a fixed
+   list of about 65 Google Fonts; a seed colour with a Material dynamic-colour variant (TONAL_SPOT, FIDELITY,
+   VIBRANT…) and optional overrides; a roundness level (2, 4, 8, 12 px or full); a spacing map; named typography
+   levels (family, size, weight, line height, tracking); and a free-text DESIGN.md.
+2. **DESIGN.md in Google's format.** An uploaded DESIGN.md comes back with YAML front matter: the Material colour
+   roles generated from the seed, named type levels, radius and spacing scales, then the prose. Fonts outside its
+   list are replaced silently (Geist Mono became Public Sans), and the prose is rewritten to match.
+3. **A compiled Tailwind config per screen**, with the levels as `text-<level>` sizes bundling line height,
+   tracking and weight, plus the colours, spacing and radii. Markup is written against those names, mixed with
+   Tailwind's default steps (`text-sm`, `text-xs`), whose sizes carry fixed line heights.
+4. **Prompts carry content only.** Google's own Stitch skills keep colours, fonts and radii out of prompts; their
+   references are vocabulary lists. Stitch's visual judgement lives in its model and hidden prompt.
+
+## What its screens tend to do
+
+- About 70% of text at 10–13 px; one or two elements per screen at 20 px or more.
+- Semibold carries hierarchy, including on 11–12 px labels; medium for names and values.
+- Headings tightened (about −0.025em), small labels and capitals opened (+0.025 to +0.05em).
+- A third text grey and opacity steps; the third grey often fails AA contrast.
+- Pressed, hover and focus styles on nearly every control.
+- Labels that make charts readable (axes, legends, figure captions) and distinct icons per item.
+
+And what to watch for:
+
+- Invented content: captions, statistics and features the prompt did not ask for.
+- The accent on several elements per region; accent text on tinted backgrounds failing contrast.
+- Monospace decimals with wide gaps ("80 . 7").
+- Chrome that differs on every screen (tab bars, headers, icon buttons), because screens share nothing.

package/skills/stitch2-variants/SKILL.md

@@ -0,0 +1,45 @@
+---
+name: stitch2-variants
+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
+
+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,
+so a fresh agent designs from the brief alone. Its result comes back as the next version of the screen, for
+the user to compare on the canvas.
+
+## Alternatives for a screen
+
+1. **Write the brief** (`<screen>.md`): what the screen is for, its sections and controls, real data. Content
+   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
+   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
+   the user the folder and ask them to open a new agent session in it. Run them in parallel; they do not share
+   anything.
+4. **Import**: `stitch2 sandbox import <dir> --label "calendar first"` for each. Every screen comes back as the
+   next version (status review) with a note saying where it came from.
+5. **Compare** with `stitch2 check` and `stitch2 consistency` (they should pass like any version), then tell the
+   user the versions are on the canvas side by side, what each tried, and which you would choose and why. The
+   user approves one; the others get archived.
+
+## Testing a change to the skills or DESIGN.md
+
+1. Pick briefs for screens that already have versions made under the old rules.
+2. Create sandboxes from the project with the changed skills or DESIGN.md, run fresh agents on the same briefs.
+3. Import them with a label (`--label "rules v2"`) and compare with the old versions: `stitch2 check` (errors,
+   warnings), `stitch2 type` (share of text on the type scale, number of sizes), `stitch2 consistency`, and the
+   review rubric. Report numbers, not impressions; archive the trial versions afterwards.
+
+## Rules
+
+- Never copy files from the project into a sandbox by hand, and never tell the sandbox agent about the existing
+  versions: that is the anchoring the sandbox avoids.
+- Briefs say what, not how. A brief that describes another version's layout defeats the purpose.
+- Imported versions are drafts like any other: the user decides.