@motion-proto/live-tokens 0.78.0 → 0.80.0

package/CHANGELOG.md

@@ -1,5 +1,276 @@
 # Changelog
 
+## 0.80.0 — The build runs the design checks
+
+### Added
+
+- **`vite build` runs the design checks.** `themeFileApi` runs both static
+  checkers at the start of the build, under the project's severities and
+  without repairs. An error stops the build, and warnings print.
+  `themeFileApi({ checks: false })` turns the checks off. The dev server
+  runs no checks.
+
+### Changed
+
+- **A CollapsibleSection header toggles from its label.** Without `href`, the
+  chevron and the label share one button, so a click anywhere on the header
+  opens or closes the section. The label is the button's accessible name, in
+  place of "Expand section" or "Collapse section".
+- **The template's build is `vite build`.** Its `check:design` script is
+  gone, since the plugin runs the same checks.
+- **check-compliance leaves the build alone.** It no longer adds
+  `check:design` to `package.json`.
+- **`migrate` removes the `check:design` build step.** It removes the script
+  and its place in `build` when both hold what live-tokens wrote and the Vite
+  config uses `themeFileApi` with its checks on. It reports any other
+  `check:design` and leaves it in place.
+
+- **The checkers bring `tokens.css` up to the installed package.** Before
+  either checker reads the design tokens, it applies every pending additive
+  migration and lists it in `fix.applied` under `tokens-migration`. A pending
+  breaking migration is a `tokens-breaking-migration` finding with
+  `repair: 'choice'`, and `npx live-tokens migrate` still applies it.
+  `--no-fix` reports both and writes nothing.
+- **check-compliance runs only the checkers.** It no longer runs
+  `npx live-tokens report` or `npx live-tokens migrate` first. `report` stays
+  a CLI command.
+
+### Fixed
+
+- **`migrate`'s usage text names the breaking migrations it applies.** It
+  said additive only, and it has always applied both.
+
+## 0.79.0 — Checks fix what they find
+
+### Added
+
+- **Every finding carries its own repair.** `report --json` and both
+  checkers' `--json` now put `guidance`, `repair`, and `exception` on every
+  finding, alongside `rule`, `severity`, `file`, `line`, and `message`.
+  `guidance` is the rule's repair instruction in plain sentences, such as the
+  design token each color role takes for a `color-literal`.
+  `repair` is `auto` (code can apply the patch), `choice` (a role or a tie
+  needs the user, and `details` lists the candidates), or `authored` (the
+  user's own words are the fix). `exception` is the narrower
+  `live-tokens.config.json` entry that steps the rule down one level to
+  record a deliberate decision to leave the finding as it is.
+- **`check-page` and `check-component` fix what they can.** Both apply every
+  `auto` finding's patch before they report: a deep import rewritten to its
+  public path, a spacing, radius, or stroke-width literal replaced by its one
+  nearest design token, a page's `size` prop deleted, a semantic property
+  override deleted. They then recheck and list each fix beside the findings
+  that remain, in `--json` as `fix.applied`. With `--tests`, the fixes land
+  before the tests run. A second run applies nothing. `--no-fix` reports
+  without editing, for a build or CI; the template's `check:design` passes it.
+- **Three findings that used to be report-only facts.** `unread-token`
+  (warn): a runtime declares a property in `:global(:root)` and reads it
+  nowhere in its own CSS. `missing-description` (warn): a runtime file has no
+  `catalogue` export, or a required field in it is not a string literal. `config-token`: an alias in
+  `component-configs/<id>/default.json` names something the vocabulary
+  lacks, or a bare literal stands on a property the editor declares no
+  intrinsic for.
+- **`ComponentContract` gains `behavior`.** A Vitest suite mounts the
+  runtime under happy-dom by its registration and drives each declared case
+  with a real DOM event: a callback fires with its documented argument,
+  stays silent under `disabled`, or a controlled prop drives its attribute
+  while an action leaves it alone. A failure reports `contract-behavior`,
+  naming the case. `behavior` is a required field; a component with no
+  callback prop declares it `{ applicable: false, reason: '...' }`.
+- **A stroke's width has its own token scale**, `border-width`, so a
+  `dimension-literal` on a border, divider, or accent resolves to a stroke
+  step instead of a colour scale with nothing to offer it. 26 scales in
+  total; `tokens --scale border-width` resolves the name.
+- **One component inventory.** `componentDirs` in `live-tokens.config.json`
+  is honoured everywhere a component is discovered, checked, or run under
+  `--tests`, not only by `report`. A registered id with no runtime, or a
+  runtime with no editor, now surfaces as a `missing-file` finding rather
+  than silently dropping out of the batch.
+- **`CatalogueEntry` and the `catalogue` export.** A runtime file's
+  `<script module>` block exports `catalogue`, typed `CatalogueEntry`, with
+  `description`, `useFor`, `notFor`, and an optional `props` map keyed by
+  prop name. `CatalogueEntry` is exported from `@motion-proto/live-tokens`
+  and from `@motion-proto/live-tokens/component-editor`. `catalogueOf` reads
+  the export statically, the way the CLI already reads `component` and
+  `allTokens` from editor files, and `components <id>` prints its fields.
+
+### Changed (breaking)
+
+- **`check-page` and `check-component` edit files by default.** `--fix` is
+  gone; every run applies the `auto` patches. A build or CI script that runs
+  either checker must pass `--no-fix` to stay report-only, as the template's
+  `check:design` does.
+- **`behavior` is a required `ComponentContract` field.** A consumer's
+  `tests/contracts.ts` stops compiling until each contract declares a
+  behavior or marks it inapplicable with a reason. `references/contract-tests.md`
+  in the create-component skill carries the Toggle-shaped example and the
+  one-line inapplicable form.
+- **`RegistryEntry.catalogue` is required, with no default.** A
+  `registerComponent` call now passes `catalogue`, imported from the
+  runtime file beside its editor import. The runtime file's leading comment
+  is deleted; the CLI never falls back to it. A consumer's registration
+  stops compiling until it imports and passes `catalogue`.
+- **Selection says `selected`.** RadioButton's `active` prop is `selected`
+  and SideNavigation's `forceActivePart` is `forceSelectedPart`. The
+  `-active-` segment reads `-selected-` across RadioButton's nine, TabBar's
+  fourteen, and SideNavigation's forty semantic properties, and the `.active`
+  class on a radio row, a tab, and a rail part is `.selected`. A saved theme
+  or component config is renamed on load. `active` stays the pressed state,
+  so Button's and IconButton's `--*-outline-active-*` are untouched.
+- **One hairline.** The line a component draws between its parts is
+  `-hairline-color` and its width is `-hairline-width` everywhere. Dialog's,
+  Table's, and TabBar's `-divider` and `-divider-width`, SegmentedControl's
+  `-divider-color`, `-divider-thickness`, and `-divider-inset`,
+  CollapsibleSection's twenty-three `--collapsiblesection-divider-*`, and
+  SectionDivider's three `-hairline-thickness` are renamed on load.
+  CollapsibleSection's `variant="divider"` is `variant="hairline"`, and its
+  class is `.variant-hairline`. `check-component` no longer accepts the
+  suffixes `-thickness`, `-divider`, `-divider-width`, `-divider-thickness`,
+  `-hairline-thickness`, `-divider-height`, `-divider-inset`, or `-inset`; a
+  property carrying one is a naming finding. The `set-geometry` op kind
+  `divider-width` is `hairline-width`, and an ops file naming the old kind is
+  rejected.
+- **One indicator.** The bar beside SideNavigation's current item and the
+  stripe on Callout's leading edge are indicators, the word MenuSelect and
+  TabBar already use. SideNavigation's twelve `-accent` and twelve
+  `-accent-width` properties and Callout's four `-accent-width` are
+  `-indicator` and `-indicator-width`, renamed on load. `check-component` no
+  longer accepts the suffixes `-accent` or `-accent-width`; a property
+  carrying one is a naming finding. The `set-geometry` op kind `accent-width`
+  is `indicator-width`, and an ops file naming the old kind is rejected.
+  `accent` now names the color family only, so Badge's and CornerBadge's
+  `--*-accent-*` are untouched.
+- **SectionDivider's fill reads `-surface`.** Its three `-background`
+  properties are `-surface`, matching every other component's fill name,
+  renamed on load. `check-component` no longer accepts the suffix
+  `-background`; a property carrying one is a naming finding.
+- **A property's prefix is the component's id, with no exception.**
+  CornerBadge's forty `--corner-badge-*` properties are `--cornerbadge-*`,
+  renamed on load. `check-component` no longer accepts a hyphenated prefix
+  for any component; a property that carries one is a naming finding.
+- **A text part's color is its bare name.** Toggle's `--toggle-label-text`
+  and `--toggle-disabled-label-text` are `--toggle-label` and
+  `--toggle-disabled-label`, renamed on load, matching every other
+  component's bare-part color.
+- **A callback prop is `on` followed by the event name, all lowercase.**
+  TabBar's `ontabChange` is `onchange`. InlineEditActions' `onSave` and
+  `onCancel` are `onsave` and `oncancel`. A consumer passing the old prop
+  name stops compiling; there is no runtime migration for a prop.
+- **`open` everywhere.** Dialog's `show` prop is `open`, still `$bindable`.
+  CollapsibleSection's `expanded` prop is `open`, and its four
+  `-expanded-` properties are `-open-`, renamed on load. A consumer passing
+  the old prop name stops compiling; there is no runtime migration for a
+  prop.
+- **Size values are `default` and `small`.** Card's `size="compact"` is
+  `size="small"`. Notification's `size="normal"` is `size="default"` and
+  `size="compact"` is `size="small"`. A consumer passing the old value
+  stops compiling; there is no runtime migration for a prop.
+- **TabBar's `selectedTab` is `value`; SideNavigation's `titleLabel` is
+  `title`.** Both now hold the same kind of value SegmentedControl's and
+  MenuSelect's `value` props do. `titleHref` is unchanged. A consumer
+  passing the old prop name stops compiling; there is no runtime migration
+  for a prop.
+- **Badge's and CornerBadge's `primary` variant is `brand`.** The variant
+  paints the brand color family, which its tokens already name
+  (`--surface-brand`), so `variant="primary"` on either component is
+  `variant="brand"` and the rendered class is `badge-brand`. Badge's
+  thirteen `--badge-primary-*` and CornerBadge's three
+  `--cornerbadge-primary-*` properties are `--badge-brand-*` and
+  `--cornerbadge-brand-*`, renamed on load. Button's and IconButton's
+  `primary`, the one primary action a page carries, is unchanged. A consumer
+  passing the old value stops compiling; there is no runtime migration for a
+  prop.
+
+### Changed
+
+- **Every shipped catalogue entry explains the props that carry a choice.**
+  `props.variant` on Badge, CornerBadge, Callout, Notification, Card, and
+  Slider, `props.anchor` on CornerBadge, `props.type` on Input,
+  `props.role` on MenuSelect, and `props.minHeight` on Panel, which used to
+  sit inside `useFor`. SectionDivider's entry keys its size guidance under
+  `variant`, the prop's real name, instead of `level`, and adds `eyebrow`
+  and `description`. The registry contract test now fails on a `props` key
+  that names no declared prop.
+- **`components` prints only the catalogue fields a file has.** A file whose
+  export lacks a field no longer prints `Use for: undefined`; the
+  `missing-description` finding already names the field.
+- **"section" replaces "band" and "range" replaces "band"** in the catalogue,
+  the skills, the docs, and the README, following the design vocabulary in
+  `docs/terminology.md`.
+- **`contract-preview` is retired.** The harness throws `contract-states`
+  from its state assertions and `contract-interaction` from its interaction
+  assertions directly, so a failure the CLI used to report under
+  `contract-preview` now reports under the rule that actually failed.
+- **`report --json`'s `components[]` facts are narrower.** No `name`,
+  `unread`, or `described`; a component's unread tokens and missing
+  description are now the `unread-token` and `missing-description` findings
+  under `findings.components`. `usage` drops `customUnregistered`; an
+  unregistered project component is now `missing-registration`.
+- **The catalogue reads "views" for what TabBar switches, "a note" for
+  Tooltip, "section" for what Panel frames, and "a modal window" for
+  Dialog.**
+- **`docs/terminology.md` and the create-component skill record the
+  component naming rules**: which word names a prop or a semantic property,
+  and the retired spellings each replaces.
+
+### Removed
+
+- **`live-tokens-fix-findings` is gone.** `live-tokens-check-compliance`
+  now checks and fixes the whole project: it reads the report, runs the
+  token migrations, runs both checkers, repairs each remaining finding from
+  its `guidance`, and adds `check:design` to the build. "Make check:design
+  pass" and "fix the project" now reach it. `npx live-tokens setup-claude
+  --force` deletes a project's old copy, because it prunes every
+  `live-tokens-` skill a release no longer ships.
+
+### Fixed
+
+- **The overlay's collapsed pill no longer covers the pinned variant strip on
+  the components page.** While the pill rests in the top band the overlay
+  publishes its right inset as `--lt-pill-inset`, and the pinned preview header
+  wraps its tabs clear of it. The contract harness's tab clicks are forced
+  clicks again, so chrome over a tab fails the run.
+- **The component inventory discovers a runtime nested below a
+  `componentDirs` entry**, not only one directly inside it. `componentInventory`
+  now walks each directory recursively, the way the discovery it replaced did.
+- **`config-token` reads `component-configs/<id>/default.json` from the
+  project's actual data directory** — `dataDir` in `live-tokens.testing.ts` or
+  `live-tokens.config.json`, same resolution `check-component --tests`
+  already isolates — instead of the literal `src/live-tokens/data`.
+- **`config-token` checks an alias against its own component's properties**,
+  not the union across every component's. An alias that names a sibling
+  component's property now fires, where it used to pass silently.
+- **A component with neither a runtime nor an editor reports both
+  `missing-file` findings**, not only the runtime's. The editor check runs
+  before the runtime check returns.
+- **`check-page`'s attribute parser reads an attribute a newline separates
+  from the tag name**, and reads `size = "small"` — spaces around `=` — as
+  Svelte does, as one attribute rather than a stray `=` that stopped the scan.
+- **One broken alias is one finding.** `check-component <id> --tests` used to
+  report a `default.json` alias naming an unknown token twice: once as
+  `config-token` from the static read, once as `contract-alias` from the
+  browser watching the same property resolve to nothing. The merge now drops
+  the browser's copy when every property it names already carries a
+  `config-token` finding for that component. A `contract-alias` naming a token
+  the vocabulary knows, declared and still unresolved, is a different defect
+  and stays.
+- **A missing runtime is the registry rule's finding.** The behavior suite
+  skips a component's cases, with the reason, when the file its registration
+  names does not exist, instead of failing every declared case on the same
+  unresolved import. `contract-behavior` then reads `incomplete` in coverage,
+  explained by the `contract-registry` failure beside it.
+- **Every registry assertion names its component.** "Every authored component
+  is registered" is now one assertion per authored id, so an unregistered
+  component reports `contract-registry` naming itself. It used to reach the
+  CLI as `tests-setup`, which means the tooling never ran.
+- **A page obligation measures a page that has stopped moving.** `PageHarness`
+  waited on `--body-md-font-size`, which `tokens.css` sets on its own, then on
+  two animation frames. A page whose theme values, route stylesheet, or fonts
+  were still arriving could be measured mid-flight, and a rule reading its
+  geometry would report a finding on one run and none on the next. The harness
+  now waits for a quiet window over the page's geometry, its projected root
+  style, and its font set, bounded so a page that never settles is still
+  measured.
+
 ## 0.78.0 — A page proves compliance as rendered
 
 ### Added

package/README.md

@@ -332,13 +332,13 @@ npx @motion-proto/live-tokens <command>
 | `set-type <pairing.json> [--dry-run] [--no-verify]` | Bind Google Fonts families to the theme's font stacks, verified against the API. |
 | `set-geometry <ops.json> [--dry-run]` | Move radius, padding, gap, and border-width aliases along their token scales. |
 | `save-theme <name> [--no-activate] [--dry-run]` | Compose the live state into `themes/<slug>.json` and open it, which clears the unsaved buffers. |
-| `migrate [--check] [--write] [--tokens <path>]` | Reconcile the project with the installed package: additive `tokens.css` migrations, the pre-0.48 data-tree move, and a report on source references to the routes that moved in 0.35.0. |
+| `migrate [--check] [--write] [--tokens <path>]` | Reconcile the project with the installed package: every `tokens.css` migration, breaking ones included, the pre-0.48 data-tree move, and a report on source references to the routes that moved in 0.35.0. |
 
 Once installed in a project, the same commands are available as `npx live-tokens <command>`.
 
 ## Claude Code skills
 
-The package bundles nine Claude Code skills. They encode the conventions this README cannot carry in full: which component fits a need, how a page is wired, how one request becomes a whole look, what a valid theme looks like in OKLCH, how two typefaces sit together, how geometry moves along the token scales, how a project is checked against all of that, and how an existing page or component is brought back into line. Each triggers from an ordinary request, so there are no slash commands to learn.
+The package bundles eight Claude Code skills. They encode the conventions this README cannot carry in full: which component fits a need, how a page is wired, how one request becomes a whole look, what a valid theme looks like in OKLCH, how two typefaces sit together, how geometry moves along the token scales, how a project is checked against all of that, and how an existing page or component is brought back into line. Each triggers from an ordinary request, so there are no slash commands to learn.
 
 ### Install
 
@@ -390,7 +390,7 @@ Ask for color: "a cooler palette", "warmer", "more contrast", "calmer", "make th
 
 The skill translates the color intent into ten OKLCH base colors (Brand, Accent, Special, Canvas, Neutral, Alternate, Info, Success, Warning, Danger) plus a light or dark scheme, then runs `npx live-tokens set-colors <base-colors.json>`. The CLI assembles the curves, enforces AA contrast on derived text tokens and auto-corrects where it can, writes the result to the unsaved colors-and-type buffer, and prints a contrast report. Exit 1 means the base colors themselves are unworkable, and each failure line names the base color to change.
 
-Most of the skill is the judgment the generator cannot supply: a chroma budget scaled to how much screen area each palette covers, per-role lightness and hue bands for each scheme, three levels of canvas commitment, gamut guardrails against impossible base colors, harmony modes, and the optional canvas gradient. OKLCH anchors for every named feeling, idiom, and occasion live in a reference file the skill reads on demand.
+Most of the skill is the judgment the generator cannot supply: a chroma budget scaled to how much screen area each palette covers, per-role lightness and hue ranges for each scheme, three levels of canvas commitment, gamut guardrails against impossible base colors, harmony modes, and the optional canvas gradient. OKLCH anchors for every named feeling, idiom, and occasion live in a reference file the skill reads on demand.
 
 Color is the one dimension every look fixes, so it runs first and never skips. `--dry-run` prints the report without writing. Saving the open theme in the editor, or running `save-theme`, keeps the result; Adopt ships it. A re-run replaces the buffer's whole color state, including palette edits made in the editor since the last run, and carries the type and geometry buffers forward.
 
@@ -420,25 +420,19 @@ Ask for something the catalogue lacks: "author a Rating component", "make my Chi
 
 The skill covers the recipe: the runtime `.svelte` file with its `:global(:root)` token block, the editor `.svelte` file exporting `allTokens` and its variant groups, the `registerComponent()` call, and the catalogue entry that keeps `live-tokens-pick-component` current. It carries the naming scheme, the token suffix vocabulary, the state model (component states such as selected and disabled are separate from interaction states such as hover), and the public-imports rule, and points at the shipped `Toggle` in `node_modules` as the worked example. Linked siblings, intrinsics, and the fixed-overlay portal rule sit in reference files the skill reads only when a component needs them.
 
-### `live-tokens-check-compliance`
-
-Ask how things stand: "check this project against the design system", "audit the pricing page", "what would it take to make the build pass?", "review this before I upgrade".
-
-The skill runs `npx live-tokens report --json`, which is the project as facts: pending `tokens.css` migrations, the tokens each component declares and reads, which page renders which component, and both checkers' findings by rule under the project's severities and under `--strict`. It presents the report, says what each rule holds, marks each recommended fix as mechanical or a judgement call, names any visible shift, and flags a finding that looks deliberate together with the config entry that would record the decision. It edits nothing and ends by handing the list to `live-tokens-fix-findings`.
-
-### `live-tokens-fix-findings`
-
-Ask for the existing code to catch up: "make check:design pass", "fix the design-system warnings", "replace the hex and pixel values with tokens", "why is check-page failing on the pricing page?".
-
-The two checkers report a stable rule id per finding. The skill runs them with `--json`, groups the findings by rule, and carries one fix recipe per rule: a colour literal becomes the token for its role rather than the nearest hue, a spacing literal moves to the nearest `--space-*` step with the shift named, a raw `font-size` becomes a whole text style, a prop the component does not declare is mapped or dropped, and `site.css` moves out of `main.ts` into each page. It re-runs after every rule and stops at exit 0, then reports what changed, what it left and why, and what `--strict` would add. It never silences a rule to pass and never adds a token to `tokens.css` to match a value a page happened to use.
-
 Verify the result:
 
 ```bash
 npx @motion-proto/live-tokens check-component <id>
 ```
 
-The validator checks the file layout, the `:global(:root)` block, the token-suffix vocabulary, the state-before-property rule, the public-imports rule, the `registerComponent({ id })` call, and that every default resolves to a theme token rather than a literal. Exit code 0 means the static contract is met. A project scaffolded by `create` runs it, with `check-page`, as `npm run check:design` before every `vite build`, so a component or page that opts out of the theme cannot ship by accident.
+The validator checks the file layout, the `:global(:root)` block, the token-suffix vocabulary, the state-before-property rule, the public-imports rule, the `registerComponent({ id })` call, and that every default resolves to a design token rather than a literal. Exit code 0 means the static contract is met. `themeFileApi` runs it, with `check-page`, at the start of every `vite build`, so a component or page that opts out of the theme cannot ship by accident. An error stops the build, and warnings print. `themeFileApi({ checks: false })` turns the checks off.
+
+### `live-tokens-check-compliance`
+
+Ask how things stand, or ask for the code to catch up: "check this project against the design system and fix it", "audit the pricing page", "make the build's design checks pass", "fix the design-system warnings", "replace the hex and pixel values with tokens", "review this before I upgrade".
+
+The skill runs both checkers, which apply every pending additive `tokens.css` migration and every `auto` repair themselves and return each remaining finding with its own `guidance`. The skill groups what remains by rule, largest error group first, makes each repair from its guidance, and re-runs until both checkers exit 0. It reports what `--strict` adds and clears the warnings when the request covers them. The reply names the fixes the checkers applied, the changes by rule with any visible shift, and each finding left with its reason. It never silences a rule to pass and never adds a token to `tokens.css` to match a value a page happened to use. A finding the user chooses to keep goes into the config entry its `exception` field names.
 
 ## From edit to production