@motion-proto/live-tokens 0.73.0 → 0.74.0

package/.claude/skills/live-tokens-build-page/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: live-tokens-build-page
-description: Apply the @motion-proto/live-tokens project conventions when building a page: shipped components, theme tokens over hex/pixel literals, dynamic route mounting, per-page site.css. Use when the user asks to build, create, lay out, or rearrange a page, route, hero, landing page, dashboard, settings screen, pricing page, or a tool screen with a stage and controls; add a route; place an existing component on a page; assemble a screen from the catalogue; or says the layout, label sizes, or control sizes of a page are off. For component choice see live-tokens-pick-component; for a brand-new component, live-tokens-create-component; for look and feel mid-build, live-tokens-generate-theme or live-tokens-adjust-geometry.
+description: Apply the @motion-proto/live-tokens project conventions when building a page: shipped components, theme tokens over hex/pixel literals, dynamic route mounting, per-page site.css. Use when the user asks to build, create, lay out, or rearrange a page, route, hero, landing page, dashboard, settings screen, pricing page, or a tool screen with a stage and controls; add a route; place an existing component on a page; assemble a screen from the catalogue; or says the layout, label sizes, or control sizes of a page are off. For component choice see live-tokens-pick-component; for a brand-new component, live-tokens-create-component; for look and feel mid-build, live-tokens-create-theme or live-tokens-set-geometry.
 ---
 
 # Building pages in a live-tokens project
@@ -8,7 +8,7 @@ description: Apply the @motion-proto/live-tokens project conventions when buildi
 Two rules above all else:
 
 1. **Use a shipped component if one fits.** Import from `@motion-proto/live-tokens/components/<Name>.svelte`. See **live-tokens-pick-component** for the catalogue and the confusing-pair decisions. Pass only the props it declares, with variant and size values from its union: `npx live-tokens components <id>` prints them (`--json` for data), and the list includes the project's own components beside the shipped ones. A prop a component does not declare is dropped silently at runtime, and the checker reports it. Author custom markup only when nothing fits, and then consider **live-tokens-create-component** so the new piece is editable too.
-2. **Use theme tokens for every value.** Every color, spacing, radius, font-size, and font-family in page CSS is a `var(--token-*)`, whether it sits in the `<style>` block, an inline `style=` attribute, or a `style:` directive. No colour literals in any notation, `white` and `rgb()` included. No px or rem in spacing, stroke, radius, or shadow: that is the geometry the theme owns and `adjust` moves. Sizing is layout, not theme: a hero's height, a max content width, or a column's minimum width stays a literal. A change in `/live-tokens/editor` should repaint your page.
+2. **Use theme tokens for every value.** Every color, spacing, radius, font-size, and font-family in page CSS is a `var(--token-*)`, whether it sits in the `<style>` block, an inline `style=` attribute, or a `style:` directive. No colour literals in any notation, `white` and `rgb()` included. No px or rem in spacing, stroke, radius, or shadow: that is the geometry the theme owns and `set-geometry` moves. Sizing is layout, not theme: a hero's height, a max content width, or a column's minimum width stays a literal. A change in `/live-tokens/editor` should repaint your page.
 
 For text, reach for a whole text style rather than assembling one: `--heading-xl` through `--heading-sm`, `--body-md`, `--body-sm`, `--editorial-xl` through `--editorial-sm`, `--eyebrow`, and `--code` each carry a `-font-family`, `-font-size`, `-font-weight`, `-line-height`, and `-letter-spacing`. A heading set from `--heading-lg-*` retypes when the theme's fonts change; one set from a raw `font-size` does not.
 

package/.claude/skills/live-tokens-check-compliance/SKILL.md

@@ -27,7 +27,7 @@ The answer to "check this project" is a report. Every fact in it comes from one
 | `usage.byPage` | Which catalogue component each page renders, and how many times | A page rendering none is either chrome or hand-rolled markup that a shipped component covers. |
 | `usage.unusedShipped` | Shipped components no page renders | Information, not a finding. |
 | `usage.customUnregistered`, `usage.customUnused` | The project's own components that are unregistered or unused | Dead or half-wired work. |
-| `findings.pages`, `findings.components` | Both checkers' findings by rule, under the project's severities and again under `--strict` | The errors are what fails the build today; the strict count is what a fully tokenized project would fail. |
+| `findings.pages`, `findings.components` | Both checkers' findings by rule, under the project's severities and again with every warning counted as an error | The errors are what fails the build today; the strict count is what a fully tokenized project would fail. |
 
 ## Mechanical or judgement
 
@@ -42,7 +42,7 @@ A translucent overlay on an app shell, or a layout size the project owns, may be
 
 1. Migrations pending, and the one command that clears them.
 2. What fails the build now: errors by rule, with the files.
-3. What `--strict` would add: warnings by rule.
+3. What the strict count adds: warnings by rule.
 4. Components: unread tokens, unregistered, undescribed.
 5. Usage: what each page renders, and what is used nowhere.
 6. Recommended fixes, in the order **live-tokens-fix-findings** would take them: migrations, then the largest group of errors, then the rest, then warnings. Mark each as mechanical or judgement.

package/.claude/skills/live-tokens-create-component/SKILL.md

@@ -49,7 +49,7 @@ Shipped editors live in `src/editor/component-editor/` because they are library-
    ```bash
    npx live-tokens check-component <id> --strict --json
    ```
-   `--json` gives each finding a stable `rule` id and a line number, so work one rule at a time. `--strict` fails on warnings too, the right setting for a new component: every warning is a naming or token decision that is cheaper to make now than to migrate later. Exit code 0 is the gate. With no id it checks every component under `src/system/components`; a project scaffolded by `create` runs that as `npm run check:design` before every `vite build`.
+   `--json` gives each finding a stable `rule` id and a line number, so work one rule at a time. `--strict` fails on warnings too, the right setting for a new component: every warning is a naming or token decision that is cheaper to make now than to migrate later. `--off=<rule>` silences a rule for one run, which a component still being authored has no use for: the finding is a decision to make. Exit code 0 is the gate. With no id it checks every component under `src/system/components`; a project scaffolded by `create` runs that as `npm run check:design` before every `vite build`.
 
    If it rejects a suffix, do not invent a new name for the role. Find a shipped component that paints the same thing and use the name it uses: every shipped component passes this same check, so the catalogue is the worked reference.
 7. **Verify** with the checklist at the bottom of this file, then place the component on a page with **live-tokens-build-page**.
