@motion-proto/live-tokens 0.73.0 → 0.74.0

package/.claude/skills/{live-tokens-pair-fonts → live-tokens-set-type}/SKILL.md

@@ -1,24 +1,25 @@
 ---
-name: live-tokens-pair-fonts
-description: Choose and apply a Google Fonts pairing for a live-tokens theme, binding families to the shipped --font-* stacks. Use whenever the user asks to pair fonts, pick a typeface, change or set the fonts, or describes type by voice: what font should the headings use, make the type more editorial, friendlier, more technical, more elegant, a serif for headings, a display font for this theme, less generic type, match the fonts to the theme. Also invoked by live-tokens-generate-theme for the type half of a whole look. Changes type only, never color. Not for a single token (use the editor) or for color (see live-tokens-generate-theme).
+name: live-tokens-set-type
+description: Choose and apply a Google Fonts pairing for a live-tokens theme, binding families to the shipped --font-* stacks. Use whenever the user asks to pair fonts, pick a typeface, change or set the fonts, or describes type by voice: what font should the headings use, make the type more editorial, friendlier, more technical, more elegant, a serif for headings, a display font for this theme, less generic type, match the fonts to the theme. Also invoked by live-tokens-create-theme, which supplies the type intent for a whole look. Changes type only, never color. Not for a single token (use the editor) or for a whole look (see live-tokens-create-theme).
 ---
 
-# Pairing fonts for a theme
+# Setting a theme's fonts
 
 You choose the families; the CLI verifies each against Google Fonts, builds the URL from the weights the family actually has, and writes the result into the unsaved buffer. Never hand-author font JSON and never edit the data tree directly. Google Fonts is the pool because it is freely licensable and loads by URL; other sources go in by hand through the editor's Project fonts section.
 
 ## Workflow
 
-1. Choose the pairing with the framework below and write a brief to `scratch/font-brief.json`.
-2. Run `npx live-tokens set-fonts scratch/font-brief.json`. It prints each stack that moved, each family's real weights and URL, and the weights your typography tokens ask for that the family lacks.
+1. Read the type intent. When it names an anchor (a feeling, an idiom, or a genre), read `references/type-anchors.md` for that entry; it overrides the Voice table below. Choose the pairing with the framework here and write the pairing file to `scratch/font-pairing.json`.
+2. Run `npx live-tokens set-type scratch/font-pairing.json`. It prints each stack that moved, each family's real weights and URL, and the weights your typography tokens ask for that the family lacks.
 3. Read the report. A weight gap is a quality note: name it and offer an alternative only if it matters (a body face without 400, 700, or italic matters; a display face without 300 does not). A family not on Google Fonts fails the run; fix the spelling and re-run.
-4. Tell the user to reload the editor page before saving. A running editor holds its own copy of the buffer this CLI just wrote and never re-reads it, so a Save without a reload writes the stale copy back and the pairing vanishes with a success report still on screen. After the reload the type is on the page, and unsaved until they save the open theme.
+4. Report back in a line: the two families, the form model behind each, and any weight gap worth naming.
+5. Tell the user to reload the editor page before saving. A running editor holds its own copy of the buffer this CLI just wrote and never re-reads it, so a Save without a reload writes the stale copy back and the pairing vanishes with a success report still on screen. After the reload the type is on the page, and unsaved until they save the open theme.
 
 State your reasoning when you propose the pairing: each face's form model and the matrix verdict, in one sentence, so the user can argue with the argument rather than only the result.
 
 Flags: `--dry-run` reports without writing. `--no-verify` skips the network and requires an explicit URL per family; use it only offline with a URL in hand.
 
