@motion-proto/live-tokens 0.74.0 → 0.76.0

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.

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)) {