@@ -90,9 +90,9 @@ state-after-property and fails.
 
 Read `references/token-naming.md` for what each one means and when two of them
 compete. A suffix outside that list fails `check-component`. The list lives in
-`KIND_RULES` in the editor's `aliasKinds.ts`, which the picker, the `adjust`
-CLI, and `check-component` all read, so a name accepted here always has a
-control behind it.
+`KIND_RULES` in the editor's `aliasKinds.ts`, which the picker, the
+`set-geometry` CLI, and `check-component` all read, so a name accepted here
+always has a control behind it.
 
 ### Rules that bite
 

package/.claude/skills/live-tokens-create-theme/SKILL.md

@@ -0,0 +1,80 @@
+---
+name: live-tokens-create-theme
+description: Create a complete live-tokens theme from a natural-language request by stating one design direction and routing a color intent, a type intent, and a geometry intent to live-tokens-set-colors, live-tokens-set-type, and live-tokens-set-geometry. Use whenever the user asks for a theme, look, vibe, or brand feel by mood, style, era, season, holiday, or hue; when they name only a color and want a theme around it; or when they refine a look across more than one dimension. Not for a single token (use the editor), and not for one dimension alone: color is live-tokens-set-colors, type is live-tokens-set-type, geometry is live-tokens-set-geometry.
+---
+
+# Creating a theme from a request
+
+A look is three decisions: color, type, and geometry. This skill reads the
+**request**, the user's own words, and states one **design direction**, a line
+or two that fixes all three. From it come three **intents**, one per dimension,
+each naming an outcome and never a value. Each goes to the contributing skill
+that owns that dimension, and their three reports come back as one **assembled
+report**, so the whole look comes from one reading.
+
+Every contributing skill writes its dimension into the unsaved buffers the app
+already renders, and those three buffers are the **look**. This skill runs one
+CLI of its own, `save-theme`, which turns the look into the **theme**, the
+document at `themes/<slug>.json`, and opens it. Never hand-author theme JSON and
+never edit the data tree directly.
+
+## Workflow
+
+1. Read the request once and state the design direction to the user: the mood, the hue family, the scheme, and the type and geometry that mood implies. It fixes enough to derive the three intents in step 3, and it names the default where the request leaves a dimension open. Keep it to a line or two. Every step below keys off it.
+2. Read `references/design-directions.md` and name the **anchor** the request matches: a feeling, an idiom, or an occasion that reference lists, each one fixing color, type, and geometry together. An idiom sets constraints and a feeling moves dials inside them, so a request matching both reads the idiom first. A request matching none takes the design direction alone.
+3. State the three intents the design direction and the anchor imply, one line each: the color intent, the type intent, and the geometry intent. Each names an outcome. Pass the anchor's name with each one, because every contributing skill holds its own anchors for its own dimension under the same names. Never reach for an OKLCH triple, a font family, or a token on a contributing skill's behalf.
+4. Invoke **live-tokens-set-colors** with the color intent. This step never skips: a theme request names a color identity, so color is the one dimension every look fixes.
+5. Invoke **live-tokens-set-type** with the type intent. Skip only when the user asked to leave the type alone.
+6. Invoke **live-tokens-set-geometry** with the geometry intent. Skip when the geometry intent is to leave the geometry alone.
+7. Take the theme name from the design direction and run `npx live-tokens save-theme "<name>"`. It composes the three buffers into `themes/<slug>.json` and opens it, so nothing is left unsaved. `--dry-run` prints what it would write.
+8. Assemble the three reports into the assembled report: the design direction, what each contributing skill changed, the theme `save-theme` wrote, and anything one of them flagged. Tell the user to look at the running app. Offer refinements (see Refining a look).
+
+A set of themes runs steps 4 to 7 once per theme, with `--no-activate` on every
+save but the last, so each theme starts from the same live look.
+
+## What each contributing skill owns
+
+Hand an outcome and the anchor's name. The mechanics stay where they are.
+
+| Dimension | Contributing skill | It decides |
+|---|---|---|
+| color | live-tokens-set-colors | ten base colors, the scheme, harmony, the canvas commitment, the contrast pass |
+| type | live-tokens-set-type | the two families, the form models behind them, the weights |
+| geometry | live-tokens-set-geometry | radius, padding, gap, and border-width moves, global or per component |
+
+A dimension the request leaves open still gets an intent, taken from the anchor.
+A dimension the request rules out gets no invocation at all, and the assembled
+report says which.
+
+## Refining a look
+
+A refinement arrives against a theme that is already open, and one adjective
+usually names one dimension. Route it rather than re-reading the whole look:
+
+| The user says | Goes to |
+|---|---|
+| warmer, cooler, calmer, louder, lighter, darker, moodier, more contrast | live-tokens-set-colors |
+| more editorial, friendlier, more technical, a serif for headings | live-tokens-set-type |
+| rounder, sharper, pill buttons, tighter, airier, thicker borders | live-tokens-set-geometry |
+
+Keep this skill for a refinement that spans dimensions ("make it feel more
+serious"), or one that names no dimension at all. State a new design direction
+and route all three again.
+
+## Files each step writes
+
+Color, type, and geometry each write an unsaved buffer, which the page already
+runs. `save-theme` composes the three into `themes/<slug>.json` and opens it,
+which clears the buffers; Adopt then ships the theme. Opening a theme never
+changes what the site ships. Only Adopt, in the editor, does that. Component
+aliases and gradients carry forward from the live look into the theme
+`save-theme` writes; user-tuned gradients survive, stock ones rebuild from the
+new families.
+
+## Verify
+
+- Each contributing skill reports back, and `set-colors` exits 0 with every check passing (auto-corrected is fine).
+- `save-theme` exits 0 and names the theme it wrote and opened.
+- The app (dev server running) shows the whole look after a reload, and the editor's Theme panel names that theme with no unsaved marker.
+- The assembled report names one design direction, and the three intents trace to it.
+- To return to the previous look, load the earlier theme from the Theme panel.

package/.claude/skills/live-tokens-create-theme/references/design-directions.md

@@ -0,0 +1,94 @@
+# Design directions: feelings, idioms, and occasions
+
+Read this once the request names a feeling, a design idiom, an era, a genre, a
+holiday, a season, or a natural scene. Each entry places the request and gives
+the direction the three intents come from.
+
+The mechanics live with the executors. Color anchors are in
+live-tokens-set-colors, type anchors in live-tokens-set-type, geometry anchors
+in live-tokens-set-geometry, each keyed on the same names as the tables below.
+Name the anchor when you state an intent and the sibling reads its own column.
+
+Three axes place any request, including one no entry lists:
+
+| Axis | Reads as | Carried by |
+|---|---|---|
+| Valence | pleasant against unpleasant | lightness, above everything else |
+| Energy | aroused against calm | chroma, and hue distance on screen |
+| Dominance | assertive against yielding | surface contrast, type weight, border weight, tightness |
+
+An idiom sets constraints and a feeling moves dials, so a request that names
+both ("cozy brutalist", "clinical Swiss") reads the idiom first and lets the
+feeling move the dials inside it.
+
+## Feelings
+
+Valence and energy set the quadrant, and the table runs in quadrant order:
+pleasant-aroused, pleasant-calm, unpleasant-aroused, unpleasant-calm. Dominance
+separates confident from gentle inside one quadrant and lives almost entirely
+outside color.
+
+| Request | Placement | Direction |
+|---|---|---|
+| Joyful, exuberant, energetic | pleasant, high energy | warm and bright throughout, with nothing held back |
+| Playful, whimsical | pleasant, high energy, low dominance | four hue families at play, soft and generous |
+| Optimistic, hopeful | pleasant, moderate energy | a cool ground lit by one warm counterpoint, like sunrise |
+| Confident, bold | pleasant, high energy, high dominance | wide contrast, heavy weight, held tight |
+| Serene, tranquil | pleasant, low energy | cool and quiet, with nothing loud anywhere |
+| Tender, gentle, romantic | pleasant, low energy, low dominance | a soft warm ground, a narrow range, light weights |
+| Cozy, comforting | pleasant, low energy | warm through and through, nothing cool on screen |
+| Wistful, nostalgic, vintage, faded | pleasant, low energy | chroma withheld rather than light withheld |
+| Earthy, grounded, natural | pleasant, low energy, moderate dominance | warm mineral hues, nothing synthetic |
+| Clinical, sterile, precise | neutral, low energy, high dominance | an untinted ground, one cool hue, tightly set |
+| Contemplative, focused | neutral, low energy | one cool hue and almost nothing else |
+| Urgent, alarming | unpleasant, high energy, high dominance | a neutral ground so the alarm lands, heavy and tight |
+| Tense, anxious | unpleasant, high energy | an uncomfortable ground under a pair that vibrates |
+| Defiant, rebellious, loud | unpleasant, high energy, highest dominance | near-black under one acid hue, blunt everywhere |
+| Melancholy, moody, sad | unpleasant, low energy | dark and cool, holding one moment of color |
+| Somber, grave, mournful | unpleasant, low energy, high dominance | near-neutral dark, sharp and quiet |
+| Ominous, dramatic, haunted | unpleasant, low energy, high dominance | dark with one hot accent and real atmosphere |
+| Austere, severe, cold | unpleasant, lowest energy, highest dominance | monochrome at one extreme of lightness |
+
+## Idioms, eras, and genres
+
+The table runs modernist, digital, quiet, print, expressive.
+
+| Request | Placement | Direction |
+|---|---|---|
+| Swiss, International | neutral, low energy, high dominance | one hue on a near-white ground, rational, tight |
+| Bauhaus | pleasant, high energy, high dominance | primaries at full commitment on paper, geometric, square but for the circle |
+| Mid-century modern | pleasant, moderate energy | warm muted mid-tones, soft and open, no borders |
+| Art deco, opulent, luxurious | pleasant, low energy, high dominance | dark with one metal, high-contrast type, sharp |
+| Terminal, phosphor | neutral, moderate energy, high dominance | one phosphor hue on near-black, mono, bordered |
+| Cyberpunk, neon noir, futuristic | unpleasant, high energy, high dominance | dark with two neons and a glow, wide type, sharp |
+| Vaporwave | pleasant, moderate energy, low dominance | light sunset pastels with a gradient, retro display, soft |
+| Y2K, bubble | pleasant, high energy | a chrome ground under electric color, geometric, pills |
+| Blueprint | neutral, low energy, high dominance | a drafting ground with pale rules, technical type, gridded |
+| Scandinavian, hygge | pleasant, low energy, low dominance | a chalk ground and muted naturals, soft and open |
+| Japandi, wabi-sabi | pleasant, lowest energy | unbleached paper, near-monochrome, generous space, no borders |
+| Cottagecore, botanical | pleasant, low energy, low dominance | warm cream and garden hues, serif display, soft |
+| Editorial, magazine | neutral, low energy, high dominance | paper and ink with one strong hue, carried by rules |
+| Newsprint, broadsheet | neutral, low energy | grey-warm paper under near-black ink, serif throughout, tight |
+| Risograph, zine | pleasant, high energy, high dominance | two flat spot inks on paper, expressive display, heavy rules |
+| Corporate, professional, trustworthy | pleasant, low energy | cool near-white with navy and teal, conventional everywhere |
+| Brutalist | unpleasant, high energy, highest dominance | a pure ground, one alarming hue, heavy type, thick borders |
+| Memphis, postmodern | pleasant, highest energy | a pastel ground under four hue families, shapes set against each other |
+| Industrial, workshop, gritty | neutral, moderate energy, high dominance | concrete and steel with safety orange, condensed type, thick borders |
+
+## Occasions
+
+An occasion fixes color only, so its type and geometry intents come from the
+feeling it implies or from the generic tables in the sibling skills.
+
+Every occasion is a statement request: the named color goes on the ground
+rather than only on the buttons.
+
+| Request | Direction |
+|---|---|
+| Christmas | red and green with gold, one of the two owning the ground |
+| Halloween | pumpkin, violet, and poison green, dark either way |
+| St. Patrick's | green with gold over a pale ground |
+| Ocean | blues held to one narrow band |
+| Sunset | a hue sweep through red, falling in lightness |
+| Autumn | parchment under rust, gold, and moss |
+| Spring | pastels, greens and pinks over a mint ground |

package/.claude/skills/live-tokens-set-colors/SKILL.md

@@ -0,0 +1,140 @@
+---
+name: live-tokens-set-colors
+description: Set a live-tokens theme's color from a color intent: ten OKLCH base colors, a light or dark scheme, and an AA-gated contrast pass, written into the unsaved color buffer the app already renders. Use whenever the user asks for a palette, colors, or hues by mood, style, era, season, holiday, or hue; when they name only a color; or when they refine the color of a look: warmer, cooler, calmer, louder, lighter, darker, moodier, more contrast. Also invoked by live-tokens-create-theme, which supplies the color intent for a whole look. Changes color only, never fonts or geometry. Not for a single token (use the editor), and not for a whole look (see live-tokens-create-theme).
+---
+
+# Setting a theme's colors
+
+You choose ten base colors; the CLI builds every ramp from them, enforces AA
+contrast on the derived text tokens, writes the result into the unsaved colors
+buffer the app already renders, and prints a contrast report. Never hand-author
+theme JSON and never edit the data tree directly.
+
+The run replaces the color state in that buffer and carries everything else
+forward, so it composes with type and geometry in any order. Saving the open
+theme in the editor, or running `save-theme`, turns the live look into a theme.
+
+## Workflow
+
+1. Read the color intent. When it names an anchor (a feeling, an idiom, or an occasion), read `references/color-anchors.md` for that entry; it overrides the generic bands below. Say which anchor you took.
+2. Translate the intent into ten base colors using the framework below and write `scratch/<slug>-base-colors.json`. Nothing else records the base colors, so this file is the only copy; one per slug is what makes the refinement pass cheap.
+3. Run `npx live-tokens set-colors scratch/<slug>-base-colors.json`. It writes the color state into the unsaved buffer the page already runs, and prints a contrast report.
+4. Read the report. Exit 0 passes, and auto-corrected values count as passing. Exit 1 means the base colors are unworkable; each failure line names the base color to change, usually by raising its lightness or cutting its chroma. Fix the base color file and re-run.
+5. Report back in a line: the scheme, the hue families on screen, the canvas commitment level, and anything the report auto-corrected.
+
+Flags: `--dry-run` prints the contrast report without writing.
+
+## The base color file
+
+```json
+{
+  "scheme": "light",
+  "baseColors": {
+    "Brand":     { "l": 0.62, "c": 0.17, "h": 145 },
+    "Accent":    { "l": 0.80, "c": 0.15, "h": 95 },
+    "Special":   { "l": 0.60, "c": 0.19, "h": 300 },
+    "Canvas":    { "l": 0.93, "c": 0.04, "h": 120 },
+    "Neutral":   { "l": 0.55, "c": 0.012, "h": 140 },
+    "Alternate": { "l": 0.58, "c": 0.009, "h": 60 },
+    "Info":      { "l": 0.60, "c": 0.15, "h": 255 },
+    "Success":   { "l": 0.60, "c": 0.16, "h": 150 },
+    "Warning":   { "l": 0.75, "c": 0.15, "h": 85 },
+    "Danger":    { "l": 0.58, "c": 0.20, "h": 25 }
+  }
+}
+```
+
+A base color is the one color a palette's whole ramp derives from. All 10 are required, and each may be given as a `"#rrggbb"` string instead. OKLCH: `l` is 0 to 1 lightness, `c` is chroma (0 grey, about 0.37 max), `h` is hue in degrees. The file names no theme: the slug in its own path is the theme name live-tokens-create-theme intends, or any label when this skill runs alone. `canvasGradient` is an optional boolean, see below.
+
+Roles: **Brand** is the dominant chromatic identity; **Accent** the supporting color; **Special** the rare expressive tertiary; **Canvas** is the page background verbatim; **Neutral** drives neutral surfaces and body text; **Alternate** is the second near-grey family; the four statuses are conventional signals.
+
+## Chroma budget: color is inversely proportional to area
+
+| Tier | Palettes | Chroma |
+|---|---|---|
+| Ground (about 60% of every screen) | Neutral, Alternate | C 0.008 to 0.02 |
+| Canvas (the largest single area) | Canvas | Per the commitment levels below, C 0.02 to 0.14 |
+| Dominant chromatic (about 30%) | Brand | C 0.10 to 0.20 |
+| Garnish (about 10%) | Accent, Special | may exceed Brand; at most one at the gamut cap for its hue (see Gamut guardrails) |
+| Conditional | Info, Success, Warning, Danger | C 0.12 to 0.19 |
+
+A good theme reads as 3 or 4 hue families on screen, never 10. Neutral and Alternate stay near-grey but tinted toward the theme (Neutral near Brand's hue; Alternate offset 15 to 60 degrees, or a warm/cool counterpoint), never pure C = 0 unless an anchor calls for it.
+
+## Per-role bands
+
+| Base color | Light scheme | Dark scheme | Hue |
+|---|---|---|---|
+| Canvas | L 0.92 to 0.98, C 0.02 to 0.06 | L 0.15 to 0.28, C 0.01 to 0.05 | Brand's hue or its harmony slot |
+| Neutral, Alternate | L about 0.55, C 0.008 to 0.02 | same | per the chroma budget |
+| Brand | L 0.45 to 0.62, C 0.12 to 0.20 | L 0.70 to 0.83, C cut by a third | the request's identity hue |
+| Accent | harmony slot, or at least 0.25 L from Brand when the mode collapses hue distance | lighten and desaturate like Brand | harmony slot |
+| Special | most expressive; default Brand hue +60 at about 65% of Brand's C | same transform | harmony slot |
+| Info | shared status L (0.55 to 0.65 light) | lighten like Brand | H 230 to 260 |
+| Success | shared status L | same | H 140 to 155 |
+| Warning | L 0.75 or higher (vivid yellow must be light) | same | H 70 to 90 |
+| Danger | shared status L, C 0.15 to 0.20 | same | H 20 to 30 |
+
+**The canvas carries the theme's identity, so commit to it.** The page background is the largest area on screen and the strongest difference between themes; a timid canvas makes every theme look the same. Below C 0.015 at L 0.95 a tint is imperceptible, which makes near-white a deliberate choice for clean or minimal intents and never the default. Three levels of commitment:
+
+1. *Tinted paper* (most UI intents): C 0.02 to 0.06, with L down to 0.92 where the hue needs room.
+2. *Colored ground* (expressive intents): L 0.85 to 0.92 at C 0.05 to 0.10. The page is unmistakably mint, parchment, sky.
+3. *Full-color ground* (holiday and statement intents): the canvas is the theme color, like a red Christmas page with green and gold on it. Keep canvas L at or below 0.48 or at or above 0.85 so text has somewhere to go; the contrast gate enforces legibility either way.
+
+Also:
+
+- Blue tints cap very low at high L (H 264 at L 0.95 barely reaches C 0.03): lower L for a blue canvas rather than fighting the ceiling. Yellow, green, and cream tint generously at high L.
+- When generating a set of themes, make the canvases pairwise distinct in hue or in L. Two light themes both near (0.97, 0.01) read as one theme with different buttons.
+- A dark scheme transforms every base color: each chromatic one lightens to L 0.75 to 0.85 and drops about a third of its chroma, because saturated color vibrates on dark grounds.
+- Equal lightness reads as equal weight: give the four statuses one shared L, and do the same for Brand and Accent when they should balance.
+- Status hues never rotate with the harmony; only their L and C adapt to the mood.
+
+## Mood dials
+
+Pleasantness rises with lightness (strongly) and saturation (weakly); energy rises with saturation; drama rises with dark plus saturated. Dominance, the third axis, is carried by surface contrast, type weight, and tightness rather than by color at all.
+
+That is the whole mechanism, and one dial moves without a reference: warm is hues 20 to 110 plus pink 290 to 360, cool is 140 to 290. For an intent that names a feeling, read `references/color-anchors.md` instead of guessing the dial settings.
+
+Avoid mid-lightness yellow-green (H 100 to 120 at L 0.5 to 0.7, C about 0.1) unless the intent asks for olive or toxic.
+
+## Gamut guardrails
+
+The engine clamps to gamut regardless; these keep the intent achievable.
+
+- Dark saturated yellow does not exist: H 90 at L 0.4 caps at C 0.08 and reads olive. Vivid yellow needs L 0.8 or more. Brown is dark low-chroma orange.
+- Vivid light blue does not exist: H 264 at L 0.9 caps at C 0.05. Rich blue lives at L 0.40 to 0.55.
+- Teal and sky cap at C 0.15.
+- Peak chroma anchors: red H20 C 0.25 at L 0.63; orange H60 C 0.18 at L 0.76; yellow H90 C 0.18 at L 0.86; green H140 C 0.28 at L 0.88; blue H264 C 0.28 at L 0.50; magenta H320 C 0.31 at L 0.65.
+
+## Harmony
+
+Hue offsets from Brand: complementary +180; split-complementary +150/+210; triadic +120/+240; tetradic +60/+180/+240; square +90 steps; compound +30/+180/+210; analogous plus or minus 30; monochromatic same hue.
+
+- A vague or single-adjective intent takes monochromatic or analogous, with Accent separated from Brand by L and C rather than hue. The polished-UI default: Accent at Brand's hue and about 45% of its chroma, Special at +60 and about 65%.
+- An intent naming two colors: measure their hue gap and pick the matching mode (green plus gold is 60 to 90 degrees, so analogous or compound).
+- Drama or maximum contrast: complementary, triadic, or tetradic, and then tone one side down, since max-chroma text on a near-black ground vibrates.
+
+## Canvas sky and shadows
+
+`"canvasGradient": true` renders the page background as a vertical gradient from the Canvas ramp. Default off. Turn it on only when the intent evokes atmosphere (sky, night, dusk, glow, underwater) or asks for a gradient outright; keep it off for crisp, flat, minimal, or corporate intents and whenever in doubt, because a sky on every theme stops meaning anything. It needs a committed canvas (level 2 or 3); at the ramp edge the engine skips it and says so. Say why it is on, in one line.
+
+Shadow opacity derives from Canvas lightness and re-derives on every run, so there is nothing to choose. When shadows read heavy or muddy, raise the Canvas base color's L.
+
+## Refining the color of a theme that exists
+
+"Warmer", "calmer", "more contrast" arrive against a theme that is already open, and the answer is a new base color file. Edit `scratch/<slug>-base-colors.json` when it is still there. When it is not, recover the base colors: `src/live-tokens/data/themes/<slug>.json` holds each one verbatim at `colorsAndType.editorConfigs.<Palette>.baseColor` as `{l, c, h}`, and the Canvas base color's lightness gives the scheme. Rebuild the base color file from those ten values, move the dial the user named, and re-run. A re-run replaces the buffer's whole color state, including palette edits made in the editor since the last run, so say so once when iterating; a Save or a `save-theme` run keeps the result.
+
+One adjective moves one dial. Warmer and cooler rotate hue; calmer and louder move chroma; lighter, darker, and moodier move Canvas L and the scheme; more contrast widens the L gap between Canvas and Brand and takes chroma out of the ground rather than adding it to the garnish. Leave every base color the user did not name alone, because a refinement that re-rolls the whole palette reads as a different theme and loses the thing they liked.
+
+## Scope
+
+Color only. Type and geometry are untouched: `set-colors` replaces the color
+state in the unsaved buffer and carries every other value in it forward. Save
+the open theme in the editor, or run `save-theme`, to keep the result; Adopt
+ships it.
+
+## Verify
+
+- The CLI exits 0 with every check passing (auto-corrected is fine), and the report names the layer it carried the rest of the look forward from.
+- The app (dev server running) shows the new palette after a reload. The editor's Theme panel marks the open theme unsaved, unless the run was a dry one or the report says the layer under the buffer, the open theme or the package default, already holds these colors.
+- The canvas is committed: on screen it reads as the theme's color rather than as generic near-white.
+- To revert, re-run with the previous base color file, or load the open theme again to discard the buffer.

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

@@ -0,0 +1,80 @@
+# Color anchors: feelings, idioms, and occasions
+
+Read this when the color intent names one of these. Entries are starting
+points: apply the chroma budget, the per-role bands, and the canvas commitment
+rules from SKILL.md on top of them.
+
+An idiom sets constraints and overrides the generic defaults in SKILL.md. The
+polished-UI Accent at 45% of Brand's chroma is right for a vague intent and
+wrong for Bauhaus. A feeling moves dials, and moves them inside an idiom's
+constraints when the intent names both.
+
+Energy spent on the ground tier fights the contrast gate, so keep chroma on the
+garnish. A low-valence, low-energy intent taken literally reads as broken
+rather than sad, which is why every dark entry below holds one moment of color.
+
+Riso, Memphis, and brutalist break the chroma budget on purpose. Break it in
+the one layer the style is about and hold the rest of the ground tier down.
+
+## Feelings
+
+| Anchor | Anchors (L, C, H) |
+|---|---|
+| Joyful, exuberant, energetic | butter canvas (0.95, 0.05, 90), Brand (0.80, 0.17, 75), coral Accent (0.72, 0.18, 20), green Special (0.75, 0.16, 145); analogous warm. Yellow stays yellow only above L 0.80 |
+| Playful, whimsical | tinted canvas (0.93, 0.05, 330), Special at full chroma; tetradic, the rare request that wants four hue families |
+| Optimistic, hopeful | sky canvas (0.94, 0.03, 220), Brand (0.62, 0.14, 200), warm yellow Accent (0.85, 0.14, 90); complementary across the warm/cool line, which reads as sunrise rather than sky |
+| Confident, bold | canvas (0.90, 0.07, 250), Brand C 0.18 at L 0.55, wide L range between surfaces. High dominance is the point |
+| Serene, tranquil | cool canvas (0.95, 0.03, 200), nothing above C 0.08, analogous 160 to 240 |
+| Tender, gentle, romantic | blush canvas (0.95, 0.03, 20), rose Brand (0.70, 0.08, 10), sage Accent (0.68, 0.06, 150); narrow L range |
+| Cozy, comforting | amber-cream canvas (0.92, 0.05, 75), rust Brand (0.55, 0.12, 40), neutrals at H 60; nothing cool on screen |
+| Wistful, nostalgic, vintage, faded | faded canvas (0.92, 0.03, 70), every chromatic base color capped at C 0.10, hues warm and close. The feeling is chroma withheld, not darkness |
+| Earthy, grounded, natural | canvas (0.90, 0.05, 90) at commitment level 2, hues 30 to 140 at C 0.06 to 0.14, neutrals H 60 to 80; no magenta, no cyan, nothing over C 0.16 |
+| Clinical, sterile, precise | near-white canvas at C 0.01, the one request an untinted ground suits; one cool Brand 200 to 260 at C 0.10; statuses carry the only other color |
+| Contemplative, focused | canvas (0.94, 0.015, 250) or its dark twin (0.20, 0.02, 250), one cool Brand at C 0.10, almost no other hue |
+| Urgent, alarming | ground held near-neutral so the alarm lands, red Brand (0.58, 0.22, 27) given real area, Warning and Danger on one shared L |
+| Tense, anxious | an uncomfortable ground, (0.88, 0.04, 105) light or (0.22, 0.03, 280) dark, plus a near-complementary pair that vibrates with one side toned down |
+| Defiant, rebellious, loud | near-black canvas (0.15, 0.01, 0), one acid hue (0.85, 0.20, 120), nothing else chromatic |
+| Melancholy, moody, sad | dark; canvas (0.22, 0.03, 250), chromatic base colors C 0.06 to 0.10 at L 0.72 to 0.80, blue through violet, with Accent held at C 0.14 as the moment of color |
+| Somber, grave, mournful | near-neutral dark canvas (0.18, 0.01, 260), one desaturated Brand, gradient off |
+| Ominous, dramatic, haunted | dark canvas (0.15, 0.04, 300), one hot accent (0.75, 0.16, 30) used sparingly, canvasGradient on |
+| Austere, severe, cold | monochrome; canvas at either L extreme at C 0.01 or below, one low-chroma Brand, muted statuses |
+
+## Idioms, eras, and genres
+
+| Anchor | Anchors (L, C, H) |
+|---|---|
+| Swiss, International | near-white canvas (0.97, 0.01, 0), or true black for the poster reading; one red Brand (0.55, 0.22, 27) as the only hue on screen; Neutral at C 0.005, untinted on purpose; monochromatic |
+| Bauhaus | paper canvas (0.95, 0.02, 85) under primaries at full commitment: red (0.58, 0.21, 27), blue (0.48, 0.20, 264), yellow (0.86, 0.17, 90); triadic |
+| Mid-century modern | canvas (0.90, 0.05, 75), mustard (0.75, 0.13, 85), teal (0.55, 0.10, 195), burnt orange (0.60, 0.15, 45), walnut neutrals H 60; nothing over C 0.16; compound |
+| Art deco, opulent, luxurious | near-black canvas (0.20, 0.02, 280), gold (0.78, 0.13, 88), jade (0.60, 0.10, 165); dark, one metallic accent, everything else grey |
+| Terminal, phosphor | canvas (0.16, 0.01, 150), phosphor green Brand (0.80, 0.16, 145), amber Accent (0.80, 0.13, 80); monochromatic, dark, gradient off |
+| Cyberpunk, neon noir, futuristic | canvas (0.18, 0.04, 300), magenta Brand (0.78, 0.18, 330), cyan Accent (0.82, 0.12, 200); complementary, dark, canvasGradient on for the glow |
+| Vaporwave | sunset canvas (0.88, 0.06, 330), pink (0.72, 0.16, 350), cyan (0.80, 0.11, 205), lilac Special; light, gradient on |
+| Y2K, bubble | chrome canvas (0.96, 0.015, 240), electric blue Brand (0.62, 0.18, 255), lime Accent (0.85, 0.17, 130) |
+| Blueprint | canvas (0.35, 0.07, 245), pale rules (0.90, 0.02, 240), one warm accent (0.75, 0.14, 60); dark |
+| Scandinavian, hygge | chalk canvas (0.96, 0.012, 70), sage Brand (0.60, 0.06, 150), clay Accent (0.70, 0.08, 40); nothing above C 0.10; analogous |
+| Japandi, wabi-sabi | unbleached paper canvas (0.93, 0.025, 80), ink Brand (0.35, 0.02, 250), one earth Accent (0.62, 0.09, 45); near-monochrome |
+| Cottagecore, botanical | cream canvas (0.94, 0.04, 85), moss (0.55, 0.10, 135), dusty rose (0.70, 0.09, 15), butter (0.85, 0.11, 95); warm analogous |
+| Editorial, magazine | paper canvas (0.97, 0.015, 85), ink neutrals, one strong Brand (0.50, 0.18, 20) carried by rules and pull quotes |
+| Newsprint, broadsheet | grey-warm canvas (0.91, 0.02, 80), near-black ink, nothing chromatic above C 0.10 |
+| Risograph, zine | paper canvas (0.94, 0.03, 80) with two flat spot inks, fluoro pink (0.68, 0.22, 5) and blue (0.52, 0.18, 260); complementary, no midtones between them |
+| Corporate, professional, trustworthy | canvas (0.97, 0.012, 250), navy Brand (0.48, 0.12, 255), teal Accent (0.60, 0.09, 195), conventional statuses |
+| Brutalist | pure canvas, (0.98, 0, 0) or (0.15, 0, 0), with Neutral at C 0, untinted because that is the point; one alarming Brand (0.58, 0.24, 27) |
+| Memphis, postmodern | pastel canvas (0.95, 0.03, 60) carrying full-chroma primaries and a hot pink Special (0.70, 0.20, 350); tetradic or square, four hue families on purpose |
+| Industrial, workshop, gritty | concrete canvas (0.88, 0.008, 250), or (0.22, 0.01, 250) dark, safety orange Brand (0.68, 0.18, 50), steel neutrals |
+
+## Occasions
+
+An occasion is a statement request. Default to canvas commitment level 2 or 3,
+never cream, and put the named color on the ground rather than only on the
+buttons.
+
+| Anchor | Anchors (L, C, H) | Strongest form |
+|---|---|---|
+| Christmas | red (0.53, 0.21, 22), green (0.46, 0.11, 155), gold (0.77, 0.14, 91) | red canvas (0.42, 0.14, 25), green Brand, gold Accent, dark scheme. Softer: evergreen canvas (0.35, 0.07, 160) or deep cream (0.95, 0.04, 85). One of red or green owns the ground; never a 50/50 split. |
+| Halloween | pumpkin (0.70, 0.20, 46), purple (0.51, 0.21, 313), poison green (0.73, 0.20, 137) | orange canvas (0.45, 0.13, 55) with violet and poison-green accents, or near-black violet canvas with pumpkin Brand. Dark scheme either way. |
+| St. Patrick's | green (0.51, 0.13, 152) | green Brand, gold Accent, white or beige neutrals. |
+| Ocean | deep blue (0.35, 0.08, 237), aqua (0.78, 0.12, 214) | hues held to 180 to 240. |
+| Sunset | hues 90 to 320 through red | L falls 0.85 to 0.40 across the sweep. |
+| Autumn | parchment canvas (0.87, 0.06, 80), rust Brand (0.55, 0.15, 40), gold Accent (0.75, 0.15, 85), moss Special (0.55, 0.10, 120) | warm brown neutrals H 50 to 70; deep red H 25 welcome. |
+| Spring | pastels L 0.85 to 0.95, C 0.04 to 0.10 | greens 130 to 150, pinks 0 to 20, mint canvas. |

package/.claude/skills/{live-tokens-adjust-geometry → live-tokens-set-geometry}/SKILL.md

@@ -1,6 +1,6 @@
 ---
-name: live-tokens-adjust-geometry
-description: Adjust corner radius, padding, gap, and border width across live-tokens components by moving each token alias along the shipped scales. Use when the user asks for pill or capsule buttons; rounded, rounder, sharp, sharper, square, softer, or harder corners; thicker or thinner borders; or density: space it out, tighter, denser, more compact, airier, more breathing room. Also invoked by live-tokens-generate-theme for the geometry half of a whole look. Changes shape and space aliases per component, never color, fonts, or tokens.css. Not for editing a single token (use the editor) or for color (see live-tokens-generate-theme).
+name: live-tokens-set-geometry
+description: Adjust corner radius, padding, gap, and border width across live-tokens components by moving each token alias along the shipped scales. Use when the user asks for pill or capsule buttons; rounded, rounder, sharp, sharper, square, softer, or harder corners; thicker or thinner borders; or density: space it out, tighter, denser, more compact, airier, more breathing room. Also invoked by live-tokens-create-theme, which supplies the geometry intent for a whole look. Changes shape and space aliases per component, never color, fonts, or tokens.css. Not for editing a single token (use the editor) or for a whole look (see live-tokens-create-theme).
 ---
 
 # Adjusting geometry
@@ -9,10 +9,11 @@ You translate the request into a small ops file; the CLI resolves each matching
 
 ## Workflow
 
-1. Write the ops file to `scratch/adjust-ops.json`.
-2. Run `npx live-tokens adjust scratch/adjust-ops.json`. It writes `component-configs/<id>/_working.json` for every component the ops change, which is the buffer the page already runs. `--dry-run` prints the report without writing.
+1. Read the geometry intent. When it names an anchor (a feeling, an idiom, or a genre), read `references/geometry-anchors.md` for that entry; it overrides the Idioms table below. Write the ops file to `scratch/geometry-ops.json`.
+2. Run `npx live-tokens set-geometry scratch/geometry-ops.json`. It writes `component-configs/<id>/_working.json` for every component the ops change, which is the buffer the page already runs. `--dry-run` prints the report without writing.
 3. Read the report card: every changed alias old → new, plus skips (raw value, off the ladder, already at the ladder end, pill preserved). Exit 1 means the run was rejected; the message names the offending op or the missing input, so fix it and re-run. Read where the controls landed, not only that the run succeeded: a button, badge, input, or tab padding sitting at `--space-6` is on its floor, and one that also carries `--radius-full` wants a targeted lift.
-4. Tell the user to reload the page before saving. The editor keeps the look in the browser and writes the buffers from that copy, so a Save in a tab that was open during the run puts the pre-run shape back and the report you just showed them becomes a lie. After the reload, offer the inverse op as the undo and say the edit is unsaved until they save the open theme.
+4. Report back in a line: every alias that moved, and any skip or clamp worth naming.
+5. Tell the user to reload the page before saving. The editor keeps the look in the browser and writes the buffers from that copy, so a Save in a tab that was open during the run puts the pre-run shape back and the report you just showed them becomes a lie. After the reload, offer the inverse op as the undo and say the edit is unsaved until they save the open theme.
 
 Each run reads the LIVE config (buffer, else the open theme, else the shipped default), so "a bit more" and "back one" compound naturally.
 
@@ -38,7 +39,9 @@ Targeted, absolute:
 
 ## Idioms
 
-| Request | Ops |
+This table covers an intent that names no anchor. When the intent names one, `references/geometry-anchors.md` has the row and it wins.
+
+| The intent says | Ops |
 |---|---|
 | pill, capsule | radius `set: "--radius-full"`, plus the padding the pill needs (see below) |
 | sharp, square corners | radius `set: "--radius-none"`, or `--radius-sm` for "mostly sharp" |
@@ -50,13 +53,15 @@ Targeted, absolute:
 | tighter, denser, more compact | padding and gap `shift: -1` |
 | thicker, thinner borders | border-width `shift: 1` or `-1` |
 
+A whole-look intent often arrives as a direction rather than an op. Playful, friendly, or soft is rounder and a step airier, with pill buttons when the direction is warm. Luxurious, elegant, or editorial is sharper corners, airier padding, thin borders. Technical, dense, or systematic is tighter spacing, a small radius, and square corners on containers. Calm or minimal leaves geometry alone.
+
 Magnitude words: "slightly" or "a bit" is 1 step, unqualified is 1 to 2, "much", "way", or "really" is 2 to 3. Mood words often mean both axes: "softer" is rounder plus airier, "compact" is tighter padding plus smaller gaps.
 
 ## Controls squeeze before containers
 
 A global op spends the same number of steps everywhere, but a step costs a control far more than a container. `padding shift: -2` takes a card from a 16px inset to 10px and it is still a card. It takes a button from 8 to 4, doubled to 8px at each end, around an 18px line. The button stops reading as a button.
 
-So a global compaction is `shift: -1`. When the brief wants more, spend the extra steps on the containers by name (`card`, `dialog`, `panel`, `collapsiblesection`, `sidenavigation`, `table`, `codesnippet`) and leave the controls alone. Loosening is not symmetric: airier is safe globally, because nothing breaks by growing.
+So a global compaction is `shift: -1`. When the request wants more, spend the extra steps on the containers by name (`card`, `dialog`, `panel`, `collapsiblesection`, `sidenavigation`, `table`, `codesnippet`) and leave the controls alone. Loosening is not symmetric: airier is safe globally, because nothing breaks by growing.
 
 A pill needs the room most. `--radius-full` bends the corner in over the first and last glyph, so a capsule wants more horizontal inset than a square-cornered control, never less. `--space-8` is the floor for a large-text pill, which is where compact Midnight Study sits; the roomier pill presets (Ocean, Sunset, Royal Velvet) run `--space-10` to `--space-12`. Pair the radius op with a padding `set` on the same target, placed after any global compaction so it wins outright:
 

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

@@ -0,0 +1,61 @@
+# Geometry anchors: feelings, idioms, and genres
+
+Read this when the geometry intent names one of these. An anchor overrides the
+Idioms table in SKILL.md, because it is tuned to the same direction the color
+came from, and a style's geometry is often targeted rather than global.
+
+Entries are written in the ops vocabulary: "radius +2" is a radius shift of 2,
+"borders +1" a border-width shift of 1, "padding +1" a padding and gap shift of
+1. A named component means a targeted op. Controls squeeze before containers,
+so a compaction of more than one step still spends its extra steps on
+containers by name.
+
+An occasion (Christmas, Autumn, Ocean) fixes color only. Take its geometry from
+the feeling it implies, or leave geometry alone.
+
+## Feelings
+
+| Anchor | Geometry |
+|---|---|
+| Joyful, exuberant, energetic | radius +2, padding +1, pill buttons |
+| Playful, whimsical | pill buttons, rounder cards, wide gaps |
+| Optimistic, hopeful | radius +1 |
+| Confident, bold | radius -1, borders +1, tight gaps |
+| Serene, tranquil | soft radius, padding +1, no borders |
+| Tender, gentle, romantic | rounder, hairline borders |
+| Cozy, comforting | radius +1, padding +1 |
+| Wistful, nostalgic, vintage, faded | unchanged, hairline rules |
+| Earthy, grounded, natural | radius +1, padding +1 |
+| Clinical, sterile, precise | radius sm, tight gaps, hairline borders |
+| Contemplative, focused | padding +1, minimal borders |
+| Urgent, alarming | radius -2, borders +2, tight padding |
+| Tense, anxious | tight gaps, radius sm |
+| Defiant, rebellious, loud | radius none, borders +3 |
+| Melancholy, moody, sad | padding +1, hairline borders |
+| Somber, grave, mournful | sharp, tight gaps, hairline rules |
+| Ominous, dramatic, haunted | sharp, borders +2 |
+| Austere, severe, cold | radius none, tight padding, hairline borders |
+
+## Idioms, eras, and genres
+
+| Anchor | Geometry |
+|---|---|
+| Swiss, International | radius none, tight gaps, hairline borders |
+| Bauhaus | radius none on containers, radius full on buttons alone, so the circle reads as a decision |
+| Mid-century modern | radius +1 to +2, padding +1, no borders |
+| Art deco, opulent, luxurious | sharp, padding +1, thin borders |
+| Terminal, phosphor | radius none, tight padding, a 1px border on everything |
+| Cyberpunk, neon noir, futuristic | sharp, tight gaps |
+| Vaporwave | rounder, airier |
+| Y2K, bubble | radius full on buttons with the padding a pill needs, generous spacing |
+| Blueprint | radius none, 1px borders, tight grid |
+| Scandinavian, hygge | soft radius, padding +1, hairline borders |
+| Japandi, wabi-sabi | radius sm, padding +2, no borders |
+| Cottagecore, botanical | rounder, airier |
+| Editorial, magazine | sharp, padding +1, hairline rules |
+| Newsprint, broadsheet | radius none, tight gaps, hairline rules |
+| Risograph, zine | radius none, borders +2 |
+| Corporate, professional, trustworthy | leave it alone |
+| Brutalist | radius none, borders +2 to +3, tight padding |
+| Memphis, postmodern | targeted rather than global: pill buttons against radius-none cards |
+| Industrial, workshop, gritty | radius sm, thick borders, tight padding |