-## The brief
+## The pairing file
 
 ```json
 { "display": "Fraunces", "body": "Nunito Sans" }
@@ -28,7 +29,7 @@ Every slot is optional and an omitted slot is left exactly as it is. `display` i
 
 ## Choose the body face first
 
-The body face is the anchor. It carries most of the words, and text faces survive small sizes where display faces do not. Pick it against the brief, then pick the display face against it. A body face must have regular, bold, and italic; low to moderate stroke contrast; open apertures; and a large x-height. A face failing any of these is a display face whatever its name says. Single-weight families are fine for `display` and disqualifying for `body`.
+The body face is the anchor. It carries most of the words, and text faces survive small sizes where display faces do not. Pick it against the type intent, then pick the display face against it. A body face must have regular, bold, and italic; low to moderate stroke contrast; open apertures; and a large x-height. A face failing any of these is a display face whatever its name says. Single-weight families are fine for `display` and disqualifying for `body`.
 
 The shipped text styles ask the display face for 600, across all four heading levels, and the body face for 400; prose markup adds 700 and italic for `strong` and `em`. Screen candidates against those four before running, so the report confirms a decision instead of reporting a surprise.
 
@@ -50,7 +51,7 @@ Many faces sit between columns. When one straddles, say so and lean on the voice
 
 ## Voice
 
-| Brief says | Type voice |
+| The intent says | Type voice |
 |---|---|
 | editorial, literary, considered | dynamic serif display over a humanist sans body |
 | elegant, luxurious, formal | rational high-contrast serif display; keep the body quiet |
@@ -60,13 +61,15 @@ Many faces sit between columns. When one straddles, say so and lean on the voice
 | serious, institutional, trustworthy | rational sans body, rational serif display |
 | quiet, minimal, unbranded | one superfamily across both slots |
 
-Match the type to the same brief the color came from. A warm autumn palette under a cold geometric sans reads as two projects.
+This table covers an intent that names no anchor. When the intent names one, `references/type-anchors.md` has the row and it wins.
+
+Match the type to the same design direction the color came from. A warm autumn palette under a cold geometric sans reads as two projects.
 
 ## Shortcuts
 
-These find an adequate pairing fast and skip the reasoning; use them when the brief is vague or the type should stay quiet.
+These find an adequate pairing fast and skip the reasoning; use them when the request is vague or the type should stay quiet.
 
-- **A superfamily.** Google Fonts families with both sans and serif siblings, among them Alegreya, Ancizar, IBM Plex, Inria, Merriweather, Noto, PT, Roboto, Source. The catalogue moves and this list does not, so treat it as a starting set: `set-fonts` verifies every family against the API and fails loudly on one that is gone.
+- **A superfamily.** Google Fonts families with both sans and serif siblings, among them Alegreya, Ancizar, IBM Plex, Inria, Merriweather, Noto, PT, Roboto, Source. The catalogue moves and this list does not, so treat it as a starting set: `set-type` verifies every family against the API and fails loudly on one that is gone.
 - **One family across weights.**
 - **Same designer or foundry.**
 - **Serif display over sans body** when nothing else decides it.
@@ -75,16 +78,16 @@ These find an adequate pairing fast and skip the reasoning; use them when the br
 
 - **x-height parity.** Both faces are set from one size scale, so a small-x-height display face over a large-x-height body face gives a heading that looks weaker than its own body text. This is the one visual check that matters on screen; make it on the rendered page.
 - **Print faces at small sizes.** Delicate serifs and high stroke contrast turn to mud below 16px.
-- **Every family is a request.** Two is the target; three needs a reason.
+- **Every family is a download.** Two is the target; three needs a reason.
 - **Sets of themes:** no two share a display face or a body face.
 
 ## Scope
 
-Type only. Color, component aliases, shape, and the type scale are untouched: `set-fonts` moves families between stacks and nothing else, writing only the unsaved colors-and-type buffer. Save the theme to keep it, Adopt to ship it. Adopt is also what rewrites `fonts.css`, which is how a build with no editor in it loads the family at all.
+Type only. Color, component aliases, shape, and the type scale are untouched: `set-type` moves families between stacks and nothing else, writing only the font entries in the unsaved buffer. Save the theme to keep it, Adopt to ship it. Adopt is also what rewrites `fonts.css`, which is how a build with no editor in it loads the family at all.
 
 ## Verify
 
 - The CLI exits 0 and names each stack that moved, before and after.
 - Each URL reflects the family's real weights: a range for a variable family, an enumeration for a static one, a bare URL for a single-weight face.
 - The app shows the new type after a reload, and the editor's Fonts section lists both families with their fallbacks intact.
-- To revert, run the inverse brief, or load the open theme again to discard the buffer.
+- To revert, run the inverse pairing file, or load the open theme again to discard the buffer.

package/.claude/skills/live-tokens-set-type/references/type-anchors.md

@@ -0,0 +1,60 @@
+# Type anchors: feelings, idioms, and genres
+
+Read this when the type intent names one of these. An anchor overrides the
+Voice table in SKILL.md, because it is tuned to the same direction the color
+came from.
+
+An entry names a form model and a role, never a family. Take the families from
+the font matrix and the body-face rule in SKILL.md, and screen them against the
+weights the shipped text styles ask for.
+
+An occasion (Christmas, Autumn, Ocean) fixes color only. Take its type from the
+feeling it implies: Autumn reads cozy, Halloween reads ominous, Spring reads
+tender.
+
+## Feelings
+
+| Anchor | Type voice |
+|---|---|
+| Joyful, exuberant, energetic | dynamic sans in both slots |
+| Playful, whimsical | expressive display over a plain workhorse |
+| Optimistic, hopeful | humanist sans, low contrast |
+| Confident, bold | heavy rational display, plain body |
+| Serene, tranquil | dynamic sans, one family |
+| Tender, gentle, romantic | soft serif display over humanist sans, light weights |
+| Cozy, comforting | dynamic serif over dynamic sans |
+| Wistful, nostalgic, vintage, faded | rational serif display, quiet body |
+| Earthy, grounded, natural | dynamic serif over humanist sans |
+| Clinical, sterile, precise | one neo-grotesque, tightly set |
+| Contemplative, focused | one quiet superfamily |
+| Urgent, alarming | condensed grotesque, heavy |
+| Tense, anxious | neo-grotesque, tightly set |
+| Defiant, rebellious, loud | heavy display; a mono body works |
+| Melancholy, moody, sad | rational serif display over quiet sans |
+| Somber, grave, mournful | rational serif in both slots |
+| Ominous, dramatic, haunted | heavy high-contrast display |
+| Austere, severe, cold | one rational family |
+
+## Idioms, eras, and genres
+
+| Anchor | Type voice |
+|---|---|
+| Swiss, International | one rational neo-grotesque across both slots |
+| Bauhaus | geometric sans, heavy display |
+| Mid-century modern | dynamic sans, or a geometric display over a dynamic body |
+| Art deco, opulent, luxurious | rational high-contrast serif display, quiet body |
+| Terminal, phosphor | mono in both slots |
+| Cyberpunk, neon noir, futuristic | wide geometric display, neutral body |
+| Vaporwave | wide retro display, serif welcome |
+| Y2K, bubble | geometric sans, heavy display |
+| Blueprint | mono, or a technical grotesque; a mono body works here and almost nowhere else |
+| Scandinavian, hygge | dynamic sans on both sides |
+| Japandi, wabi-sabi | rational serif display over a quiet humanist body |
+| Cottagecore, botanical | dynamic serif display over humanist sans |
+| Editorial, magazine | high-contrast serif display over a text serif or humanist sans |
+| Newsprint, broadsheet | rational serif in both slots |
+| Risograph, zine | expressive display over a plain workhorse |
+| Corporate, professional, trustworthy | rational sans body with a rational serif or same-family display |
+| Brutalist | neo-grotesque or mono at heavy weight |
+| Memphis, postmodern | geometric display, plain body |
+| Industrial, workshop, gritty | condensed grotesque display over a plain body |

package/CHANGELOG.md

@@ -1,5 +1,96 @@
 # Changelog
 
+## 0.74.0 — A theme is three decisions and one document
+
+### Changed
+
+- **Breaking: the three theme CLI verbs are renamed, and there is no alias.**
+  `generate-theme` is now `set-colors`, `set-fonts` is now `set-type`, and
+  `adjust-geometry` is now `set-geometry`. Each verb names the dimension it
+  sets, and each matches the skill that runs it. A script or note that types
+  an old verb fails with "Unknown command"; there is no deprecation path,
+  because nothing is released against these names yet. `set-type` and
+  `set-geometry` keep their flags, their file formats, and their behaviour, and
+  the geometry ops file is now written to `scratch/geometry-ops.json`.
+
+  **`set-colors` writes the color buffer, and `save-theme` writes the theme.**
+  A theme is three decisions and one document. Each set verb now writes only
+  its own dimension into the unsaved buffers the app already renders:
+  `set-colors` joins `set-type` and `set-geometry` there, and no longer writes
+  or opens a theme. The new `save-theme <name>` composes the live state into
+  `themes/<slug>.json` and opens it, and with no unsaved edits it saves a copy
+  of the open theme under the new name. `--no-activate` saves without opening,
+  which is how a set of themes comes off one starting look. `--carry-from` is
+  gone: it existed because `set-colors` activated, and nothing activates now
+  until you save. The base color file no longer carries `name`; a name in it
+  is ignored with a notice. `live-tokens-create-theme` runs `save-theme` once,
+  after its three contributing skills. `init`, an undocumented alias for
+  `create` since 0.21.0, is gone: type `create`.
+
+  **36 dead keys left the override bag.** Themes carried the color, type, and
+  border-width siblings of keys an earlier migration dropped (Badge's `trait`
+  variant, SectionDivider's title and description slots, Dialog's variant and
+  state axes). Nothing read them, and every Adopt baked them into
+  `tokens.generated.css`. A colors-and-type migration drops them from your
+  themes on the next Save, the nine shipped themes are rewritten, and
+  `check:preset-themes` now refuses any shipped theme, `default` included,
+  whose override bag names a variable `tokens.css` does not declare.
+
+  Internal: the engine bundles are `dist-plugin/setColors`, `setType`, and
+  `setGeometry`, named for the verbs that load them. They have no `exports`
+  entry and no consumer imports them.
+
+- **A theme is one design direction routed to three contributing skills.**
+  `live-tokens-generate-theme` did two jobs: it read the request and fixed a
+  whole look, and it executed the color layer itself. So two of a theme's three
+  dimensions were skills and the third was a section. It is now
+  **live-tokens-create-theme**, which reads the request once, states one design
+  direction, states a color, a type, and a geometry intent, routes each to
+  **live-tokens-set-colors**, **live-tokens-set-type**, and
+  **live-tokens-set-geometry**, and assembles their three reports. Its one CLI
+  is `save-theme`. Every contributing skill still works when invoked directly
+  with an intent and no direction behind it. This changes four `description` triggers:
+  a whole look reaches create-theme, and a request naming one dimension goes
+  straight to that dimension's skill, including a color-only refinement like
+  "warmer".
+
+- **The anchor tables split by dimension.** A row in the old mood and style
+  vocabularies fixed color, type, and geometry at once, which meant the
+  coordinator read color mechanics and handed on the other two. create-theme
+  now holds `references/design-directions.md`, an index placing each anchor on
+  the valence, energy, and dominance axes with its one-line direction; each
+  contributing skill holds the column it executes, keyed on the same names.
+  `check:skills` gains an anchor-key parity gate, so a name that reaches only
+  some of the four files fails at commit.
+
+- **The theme skills call the user's own words the request, not the brief.**
+  "Brief" named two things at once: the user's words, and the seed JSON at
+  `scratch/<slug>-brief.json`. The second sense is fixed in two filenames and
+  in the CLI's own `<brief.json>` usage string, so the first sense moves.
+  Layer 0 of the pipeline in `docs/terminology.md` is now the request; the
+  files stay where they are and the prose calls them the seed file and the
+  pairing file. This changes one `description` trigger, in
+  `live-tokens-generate-theme`, from "from a natural-language brief" to "from
+  a natural-language request". set-fonts loses its one clash with the new
+  term: every family is a download rather than a request. The atlas tagline
+  named the wrong layer and now credits the design direction, the one sentence
+  three skills actually read.
+
+- **A palette's base color is called that, not its seed.** The word already
+  meant something else in this product: sketch mode displaces its strokes on
+  random seeds, and says so in copy a user reads. The theme document has always
+  called the value `baseColor`, so the skill and the CLI were the drift. The
+  generator's input key is now `baseColors` rather than `seeds`, and the file
+  the skill writes is `scratch/<slug>-base-colors.json`; the pairing file
+  `set-fonts` reads is `scratch/font-pairing.json`. Both CLI verbs report
+  against the new names, so a contrast failure now says "raise the Brand base
+  color lightness". Internally `buildColorsAndTypeFromSeeds` becomes
+  `buildColorsAndType`, dropping a "from" clause that was never true on the
+  type half, and `ColorsAndTypeBrief` becomes `ColorsAndTypeInput`; neither is
+  a public export. A kept base color file with
+  the old `seeds` key needs that one key renamed, and the skill rewrites the
+  file from scratch on every run anyway.
+
 ## 0.73.0 — The skill atlas ships from the package
 
 ### Added

package/README.md

@@ -328,16 +328,17 @@ npx @motion-proto/live-tokens <command>
 | `report [--json]` | The project as facts: pending migrations, tokens each component reads, which page renders which component, and both checkers' findings by rule. Always exits 0. |
 | `check-component [id]` | Validate a component's runtime, editor, and registration against the authoring contract; with no id, every component authored under `src/system/components`. |
 | `check-page [paths...]` | Validate pages against the build-page contract: catalogue components and their props, theme tokens over literals, route wiring. |
-| `generate-theme <brief.json> [--no-activate] [--dry-run] [--carry-from <name>]` | Build a full theme from a 10-seed OKLCH brief, enforce AA contrast, write `themes/<slug>.json`, and open it. |
-| `adjust <ops.json> [--dry-run]` | Move radius, padding, gap, and border-width aliases along their token scales. |
-| `set-fonts <brief.json> [--dry-run] [--no-verify]` | Bind Google Fonts families to the theme's font stacks, verified against the API. |
+| `set-colors <base-colors.json> [--dry-run]` | Build the theme's whole color identity from 10 OKLCH base colors, enforce AA contrast on the derived text tokens, and write the result to the unsaved colors-and-type buffer. |
+| `set-type <pairing.json> [--dry-run] [--no-verify]` | Bind Google Fonts families to the theme's font stacks, verified against the API. |
+| `set-geometry <ops.json> [--dry-run]` | Move radius, padding, gap, and border-width aliases along their token scales. |
+| `save-theme <name> [--no-activate] [--dry-run]` | Compose the live state into `themes/<slug>.json` and open it, which clears the unsaved buffers. |
 | `migrate [--check] [--write] [--tokens <path>]` | Reconcile the project with the installed package: additive `tokens.css` migrations, the pre-0.48 data-tree move, and a report on source references to the routes that moved in 0.35.0. |
 
 Once installed in a project, the same commands are available as `npx live-tokens <command>`.
 
 ## Claude Code skills
 
-The package bundles eight Claude Code skills. They encode the conventions this README cannot carry in full: which component fits a need, how a page is wired, what a valid theme looks like in OKLCH, how two typefaces sit together, how geometry moves along the token scales, how a project is checked against all of that, and how an existing page or component is brought back into line. Each triggers from an ordinary request, so there are no slash commands to learn.
+The package bundles nine Claude Code skills. They encode the conventions this README cannot carry in full: which component fits a need, how a page is wired, how one request becomes a whole look, what a valid theme looks like in OKLCH, how two typefaces sit together, how geometry moves along the token scales, how a project is checked against all of that, and how an existing page or component is brought back into line. Each triggers from an ordinary request, so there are no slash commands to learn.
 
 ### Install
 
@@ -363,33 +364,41 @@ Ask for a page, a route, or a screen: "build a pricing page", "add a /settings r
 
 The skill composes the page from shipped components, styles every value with `var(--token-*)` (no hex, no pixel literals, so editor changes repaint the page), places content on the column grid via `--columns-count`, `--columns-gutter`, and `--columns-max-width`, adds the route as a `lazy` import with a `source` so the overlay's "Page Source" button works, and imports `site.css` from the page rather than `main.ts` so page CSS stays out of the editor routes. It writes your page files and the route entry, and never touches the data tree.
 
-### `live-tokens-generate-theme`
+### `live-tokens-create-theme`
 
-Ask for a look: "a dark, moody night theme", "a St Patrick's Day theme in green and gold", "warmer", "more contrast", "calmer".
+Ask for a look: "a dark, moody night theme", "a St Patrick's Day theme in green and gold", "make it feel more serious".
 
-A theme is three decisions made from one brief: color, type, and geometry. The skill owns color and delegates the other two to `live-tokens-pair-fonts` and `live-tokens-adjust-geometry`, so the whole look comes from the same reading of the brief.
+A theme is three decisions: color, type, and geometry. This skill reads the request once, states one design direction that fixes all three, and routes a color, a type, and a geometry intent to `live-tokens-set-colors`, `live-tokens-set-type`, and `live-tokens-set-geometry`. Each of them writes its dimension into the unsaved buffers the app already renders. The skill then runs `npx live-tokens save-theme "<name>"`, which turns those buffers into `themes/<slug>.json` and opens it, and assembles the three reports into one summary.
 
-For color it translates the brief into ten OKLCH seeds (Brand, Accent, Special, Canvas, Neutral, Alternate, Info, Success, Warning, Danger) plus a light or dark scheme, then runs `npx live-tokens generate-theme <brief.json>`. The CLI assembles the curves, enforces AA contrast on derived text tokens and auto-corrects where it can, writes `themes/<slug>.json`, opens it, and prints a contrast report. Exit 1 means the seeds themselves are unworkable, and each failure line names the seed to change.
+It carries the anchor index: every feeling, idiom, era, genre, holiday, and season the skills know, placed on the valence, energy, and dominance axes with the direction each implies. An idiom sets constraints and a feeling moves dials inside them, so "cozy brutalist" reads the idiom first. Each contributing skill holds the mechanics for its own dimension, keyed on the same anchor names.
 
-Most of the skill is the judgment the generator cannot supply: a chroma budget scaled to how much screen area each palette covers, per-role lightness and hue bands for each scheme, gamut guardrails against impossible seeds, harmony modes, the optional canvas gradient, and a voice-to-shape table for the shape step. OKLCH anchors for named holidays and seasons live in a reference file the skill reads on demand.
+A refinement that names one dimension goes straight to that sibling. This skill takes the ones that span dimensions.
 
-Color lands in the theme file; type and shape land in the unsaved buffers, and one Save keeps all three. `--dry-run` prints the report without writing; `--no-activate` writes without opening. Opening a theme never changes what your site ships; Adopt does. Regenerating replaces that theme's whole color state, including palette edits made in the editor since the last run, and carries the live buffers forward, so re-rolling color after setting fonts and shape keeps both.
+### `live-tokens-set-colors`
 
-### `live-tokens-pair-fonts`
+Ask for color: "a cooler palette", "warmer", "more contrast", "calmer", "make the ground darker".
+
+The skill translates the color intent into ten OKLCH base colors (Brand, Accent, Special, Canvas, Neutral, Alternate, Info, Success, Warning, Danger) plus a light or dark scheme, then runs `npx live-tokens set-colors <base-colors.json>`. The CLI assembles the curves, enforces AA contrast on derived text tokens and auto-corrects where it can, writes the result to the unsaved colors-and-type buffer, and prints a contrast report. Exit 1 means the base colors themselves are unworkable, and each failure line names the base color to change.
+
+Most of the skill is the judgment the generator cannot supply: a chroma budget scaled to how much screen area each palette covers, per-role lightness and hue bands for each scheme, three levels of canvas commitment, gamut guardrails against impossible base colors, harmony modes, and the optional canvas gradient. OKLCH anchors for every named feeling, idiom, and occasion live in a reference file the skill reads on demand.
+
+Color is the one dimension every look fixes, so it runs first and never skips. `--dry-run` prints the report without writing. Saving the open theme in the editor, or running `save-theme`, keeps the result; Adopt ships it. A re-run replaces the buffer's whole color state, including palette edits made in the editor since the last run, and carries the type and geometry buffers forward.
+
+### `live-tokens-set-type`
 
 Ask for type: "pair some fonts for this theme", "what font should the headings use?", "make the type more editorial", "something friendlier", "a serif for headings".
 
-The skill chooses the families and runs `npx live-tokens set-fonts <brief.json>`, which binds each one to `--font-display`, `--font-sans`, `--font-serif`, or `--font-mono`. Every family is checked against the Google Fonts API before it is written, and the URL is built from the weights that family actually has: a range for a variable font, an enumeration for a static one, a bare URL for a single-weight display face. The report names the weights your typography tokens ask for and the family does not carry.
+The skill chooses the families and runs `npx live-tokens set-type <pairing.json>`, which binds each one to `--font-display`, `--font-sans`, `--font-serif`, or `--font-mono`. Every family is checked against the Google Fonts API before it is written, and the URL is built from the weights that family actually has: a range for a variable font, an enumeration for a static one, a bare URL for a single-weight display face. The report names the weights your typography tokens ask for and the family does not carry.
 
-The judgment is the skill's half. It anchors on the body face, because that is most of the words on the page and text faces survive small sizes where display faces do not. It classifies both candidates by form model (dynamic, rational, geometric) and applies the font matrix: two faces sharing a skeleton under different surfaces pair reliably, two faces sharing a surface over different skeletons fight, and two faces far apart on both read as a decision. It also carries the screen test a body face has to pass, a voice table from brief to type, and the Google Fonts superfamilies for when the type should stay quiet.
+The judgment is the skill's half. It anchors on the body face, because that is most of the words on the page and text faces survive small sizes where display faces do not. It classifies both candidates by form model (dynamic, rational, geometric) and applies the font matrix: two faces sharing a skeleton under different surfaces pair reliably, two faces sharing a surface over different skeletons fight, and two faces far apart on both read as a decision. It also carries the screen test a body face has to pass, a voice table from intent to type, a type anchor per named feeling and idiom, and the Google Fonts superfamilies for when the type should stay quiet.
 
 Scope: type only, and never color. Edits land in the colors-and-type `_working.json` buffer, so save the open theme to keep them. `--dry-run` reports without writing.
 
-### `live-tokens-adjust-geometry`
+### `live-tokens-set-geometry`
 
 Ask for shape or space: "make the buttons pill shaped", "sharper corners on the cards", "space it out", "tighter", "thinner borders".
 
-The skill turns the phrase into ops (`kind` of `radius`, `padding`, `gap`, or `border-width`, with `shift: N` or `set: <token>`, optionally scoped to one component id), then runs `npx live-tokens adjust <ops.json>`. The CLI moves each matching alias along its ladder, reads the live config first so "a bit more" compounds, and prints every change and every skip.
+The skill turns the phrase into ops (`kind` of `radius`, `padding`, `gap`, or `border-width`, with `shift: N` or `set: <token>`, optionally scoped to one component id), then runs `npx live-tokens set-geometry <ops.json>`. The CLI moves each matching alias along its ladder, reads the live config first so "a bit more" compounds, and prints every change and every skip.
 
 It also knows where these edits go wrong: controls run out of room long before containers do, so a global compaction is one step and anything deeper is aimed at named containers; a pill needs more horizontal padding than a square-cornered control, not less; and content insets stop at `--space-4`, below which a relative "tighter" reports as clamped instead of writing.
 

package/bin/check-page.mjs

@@ -46,9 +46,9 @@ const DEEP_IMPORT_PATTERNS = [
 const TEXT_AXES = ['font-size', 'font-family', 'font-weight', 'line-height', 'letter-spacing'];
 
 // The geometry the theme owns: spacing, stroke, radius, and shadow all have a
-// token scale, and `adjust` moves them. Sizing (a hero's height, a column's
-// minimum width, a max content width) is layout, has no scale, and stays
-// literal.
+// token scale, and `set-geometry` moves them. Sizing (a hero's height, a
+// column's minimum width, a max content width) is layout, has no scale, and
+// stays literal.
 const THEMED_GEOMETRY = /^(padding|margin|gap|row-gap|column-gap|border|outline|inset|top|right|bottom|left|box-shadow|text-shadow)(-|$)|-radius$/;
 
 // A local two-up or three-up is a layout. From four columns on, a hardcoded

package/bin/cli.mjs

@@ -8,9 +8,10 @@
 //   report                   The project as facts: tokens read, components used, findings by rule. Always exits 0.
 //   check-component [id]     Validate a component (or every authored one) against the create-component skill contract.
 //   check-page [paths...]    Validate pages against the build-page skill contract.
-//   generate-theme <brief>   Build a theme from a 10-seed OKLCH brief and open it.
-//   adjust <ops.json>        Apply radius/padding/gap/border-width ops to the open buffer.
-//   set-fonts <brief.json>   Bind Google Fonts families to the theme's font stacks.
+//   set-colors <colors>      Build the color identity from 10 OKLCH base colors, into the open buffer.
+//   set-geometry <ops>       Apply radius/padding/gap/border-width ops to the open buffer.
+//   set-type <pairing>       Bind Google Fonts families to the theme's font stacks.
+//   save-theme <name>        Compose the live state into themes/<slug>.json and open it.
 //   migrate [...]            Reconcile tokens.css, the data tree, and route references.
 
 import { cpSync, existsSync, mkdirSync, readdirSync, statSync, writeSync } from 'node:fs';
@@ -38,9 +39,10 @@ import {
 } from './migrate.mjs';
 import { runMigrateRoutes, formatRouteResult } from './migrate-routes.mjs';
 import { runCreate, formatCreateResult } from './create.mjs';
-import { runGenerateTheme, formatGenerateThemeResult } from './generate-theme.mjs';
-import { runAdjust, formatAdjustResult } from './adjust.mjs';
-import { runSetFonts, formatSetFontsResult } from './set-fonts.mjs';
+import { runSetColors, formatSetColorsResult } from './set-colors.mjs';
+import { runSetGeometry, formatSetGeometryResult } from './set-geometry.mjs';
+import { runSetType, formatSetTypeResult } from './set-type.mjs';
+import { runSaveTheme, formatSaveThemeResult } from './save-theme.mjs';
 
 const USAGE = `Usage: npx @motion-proto/live-tokens <command> [options]
 
