@motion-proto/live-tokens 0.74.0 → 0.75.0

package/bin/check-page.mjs

@@ -1,7 +1,7 @@
 // Static validator for a live-tokens page.
 //
 // Asserts that a page satisfies the contract described in the
-// live-tokens-build-page skill: it is assembled from catalogue components, and
+// live-tokens-create-page skill: it is assembled from catalogue components, and
 // every value in its CSS is a theme token rather than a literal. The rules and
 // their default severities are in PAGE_RULES; each is overridable per project
 // (live-tokens.config.json) or per run (--off/--warn/--error/--strict), because
@@ -26,10 +26,13 @@ export const PAGE_RULES = {
   'color-literal': 'error',
   'reserved-route': 'error',
   'site-css-in-main': 'error',
+  'raw-text-axis': 'error',
   'dimension-literal': 'warn',
   'hardcoded-columns': 'warn',
-  'raw-text-axis': 'warn',
   'missing-source': 'warn',
+  'control-size': 'warn',
+  'multiple-primary': 'warn',
+  'danger-without-dialog': 'warn',
 };
 
 // Directories that hold the system, not pages built on it.
@@ -45,6 +48,13 @@ const DEEP_IMPORT_PATTERNS = [
 
 const TEXT_AXES = ['font-size', 'font-family', 'font-weight', 'line-height', 'letter-spacing'];
 
+// The single-axis scales in tokens.css. A text style bundle carries its axis
+// as a suffix (--body-md-font-size, --code-font-family), so no bundle name
+// matches, and neither does a custom property the page declares itself. A
+// weight alone cannot move the scale or the fonts, so --font-weight-* is not one.
+const SINGLE_AXIS_TOKEN =
+  /^--(?:font-size|line-height|letter-spacing)-|^--font-(?:sans|serif|mono|display|editorial)$/;
+
 // The geometry the theme owns: spacing, stroke, radius, and shadow all have a
 // token scale, and `set-geometry` moves them. Sizing (a hero's height, a
 // column's minimum width, a max content width) is layout, has no scale, and
@@ -184,7 +194,10 @@ function tagAttributes(code, start) {
   return { attrs, end: tagEnd };
 }
 
-/** Props a page passes that the component does not declare, or values outside a prop's union. */
+/**
+ * Props a page passes that the component does not declare, values outside a
+ * prop's union, and a shipped component the page sizes itself.
+ */
 function checkComponentUsage(code, imports, add) {
   for (const [local, entry] of imports) {
     const props = entry.props;
@@ -203,11 +216,64 @@ function checkComponentUsage(code, imports, add) {
         if (allowed && value !== null && !allowed.has(value)) {
           add('unknown-prop-value', index, `${entry.name} ${name}="${value}" is not one of ${[...allowed].join(', ')}`);
         }
+        if (name === 'size' && entry.origin === 'shipped') {
+          add(
+            'control-size',
+            index,
+            `${entry.name} ${value === null ? 'is sized here' : `size="${value}"`}. Drop it for the shipped default, or retune ${entry.name} for the whole project in /live-tokens/components.`,
+          );
+        }
       }
     }
   }
 }
 
