@motion-proto/live-tokens 0.77.0 → 0.79.0

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

@@ -1,98 +0,0 @@
----
-name: live-tokens-fix-findings
-description: Fix every finding of check-page and check-component in an existing @motion-proto/live-tokens project until both exit 0. Called with the fix list by live-tokens-check-compliance. Use when the user asks to fix the project. Edits the files the checkers name. Updates tokens.css only through the migration command.
----
-
-# Fixing the findings of check-page and check-component
-
-Fix every finding of `check-page` and `check-component` until both exit 0. `check-page` checks pages. Every component comes from the catalogue, every prop is declared, and every value in page CSS is a design token. `check-component` checks authored components. Every token names a semantic property, and its default is the design token that property reads. Update `tokens.css` only through the migration command. That command also heals the data tree, and with `--write` rewrites the route references it lists. When live-tokens-check-compliance hands over a fix list, the user's choices in it stand.
-
-## Workflow
-
-When `check-page` is an unknown command, upgrade `@motion-proto/live-tokens` first.
-
-1. Run `npx live-tokens migrate --check` to see the plan, then `npx live-tokens migrate` to apply it. `--tokens <path>` names a tokens.css in an unusual place.
-2. Run both checkers with `--json`. Each finding carries a `rule`, a file, and a line.
-   ```sh
-   npx live-tokens check-page --json
-   npx live-tokens check-component --json
-   ```
-3. Group the findings by rule.
-4. Take the largest error group first, then the remaining errors. Take warnings only when the repair scope includes warnings.
-5. Fix every finding in the group with its section: Color by role, Geometry by scale, or The remaining rules.
-6. Run both checkers again. When repairable findings remain in scope, return to step 3. When no token fits a remaining finding, leave it and continue to the reply with its reason.
-7. When the errors are clear, run both checkers with `--strict`. Report what `--strict` adds. Clear warnings within the existing request. Otherwise ask whether to clear the warnings now.
-8. When the repair scope includes warnings, return to step 3 with `--strict`. When strict checks pass or the user defers warnings, continue to the reply.
-9. Reply with:
-   - the changes by rule, each with its count and any visible shift
-   - the findings left, each with its reason and any config entry the user chose
-   - both checker commands with their exit codes
-
-`check-page <path>` scopes a run to one page. `check-component <id>` scopes a run to one component: its runtime, its editor, and its registration. The checkers read tokens.css from its default location.
-
-When `package.json` has no `check:design` script, add `"check:design": "live-tokens check-page && live-tokens check-component"`. When both checkers exit 0, prepend `npm run check:design &&` to the existing build command. Preserve its other build steps.
-
-## Scope
-
-- Add no token to `tokens.css`. Map a literal with no matching token to the nearest existing token by role. When no token fits, leave the finding and say so.
-- When the user has chosen to lower a rule's severity, record it in `live-tokens.config.json` under `"checks": { "rules": { "<rule>": "warn" } }`. `--off=<rule>` silences a rule for one run only.
-- When the nearest token differs from the literal, use the token and name the shift in the report, such as `14px` to `--space-16`.
-
-## Color by role
-
-`color-literal` is a judgement finding. The replacement is the token for the role the color plays. The theme moves every role together. `npx live-tokens tokens --scale <name>` prints a scale's names and values, with `--json` for data.
-
-| Literal | Token | Notes |
-| --- | --- | --- |
-| Text on a surface | `--text-primary` through `--text-disabled` | The neutral text scale. `--text-<family>` for a family color. |
-| Light text on a dark chip | `--text-inverted` | No AA guarantee. |
-| A surface fill | `--surface-<family>-<level>` | The role names the family: `neutral` for chrome, `brand` for emphasis, `danger` for status. |
-| A stroke | `--border-<family>-<level>` | Levels run `faint` to `strong`. |
-| A translucent layer that dims what is behind it | `--scrim-low`, `--scrim`, `--scrim-high` | Behind a modal. |
-| A translucent wash on a surface | `--tint-low`, `--tint`, `--tint-high` | A hover state. |
-| Any other translucent color | The role's token at an opacity: `color-mix(in srgb, var(--surface-brand) 80%, transparent)` | The editor reads that form. |
-| Fully transparent | `--color-transparent` | |
-| A gradient | `--gradient-*` | Or compose one from surface tokens. |
-
-## Geometry by scale
-
-`dimension-literal` is a mechanical finding. A size, such as a hero's height, is layout. Leave it.
-
-| Literal | Token | Notes |
-| --- | --- | --- |
-| Spacing | `--space-<px>` | `npx live-tokens tokens --scale space` prints the steps. Round to the nearest step. |
-| A stroke width | `--border-width-1`, `-2`, `-4` | Also for `outline`. |
-| A corner | `--radius-sm` through `--radius-4xl`, or `--radius-full` | |
-| A shadow | `--shadow-sm` through `--shadow-xl` | Replace the whole value. |
-| Part of a `calc()` | The token inside the calc | `calc(var(--space-64) * -2 + var(--space-8))` |
-| A duration or easing | `--duration-*`, `--ease-*` | No rule reports it. Fix it while in the file. |
-| A `blur()` | `--blur-*` | No rule reports it. Fix it while in the file. |
-
-## The remaining rules
-
-| Rule | Fix |
-| --- | --- |
-| `unknown-token` | Search `tokens.css` for the stem. When a contract-family name is gone, `npx live-tokens migrate --check` lists the migration that adds the current name. |
-| `raw-text-axis` | Set every axis from one text style, `-font-family` through `-letter-spacing`. `npx live-tokens tokens --scale heading` prints one text style. The text styles are `heading`, `body`, `editorial`, and `code`. Rewrite a `font:` shorthand the same way. |
-| `unknown-component` | Read **live-tokens-pick-component** for the shipped component that fits. When none fits, author one with **live-tokens-create-component**. |
-| `unknown-prop` | `npx live-tokens components <id>` prints the declared props and their values. Map the prop to one of them, or delete it. |
-| `unknown-prop-value` | Use a value from the union the message lists. |
-| `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. |
-| `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. |
-| `reserved-route` | Move the route out of `/live-tokens/*`. |
-| `deep-import` | Import from `@motion-proto/live-tokens`, `/component-editor`, or `/components/<Name>.svelte`. |
-| `fix: property-name` | Rename the token to the name a shipped component uses for the same role. The vocabulary and the state model are in **live-tokens-create-component**. |
-| `fix: property-token` | Make the `:global(:root)` default read a design token, composed when needed. Declare a structural keyword, such as `start`, in the editor's `intrinsics`. |
-| `fix: runtime` | Wire the component as the recipe in **live-tokens-create-component** wires it. |
-| `fix: runtime-defaults` | Make the `:global(:root)` default the value Reset should restore, per the Runtime component section of **live-tokens-create-component**. |
-| `fix: editor` | The editor names a token the runtime never declares, or a property targets the wrong part. Fix the editor's schema, states, or preview props by the Component editor section of **live-tokens-create-component**. |
-| `fix: registration` | Register the component in the shared module the Registration section of **live-tokens-create-component** wires up, importable by the app and by `check-component --tests`. |
-| `fix: sketch` | Add the missing Sketch part or marker, per the Sketch mode and overlays section of **live-tokens-create-component**. |
-| `fix: tooling` | Install the named package (`@playwright/test`, `vitest`, or `happy-dom`) as a devDependency, then `npx playwright install chromium` for a missing browser. A bad path or config is named in the message; fix it and rerun `check-component <id> --tests`. |
-| `fix: coverage` | A contract obligation never ran to a result. Add the missing contract, or find why the suite skipped it, then rerun. |
-
-A `tests-*` finding names a problem with the run itself: the tool, the path, or a missing contract. Fix what the message names and rerun `check-component <id> --tests --json` until every applicable rule passes with no rule left `--off`.