@@ -69,7 +71,7 @@ Commands:
                               value a theme token. Checks every page under src/
                               when given no paths.
 
-Both check commands accept:
+check-component and check-page also accept:
   --json                      Machine-readable findings, for a skill to iterate
                               against until the exit code is 0
   --strict                    Treat warnings as errors
@@ -77,31 +79,29 @@ Both check commands accept:
                               (or set "checks": { "rules": {...} } in
                               live-tokens.config.json; "checks": { "exclude":
                               [...] } drops paths from discovery entirely)
-  generate-theme <brief.json> [--no-activate] [--dry-run] [--carry-from <name>]
-                              Build a full theme from a 10-seed OKLCH brief
-                              (see the live-tokens-generate-theme skill),
-                              enforce AA contrast on derived text tokens, write
-                              themes/<slug>.json, and open it in the editor.
-                              Opening never changes what your site ships; Adopt
-                              in the editor does that.
-                              --no-activate writes the theme without opening it;
-                              --dry-run prints the contrast report without
-                              writing. Non-color content (gradients, fonts,
-                              component aliases) carries forward from the live
-                              look, or from theme <name> with --carry-from.
-  adjust <ops.json> [--dry-run]
+  set-colors <base-colors.json> [--dry-run]
+                              Build the theme's whole color identity from 10
+                              OKLCH base colors (see the live-tokens-set-colors
+                              skill) and enforce AA contrast on the derived text
+                              tokens. Reads the live colors and type and writes
+                              the result to the unsaved colors-and-type buffer,
+                              so save the open theme in the editor or run
+                              save-theme to keep it. Fonts and every override no
+                              palette owns carry forward. --dry-run prints the
+                              contrast report without writing.
+  set-geometry <ops.json> [--dry-run]
                               Move radius, padding, gap, and border-width
                               aliases along their token scales (see the
-                              live-tokens-adjust-geometry skill). Reads each
+                              live-tokens-set-geometry skill). Reads each
                               component's live config and writes the result to
                               that component's unsaved buffer, so save the open
                               theme in the editor to keep it. --dry-run prints
                               the report without writing.