+/**
+ * One finding when a page holds more than one primary Button, at the second of
+ * them. Emphasis is what the variant carries, so a second primary leaves the
+ * page with no single most important action. A Button with no variant is
+ * primary, the component's default.
+ */
+function checkPrimaryActions(code, imports, add) {
+  const primaries = [];
+  for (const [local, entry] of imports) {
+    if (entry.id !== 'button') continue;
+    for (const m of code.matchAll(new RegExp(`<${local}(?=[\\s/>])`, 'g'))) {
+      const tag = tagAttributes(code, m.index);
+      const variant = tag?.attrs.find((a) => a.name === 'variant');
+      if (tag && (variant === undefined || variant.value === 'primary')) primaries.push(m.index);
+    }
+  }
+  if (primaries.length < 2) return;
+  primaries.sort((a, b) => a - b);
+  add(
+    'multiple-primary',
+    primaries[1],
+    `${primaries.length} primary Buttons in this page. Keep the most important action primary and make the other ${primaries.length - 1} secondary.`,
+  );
+}
+
+/**
+ * One finding when a page holds a danger Button and imports no Dialog. A
+ * danger action destroys saved work, and the page has nothing to confirm it.
+ */
+function checkDestructiveActions(code, imports, add) {
+  if ([...imports.values()].some((entry) => entry.id === 'dialog')) return;
+  for (const [local, entry] of imports) {
+    if (entry.id !== 'button' && entry.id !== 'iconbutton') continue;
+    for (const m of code.matchAll(new RegExp(`<${local}(?=[\\s/>])`, 'g'))) {
+      const tag = tagAttributes(code, m.index);
+      if (!tag?.attrs.some((a) => a.name === 'variant' && a.value === 'danger')) continue;
+      add(
+        'danger-without-dialog',
+        m.index,
+        `${entry.name} variant="danger" with no Dialog in this page. A destructive action confirms in a Dialog before it runs.`,
+      );
+      return;
+    }
+  }
+}
+
 /** The object literal enclosing `index`, found by balancing braces outward. */
 function enclosingObject(text, index) {
   let depth = 0;
@@ -267,6 +333,8 @@ function checkFile(file, text, vocab, root) {
       if (local) imports.set(local, entry);
     }
     checkComponentUsage(code, imports, add);
+    checkPrimaryActions(code, imports, add);
+    checkDestructiveActions(code, imports, 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`);
@@ -315,8 +383,8 @@ function checkFile(file, text, vocab, root) {
         'unknown-token',
         at(m.index),
         isContractToken(name)
-          ? `${name} looks like a theme token but no longer exists; check tokens.css for a rename`
-          : `${name} is not a theme token, a component token, or declared in this file`,
+          ? `${name} has the shape of a design token but no longer exists. Check tokens.css for a rename`
+          : `${name} is not a design token, a semantic property, or declared in this file`,
       );
     }
 
@@ -328,25 +396,38 @@ function checkFile(file, text, vocab, root) {
       // inside one is not the page's value.
       const painted = stripVarFallbacks(value);
       if (!TEXT_AXES.includes(prop) && hasColorLiteral(painted)) {
-        add('color-literal', at(index), `${prop}: ${value}. Use a theme token, not a colour literal.`);
+        add('color-literal', at(index), `${prop}: ${value}. Use a design token.`);
         continue;
       }
 
-      // Only absolute type values are a finding. `em`, `%`, and a unitless
-      // line-height are relative to the inherited type, so they ride whatever
-      // the theme sets rather than overriding it.
-      if (
-        (TEXT_AXES.includes(prop) || prop === 'font') &&
-        !value.includes('var(') &&
-        !/^(inherit|initial|unset|normal)$/.test(value) &&
-        /\d(px|rem|pt)\b|^[a-z"']/i.test(value)
-      ) {
-        add(
-          'raw-text-axis',
-          at(index),
-          `${prop}: ${value}. Set type from a text style bundle (--heading-*, --body-*, --editorial-*).`,
-        );
-        continue;
+      if (TEXT_AXES.includes(prop) || prop === 'font') {
+        const axis = [...painted.matchAll(/var\(\s*(--[a-z0-9-]+)/g)]
+          .map((m) => m[1])
+          .find((name) => SINGLE_AXIS_TOKEN.test(name));
+        if (axis) {
+          add(
+            'raw-text-axis',
+            at(index),
+            `${prop}: ${value}. ${axis} is one axis. Set every axis from one text style bundle (--heading-*, --body-*, --editorial-*, --code-*).`,
+          );
+          continue;
+        }
+
+        // Of the literals only absolute type values are a finding. `em`, `%`,
+        // and a unitless line-height are relative to the inherited type, so
+        // they ride whatever the theme sets rather than overriding it.
+        if (
+          !value.includes('var(') &&
+          !/^(inherit|initial|unset|normal)$/.test(value) &&
+          /\d(px|rem|pt)\b|^[a-z"']/i.test(value)
+        ) {
+          add(
+            'raw-text-axis',
+            at(index),
+            `${prop}: ${value}. Set type from a text style bundle (--heading-*, --body-*, --editorial-*, --code-*).`,
+          );
+          continue;
+        }
       }
 
       if (THEMED_GEOMETRY.test(prop) && hasDimensionLiteral(painted)) {

package/bin/cli.mjs

@@ -4,10 +4,10 @@
 //   create <dir>             Scaffold a new app that depends on this package.
 //   setup-claude [--force]   Copy bundled Claude Code skills into ./.claude/skills/.
 //   components [id]          List every component the project has, shipped and its own, with props and tokens.
-//   tokens [--family <name>] List every theme token by family, with its value.
+//   tokens [--scale <name>]  List every design token by scale, with its value.
 //   report                   The project as facts: tokens read, components used, findings by rule. Always exits 0.
 //   check-component [id]     Validate a component (or every authored one) against the create-component skill contract.
-//   check-page [paths...]    Validate pages against the build-page skill contract.
+//   check-page [paths...]    Validate pages against the create-page skill contract.
 //   set-colors <colors>      Build the color identity from 10 OKLCH base colors, into the open buffer.
 //   set-geometry <ops>       Apply radius/padding/gap/border-width ops to the open buffer.
 //   set-type <pairing>       Bind Google Fonts families to the theme's font stacks.
@@ -18,12 +18,13 @@ import { cpSync, existsSync, mkdirSync, readdirSync, statSync, writeSync } from
 import { dirname, join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import process from 'node:process';
-import { COMPONENT_RULES, checkComponent, discoverComponents, formatReport } from './check-component.mjs';
+import { COMPONENT_RULES, COMPONENT_RULE_FIX, checkComponent, discoverComponents, formatReport } from './check-component.mjs';
 import { PAGE_RULES, checkPages, discoverPages } from './check-page.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';
 import {
+  applyCoverageSeverity,
   applySeverity,
   countBySeverity,
   formatFindings,
@@ -48,27 +49,33 @@ const USAGE = `Usage: npx @motion-proto/live-tokens <command> [options]
 
 Commands:
   create <dir> [--force]      Scaffold a new Svelte + Vite app wired up with
-                              live-tokens (editor, components, theme tokens)
+                              live-tokens (editor, components, design tokens)
   setup-claude [--force]      Install bundled Claude Code skills into ./.claude/skills/
   components [id] [--json]    List every component the project has, shipped and
                               its own (src/system/components plus any
-                              "componentDirs" in live-tokens.config.json), with
-                              the props each takes; with an id, that component's
-                              props, variants, tokens, and defaults
-  tokens [--family <name>] [--json]
-                              List every theme token the project's tokens.css
-                              declares, by family, with its value
+                              "componentDirs" in live-tokens.config.json). With
+                              an id, that component's props, variants, tokens,
+                              and defaults
+  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 declares and reads, which page
                               renders which component, and both checkers'
                               findings by rule under the project's severities
-                              and under --strict. A reading, not a gate: always
-                              exits 0
-  check-component [id]        Validate <id>'s runtime, editor, and registration
-                              against the live-tokens-create-component contract
-  check-page [paths...]       Validate pages against the live-tokens-build-page
+                              and under --strict. Always exits 0
+  check-component [id] [--tests]
+                              Validate <id>'s runtime, editor, and registration
+                              against the live-tokens-create-component contract.
+                              --tests also runs the registry contract under
+                              vitest and the component contract suites under
+                              Playwright, reporting coverage by rule. Needs
+                              @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
                               contract: catalogue components only, and every CSS
-                              value a theme token. Checks every page under src/
+                              value a design token. Checks every page under src/
                               when given no paths.
 
 check-component and check-page also accept:
@@ -84,44 +91,42 @@ check-component and check-page also accept:
                               OKLCH base colors (see the live-tokens-set-colors
                               skill) and enforce AA contrast on the derived text
                               tokens. Reads the live colors and type and writes
-                              the result to the unsaved colors-and-type buffer,
-                              so save the open theme in the editor or run
-                              save-theme to keep it. Fonts and every override no
-                              palette owns carry forward. --dry-run prints the
-                              contrast report without writing.
+                              the result to the colors-and-type buffer. Run
+                              save-theme to keep it as a theme. Fonts and every
+                              override no palette owns carry forward. --dry-run
+                              prints the contrast report without writing.
   set-geometry <ops.json> [--dry-run]
                               Move radius, padding, gap, and border-width
                               aliases along their token scales (see the
                               live-tokens-set-geometry skill). Reads each
                               component's live config and writes the result to
-                              that component's unsaved buffer, so save the open
-                              theme in the editor to keep it. --dry-run prints
-                              the report without writing.
+                              that component's buffer. Run save-theme to keep it
+                              as a theme. --dry-run prints the report without
+                              writing.
   set-type <pairing.json> [--dry-run] [--no-verify]
                               Bind Google Fonts families to --font-display,
                               --font-sans, --font-serif, --font-mono and
                               --font-editorial (see
                               the live-tokens-set-type skill). Each family is
                               verified against the Google Fonts API and the URL
-                              is negotiated from the weights it actually has.
-                              Writes the result to the unsaved colors-and-type
-                              buffer, so save the open theme in the editor to
-                              keep it. --dry-run prints the report without
-                              writing; --no-verify skips the network and
-                              requires an explicit URL per family.
+                              is negotiated from the weights it has. Writes the
+                              result to the colors-and-type buffer. Run
+                              save-theme to keep it as a theme. --dry-run prints
+                              the report without writing. --no-verify skips the
+                              network and requires an explicit URL per family.
   save-theme <name> [--no-activate] [--dry-run]
-                              Compose the live state (the unsaved buffers, the
-                              open theme under them, the shipped defaults under
-                              that) into themes/<slug>.json and open it, which
-                              clears the buffers. With no unsaved edits it saves
-                              a copy of the open theme under the new name.
-                              Opening never changes what your site ships; Adopt
-                              in the editor does that. --no-activate writes the
-                              theme and leaves the live state alone, so a set of
-                              themes comes off one starting look; --dry-run
-                              prints the report without writing.
+                              Compose the live state (the buffers, the open
+                              theme under them, the shipped defaults under that)
+                              into themes/<slug>.json and load it, which clears
+                              the buffers. With no buffer it saves a copy of the
+                              open theme under the new name. Loading never
+                              changes what the site ships. Adopt in the editor
+                              does that. --no-activate writes the theme and does
+                              not load it, so a set of themes comes off one
+                              starting theme. --dry-run prints the report
+                              without writing.
   migrate [--check] [--write] [--tokens <path>]
-                              Reconcile your project with the installed package:
+                              Reconcile the project with the installed package:
                               applies additive tokens.css migrations, moves a
                               pre-0.48 data tree onto the current directory
                               names, heals what the retired pointer files named,
@@ -177,14 +182,19 @@ if (command === 'create') {
   }
 }
 
