@motion-proto/live-tokens 0.73.0 → 0.75.0

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

@@ -1,156 +0,0 @@
----
-name: live-tokens-generate-theme
-description: Generate a complete live-tokens theme (color, type, and geometry) from a natural-language brief, delegating the type and geometry halves to its sibling skills. Use whenever the user asks for a theme, look, vibe, brand feel, color scheme, or palette by mood, style, era, season, holiday, or hue; when they name only a color (something red-based, green and gold for St. Patrick's Day); or when they refine an existing theme (warmer, more contrast, calmer). Examples: bright and cheerful, dark and moody, brutalist, mid-century modern, Swiss and minimal, cyberpunk neon, editorial magazine, make it feel like a terminal. Not for a single token (use the editor), type alone (live-tokens-pair-fonts), or geometry alone (live-tokens-adjust-geometry).
----
-
-# Generating a theme from a brief
-
-A theme is three decisions made from one brief: color, type, and geometry. This skill owns the color decision directly and delegates the other two, so the whole look comes from the same reading of the brief. Never hand-author theme JSON and never edit the data tree directly.
-
-## Workflow
-
-1. Read the brief once and name its voice in a sentence: the mood, the hue family, the scheme, and the type and geometry that mood implies. Everything below keys off that sentence.
-2. Read the anchor reference that matches the voice (feeling, idiom, or occasion; see Anchor references) before seeding. Each entry fixes all three decisions together and overrides the generic defaults here.
-3. Translate the brief into a seed file using the framework below. Write it to `scratch/<slug>-brief.json`. Nothing else records the seeds, so this file is the only copy; one per slug is what makes the refinement pass below cheap.
-4. Run `npx live-tokens generate-theme scratch/<slug>-brief.json`. It writes `themes/<slug>.json`, opens that theme, and prints a contrast report. Auto-corrections are fine. Unmet floors (exit 1) mean the seeds themselves are unworkable; each failure line names the seed to change, usually by raising its lightness or cutting its chroma. Fix the brief and re-run; the same name overwrites. Regeneration replaces that theme's whole color state, including palette edits made in the editor since the last run, so say so once when iterating.
-5. Invoke **live-tokens-pair-fonts** with the same voice. Skip only when the user asked for colors specifically and said to leave the type alone.
-6. Invoke **live-tokens-adjust-geometry** with the geometry the voice implies (table below). Skip when the voice implies nothing about geometry.
-7. Tell the user to look at the running app, and that type and geometry sit in the unsaved buffer until they save the open theme. Offer refinements as edits to the same brief (see Refining a theme that exists).
-
-Order matters only for safety, and the order above is safe: the color generator carries the live buffers forward into the new theme file, so a color re-roll after fonts and geometry keeps both.
-
-Flags: `--dry-run` prints the report without writing; `--no-activate` writes without opening; `--carry-from <theme>` takes the non-color content (gradients, fonts, component aliases) from a named theme rather than from the live look. Generating a set needs it: the first run becomes the live look, so a second run without it carries the first theme's fonts and geometry into the second. Opening a theme never changes what the site ships. Only Adopt, in the editor, does that.
-
-## The brief
-
-```json
-{
-  "name": "Spring Meadow",
-  "scheme": "light",
-  "seeds": {
-    "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 }
-  }
-}
-```
-
-All 10 seeds are required; a seed may also be a `"#rrggbb"` string. OKLCH: `l` is 0 to 1 lightness, `c` is chroma (0 grey, about 0.37 max), `h` is hue in degrees. `name` becomes the file slug; `"default"` is refused. `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) | Canvas, Neutral, Alternate | C 0.005 to 0.03 |
-| Dominant chromatic (about 30%) | Brand | C 0.10 to 0.20 |
-| Garnish (about 10%) | Accent, Special | may exceed Brand; at most one at full saturation |
-| 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.
-
-## Per-role bands
-
-| Seed | 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 brief'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 briefs and never the default. Three levels of commitment:
-
-1. *Tinted paper* (most UI briefs): C 0.02 to 0.06, with L down to 0.92 where the hue needs room.
-2. *Colored ground* (expressive briefs): 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 briefs): 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 is a transform, not just a dark canvas: every chromatic seed 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 a brief that names a feeling, read `references/mood-vocabulary.md` instead of guessing the dial settings; each entry places the emotion on the three axes and gives the color, type, and geometry together.
-
-Avoid mid-lightness yellow-green (H 100 to 120 at L 0.5 to 0.7, C about 0.1) unless the brief asks for olive or toxic.
-
-## Gamut guardrails
-
-The engine clamps to gamut regardless; these keep your intent achievable rather than silently muted.
-
-- 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 brief 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%.
-- A brief 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 brief evokes atmosphere (sky, night, dusk, glow, underwater) or asks for a gradient outright; keep it off for crisp, flat, minimal, or corporate briefs 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 you enabled it 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 seed's L.
-
-## Anchor references
-
-Read the matching reference before seeding, and apply the bands above on top of it.
-
-- `references/mood-vocabulary.md` covers feelings: joyful, playful, optimistic, confident, serene, tender, cozy, earthy, clinical, wistful, contemplative, urgent, tense, defiant, melancholy, somber, ominous, austere. It opens with the valence, energy, and dominance axes, so a feeling it does not list still places on them.
-- `references/style-vocabulary.md` covers named idioms, eras, and genres: Swiss, Bauhaus, mid-century, art deco, terminal, cyberpunk, vaporwave, Y2K, blueprint, Scandinavian, Japandi, cottagecore, editorial, newsprint, riso, corporate, brutalist, Memphis, industrial. Each entry fixes color, type, and geometry as one set, so hand its Type and Geometry columns to the sibling skills verbatim.
-- `references/named-themes.md` covers holidays, seasons, and natural scenes: Christmas, Halloween, St. Patrick's, Ocean, Sunset, Autumn, Spring. A holiday or season brief is a statement brief: commitment level 2 or 3, with the named color on the ground rather than only on the buttons.
-
-Most briefs hit the first file. A brief that matches two ("cozy brutalist", "clinical Swiss") reads the idiom first and lets the feeling move the dials inside it: an idiom sets constraints, and dials move within constraints. A brief that names no feeling, idiom, or occasion at all takes the bands above and the geometry table below.
-
-## Geometry from the voice
-
-The geometry lives in radius, padding, gap, and border width, and `live-tokens-adjust-geometry` knows the mechanics. Hand it the intent:
-
-| Voice | Geometry |
-|---|---|
-| playful, friendly, soft | rounder, a step airier; pill buttons when the brief is warm |
-| luxurious, elegant, editorial | sharper corners, airier padding, thin borders |
-| technical, dense, systematic | tighter spacing, small radius, square corners on containers |
-| calm, minimal | leave geometry alone unless the brief says otherwise |
-
-This table is the fallback. When the brief matched an entry in the mood or style reference, take the geometry from that entry instead: it is tuned to the same reading the color came from, and a style's geometry is often targeted rather than global.
-
-## Refining a theme that exists
-
-"Warmer", "calmer", "more contrast" arrive against a theme that is already open, and the answer is a new brief rather than hand-edits. Edit `scratch/<slug>-brief.json` when it is still there. When it is not, recover the seeds: `src/live-tokens/data/themes/<slug>.json` holds each one verbatim at `colorsAndType.editorConfigs.<Palette>.baseColor` as `{l, c, h}`, and the Canvas seed's lightness tells you the scheme. Rebuild the brief from those ten values, move the dial the user named, re-run under the same name.
-
-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 seed 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.
-
-## Files each step writes
-
-Color writes `themes/<slug>.json` and opens it. Type and geometry write the unsaved buffers, which the page already runs. One Save in the editor keeps all three; Adopt ships them. Component aliases and gradients carry forward from the live look into a generated theme; user-tuned gradients survive, stock ones rebuild from the new families.
-
-## Verify
-
-- The color CLI exits 0 with every check passing (auto-corrected is fine), and the two sibling skills report what they changed.
-- The app (dev server running) shows the whole look after a reload, and the editor's Theme panel names the theme.
-- To return to the previous look, load the theme the CLI output named from the Theme panel; that discards the buffers too.

package/.claude/skills/live-tokens-generate-theme/references/mood-vocabulary.md

@@ -1,43 +0,0 @@
-# Mood vocabulary: feelings
-
-Read this when the brief names a feeling. Entries are starting points, not seeds
-to copy: apply the chroma budget, per-role bands, and canvas commitment rules
-from SKILL.md on top of them.
-
-Three axes place any feeling, including one the table omits:
-
-| 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 |
-
-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.
-
-Energy spent on the ground tier fights the contrast gate, so keep chroma on the
-garnish. And a low-valence, low-energy brief taken literally reads as broken
-rather than sad, which is why every dark entry below holds one moment of color.
-
-| Brief | Anchors (L, C, H) | Type | Geometry |
-|---|---|---|---|
-| 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 | dynamic sans in both slots | radius +2, padding +1, pill buttons |
-| Playful, whimsical | tinted canvas (0.93, 0.05, 330), Special at full chroma; tetradic, the rare brief that wants four hue families | expressive display over a plain workhorse | pill buttons, rounder cards, wide gaps |
-| 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 | humanist sans, low contrast | radius +1 |
-| 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 | heavy rational display, plain body | radius -1, borders +1, tight gaps |
-| Serene, tranquil | cool canvas (0.95, 0.03, 200), nothing above C 0.08, analogous 160 to 240 | dynamic sans, one family | soft radius, padding +1, no borders |
-| 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, light weights | soft serif display over humanist sans | rounder, hairline borders |
-| 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 | dynamic serif over dynamic sans | radius +1, padding +1 |
-| Wistful, nostalgic, vintage, faded | faded canvas (0.92, 0.03, 70), every chromatic seed capped at C 0.10, hues warm and close. The feeling is chroma withheld, not darkness | rational serif display, quiet body | unchanged, hairline rules |
-| 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 | dynamic serif over humanist sans | radius +1, padding +1 |
-| Clinical, sterile, precise | near-white canvas at C 0.01, the one brief an untinted ground suits; one cool Brand 200 to 260 at C 0.10; statuses carry the only other color | one neo-grotesque, tightly set | radius sm, tight gaps, hairline borders |
-| 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 | one quiet superfamily | padding +1, minimal borders |
-| 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 | condensed grotesque, heavy | radius -2, borders +2, tight padding |
-| 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 | neo-grotesque, tightly set | tight gaps, radius sm |
-| Defiant, rebellious, loud | near-black canvas (0.15, 0.01, 0), one acid hue (0.85, 0.20, 120), nothing else chromatic | heavy display; a mono body works | radius none, borders +3 |
-| Melancholy, moody, sad | dark; canvas (0.22, 0.03, 250), chromatic seeds 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 | rational serif display over quiet sans | padding +1, hairline borders |
-| Somber, grave, mournful | near-neutral dark canvas (0.18, 0.01, 260), one desaturated Brand, gradient off | rational serif in both slots | sharp, tight gaps, hairline rules |
-| Ominous, dramatic, haunted | dark canvas (0.15, 0.04, 300), one hot accent (0.75, 0.16, 30) used sparingly, canvasGradient on | heavy high-contrast display | sharp, borders +2 |
-| Austere, severe, cold | monochrome; canvas at either L extreme at C 0.01 or below, one low-chroma Brand, muted statuses. Highest dominance, lowest energy | one rational family | radius none, tight padding, hairline borders |

package/.claude/skills/live-tokens-generate-theme/references/named-themes.md

@@ -1,18 +0,0 @@
-# Named themes: canonical OKLCH anchors
-
-Read this when the brief names a holiday, a season, or a natural scene. These
-are starting points, not seeds to copy: apply the chroma budget, per-role bands,
-and canvas commitment rules from SKILL.md on top of them.
-
-Holiday briefs are statement briefs. Default to canvas commitment level 2 or 3,
-never cream, and put the named color on the ground, not only on the buttons.
-
-| Brief | 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-generate-theme/references/style-vocabulary.md

@@ -1,35 +0,0 @@
-# Style vocabulary: idioms, eras, and genres
-
-Read this when the brief names a design idiom, a decade, or a genre. A mood
-moves dials; an idiom sets constraints, and it overrides the generic defaults in
-SKILL.md: the polished-UI Accent at 45% of Brand's chroma is right for a vague
-brief and wrong for Bauhaus.
-
-Entries are starting points, not seeds to copy: apply the chroma budget,
-per-role bands, and canvas commitment rules on top of them. 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.
-
-The table runs modernist, digital, quiet, print, expressive.
-
-| Brief | Anchors (L, C, H) | Type | Geometry |
-|---|---|---|---|
-| 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 | one rational neo-grotesque across both slots | radius none, tight gaps, hairline borders |
-| 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 | geometric sans, heavy display | radius none on containers, radius full on buttons alone, so the circle reads as a decision |
-| 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 | dynamic sans, or a geometric display over a dynamic body | radius +1 to +2, padding +1, no borders |
-| 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 | rational high-contrast serif display, quiet body | sharp, padding +1, thin borders |
-| 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 | mono in both slots | radius none, tight padding, a 1px border on everything |
-| 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 | wide geometric display, neutral body | sharp, tight gaps |
-| 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 | wide retro display, serif welcome | rounder, airier |
-| Y2K, bubble | chrome canvas (0.96, 0.015, 240), electric blue Brand (0.62, 0.18, 255), lime Accent (0.85, 0.17, 130) | geometric sans, heavy display | radius full on buttons with the padding a pill needs, generous spacing |
-| Blueprint | canvas (0.35, 0.07, 245), pale rules (0.90, 0.02, 240), one warm accent (0.75, 0.14, 60); dark | mono, or a technical grotesque; a mono body works here and almost nowhere else | radius none, 1px borders, tight grid |
-| 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 | dynamic sans on both sides | soft radius, padding +1, hairline borders |
-| 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 | rational serif display over a quiet humanist body | radius sm, padding +2, no borders |
-| 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 | dynamic serif display over humanist sans | rounder, airier |
-| 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 | high-contrast serif display over a text serif or humanist sans | sharp, padding +1, hairline rules |
-| Newsprint, broadsheet | grey-warm canvas (0.91, 0.02, 80), near-black ink, nothing chromatic above C 0.10 | rational serif in both slots | radius none, tight gaps, hairline rules |
-| 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 | expressive display over a plain workhorse | radius none, borders +2 |
-| 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 | rational sans body with a rational serif or same-family display | leave it alone |
-| 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) | neo-grotesque or mono at heavy weight | radius none, borders +2 to +3, tight padding |
-| 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 | geometric display, plain body | targeted rather than global: pill buttons against radius-none cards |
-| 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 | condensed grotesque display over a plain body | radius sm, thick borders, tight padding |

package/.claude/skills/live-tokens-pair-fonts/SKILL.md

@@ -1,90 +0,0 @@
----
-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).
----
-
-# Pairing fonts for a theme
-
-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.
-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.
-
-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
-
-```json
-{ "display": "Fraunces", "body": "Nunito Sans" }
-```
-
-Every slot is optional and an omitted slot is left exactly as it is. `display` is `--font-display`, `body` is `--font-sans`; `serif`, `mono` and `editorial` exist when a theme needs them. `editorial` is `--font-editorial`, the long-reading face behind the `--editorial-*` text styles: it tracks the body face until a theme repoints it, so set it only when essays and articles should not carry the body face. A slot may be `{ "name": "...", "url": "..." }` to pin an exact URL. Spell families as Google does; the CLI reports the canonical spelling back.
-
-## 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 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.
-
-## The font matrix: the decision rule
-
-Classify each candidate on two layers. The **skeleton** is its form model; the **flesh** is its stroke contrast and serif treatment.
-
-| Form model | Construction | Reads as |
-|---|---|---|
-| **Dynamic** | diagonal stress, open apertures, written origin | open, warm, humane, timeless |
-| **Rational** | vertical stress, closed apertures, drawn not written | orderly, reserved, elegant, authoritative |
-| **Geometric** | monolinear, circle-and-line | technical, modern, systematic, sober |
-
-- **Same skeleton, different flesh: reliable.** Helvetica and Bodoni are both rational, one a linear sans and one a contrasting serif.
-- **Same flesh, different skeleton: the failure case.** The two look alike on the surface and fight underneath. This is why two arbitrary sans-serifs so often clash.
-- **Far apart on both: works, deliberately.** An unmistakable difference reads as a decision.
-
-Many faces sit between columns. When one straddles, say so and lean on the voice table and the x-height check instead.
-
-## Voice
-
-| Brief 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 |
-| friendly, warm, approachable | dynamic sans on both sides, or a soft serif display |
-| technical, systematic, precise | geometric or neo-grotesque sans; a mono for code |
-| playful, informal | an expressive display face over a plain workhorse body |
-| 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.
-
-## Shortcuts
-
-These find an adequate pairing fast and skip the reasoning; use them when the brief 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.
-- **One family across weights.**
-- **Same designer or foundry.**
-- **Serif display over sans body** when nothing else decides it.
-
-## Watch for
-
-- **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.
-- **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.
-
-## 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.

package/bin/generate-theme.mjs

@@ -1,260 +0,0 @@
-// `live-tokens generate-theme` worker.
-//
-// Reads a seed brief (JSON), builds a full validated colors-and-type layer via
-// the compiled engine (dist-plugin/generateColorsAndType — the CLI never imports
-// TS sources), enforces the AA contrast gate, and saves the result as a theme:
-// <themesDir>/<slug>.json, the document that carries the whole theme by value.
-// Unless --no-activate it then opens that theme the way the dev server's apply
-// door does — existing `_working` buffers are cleared and
-// `themes/_active.json` names it. Nothing else moves, so generating a theme
-// cannot change what the site ships.
-//
-// Non-color content (shadows, component aliases, fonts) carries forward from
-// the live state so generation only replaces the color identity. Swatch
-// gradients ride along too when user-tuned; stock ones are rebuilt from the new
-// theme's families by the engine.
-
-import { existsSync, mkdirSync, readFileSync, readdirSync, rmSync, writeFileSync } from 'node:fs';
-import { dirname, join, relative, resolve } from 'node:path';
-import { fileURLToPath } from 'node:url';
-
-const pkgRoot = resolve(dirname(fileURLToPath(import.meta.url)), '..');
-const ENGINE = resolve(pkgRoot, 'dist-plugin/generateColorsAndType/index.js');
-const packageDataDir = join(pkgRoot, 'src/live-tokens/data');
-// Source of truth: src/editor/core/themes/themeTypes.ts, which
-// normalizeTheme.ts re-exports. This copy cannot import TS, so
-// `check:preset-themes` and generate-theme.test.ts are what catch a drift.
-const THEME_SCHEMA_VERSION = 5;
-
-async function loadEngine() {
-  if (!existsSync(ENGINE)) {
-    throw new Error(
-      `theme engine not found at ${relative(process.cwd(), ENGINE)}. ` +
-        `Build the plugin first (npm run build:plugin).`,
-    );
-  }
-  return import(ENGINE);
-}
-
-function readJson(path) {
-  return JSON.parse(readFileSync(path, 'utf8'));
-}
-
-function readJsonIfExists(path) {
-  try {
-    return existsSync(path) ? readJson(path) : null;
-  } catch {
-    return null;
-  }
-}
-
-/** Local dir first, then the installed package's shipped copy — the same
- *  fallback order the dev server's reads use. */
-function readData(localDir, packageSubdir, fileName) {
-  return (
-    readJsonIfExists(join(localDir, `${fileName}.json`)) ??
-    readJsonIfExists(join(packageDataDir, packageSubdir, `${fileName}.json`))
-  );
-}
-
-function componentNames(componentConfigsDir) {
-  if (!existsSync(componentConfigsDir)) return [];
-  return readdirSync(componentConfigsDir, { withFileTypes: true })
-    .filter((e) => e.isDirectory())
-    .map((e) => e.name)
-    .sort();
-}
-
-/** `_fileName` and `_source` are read-door markers, never part of a document. */
-function stripMarkers(value) {
-  if (!value || typeof value !== 'object') return value;
-  const { _fileName, _source, ...rest } = value;
-  return rest;
-}
-
-/** A component's derived default, local tree first, then the installed
- *  package's shipped copy — same fallback order every other read here uses. */
-function defaultComponentConfig(componentConfigsDir, comp) {
-  return readData(join(componentConfigsDir, comp), `component-configs/${comp}`, 'default');
-}
-
-/**
- * The look the new theme carries forward. Without --carry-from that is the LIVE
- * state — buffer first, then the open theme, then the shipped default — because
- * what the user sees is what they expect to keep. With it, the named theme,
- * then the shipped default for anything that theme omits, so an incomplete
- * source never produces an incomplete result.
- */
-function resolveCarrySource({ carryFrom, colorsAndTypeDir, componentConfigsDir, themesDir }) {
-  const comps = componentNames(componentConfigsDir);
-
-  if (carryFrom) {
-    const theme = readData(themesDir, 'themes', carryFrom);
-    if (!theme) throw new Error(`--carry-from theme "${carryFrom}" not found`);
-    const componentConfigs = {};
-    for (const comp of comps) {
-      const cfg = theme.componentConfigs?.[comp] ?? defaultComponentConfig(componentConfigsDir, comp);
-      if (cfg) componentConfigs[comp] = stripMarkers(cfg);
-    }
-    return { colorsAndType: stripMarkers(theme.colorsAndType), componentConfigs };
-  }
-
-  const activeSlug = readJsonIfExists(join(themesDir, '_active.json'))?.activeFile ?? 'default';
-  const activeTheme = readData(themesDir, 'themes', activeSlug);
-  const colorsAndType = stripMarkers(
-    readJsonIfExists(join(colorsAndTypeDir, '_working.json')) ??
-      activeTheme?.colorsAndType ??
-      readData(colorsAndTypeDir, 'colors-and-type', 'default'),
-  );
-
-  // A working buffer is an unsaved delta from the active theme; absent theme
-  // component entries fall through to the component defaults. Mirrors
-  // `bin/adjust.mjs`'s `readLiveConfigs` and the dev server's
-  // `resolveLiveComponentConfig` — all three layers, in the same order.
-  const componentConfigs = {};
-  for (const comp of comps) {
-    const live =
-      readJsonIfExists(join(componentConfigsDir, comp, '_working.json')) ??
-      activeTheme?.componentConfigs?.[comp] ??
-      defaultComponentConfig(componentConfigsDir, comp);
-    if (live) componentConfigs[comp] = stripMarkers(live);
-  }
-  return { colorsAndType, componentConfigs };
-}
-
-/** `engine` is a test seam; the CLI always runs the compiled bundle. */
-export async function runGenerateTheme({
-  briefPath,
-  activate = true,
-  dryRun = false,
-  carryFrom,
-  root = process.cwd(),
-  colorsAndTypeDir,
-  componentConfigsDir,
-  themesDir,
-  engine,
-} = {}) {
-  const { buildColorsAndTypeFromSeeds, resolveDataDirs, CURRENT_COMPONENT_SCHEMA_VERSION } =
-    engine ?? (await loadEngine());
-
-  const briefFull = resolve(root, briefPath);
-  if (!existsSync(briefFull)) {
-    throw new Error(`brief not found at ${relative(root, briefFull)}`);
-  }
-  let brief;
-  try {
-    brief = readJson(briefFull);
-  } catch (err) {
-    throw new Error(`brief is not valid JSON: ${err instanceof Error ? err.message : String(err)}`);
-  }
-
-  const dirs =
-    colorsAndTypeDir && componentConfigsDir && themesDir
-      ? { colorsAndTypeDir, componentConfigsDir, themesDir }
-      : resolveDataDirs();
-
-  const previousActive = readJsonIfExists(join(dirs.themesDir, '_active.json'))?.activeFile ?? 'default';
-  const carry = resolveCarrySource({ carryFrom, ...dirs });
-
-  const { colorsAndType, slug, report } = buildColorsAndTypeFromSeeds(
-    brief,
-    {
-      cssVariables: carry.colorsAndType?.cssVariables,
-      fontSources: carry.colorsAndType?.fontSources,
-      fontStacks: carry.colorsAndType?.fontStacks,
-      gradients: carry.colorsAndType?.gradients,
-    },
-    new Date().toISOString(),
-  );
-
-  const themePath = join(dirs.themesDir, `${slug}.json`);
-  const existing = readJsonIfExists(themePath);
-  const theme = {
-    name: colorsAndType.name,
-    createdAt: existing?.createdAt ?? colorsAndType.createdAt,
-    updatedAt: colorsAndType.updatedAt,
-    schemaVersion: THEME_SCHEMA_VERSION,
-    colorsAndType,
-    componentConfigs: carry.componentConfigs,
-    componentSchemaVersion: CURRENT_COMPONENT_SCHEMA_VERSION,
-  };
-
-  if (!dryRun) {
-    mkdirSync(dirs.themesDir, { recursive: true });
-    writeFileSync(themePath, JSON.stringify(theme, null, 2) + '\n');
-    if (activate) applyTheme(slug, dirs);
-  }
-
-  return {
-    name: theme.name,
-    slug,
-    themePath,
-    existed: existing !== null,
-    activated: activate && !dryRun,
-    previousActive,
-    carriedFrom: carryFrom ?? null,
-    componentsCarried: Object.keys(carry.componentConfigs).length,
-    dryRun,
-    report,
-  };
-}
-
-/** The apply door's write set, reproduced: clear every working delta and point
- *  `themes/_active.json` at the open document. Production is untouched. */
-function applyTheme(slug, dirs) {
-  const colorsWorking = join(dirs.colorsAndTypeDir, '_working.json');
-  if (existsSync(colorsWorking)) rmSync(colorsWorking);
-
-  for (const comp of componentNames(dirs.componentConfigsDir)) {
-    const workingPath = join(dirs.componentConfigsDir, comp, '_working.json');
-    if (existsSync(workingPath)) rmSync(workingPath);
-  }
-
-  writeFileSync(join(dirs.themesDir, '_active.json'), JSON.stringify({ activeFile: slug }));
-}
-
-export function formatGenerateThemeResult(result) {
-  const root = process.cwd();
-  const lines = [];
-  const wrote = result.dryRun ? 'Would write' : result.existed ? 'Updated' : 'Created';
-  lines.push(`${wrote} theme "${result.name}" → ${relative(root, result.themePath)}`);
-  lines.push(
-    `Carried forward from ${result.carriedFrom ? `theme "${result.carriedFrom}"` : 'the live state'}: ` +
-      `fonts, gradients and ${result.componentsCarried} component config(s).`,
-  );
-
-  lines.push(`\nContrast report (${result.report.scheme} scheme):`);
-  const width = Math.max(...result.report.checks.map((c) => c.textVar.length));
-  for (const c of result.report.checks) {
-    const mark = c.pass ? '✓' : '✗';
-    const fixed = c.corrected ? '  (auto-corrected)' : '';
-    lines.push(
-      `  ${mark} ${c.textVar.padEnd(width)}  ${c.ratio.toFixed(2).padStart(6)}:1  vs ${c.against}  floor ${c.floor}:1${fixed}`,
-    );
-  }
-  if (result.report.failures.length > 0) {
-    lines.push(`\nUnmet floors — adjust the brief's seeds and re-run:`);
-    for (const f of result.report.failures) lines.push(`  ! ${f}`);
-  }
-
-  lines.push(
-    result.report.gradients === 'carried'
-      ? '\nGradients: kept your tuned swatch gradients.'
-      : '\nGradients: swatch tokens rebuilt from the theme families.',
-  );
-  lines.push(`Shadows: ${result.report.shadows}; carried geometry kept.`);
-  if (result.report.canvasGradient) {
-    lines.push(`Canvas sky: ${result.report.canvasGradient}.`);
-  }
-
-  if (result.activated) {
-    lines.push(
-      `\nOpened "${result.slug}" (previously open: "${result.previousActive}"). ` +
-        `Reload the app to see it; switch back any time from Load in the editor's Theme panel. ` +
-        `Adopt it there to publish it to tokens.generated.css.`,
-    );
-  } else if (!result.dryRun) {
-    lines.push(`\nNot opened (--no-activate). Load "${result.slug}" from the editor's Theme panel to see it.`);
-  }
-  return lines.join('\n');
-}