-  set-fonts <brief.json> [--dry-run] [--no-verify]
+  set-type <pairing.json> [--dry-run] [--no-verify]
                               Bind Google Fonts families to --font-display,
                               --font-sans, --font-serif, --font-mono and
                               --font-editorial (see
-                              the live-tokens-pair-fonts skill). Each family is
+                              the live-tokens-set-type skill). Each family is
                               verified against the Google Fonts API and the URL
                               is negotiated from the weights it actually has.
                               Writes the result to the unsaved colors-and-type
@@ -109,6 +109,17 @@ Both check commands accept:
                               keep it. --dry-run prints the report without
                               writing; --no-verify skips the network and
                               requires an explicit URL per family.
+  save-theme <name> [--no-activate] [--dry-run]
+                              Compose the live state (the unsaved buffers, the
+                              open theme under them, the shipped defaults under
+                              that) into themes/<slug>.json and open it, which
+                              clears the buffers. With no unsaved edits it saves
+                              a copy of the open theme under the new name.
+                              Opening never changes what your site ships; Adopt
+                              in the editor does that. --no-activate writes the
+                              theme and leaves the live state alone, so a set of
+                              themes comes off one starting look; --dry-run
+                              prints the report without writing.
   migrate [--check] [--write] [--tokens <path>]
                               Reconcile your project with the installed package:
                               applies additive tokens.css migrations, moves a