-function reportChecks(label, findings, checked, rules, opts) {
-  const resolved = applySeverity(findings, rules, opts, readChecksConfig(process.cwd()));
+function reportChecks(label, findings, checked, rules, opts, { coverage, hardFailure, fixes } = {}) {
+  const checksConfig = readChecksConfig(process.cwd());
+  const resolved = applySeverity(findings, rules, opts, checksConfig, fixes ?? {});
+  const resolvedCoverage = coverage ? applyCoverageSeverity(coverage, rules, opts, checksConfig) : coverage;
   console.log(
     opts.json
-      ? toJson(resolved, { label, checked })
+      ? toJson(resolved, { label, checked, coverage: resolvedCoverage })
       : formatFindings(resolved, { label, checked }),
   );
-  process.exit(countBySeverity(resolved).errors === 0 ? 0 : 1);
+  // Decision 2: a missing tool or a setup failure under --tests is an error
+  // even if a project silenced its rule id, since silencing it would read as
+  // "the tests passed" rather than "the tests did not run".
+  process.exit(countBySeverity(resolved).errors === 0 && !hardFailure ? 0 : 1);
 }
 
 if (command === 'components') {
@@ -198,14 +208,14 @@ if (command === 'components') {
 
 if (command === 'tokens') {
   const opts = parseCheckFlags(rest);
-  const at = opts.rest.indexOf('--family');
-  const family = at >= 0 ? opts.rest[at + 1] : undefined;
+  const at = opts.rest.indexOf('--scale');
+  const scale = at >= 0 ? opts.rest[at + 1] : undefined;
   const desc = describeTokens(loadVocabulary());
-  if (family && !desc.families.some((f) => f.family === family)) fail(formatTokens(desc, { family }));
+  if (scale && !desc.scales.some((s) => s.scale === scale)) fail(formatTokens(desc, { scale }));
   writeOut(
     opts.json
-      ? JSON.stringify(family ? desc.families.find((f) => f.family === family) : desc, null, 2)
-      : formatTokens(desc, { family }),
+      ? JSON.stringify(scale ? desc.scales.find((s) => s.scale === scale) : desc, null, 2)
+      : formatTokens(desc, { scale }),
   );
   process.exit(0);
 }
@@ -231,18 +241,28 @@ if (command === 'report') {
 if (command === 'check-component') {
   const opts = parseCheckFlags(rest);
   const ids = opts.rest.length > 0 ? [opts.rest[0]] : discoverComponents();
-  if (ids.length === 0) {
+  if (ids.length === 0 && !opts.tests) {
     console.log('✓ check-component: no component authored under src/system/components yet.');
     process.exit(0);
   }
   const results = ids.map((id) => [id, checkComponent(id)]);
-  if (ids.length === 1 && !opts.json && !opts.strict && opts.off.length + opts.warn.length + opts.error.length === 0) {
+  if (!opts.tests && ids.length === 1 && !opts.json && !opts.strict && opts.off.length + opts.warn.length + opts.error.length === 0) {
     const [id, result] = results[0];
     console.log(formatReport(id, result));
     process.exit(result.errors.length === 0 ? 0 : 1);
   }
-  const label = ids.length === 1 ? `check-component ${ids[0]}` : 'check-component';
-  reportChecks(label, results.flatMap(([, r]) => r.findings), ids.length, COMPONENT_RULES, opts);
+  const label = ids.length === 1 ? `check-component ${ids[0]}${opts.tests ? ' --tests' : ''}` : `check-component${opts.tests ? ' --tests' : ''}`;
+  if (!opts.tests) {
+    reportChecks(label, results.flatMap(([, r]) => r.findings), ids.length, COMPONENT_RULES, opts, { fixes: COMPONENT_RULE_FIX });
+  }
+  const { hasHardFailure, runContractTests } = await import('./contractRunner.mjs');
+  const testOutcome = await runContractTests(opts.rest[0], { root: process.cwd() });
+  const findings = [...results.flatMap(([, r]) => r.findings), ...testOutcome.findings];
+  reportChecks(label, findings, Math.max(ids.length, 1), COMPONENT_RULES, opts, {
+    fixes: COMPONENT_RULE_FIX,
+    coverage: testOutcome.coverage,
+    hardFailure: hasHardFailure(testOutcome.findings),
+  });
 }
 
 if (command === 'check-page') {
@@ -265,7 +285,7 @@ if (command === 'set-colors') {
   }
   if (rest.includes('--carry-from')) {
     fail(
-      `set-colors has no --carry-from: it reads the live look and edits it in place, so a second theme ` +
+      `set-colors has no --carry-from: it reads the live theme and edits it in place, so a second theme ` +
         `already starts from the first. Run save-theme --no-activate between themes.`,
     );
   }
@@ -421,10 +441,10 @@ for (const skill of skills) {
   installed++;
 }
 
-console.log(`\n${installed} installed, ${skipped} skipped → ${destSkills}`);
+console.log(`\n${installed} installed, ${skipped} skipped, in ${destSkills}`);
 
 const SAMPLE_PROMPTS = {
-  'live-tokens-build-page': 'build a pricing page using live-tokens components',
+  'live-tokens-create-page': 'build a pricing page using live-tokens components',
   'live-tokens-pick-component': "what's the difference between TabBar and SegmentedControl?",
   'live-tokens-create-component': 'author a new Toggle component for my live-tokens project',
   'live-tokens-create-theme': 'make me a bright and cheerful theme',
@@ -442,6 +462,6 @@ const installedSamples = skills
 if (installedSamples.length > 0) {
   console.log(`\nIn Claude Code, prompts like these auto-trigger the matching skill:`);
   for (const [skill, prompt] of installedSamples) {
-    console.log(`  • "${prompt}"\n    → ${skill}`);
+    console.log(`  "${prompt}"\n    ${skill}`);
   }
 }