@motion-proto/live-tokens 0.73.0 → 0.75.0

package/CHANGELOG.md

@@ -1,5 +1,199 @@
 # Changelog
 
+## 0.75.0 — A component passes when the tests pass
+
+### Added
+
+- **`check-component` gains `--tests`.** Beyond the static lint, it runs the
+  registry contract under vitest and the component contract suites under
+  Playwright, for one component or every authored one, and reports coverage
+  by rule: listed, persisted and reset, themed, previewed, and drawn in
+  Sketch mode. `@playwright/test`, `vitest`, and `happy-dom` are new optional
+  peer dependencies; a missing one is a `tests-not-installed` finding naming
+  the install command. The suites ship at
+  `@motion-proto/live-tokens/testing` and `/testing/vitest`, and run here
+  against the library's own demo app and in a consumer against the
+  consumer's own app.
+
+  **live-tokens-create-component now runs `--tests` as its Verification
+  step**, in place of the manual pass through `/live-tokens/components`.
+  Every line that step asked a reader to confirm by eye is now a contract
+  assertion: the component's listing, its controls and preview, persistence
+  and reset, theme projection, linked properties, and Sketch mode.
+  live-tokens-fix-findings maps the new rule ids to the create-component
+  section that fixes each one, and the `create` template's new
+  `test:design` script runs the checks once the three peers are installed.
+
+### Changed
+
+- **Breaking: `tokens --scale` replaces `tokens --family`, and there is no
+  alias.** A token scale is the progression of one token across its range,
+  such as `space` or `radius`, and it is the one term for that grouping in the
+  CLI, the skills, and the skill atlas. "Family" now means a typeface only.
+  The `--json` output names the grouping `scales`, each with a `scale` and its
+  `tokens`. `bin/cliStrings.test.ts` bans "token family" and `--family`.
+- **Dividers and accents name their stroke role.** Three stroke roles share
+  the `--border-width-*` scale: a border encloses, a divider separates, an
+  accent emphasises. `set-geometry` moves each role on its own and reads the
+  role off the suffix, so a divider named `-border` moved with the borders.
+  TabBar's indicator is `--tabbar-<state>-indicator-width`, CollapsibleSection's
+  divider is `--collapsiblesection-divider-<state>-hairline-color` and
+  `-hairline-thickness`, Dialog's header and footer rules are
+  `--dialog-<part>-divider` and `-divider-width`, and Table's header rule is
+  `--table-default-header-divider` and `-divider-width`. Component migration 27
+  renames the keys in a saved theme; values are unchanged.
+- **CLI output uses the skills' vocabulary.** Every verb's help and report
+  lines say "the buffer" for edits a theme file does not hold yet, "load" for
+  making a theme the open one, "design token" and "semantic property" for the
+  two token classes, "shipped default", and "scale" and "step". The three set
+  verbs close with "The buffer holds this edit. Run save-theme to keep it as a
+  theme." Report lines print "old to new" in place of an arrow, and
+  `set-geometry` labels a skip "raw value", "off the scale", or "at the end of
+  the scale". `bin/cliStrings.test.ts` holds the line. The skills are corrected
+  where they described the CLI wrongly; the audit is
+  `docs/plans/cli-skill-alignment.md`.
+- **`live-tokens-build-page` is renamed `live-tokens-create-page`.** The verb
+  now matches `create-theme` and `create-component`. A project that copied the
+  skill keeps the old directory until it deletes it.
+- **The `create` template matches the skill.** `Home.svelte` drops the `h1`
+  and `p` rules `site.css` already types, the `0.9em` code size, and a `1.6`
+  line-height; its two Buttons take `--space-8`. `site.css` sets all five
+  axes from one text style on `p`, list items, `code`, and `pre`, and `ol li`
+  reads `--body-md-line-height` in place of `1.6`. A project created before
+  this release keeps its copied `site.css`.
+
+- **A page's type comes from a text style, and the checker fails a page that
+  names a raw axis.** `raw-text-axis` is an error, and it now reads a `var()`
+  as well as a literal. A `--font-size-*`, `--line-height-*`,
+  `--letter-spacing-*`, or a family stack such as `--font-sans` on a text
+  property is a finding. A text style token such as `--body-md-font-size` is
+  not. A `--font-weight-*` alone is not either, because a weight cannot move
+  the scale or the fonts. Two warnings join it. `control-size` reports a
+  `size` prop on a shipped component in a page file. `multiple-primary`
+  reports a second `variant="primary"` Button in one page file. A project
+  retunes a component's default size once, in the components editor. The
+  package's own pages, the template, and the `create` starter are all clean
+  under `--strict`. The starter's bulleted lists now take the `--body-md-*`
+  bundle.
+
+  **Every shipped component carries a usage comment.** `npx live-tokens
+  components` prints it as the description. `report` checks the shipped
+  set as it checks a custom component. The comment
+  names what the component is, what it is for, and what to reach for instead.
+  It never mentions size.
+
+- **Callout owns its box; the page owns the space around it.** `.callout` no
+  longer sets `margin: var(--space-24) 0`. A stack of callouts now takes its
+  spacing from the page's own gap, and a page that wants the old rhythm sets
+  `margin-block` on the container. The four `--callout-*-accent-width` defaults
+  point at `--border-width-1`, so the left edge matches the other three sides,
+  and the default theme follows. The token stays, so a theme can set the thick
+  left rule back, and the seven other presets keep the accents they were
+  authored with.
+
+- **A CLI run shows up in the open editor, and a Save afterwards keeps it.**
+  The dev server now watches the unsaved buffers and the active-theme pointer
+  and streams every outside change to the page as one frame over
+  `GET /api/live-tokens/events`. The editor hydrates from that frame the way
+  it does from an Apply, so `set-colors`, `set-type`, `set-geometry`, and
+  `save-theme` land on screen as they finish, and a Save afterwards writes
+  what is on screen rather than the tab's stale copy. The four verbs no longer
+  ask for a reload, and neither do the skills that run them. The server leaves
+  its own writes out of the stream, so an editor Save does not hydrate itself.
+  A branch switch that moves a buffer or the pointer reaches the page the same
+  way; any other JSON changed from outside still needs a reload.
+
+## 0.74.0 — A theme is three decisions and one document
+
+### Changed
+
+- **Breaking: the three theme CLI verbs are renamed, and there is no alias.**
+  `generate-theme` is now `set-colors`, `set-fonts` is now `set-type`, and
+  `adjust-geometry` is now `set-geometry`. Each verb names the dimension it
+  sets, and each matches the skill that runs it. A script or note that types
+  an old verb fails with "Unknown command"; there is no deprecation path,
+  because nothing is released against these names yet. `set-type` and
+  `set-geometry` keep their flags, their file formats, and their behaviour, and
+  the geometry ops file is now written to `scratch/geometry-ops.json`.
+
+  **`set-colors` writes the color buffer, and `save-theme` writes the theme.**
+  A theme is three decisions and one document. Each set verb now writes only
+  its own dimension into the unsaved buffers the app already renders:
+  `set-colors` joins `set-type` and `set-geometry` there, and no longer writes
+  or opens a theme. The new `save-theme <name>` composes the live state into
+  `themes/<slug>.json` and opens it, and with no unsaved edits it saves a copy
+  of the open theme under the new name. `--no-activate` saves without opening,
+  which is how a set of themes comes off one starting look. `--carry-from` is
+  gone: it existed because `set-colors` activated, and nothing activates now
+  until you save. The base color file no longer carries `name`; a name in it
+  is ignored with a notice. `live-tokens-create-theme` runs `save-theme` once,
+  after its three contributing skills. `init`, an undocumented alias for
+  `create` since 0.21.0, is gone: type `create`.
+
+  **36 dead keys left the override bag.** Themes carried the color, type, and
+  border-width siblings of keys an earlier migration dropped (Badge's `trait`
+  variant, SectionDivider's title and description slots, Dialog's variant and
+  state axes). Nothing read them, and every Adopt baked them into
+  `tokens.generated.css`. A colors-and-type migration drops them from your
+  themes on the next Save, the nine shipped themes are rewritten, and
+  `check:preset-themes` now refuses any shipped theme, `default` included,
+  whose override bag names a variable `tokens.css` does not declare.
+
+  Internal: the engine bundles are `dist-plugin/setColors`, `setType`, and
+  `setGeometry`, named for the verbs that load them. They have no `exports`
+  entry and no consumer imports them.
+
+- **A theme is one design direction routed to three contributing skills.**
+  `live-tokens-generate-theme` did two jobs: it read the request and fixed a
+  whole look, and it executed the color layer itself. So two of a theme's three
+  dimensions were skills and the third was a section. It is now
+  **live-tokens-create-theme**, which reads the request once, states one design
+  direction, states a color, a type, and a geometry intent, routes each to
+  **live-tokens-set-colors**, **live-tokens-set-type**, and
+  **live-tokens-set-geometry**, and assembles their three reports. Its one CLI
+  is `save-theme`. Every contributing skill still works when invoked directly
+  with an intent and no direction behind it. This changes four `description` triggers:
+  a whole look reaches create-theme, and a request naming one dimension goes
+  straight to that dimension's skill, including a color-only refinement like
+  "warmer".
+
+- **The anchor tables split by dimension.** A row in the old mood and style
+  vocabularies fixed color, type, and geometry at once, which meant the
+  coordinator read color mechanics and handed on the other two. create-theme
+  now holds `references/design-directions.md`, an index placing each anchor on
+  the valence, energy, and dominance axes with its one-line direction; each
+  contributing skill holds the column it executes, keyed on the same names.
+  `check:skills` gains an anchor-key parity gate, so a name that reaches only
+  some of the four files fails at commit.
+
+- **The theme skills call the user's own words the request, not the brief.**
+  "Brief" named two things at once: the user's words, and the seed JSON at
+  `scratch/<slug>-brief.json`. The second sense is fixed in two filenames and
+  in the CLI's own `<brief.json>` usage string, so the first sense moves.
+  Layer 0 of the pipeline in `docs/terminology.md` is now the request; the
+  files stay where they are and the prose calls them the seed file and the
+  pairing file. This changes one `description` trigger, in
+  `live-tokens-generate-theme`, from "from a natural-language brief" to "from
+  a natural-language request". set-fonts loses its one clash with the new
+  term: every family is a download rather than a request. The atlas tagline
+  named the wrong layer and now credits the design direction, the one sentence
+  three skills actually read.
+
+- **A palette's base color is called that, not its seed.** The word already
+  meant something else in this product: sketch mode displaces its strokes on
+  random seeds, and says so in copy a user reads. The theme document has always
+  called the value `baseColor`, so the skill and the CLI were the drift. The
+  generator's input key is now `baseColors` rather than `seeds`, and the file
+  the skill writes is `scratch/<slug>-base-colors.json`; the pairing file
+  `set-fonts` reads is `scratch/font-pairing.json`. Both CLI verbs report
+  against the new names, so a contrast failure now says "raise the Brand base
+  color lightness". Internally `buildColorsAndTypeFromSeeds` becomes
+  `buildColorsAndType`, dropping a "from" clause that was never true on the
+  type half, and `ColorsAndTypeBrief` becomes `ColorsAndTypeInput`; neither is
+  a public export. A kept base color file with
+  the old `seeds` key needs that one key renamed, and the skill rewrites the
+  file from scratch on every run anyway.
+
 ## 0.73.0 — The skill atlas ships from the package
 
 ### Added