@@ -150,7 +161,7 @@ if (!command || command === '--help' || command === '-h') {
 
 const pkgRoot = resolve(dirname(fileURLToPath(import.meta.url)), '..');
 
-if (command === 'create' || command === 'init') {
+if (command === 'create') {
   const targetArg = rest.find((a) => !a.startsWith('-'));
   if (!targetArg) {
     fail(`Usage: npx @motion-proto/live-tokens create <project-directory>`);
@@ -241,72 +252,97 @@ if (command === 'check-page') {
   reportChecks('check-page', findings, checked, PAGE_RULES, opts);
 }
 
-if (command === 'generate-theme') {
-  const briefPath = rest.find((a) => !a.startsWith('-'));
-  if (!briefPath) {
-    fail(`Usage: npx @motion-proto/live-tokens generate-theme <brief.json> [--no-activate] [--dry-run]`);
+if (command === 'set-colors') {
+  const baseColorsPath = rest.find((a) => !a.startsWith('-'));
+  if (!baseColorsPath) {
+    fail(`Usage: npx @motion-proto/live-tokens set-colors <base-colors.json> [--dry-run]`);
+  }
+  if (rest.includes('--no-activate')) {
+    fail(
+      `set-colors has no --no-activate: it edits the open buffer, which is what the page already runs. ` +
+        `Nothing is activated until save-theme, which takes the flag.`,
+    );
+  }
+  if (rest.includes('--carry-from')) {
+    fail(
+      `set-colors has no --carry-from: it reads the live look and edits it in place, so a second theme ` +
+        `already starts from the first. Run save-theme --no-activate between themes.`,
+    );
   }
   try {
-    const carryIdx = rest.indexOf('--carry-from');
-    const carryFrom = carryIdx !== -1 ? rest[carryIdx + 1] : undefined;
-    if (carryIdx !== -1 && !carryFrom) fail(`--carry-from requires a theme name`);
-    const result = await runGenerateTheme({
-      briefPath,
-      activate: !rest.includes('--no-activate'),
+    const result = await runSetColors({
+      baseColorsPath,
       dryRun: rest.includes('--dry-run'),
-      carryFrom,
     });
-    console.log(formatGenerateThemeResult(result));
+    console.log(formatSetColorsResult(result));
     process.exit(result.report.failures.length === 0 ? 0 : 1);
   } catch (err) {
-    fail(`generate-theme failed: ${err instanceof Error ? err.message : String(err)}`);
+    fail(`set-colors failed: ${err instanceof Error ? err.message : String(err)}`);
   }
 }
 
-if (command === 'adjust') {
+if (command === 'set-geometry') {
   const opsPath = rest.find((a) => !a.startsWith('-'));
   if (!opsPath) {
-    fail(`Usage: npx @motion-proto/live-tokens adjust <ops.json> [--dry-run]`);
+    fail(`Usage: npx @motion-proto/live-tokens set-geometry <ops.json> [--dry-run]`);
   }
   if (rest.includes('--no-activate')) {
     fail(
-      `adjust has no --no-activate: it edits the open buffer, which is what the page already runs. ` +
+      `set-geometry has no --no-activate: it edits the open buffer, which is what the page already runs. ` +
         `Drop the flag and re-run.`,
     );
   }
   try {
-    const result = await runAdjust({
+    const result = await runSetGeometry({
       opsPath,
       dryRun: rest.includes('--dry-run'),
     });
-    console.log(formatAdjustResult(result));
+    console.log(formatSetGeometryResult(result));
     process.exit(0);
   } catch (err) {
-    fail(`adjust failed: ${err instanceof Error ? err.message : String(err)}`);
+    fail(`set-geometry failed: ${err instanceof Error ? err.message : String(err)}`);
   }
 }
 
-if (command === 'set-fonts') {
-  const briefPath = rest.find((a) => !a.startsWith('-'));
-  if (!briefPath) {
-    fail(`Usage: npx @motion-proto/live-tokens set-fonts <brief.json> [--dry-run] [--no-verify]`);
+if (command === 'set-type') {
+  const pairingPath = rest.find((a) => !a.startsWith('-'));
+  if (!pairingPath) {
+    fail(`Usage: npx @motion-proto/live-tokens set-type <pairing.json> [--dry-run] [--no-verify]`);
   }
   if (rest.includes('--no-activate')) {
     fail(
-      `set-fonts has no --no-activate: it edits the open buffer, which is what the page already runs. ` +
+      `set-type has no --no-activate: it edits the open buffer, which is what the page already runs. ` +
         `Drop the flag and re-run.`,
     );
   }
   try {
-    const result = await runSetFonts({
-      briefPath,
+    const result = await runSetType({
+      pairingPath,
       dryRun: rest.includes('--dry-run'),
       verify: !rest.includes('--no-verify'),
     });
-    console.log(formatSetFontsResult(result));
+    console.log(formatSetTypeResult(result));
+    process.exit(0);
+  } catch (err) {
+    fail(`set-type failed: ${err instanceof Error ? err.message : String(err)}`);
+  }
+}
+
+if (command === 'save-theme') {
+  const name = rest.find((a) => !a.startsWith('-'));
+  if (!name) {
+    fail(`Usage: npx @motion-proto/live-tokens save-theme <name> [--no-activate] [--dry-run]`);
+  }
+  try {
+    const result = await runSaveTheme({
+      name,
+      activate: !rest.includes('--no-activate'),
+      dryRun: rest.includes('--dry-run'),
+    });
+    console.log(formatSaveThemeResult(result));
     process.exit(0);
   } catch (err) {
-    fail(`set-fonts failed: ${err instanceof Error ? err.message : String(err)}`);
+    fail(`save-theme failed: ${err instanceof Error ? err.message : String(err)}`);
   }
 }
 
@@ -391,9 +427,10 @@ const SAMPLE_PROMPTS = {
   'live-tokens-build-page': 'build a pricing page using live-tokens components',
   'live-tokens-pick-component': "what's the difference between TabBar and SegmentedControl?",
   'live-tokens-create-component': 'author a new Toggle component for my live-tokens project',
-  'live-tokens-generate-theme': 'make me a bright and cheerful theme',
-  'live-tokens-adjust-geometry': 'make the buttons pill shaped',
-  'live-tokens-pair-fonts': 'pair some fonts for this theme',
+  'live-tokens-create-theme': 'make me a bright and cheerful theme',
+  'live-tokens-set-colors': 'give me a cooler palette, same fonts',
+  'live-tokens-set-type': 'pair some fonts for this theme',
+  'live-tokens-set-geometry': 'make the buttons pill shaped',
   'live-tokens-fix-findings': 'make check:design pass',
   'live-tokens-check-compliance': 'check this project against the design system',
 };