@motion-proto/live-tokens 0.77.0 → 0.78.0

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

@@ -9,6 +9,8 @@ Run `npx live-tokens report`. The CLI prints a report with the sections in the R
 
 `report` never runs the component contract suites. The `check-component` test run does, and it is what live-tokens-create-component calls to validate a component's runtime behavior.
 
+`report` stays static for pages too. The `check-page` test run is what live-tokens-create-page calls for a rendered page, in a browser against the project's own route, and it reports `page-component-paint`, `page-text-style`, `page-contrast`, `page-grid`, and `page-overflow` findings the same way `report`'s static findings read: by rule, with a fix.
+
 ## Workflow
 
 When `report` is an unknown command, route the dependency upgrade to **live-tokens-fix-findings**. Resume the audit after the upgrade.

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

@@ -17,7 +17,7 @@ Assemble the page from the shipped components at their defaults and the theme's
 6. Write the page CSS in design tokens.
 7. Set the hierarchy: one text style per element, the shipped size on every control, one primary action, and one space step per position.
 8. Add the route, with a lazy import and the source path.
-9. Run **live-tokens-check-compliance**, then check the rendered page.
+9. Run **live-tokens-check-compliance** and `npx live-tokens check-page <file> --tests --strict`, then check the rendered page.
 10. Reply with the sections and the layout each took, the components placed, the route, and the compliance result.
 
 ## Layout
@@ -34,7 +34,7 @@ Decide the sections before the columns. Read the page top to bottom and name eac
 | Grid of equals | The reader compares or scans items of one kind. | Equal spans. Up to seven per section. |
 | Single column | The reader fills a form or reads at length. | Half the columns (6), centered. |
 
-The stage is the canvas, player, or strip the work is about. Stretch a section's containers to one height (`align-items: stretch`) so their bottom edges align. Below the scaffold's 768px breakpoint, a section's columns stack in reading order.
+The stage is the canvas, player, or strip the work is about. Stretch a section's containers to one height (`align-items: stretch`) so their bottom edges align.
 
 ### Grid
 
@@ -49,6 +49,8 @@ To place a section's children at page-column positions:
 
 A grid that follows the page columns takes `var(--columns-count)` or a `calc()` of it as its count, so it stays in step with `ColumnsOverlay`. A local grid of two or three equal columns writes its own count. A column number in `grid-column` is fixed to the count read in step 1.
 
+No scaffold collapses the page grid on a phone: the theme's own column gutter alone exceeds a phone's width at the full column count, so every page writes its own `@media (max-width: 767px)` rule setting `grid-template-columns: 1fr` and `column-gap: 0`, with each section's children spanning `grid-column: 1 / -1`. A section's columns then stack in reading order.
+
 ### Separation
 
 The page shows one thing, and every other element stays out of its way. Each element that is not content costs attention: a hairline, a border, a header bar, a shadow. Keep an element only when it serves a purpose no other element serves.