package/README.md

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

package/bin/check-component.mjs

@@ -43,6 +43,60 @@ export const COMPONENT_RULES = {
   'default-not-token': 'error',
   'phantom-link': 'warn',
   'dimension-literal': 'warn',
+  // `--tests` (bin/contractRunner.mjs). Fixed by design decision 8 so
+  // `fix-findings` can map them; every one is an error, including the setup
+  // rules, which `--tests` treats as never-silenceable (see cli.mjs).
+  'contract-registry': 'error',
+  'contract-render': 'error',
+  'contract-alias': 'error',
+  'contract-persist': 'error',
+  'contract-theme': 'error',
+  'contract-states': 'error',
+  'contract-interaction': 'error',
+  'contract-listed': 'error',
+  'contract-sketch': 'error',
+  'tests-not-installed': 'error',
+  'tests-setup': 'error',
+  'tests-incomplete': 'error',
+};
+
+/**
+ * Where a rule is fixed, as a stable slug carried on the finding. The skills
+ * resolve the slug to one of their own headings, so adding a rule here costs
+ * no skill edit as long as it reuses a slug. Two skills used to enumerate every
+ * rule id in their own tables, with nothing holding the two in agreement or
+ * checking either against this list.
+ */
+export const COMPONENT_RULE_FIX = {
+  'unknown-suffix': 'property-name',
+  'state-after-property': 'property-name',
+  'disabled-is-terminal': 'property-name',
+  'default-not-token': 'property-token',
+  'color-literal': 'property-token',
+  'dimension-literal': 'property-token',
+  'unknown-token-ref': 'property-token',
+  'contract-theme': 'property-token',
+  'invalid-id': 'runtime',
+  'missing-file': 'runtime',
+  'missing-root-block': 'runtime',
+  'no-tokens': 'runtime',
+  'contract-persist': 'runtime-defaults',
+  'missing-component-const': 'editor',
+  'missing-all-tokens': 'editor',
+  'phantom-editor-token': 'editor',
+  'phantom-link': 'editor',
+  'deep-import': 'editor',
+  'contract-render': 'editor',
+  'contract-alias': 'editor',
+  'contract-states': 'editor',
+  'contract-interaction': 'editor',
+  'missing-registration': 'registration',
+  'contract-registry': 'registration',
+  'contract-listed': 'registration',
+  'contract-sketch': 'sketch',
+  'tests-not-installed': 'tooling',
+  'tests-setup': 'tooling',
+  'tests-incomplete': 'coverage',
 };
 
 // Shipped components keep their editor beside the other editors; a