package/src/editor/skill-atlas/trees/fix-findings.ts

@@ -1,469 +0,0 @@
-import type { SkillTree } from '../types';
-
-export const fixFindings: SkillTree = {
-  "id": "live-tokens-fix-findings",
-  "digest": "sha256:2c39f9f00b03b5ad",
-  "title": "fix-findings",
-  "tagline": "Repair Deviations from the Design System",
-  "nodes": [
-    {
-      "id": "ff-trig",
-      "row": 0,
-      "kind": "trigger",
-      "title": "Fix design-system findings",
-      "desc": "Repairs every finding the two checkers report, mapping each literal to the token for its role or scale, until both exit 0.",
-      "lines": [3, 3],
-      "anchor": "description: Fix every finding of check-page and check-compo"
-    },
-    {
-      "id": "ff-migrate",
-      "row": 1,
-      "kind": "step",
-      "title": "Run the token migration",
-      "desc": "Bring tokens.css up to the installed package first. A stale file shows as unknown tokens.",
-      "lines": [14, 14],
-      "anchor": "Run `npx live-tokens migrate --check` to see the plan, then "
-    },
-    {
-      "id": "ff-run",
-      "row": 2,
-      "kind": "cli",
-      "title": "Run both checkers",
-      "desc": "Each finding names a rule, a file, and a line.",
-      "lines": [15, 19],
-      "anchor": "Run both checkers with `--json`. Each finding carries a `rul",
-      "anchorEnd": "```"
-    },
-    {
-      "id": "ff-clean",
-      "row": 3,
-      "kind": "ok",
-      "title": "Default checks pass",
-      "desc": "Both checkers exit 0.",
-      "lines": [24, 24],
-      "anchor": "When the errors are clear, run both checkers with `--strict`"
-    },
-    {
-      "id": "ff-group",
-      "row": 5,
-      "kind": "step",
-      "title": "Group findings by rule",
-      "desc": "Findings of one rule share one fix.",
-      "lines": [20, 20],
-      "anchor": "Group the findings by rule."
-    },
-    {
-      "id": "ff-order",
-      "row": 6,
-      "kind": "chipset",
-      "title": "Repair order",
-      "desc": "Errors first, largest group first. Warnings only when the repair scope includes them.",
-      "lines": [21, 21],
-      "anchor": "Take the largest error group first, then the remaining error"
-    },
-    {
-      "id": "ff-recipe",
-      "row": 7,
-      "kind": "decide",
-      "title": "Rule family",
-      "desc": "Each rule belongs to one section, and that section gives the fix.",
-      "lines": [22, 22],
-      "anchor": "Fix every finding in the group with its section: Color by ro",
-      "chips": [
-        {
-          "label": "Color by role",
-          "lines": [41, 41],
-          "anchor": "## Color by role"
-        },
-        {
-          "label": "Geometry by scale",
-          "lines": [57, 57],
-          "anchor": "## Geometry by scale"
-        },
-        {
-          "label": "The remaining rules",
-          "lines": [71, 71],
-          "anchor": "## The remaining rules"
-        }
-      ]
-    },
-    {
-      "id": "ff-color",
-      "row": 8,
-      "kind": "chipset",
-      "title": "Color by role",
-      "desc": "A color literal becomes the token for the role it plays.",
-      "lines": [41, 55],
-      "anchor": "## Color by role",
-      "anchorEnd": "| A gradient | `--gradient-*` | Or compose one from surface ",
-      "chips": [
-        {
-          "label": "Text on a surface",
-          "lines": [47, 47],
-          "anchor": "| Text on a surface | `--text-primary` through `--text-disab"
-        },
-        {
-          "label": "Light text on a dark chip",
-          "lines": [48, 48],
-          "anchor": "| Light text on a dark chip | `--text-inverted` | No AA guar"
-        },
-        {
-          "label": "A surface fill",
-          "lines": [49, 49],
-          "anchor": "| A surface fill | `--surface-<family>-<level>` | The role n"
-        },
-        {
-          "label": "A stroke",
-          "lines": [50, 50],
-          "anchor": "| A stroke | `--border-<family>-<level>` | Levels run `faint"
-        },
-        {
-          "label": "A translucent layer that dims what is behind it",
-          "lines": [51, 51],
-          "anchor": "| A translucent layer that dims what is behind it | `--scrim"
-        },
-        {
-          "label": "A translucent wash on a surface",
-          "lines": [52, 52],
-          "anchor": "| A translucent wash on a surface | `--tint-low`, `--tint`, "
-        },
-        {
-          "label": "Any other translucent color",
-          "lines": [53, 53],
-          "anchor": "| Any other translucent color | The role's token at an opaci"
-        },
-        {
-          "label": "Fully transparent",
-          "lines": [54, 54],
-          "anchor": "| Fully transparent | `--color-transparent` | |"
-        },
-        {
-          "label": "A gradient",
-          "lines": [55, 55],
-          "anchor": "| A gradient | `--gradient-*` | Or compose one from surface "
-        }
-      ]
-    },
-    {
-      "id": "ff-geometry",
-      "row": 8,
-      "kind": "chipset",
-      "title": "Geometry by scale",
-      "desc": "A dimension literal moves to the nearest step of its scale. A layout size stays.",
-      "lines": [57, 69],
-      "anchor": "## Geometry by scale",
-      "anchorEnd": "| A `blur()` | `--blur-*` | No rule reports it. Fix it while"
-    },
-    {
-      "id": "ff-remaining",
-      "row": 8,
-      "kind": "chipset",
-      "title": "The remaining rules",
-      "desc": "Every other rule has its fix in the table.",
-      "lines": [71, 90],
-      "anchor": "## The remaining rules",
-      "anchorEnd": "| `fix: runtime` | Wire the component as the recipe in **liv",
-      "chips": [
-        {
-          "label": "unknown-token",
-          "lines": [75, 75],
-          "anchor": "| `unknown-token` | Search `tokens.css` for the stem. When a"
-        },
-        {
-          "label": "raw-text-axis",
-          "lines": [76, 76],
-          "anchor": "| `raw-text-axis` | Set every axis from one text style, `-fo"
-        },
-        {
-          "label": "unknown-component",
-          "lines": [77, 77],
-          "anchor": "| `unknown-component` | Read **live-tokens-pick-component** "
-        },
-        {
-          "label": "unknown-prop",
-          "lines": [78, 78],
-          "anchor": "| `unknown-prop` | `npx live-tokens components <id>` prints "
-        },
-        {
-          "label": "unknown-prop-value",
-          "lines": [79, 79],
-          "anchor": "| `unknown-prop-value` | Use a value from the union the mess"
-        },
-        {
-          "label": "control-size",
-          "lines": [80, 80],
-          "anchor": "| `control-size` | Delete the `size` prop. The shipped defau"
-        },
-        {
-          "label": "multiple-primary",
-          "lines": [81, 81],
-          "anchor": "| `multiple-primary` | Keep the action that completes the ma"
-        },
-        {
-          "label": "danger-without-dialog",
-          "lines": [82, 82],
-          "anchor": "| `danger-without-dialog` | Open a `Dialog` from the danger "
-        },
-        {
-          "label": "hardcoded-columns",
-          "lines": [83, 83],
-          "anchor": "| `hardcoded-columns` | `repeat(var(--columns-count), 1fr)` "
-        },
-        {
-          "label": "site-css-in-main",
-          "lines": [84, 84],
-          "anchor": "| `site-css-in-main` | Delete the import from `main.ts`. Add"
-        },
-        {
-          "label": "missing-source",
-          "lines": [85, 85],
-          "anchor": "| `missing-source` | Add `source: 'src/...'` to the route en"
-        },
-        {
-          "label": "reserved-route",
-          "lines": [86, 86],
-          "anchor": "| `reserved-route` | Move the route out of `/live-tokens/*`."
-        },
-        {
-          "label": "deep-import",
-          "lines": [87, 87],
-          "anchor": "| `deep-import` | Import from `@motion-proto/live-tokens`, `"
-        },
-        {
-          "label": "Component name rules",
-          "lines": [88, 88],
-          "anchor": "| `fix: property-name` | Rename the token to the name a ship"
-        },
-        {
-          "label": "Component token rules",
-          "lines": [89, 89],
-          "anchor": "| `fix: property-token` | Make the `:global(:root)` default "
-        },
-        {
-          "label": "Component editor rules",
-          "lines": [92, 92],
-          "anchor": "| `fix: editor` | The editor names a token the runtime never"
-        },
-        {
-          "label": "Component wiring rules",
-          "lines": [90, 90],
-          "anchor": "| `fix: runtime` | Wire the component as the recipe in **liv"
-        }
-      ]
-    },
-    {
-      "id": "ff-rerun",
-      "row": 11,
-      "kind": "cli",
-      "title": "Rerun both checkers",
-      "desc": "Run both checkers again to see what remains.",
-      "lines": [23, 23],
-      "anchor": "Run both checkers again. When repairable findings remain in "
-    },
-    {
-      "id": "ff-repeat",
-      "row": 12,
-      "kind": "gate",
-      "title": "Regroup the remaining findings",
-      "desc": "Findings a token can fix go back through grouping.",
-      "lines": [23, 23],
-      "anchor": "Run both checkers again. When repairable findings remain in "
-    },
-    {
-      "id": "ff-unresolved",
-      "row": 12,
-      "kind": "step",
-      "title": "Record the unresolved findings",
-      "desc": "A finding no token fits stays, and the reply says why.",
-      "lines": [37, 37],
-      "anchor": "Add no token to `tokens.css`. Map a literal with no matching"
-    },
-    {
-      "id": "ff-strict",
-      "row": 14,
-      "kind": "cli",
-      "title": "Run strict checks",
-      "desc": "Strict mode counts every warning as an error.",
-      "lines": [24, 24],
-      "anchor": "When the errors are clear, run both checkers with `--strict`"
-    },
-    {
-      "id": "ff-warnings",
-      "row": 15,
-      "kind": "decide",
-      "title": "Warning scope",
-      "desc": "Warnings are cleared when the request includes them. Otherwise the user chooses.",
-      "lines": [24, 25],
-      "anchor": "When the errors are clear, run both checkers with `--strict`",
-      "anchorEnd": "When the repair scope includes warnings, return to step 3 wi",
-      "chips": [
-        {
-          "label": "repair scope includes warnings",
-          "lines": [25, 25],
-          "anchor": "When the repair scope includes warnings, return to step 3 wi"
-        },
-        {
-          "label": "user defers warnings",
-          "lines": [25, 25],
-          "anchor": "When the repair scope includes warnings, return to step 3 wi"
-        }
-      ]
-    },
-    {
-      "id": "ff-warning-loop",
-      "row": 16,
-      "kind": "gate",
-      "title": "Include warnings in the repair scope",
-      "desc": "The warnings go back through grouping, with --strict on every run.",
-      "lines": [25, 25],
-      "anchor": "When the repair scope includes warnings, return to step 3 wi"
-    },
-    {
-      "id": "ff-build",
-      "row": 17,
-      "kind": "step",
-      "title": "Gate the existing build",
-      "desc": "The build runs check:design first, so findings fail the build from now on.",
-      "lines": [33, 33],
-      "anchor": "When `package.json` has no `check:design` script, add `\"chec"
-    },
-    {
-      "id": "ff-reply",
-      "row": 18,
-      "kind": "chipset",
-      "title": "Reply with the repair results",
-      "desc": "Report the changes by rule, the findings left with their reasons, and both exit codes.",
-      "lines": [26, 29],
-      "anchor": "Reply with:",
-      "anchorEnd": "both checker commands with their exit codes"
-    },
-    {
-      "id": "ff-done",
-      "row": 19,
-      "kind": "done",
-      "title": "Repair results complete",
-      "desc": "Both checkers pass, or every finding left has a reason.",
-      "lines": [26, 29],
-      "anchor": "Reply with:",
-      "anchorEnd": "both checker commands with their exit codes"
-    }
-  ],
-  "edges": [
-    {
-      "to": "ff-migrate",
-      "from": "ff-trig"
-    },
-    {
-      "to": "ff-run",
-      "from": "ff-migrate"
-    },
-    {
-      "to": "ff-group",
-      "from": "ff-run",
-      "label": "findings"
-    },
-    {
-      "to": "ff-clean",
-      "from": "ff-run",
-      "label": "exit 0"
-    },
-    {
-      "to": "ff-strict",
-      "from": "ff-clean"
-    },
-    {
-      "to": "ff-order",
-      "from": "ff-group"
-    },
-    {
-      "to": "ff-color",
-      "from": "ff-recipe",
-      "label": "Color by role"
-    },
-    {
-      "to": "ff-rerun",
-      "from": "ff-color"
-    },
-    {
-      "to": "ff-geometry",
-      "from": "ff-recipe",
-      "label": "Geometry by scale"
-    },
-    {
-      "to": "ff-rerun",
-      "from": "ff-geometry"
-    },
-    {
-      "to": "ff-remaining",
-      "from": "ff-recipe",
-      "label": "The remaining rules"
-    },
-    {
-      "to": "ff-rerun",
-      "from": "ff-remaining"
-    },
-    {
-      "to": "ff-repeat",
-      "from": "ff-rerun",
-      "label": "repairable findings"
-    },
-    {
-      "to": "ff-group",
-      "from": "ff-repeat",
-      "label": "return to step 3",
-      "back": true
-    },
-    {
-      "to": "ff-unresolved",
-      "from": "ff-rerun",
-      "label": "no token fits"
-    },
-    {
-      "to": "ff-reply",
-      "from": "ff-unresolved"
-    },
-    {
-      "to": "ff-strict",
-      "from": "ff-rerun",
-      "label": "errors clear"
-    },
-    {
-      "to": "ff-warnings",
-      "from": "ff-strict",
-      "label": "warnings"
-    },
-    {
-      "to": "ff-build",
-      "from": "ff-strict",
-      "label": "strict checks pass"
-    },
-    {
-      "to": "ff-warning-loop",
-      "from": "ff-warnings",
-      "label": "repair scope includes warnings"
-    },
-    {
-      "to": "ff-build",
-      "from": "ff-warnings",
-      "label": "user defers warnings"
-    },
-    {
-      "to": "ff-group",
-      "from": "ff-warning-loop",
-      "label": "use --strict",
-      "back": true
-    },
-    {
-      "to": "ff-reply",
-      "from": "ff-build"
-    },
-    {
-      "to": "ff-done",
-      "from": "ff-reply"
-    },
-    {
-      "to": "ff-recipe",
-      "from": "ff-order"
-    }
-  ]
-};