@@ -163,7 +165,7 @@ const pages = {
 
 ## Verify
 
-Run **live-tokens-check-compliance**. Its report carries both checkers' findings by rule, and **live-tokens-fix-findings** takes the fix list. Repeat until the page is clean.
+Run **live-tokens-check-compliance**, then `npx live-tokens check-page <file> --tests --strict`. The Playwright suite runs against the page's own route and proves what only a rendered page can: the cascade leaves every component painting from its semantic properties, every run of text sits in one shipped text style, every text and surface pair meets AA, sections sit on the page grid, and nothing overflows. Each finding carries a rule id and a line; `--off=<rule>` silences a rule for one run. The two reports carry every finding by rule, and **live-tokens-fix-findings** takes the fix list. Repeat until the page is clean.
 
 The checkers cannot see a layout. Open the page at the width it is built for and check each line below.
 
@@ -172,7 +174,6 @@ The checkers cannot see a layout. Open the page at the width it is built for and
 - No label is larger than the page's body copy.
 - A line of copy runs 45 to 90 characters.
 - The containers in a section align at the bottom.
-- Every control stays inside its wrapper. A `width: 100%` field takes `box-sizing: border-box`.
 - The actions sit where the eye goes last, with the one primary at the end.
 - Every row of actions holds an action that leaves without committing.
 - An action that destroys saved work confirms in a `Dialog`.

package/.claude/skills/live-tokens-fix-findings/SKILL.md

@@ -80,6 +80,13 @@ When `package.json` has no `check:design` script, add `"check:design": "live-tok
 | `control-size` | Delete the `size` prop. The shipped default is the page's size. When that default is wrong for the project, retune the component in `/live-tokens/components`. |
 | `multiple-primary` | Keep the action that completes the main task `primary`. A Button with no `variant` counts as `primary`. Use `secondary` for supporting or related actions and `outline` for unrelated or informational actions. |
 | `danger-without-dialog` | Open a `Dialog` from the danger Button or IconButton and run the action from the Dialog's confirm. The rule fires once per page, when the page imports no Dialog. For other actions, assign emphasis by the action's relationship to the main task. |
+| `native-control` | Replace the native element with the shipped component the message names: Button or IconButton, Input, MenuSelect. |
+| `property-override` | Delete the declaration from the page. Retune the component's token for the whole project at `/live-tokens/components`. |
+| `page-component-paint` | The finding names the page file and the line of the instance whose part painted a value its semantic property never resolves to. Remove the global rule reaching past the component, from `site.css` or the page's own CSS, and retune the component's token for the whole project at `/live-tokens/components`. |
+| `page-text-style` | The finding names the page file and the line of the text element and the nearest bundle it missed. Set the container's text style directly on the text element, one shipped bundle from `npx live-tokens tokens --scale heading` (or `body`, `editorial`, `code`), rather than leaving it to inherit from an ancestor typed for a different role. |
+| `page-contrast` | The finding names the page file and the line of the text element, the surface ancestor, and both computed colors. Pick the text token the surface pairs with, from the Color by role table above. |
+| `page-grid` | The finding names the page file and the line of the section whose edge sits off a column line. Move the edge to the line: place it by page-column numbers per the Grid section of **live-tokens-create-page**, and give a centered section symmetric insets rather than a margin, a width, or a transform. |
+| `page-overflow` | The finding names the page file and the line of the element or the instance that overflows. Give the control its shipped width, remove a fixed width that does not fit its column at the viewport, and set `overflow-x: auto` only on an element deliberately meant to scroll, such as a code block. When the overflow is the page grid itself at a phone width, collapse it: `grid-template-columns: 1fr`, `column-gap: 0`, per the Grid section of **live-tokens-create-page**. |
 | `hardcoded-columns` | `repeat(var(--columns-count), 1fr)` for the page grid. `calc(var(--columns-count) - 2)` for a sub-grid spanning fewer columns. |
 | `site-css-in-main` | Delete the import from `main.ts`. Add it to each page's `<script>`. Page CSS then stays off the editor routes. |
 | `missing-source` | Add `source: 'src/...'` to the route entry. |

package/CHANGELOG.md

@@ -1,5 +1,58 @@
 # Changelog
 
+## 0.78.0 — A page proves compliance as rendered
+
+### Added
+
+- **A page proves compliance as rendered, not just in source.** `check-page
+  --tests` opens each page's own route in a Playwright browser, against the
+  consumer's own app, and reports five rule ids no static read of the source
+  could: `page-component-paint` (every shipped component instance paints its
+  contracted parts from its semantic properties, never from a page-wide or
+  `site.css` rule that reaches past them), `page-text-style` (every run of
+  text sits in one shipped text style, never inherited from a container typed
+  for a different role), `page-contrast` (every text and surface pair the
+  page composes meets AA), `page-grid` (every section's edges land on the
+  page's own column lines), and `page-overflow` (nothing overflows its
+  container, at either viewport). Coverage is reported by page, rule, and
+  viewport; a rule that observed nothing on a page reports `inapplicable`
+  with a reason, never a silent pass. `live-tokens.testing.ts` gains two
+  settings: `pageRoutes`, for a route the app's own route table cannot
+  express, and `pageViewports`, to replace the two sizes every rule runs at.
+- **Two static rules close source-level gaps `check-page` left open.**
+  `native-control` flags a raw `<button>`, `<input>`, `<select>`, or
+  `<textarea>` where a shipped component belongs. `property-override` flags a
+  page that declares or sets a component token's name directly, in a style
+  block, an inline `style`, a `style:` directive, or `setProperty`, rather
+  than retuning the component for the whole project at
+  `/live-tokens/components`.
+- **The consumer acceptance gate now covers a page.** `check:smoke-page-tests`
+  packs the built package into a fresh project outside the repository,
+  scaffolds it with `create`, and proves the documented command against the
+  template's own clean page and against the same page under a deliberate
+  `site.css` override: the clean page passes, the override fails
+  `page-component-paint` at the page file, and source-tree hashes prove the
+  isolated run never touched the project's own data. Wired into
+  `prepublishOnly` beside the existing component gate. Both gates now carry a
+  twenty-minute deadline of their own, naming the step that did not finish.
+
+### Changed
+
+- **The `create` template's `test:design` runs both suites:**
+  `live-tokens check-component --tests && live-tokens check-page --tests`.
+- **The live-tokens-create-page skill's Verify step runs the rendered check.**
+  After live-tokens-check-compliance, it runs `check-page --tests --strict`
+  on the page it built. The manual line "every control stays inside its
+  wrapper" moves to the automated `page-overflow` rule; every other
+  editorial line stays.
+- **The `create` template's own Home page collapses to one column below
+  768px.** Its `.stub` held a fixed twelve-column span with no phone
+  breakpoint, so `page-overflow` failed at 390x844, the defect
+  `check:smoke-page-tests` now catches on any page written to that shape.
+  The template ships no exclusion mechanism, so the fix is the page's own
+  `@media (max-width: 767px)` rule, the same shape every page-defects
+  fixture already takes.
+
 ## 0.77.0 — A consumer component runs the same suites
 
 ### Added

package/bin/check-page.mjs

@@ -33,10 +33,24 @@ export const PAGE_RULES = {
   'control-size': 'warn',
   'multiple-primary': 'warn',
   'danger-without-dialog': 'warn',
+  'native-control': 'warn',
+  'property-override': 'warn',
+  // `--tests` (bin/contractRunner.mjs's `runPageTests`). Fixed by design
+  // decision 9, same reasoning as `check-component`'s own `contract-*` rules:
+  // every one is an error, including the setup rules, which `--tests` treats
+  // as never-silenceable (see cli.mjs).
+  'page-component-paint': 'error',
+  'page-text-style': 'error',
+  'page-contrast': 'error',
+  'page-grid': 'error',
+  'page-overflow': 'error',
+  'tests-not-installed': 'error',
+  'tests-setup': 'error',
+  'tests-incomplete': 'error',
 };
 
 // Directories that hold the system, not pages built on it.
-const NOT_PAGES = ['src/system', 'src/editor', 'src/lib', 'src/live-tokens'];
+export const NOT_PAGES = ['src/system', 'src/editor', 'src/lib', 'src/live-tokens'];
 
 export const COMPONENT_IMPORT =
   /(?:@motion-proto\/live-tokens\/components|[./][^'"]*\/system\/components)\/([A-Za-z0-9]+)\.svelte$/;
@@ -194,6 +208,61 @@ function tagAttributes(code, start) {
   return { attrs, end: tagEnd };
 }
 
+// The shipped component that owns each native control's paint.
+const NATIVE_CONTROLS = {
+  button: 'Button or IconButton',
+  input: 'Input',
+  select: 'MenuSelect',
+  textarea: 'Input',
+};
+
+/**
+ * `{@html ...}` blanked, brace-balanced, so a tag textually present inside a
+ * raw HTML string is not mistaken for markup the page authored.
+ */
+function blankHtmlExpressions(code) {
+  let out = code;
+  const re = /\{@html\b/g;
+  let m;
+  while ((m = re.exec(out)) !== null) {
+    const start = m.index;
+    let depth = 0;
+    let i = start;
+    for (; i < out.length; i++) {
+      if (out[i] === '{') depth++;
+      else if (out[i] === '}' && --depth === 0) {
+        i++;
+        break;
+      }
+    }
+    out = out.slice(0, start) + ' '.repeat(i - start) + out.slice(i);
+    re.lastIndex = start;
+  }
+  return out;
+}
+
+/** A raw `<button>`, `<input>`, `<select>`, or `<textarea>` where a shipped
+    component belongs. `<input type="hidden">` paints nothing and is exempt.
+    A tag inside `<script>` is markup the page assembles into a string, not
+    markup it renders, so the script block is blanked the same way
+    `codeRegion` blanks `<style>`, keeping offsets aligned with `code`. */
+function checkNativeControls(code, add) {
+  const scan = blankHtmlExpressions(code).replace(/<script[^>]*>[\s\S]*?<\/script>/g, (m) => ' '.repeat(m.length));
+  for (const tag of Object.keys(NATIVE_CONTROLS)) {
+    for (const m of scan.matchAll(new RegExp(`<${tag}(?=[\\s/>])`, 'g'))) {
+      const parsed = tagAttributes(scan, m.index);
+      if (tag === 'input' && parsed?.attrs.some((a) => a.name.toLowerCase() === 'type' && a.value?.toLowerCase() === 'hidden')) {
+        continue;
+      }
+      add(
+        'native-control',
+        m.index,
+        `<${tag}> is a native control; use ${NATIVE_CONTROLS[tag]} so it paints from the theme.`,
+      );
+    }
+  }
+}
+
 /**
  * Props a page passes that the component does not declare, values outside a
  * prop's union, and a shipped component the page sizes itself.
@@ -274,6 +343,22 @@ function checkDestructiveActions(code, imports, add) {
   }
 }
 
+// Which component's :global(:root) block declared each component token,
+// cached per vocabulary since checkFile runs once per page.
+const tokenOwnersCache = new WeakMap();
+function componentTokenOwners(vocab) {
+  let owners = tokenOwnersCache.get(vocab);
+  if (owners) return owners;
+  owners = new Map();
+  for (const comp of vocab.components.values()) {
+    for (const name of comp.tokens.keys()) {
+      if (!owners.has(name)) owners.set(name, comp.name);
+    }
+  }
+  tokenOwnersCache.set(vocab, owners);
+  return owners;
+}
+
 /** The object literal enclosing `index`, found by balancing braces outward. */
 function enclosingObject(text, index) {
   let depth = 0;
@@ -335,6 +420,7 @@ function checkFile(file, text, vocab, root) {
     checkComponentUsage(code, imports, add);
     checkPrimaryActions(code, imports, add);
     checkDestructiveActions(code, imports, add);
+    checkNativeControls(code, add);
 
     for (const m of code.matchAll(/['"](\/live-tokens[^'"]*)['"]\s*:/g)) {
       add('reserved-route', m.index, `route '${m[1]}' is inside the reserved /live-tokens/* namespace`);
@@ -360,16 +446,52 @@ function checkFile(file, text, vocab, root) {
 
   // A page may also mint a custom property outside its <style> block — a
   // `style:--x={...}` directive or an el.style.setProperty call — and those are
-  // just as declared as one written in CSS.
-  const declaredHere = new Set();
+  // just as declared as one written in CSS. Each name keeps the earliest site
+  // it was declared at, so property-override reports one finding per name.
+  const declaredSites = new Map();
+  const declareAt = (name, index) => {
+    if (!declaredSites.has(name) || index < declaredSites.get(name)) declaredSites.set(name, index);
+  };
   const regions = styleRegions(text, file);
-  for (const region of regions) {
-    for (const m of neutralise(region.text).matchAll(/(?:^|[;{])\s*(--[a-z0-9-]+)\s*:/gim)) {
-      declaredHere.add(m[1]);
+  const styleBlockDeclarations = (regionList, at) => {
+    for (const region of regionList) {
+      for (const m of neutralise(region.text).matchAll(/(?:^|[;{])\s*(--[a-z0-9-]+)\s*:/gim)) {
+        at(m[1], region.offset + m.index);
+      }
     }
-  }
+  };
+  styleBlockDeclarations(regions, declareAt);
   for (const m of text.matchAll(/(?:style:|setProperty\(\s*['"`]|['"`])(--[a-z0-9-]+)/g)) {
-    declaredHere.add(m[1]);
+    declareAt(m[1], m.index);
+  }
+
+  // property-override needs a narrower set than declaredSites: the bare-quote
+  // alternative above exists only to suppress unknown-token on a name any
+  // quoted string mentions, so it also matches a read like
+  // getPropertyValue("--x"). A real declaration is a style-block rule, an
+  // inline `style="--x: ..."` attribute, a `style:--x=` directive, or a
+  // setProperty('--x', ...) call.
+  const overrideSites = new Map();
+  const overrideAt = (name, index) => {
+    if (!overrideSites.has(name) || index < overrideSites.get(name)) overrideSites.set(name, index);
+  };
+  styleBlockDeclarations(regions, overrideAt);
+  if (code !== null) styleBlockDeclarations(inlineStyleRegions(code), overrideAt);
+  for (const m of text.matchAll(/(?:style:|setProperty\(\s*['"`])(--[a-z0-9-]+)/g)) {
+    overrideAt(m[1], m.index);
+  }
+
+  // A name the vocabulary already ties to a component is that component's
+  // token, so declaring it here is one instance overriding the whole
+  // project's retuning surface at /live-tokens/components.
+  for (const [name, index] of overrideSites) {
+    if (!vocab.componentTokens.has(name)) continue;
+    const owner = componentTokenOwners(vocab).get(name) ?? 'a shipped component';
+    add(
+      'property-override',
+      index,
+      `${name} overrides ${owner}'s token here instead of the whole project; retune it at /live-tokens/components.`,
+    );
   }
 
   for (const region of [...regions, ...(code === null ? [] : inlineStyleRegions(code))]) {
@@ -378,7 +500,7 @@ function checkFile(file, text, vocab, root) {
 
     for (const m of css.matchAll(/var\(\s*(--[a-z0-9-]+)/g)) {
       const name = m[1];
-      if (declaredHere.has(name) || vocab.knows(name)) continue;
+      if (declaredSites.has(name) || vocab.knows(name)) continue;
       add(
         'unknown-token',
         at(m.index),

package/bin/cli.mjs

@@ -20,6 +20,7 @@ import { fileURLToPath } from 'node:url';
 import process from 'node:process';
 import { COMPONENT_RULES, COMPONENT_RULE_FIX, checkComponent, discoverComponents, formatReport } from './check-component.mjs';
 import { PAGE_RULES, checkPages, discoverPages } from './check-page.mjs';
+import { resolvePageTestTargets } from './lib/pageRoutes.mjs';
 import { describeComponents, describeTokens, formatComponents, formatTokens } from './lib/catalogue.mjs';
 import { buildReport, formatReport as formatProjectReport } from './lib/report.mjs';
 import { loadVocabulary } from './lib/tokenVocabulary.mjs';
@@ -74,10 +75,20 @@ Commands:
                               @playwright/test, vitest, and happy-dom; a
                               missing one is a tests-not-installed finding
                               naming the install command
-  check-page [paths...]       Validate pages against the live-tokens-create-page
+  check-page [paths...] [--tests]
+                              Validate pages against the live-tokens-create-page
                               contract: catalogue components only, and every CSS
                               value a design token. Checks every page under src/
-                              when given no paths.
+                              when given no paths. --tests also opens each
+                              page's own route in the consumer's own app and
+                              proves, per shipped rule id, that the cascade
+                              painted every component from its semantic
+                              properties, every run of text sits in one shipped
+                              text style, every text/surface pair meets AA,
+                              sections sit on the page grid, and nothing
+                              overflows. Needs @playwright/test, vitest, and
+                              happy-dom; a missing one is a tests-not-installed
+                              finding naming the install command
 
 check-component and check-page also accept:
   --json                      Machine-readable findings, for a skill to iterate
@@ -270,7 +281,18 @@ if (command === 'check-page') {
   const opts = parseCheckFlags(rest);
   const targets = opts.rest.length > 0 ? opts.rest : discoverPages(process.cwd());
   const { findings, checked } = checkPages(targets, { root: process.cwd() });
-  reportChecks('check-page', findings, checked, PAGE_RULES, opts);
+  if (!opts.tests) {
+    reportChecks('check-page', findings, checked, PAGE_RULES, opts);
+  }
+  const { hasHardFailure, runPageTests } = await import('./contractRunner.mjs');
+  const pageTargets = resolvePageTestTargets(opts.rest, process.cwd());
+  const testOutcome = await runPageTests(pageTargets, { root: process.cwd() });
+  const label = 'check-page --tests';
+  const allFindings = [...findings, ...testOutcome.findings];
+  reportChecks(label, allFindings, Math.max(checked, pageTargets.length), PAGE_RULES, opts, {
+    coverage: testOutcome.coverage,
+    hardFailure: hasHardFailure(testOutcome.findings),
+  });
 }
 
 if (command === 'set-colors') {