@@ -97,6 +151,35 @@ function capitalize(id) {
   return id.charAt(0).toUpperCase() + id.slice(1);
 }
 
+/**
+ * Where `id`'s runtime and editor files live, resolved the same way
+ * `checkComponent` does: the real on-disk filename rather than a capitalised
+ * guess, since `cornerbadge` ships as `CornerBadge.svelte`. Exported so a
+ * caller outside the lint (the `--tests` runner, attributing a contract
+ * finding to a consumer artifact) doesn't re-derive it differently.
+ */
+export function resolveComponentPaths(id, root = process.cwd()) {
+  // A consumer names a shipped id and owns no copy of its files. Falling back
+  // to the package keeps the lint reading the same source the contract run
+  // resolves, instead of reporting the component's own files missing. In this
+  // repo the consumer paths always exist, so the fallback never fires here.
+  const roots = builtInIds(root).has(id) ? [root, PKG_ROOT] : [root];
+  for (const base of roots) {
+    const dir = join(base, 'src/system/components');
+    const Id =
+      (existsSync(dir) ? readdirSync(dir) : [])
+        .find((f) => f.toLowerCase() === `${id}.svelte`)
+        ?.replace('.svelte', '') ?? capitalize(id);
+    const runtimePath = join(dir, `${Id}.svelte`);
+    const editorPath =
+      EDITOR_DIRS.map((d) => join(base, d, `${Id}Editor.svelte`)).find(existsSync) ??
+      join(base, EDITOR_DIRS[0], `${Id}Editor.svelte`);
+    if (base === roots.at(-1) || (existsSync(runtimePath) && existsSync(editorPath))) {
+      return { Id, runtimePath, editorPath };
+    }
+  }
+}
+
 function extractImports(source) {
   const out = [];
   const re = /import\s+(?:[^'"]*\s+from\s+)?['"]([^'"]+)['"]/g;
@@ -267,10 +350,10 @@ function checkDefaultsAreSemantic({ blocks, runtime, editor, root, runtimePath,
         record(
           'unknown-token-ref',
           STATE_TOKENS.includes(ref.replace(/^--/, '').split('-')[0])
-            ? `${rel}: ${name} reads ${ref}, but a state is a segment of a property name, not a token of its own; read the token the state should paint`
+            ? `${rel}: ${name} reads ${ref}, but a state is a segment of a property name. Read the token the state should paint`
             : isContractToken(ref)
-              ? `${rel}: ${name} reads ${ref}, which looks like a theme token but no longer exists; check tokens.css for a rename`
-              : `${rel}: ${name} reads ${ref}, which is not a theme token or a component token`,
+              ? `${rel}: ${name} reads ${ref}, which has the shape of a design token but no longer exists. Check tokens.css for a rename`
+              : `${rel}: ${name} reads ${ref}, which is not a design token or a semantic property`,
           at,
         );
       }
@@ -278,7 +361,7 @@ function checkDefaultsAreSemantic({ blocks, runtime, editor, root, runtimePath,
       if (hasColorLiteral(painted)) {
         record(
           'color-literal',
-          `${rel}: ${name}: ${value} is a colour literal; defaults must reference theme tokens (e.g. var(--surface-primary))`,
+          `${rel}: ${name}: ${value} is a colour literal; defaults must reference design tokens (e.g. var(--surface-primary))`,
           at,
         );
         continue;
@@ -287,7 +370,7 @@ function checkDefaultsAreSemantic({ blocks, runtime, editor, root, runtimePath,
       if (refs.length === 0 && !matchers.some((re) => re.test(name))) {
         record(
           'default-not-token',
-          `${rel}: ${name}: ${value} has no theme token behind it; back it with a token, or declare it in the editor's \`intrinsics\` if it is a structural keyword`,
+          `${rel}: ${name}: ${value} has no design token behind it. Back it with a token, or declare it in the editor's \`intrinsics\` when it is a structural keyword`,
           at,
         );
       }
@@ -326,18 +409,7 @@ export function checkComponent(id, root = process.cwd(), { vocabulary } = {}) {
     return done();
   }
 
-  // Resolve the real filename rather than capitalising the id: `cornerbadge`
-  // ships as `CornerBadge.svelte`, and the casing is what gives the kebab form
-  // of its token prefix.
-  const dir = join(root, 'src/system/components');
-  const Id =
-    (existsSync(dir) ? readdirSync(dir) : [])
-      .find((f) => f.toLowerCase() === `${id}.svelte`)
-      ?.replace('.svelte', '') ?? capitalize(id);
-  const runtimePath = join(dir, `${Id}.svelte`);
-  const editorPath =
-    EDITOR_DIRS.map((d) => join(root, d, `${Id}Editor.svelte`)).find(existsSync) ??
-    join(root, EDITOR_DIRS[0], `${Id}Editor.svelte`);
+  const { Id, runtimePath, editorPath } = resolveComponentPaths(id, root);
 
   file = relative(root, runtimePath);
   if (!existsSync(runtimePath)) {
@@ -381,7 +453,7 @@ export function checkComponent(id, root = process.cwd(), { vocabulary } = {}) {
       record(
         'state-after-property',
         `${relative(root, runtimePath)}: ${token} has '${trailingState}' after the property; ` +
-          `state must come before property (e.g. -${trailingState}-surface, not -surface-${trailingState})`,
+          `state must come before property (e.g. -${trailingState}-surface)`,
         runtime.indexOf(token),
       );
     }
@@ -512,7 +584,7 @@ export function checkComponent(id, root = process.cwd(), { vocabulary } = {}) {
   if (!registrationFile) {
     record(
       'missing-registration',
-      `no registration for '${id}' under src/ — expected registerComponent({ id: '${id}', ... }) or bootLiveTokens({ components: [{ id: '${id}', ... }] })`,
+      `no registration for '${id}' under src/. Expected registerComponent({ id: '${id}', ... }) or bootLiveTokens({ components: [{ id: '${id}', ... }] })`,
     );
   } else {
     // Check the registration file's imports too.