@motion-proto/live-tokens 0.74.0 → 0.76.0

package/src/editor/skill-atlas/trees/pick-component.ts

@@ -0,0 +1,300 @@
+import type { SkillTree } from '../types';
+
+export const pickComponent: SkillTree = {
+  "id": "live-tokens-pick-component",
+  "digest": "sha256:5e4ca458665c95fd",
+  "title": "pick-component",
+  "tagline": "Select a component from the catalogue",
+  "nodes": [
+    {
+      "id": "pk-trig",
+      "row": 0,
+      "kind": "trigger",
+      "title": "Check the catalogue",
+      "desc": "Recommends the shipped component that fits a UX need. The catalogue lists every registered component, shipped and custom, with its usage.",
+      "lines": [3, 3],
+      "anchor": "description: Recommend which shipped @motion-proto/live-toke"
+    },
+    {
+      "id": "pk-fam",
+      "row": 1,
+      "kind": "decide",
+      "title": "Component purpose",
+      "desc": "Each family names its candidates and helps select one.",
+      "lines": [8, 8],
+      "anchor": "When more than one shipped component could fit, find the fam",
+      "chips": [
+        {
+          "label": "Action family",
+          "lines": [14, 14],
+          "anchor": "## Action family"
+        },
+        {
+          "label": "Single-selection family",
+          "lines": [20, 20],
+          "anchor": "## Single-selection family"
+        },
+        {
+          "label": "Text entry",
+          "lines": [34, 34],
+          "anchor": "## Text entry"
+        },
+        {
+          "label": "On and off",
+          "lines": [43, 43],
+          "anchor": "## On and off"
+        },
+        {
+          "label": "Container family",
+          "lines": [55, 55],
+          "anchor": "## Container family"
+        },
+        {
+          "label": "Messaging family",
+          "lines": [68, 68],
+          "anchor": "## Messaging family"
+        },
+        {
+          "label": "Display family",
+          "lines": [82, 82],
+          "anchor": "## Display family"
+        }
+      ]
+    },
+    {
+      "id": "pk-act",
+      "row": 2,
+      "kind": "chipset",
+      "title": "Action family",
+      "desc": "Does the action need a word, a glyph, or a confirm and cancel pair.",
+      "lines": [14, 18],
+      "anchor": "## Action family",
+      "anchorEnd": "The pair that confirms or cancels an inline edit: `InlineEdi"
+    },
+    {
+      "id": "pk-sel",
+      "row": 2,
+      "kind": "chipset",
+      "title": "Single-selection family",
+      "desc": "How many options there are and what does the selection change.",
+      "lines": [20, 32],
+      "anchor": "## Single-selection family",
+      "anchorEnd": "The URL changes: `SideNavigation`. Sections inside one page:"
+    },
+    {
+      "id": "pk-text",
+      "row": 2,
+      "kind": "chipset",
+      "title": "Text entry",
+      "desc": "If the options are known, use a list or select. Anything else is an input field.",
+      "lines": [34, 41],
+      "anchor": "## Text entry",
+      "anchorEnd": "A number where the position on a track carries the meaning ("
+    },
+    {
+      "id": "pk-bin",
+      "row": 2,
+      "kind": "chipset",
+      "title": "On and off",
+      "desc": "If two states have names of their own use segmented control or radio buttons.",
+      "lines": [43, 53],
+      "anchor": "## On and off",
+      "anchorEnd": "When the two states share the feature's one name, use `Toggl"
+    },
+    {
+      "id": "pk-con",
+      "row": 2,
+      "kind": "chipset",
+      "title": "Container family",
+      "desc": "Is the block: an item, a section, collapsed content, or a decision.",
+      "lines": [55, 66],
+      "anchor": "## Container family",
+      "anchorEnd": "A set of items is one `Card` per item. A routine form goes i"
+    },
+    {
+      "id": "pk-msg",
+      "row": 2,
+      "kind": "chipset",
+      "title": "Messaging family",
+      "desc": "What is the message about? What triggers it? Is it dismissable?",
+      "lines": [68, 80],
+      "anchor": "## Messaging family",
+      "anchorEnd": "`Badge` and `CornerBadge` differ in position only."
+    },
+    {
+      "id": "pk-disp",
+      "row": 2,
+      "kind": "chipset",
+      "title": "Display family",
+      "desc": "Does the user view it, or interact with it?",
+      "lines": [82, 90],
+      "anchor": "## Display family",
+      "anchorEnd": "A titled break between the sections of one page: `SectionDiv"
+    },
+    {
+      "id": "pk-fits",
+      "row": 3,
+      "kind": "decide",
+      "title": "Is there a match in the catalogue",
+      "desc": "Use a component from the catalogue if one fits, otherwise build a new one.",
+      "lines": [92, 96],
+      "anchor": "## Nothing fits",
+      "anchorEnd": "`npx live-tokens components <id>` prints one component's usa",
+      "chips": [
+        {
+          "label": "shipped component",
+          "lines": [12, 12],
+          "anchor": "Before choosing, run `npx live-tokens components`. The list "
+        },
+        {
+          "label": "custom component",
+          "lines": [12, 12],
+          "anchor": "Before choosing, run `npx live-tokens components`. The list "
+        },
+        {
+          "label": "native element",
+          "lines": [94, 94],
+          "anchor": "A native element with no chrome of its own needs no componen"
+        },
+        {
+          "label": "nothing in the catalogue fits",
+          "lines": [94, 94],
+          "anchor": "A native element with no chrome of its own needs no componen"
+        }
+      ]
+    },
+    {
+      "id": "pk-inspect",
+      "row": 4,
+      "kind": "cli",
+      "title": "Check the component",
+      "desc": "See the component's props and usage before placing it.",
+      "lines": [96, 96],
+      "anchor": "`npx live-tokens components <id>` prints one component's usa"
+    },
+    {
+      "id": "pk-native",
+      "row": 4,
+      "kind": "step",
+      "title": "Use a native element",
+      "desc": "An element with no chrome of its own needs no component.",
+      "lines": [94, 94],
+      "anchor": "A native element with no chrome of its own needs no componen"
+    },
+    {
+      "id": "pk-make",
+      "row": 4,
+      "kind": "hand",
+      "title": "Create a component",
+      "desc": "A piece with chrome that nothing in the catalogue fits goes to live-tokens-create-component.",
+      "lines": [94, 94],
+      "anchor": "A native element with no chrome of its own needs no componen"
+    },
+    {
+      "id": "pk-page",
+      "row": 5,
+      "kind": "hand",
+      "title": "Return the selected component",
+      "desc": "The named component returns to live-tokens-create-page, which owns size, emphasis, and placement.",
+      "lines": [94, 94],
+      "anchor": "A native element with no chrome of its own needs no componen"
+    }
+  ],
+  "edges": [
+    {
+      "to": "pk-fam",
+      "from": "pk-trig"
+    },
+    {
+      "to": "pk-act",
+      "from": "pk-fam",
+      "label": "Action family"
+    },
+    {
+      "to": "pk-sel",
+      "from": "pk-fam",
+      "label": "Single-selection family"
+    },
+    {
+      "to": "pk-text",
+      "from": "pk-fam",
+      "label": "Text entry"
+    },
+    {
+      "to": "pk-bin",
+      "from": "pk-fam",
+      "label": "On and off"
+    },
+    {
+      "to": "pk-con",
+      "from": "pk-fam",
+      "label": "Container family"
+    },
+    {
+      "to": "pk-msg",
+      "from": "pk-fam",
+      "label": "Messaging family"
+    },
+    {
+      "to": "pk-disp",
+      "from": "pk-fam",
+      "label": "Display family"
+    },
+    {
+      "to": "pk-inspect",
+      "from": "pk-fits",
+      "label": "shipped component"
+    },
+    {
+      "to": "pk-inspect",
+      "from": "pk-fits",
+      "label": "custom component"
+    },
+    {
+      "to": "pk-native",
+      "from": "pk-fits",
+      "label": "native element"
+    },
+    {
+      "to": "pk-make",
+      "from": "pk-fits",
+      "label": "nothing in the catalogue fits"
+    },
+    {
+      "to": "pk-page",
+      "from": "pk-inspect"
+    },
+    {
+      "to": "pk-page",
+      "from": "pk-native"
+    },
+    {
+      "to": "pk-fits",
+      "from": "pk-act"
+    },
+    {
+      "to": "pk-fits",
+      "from": "pk-sel"
+    },
+    {
+      "to": "pk-fits",
+      "from": "pk-text"
+    },
+    {
+      "to": "pk-fits",
+      "from": "pk-bin"
+    },
+    {
+      "to": "pk-fits",
+      "from": "pk-con"
+    },
+    {
+      "to": "pk-fits",
+      "from": "pk-msg"
+    },
+    {
+      "to": "pk-fits",
+      "from": "pk-disp"
+    }
+  ]
+};

package/src/editor/skill-atlas/trees/set-colors.ts

@@ -0,0 +1,148 @@
+import type { SkillTree } from '../types';
+
+export const setColors: SkillTree = {
+  "id": "live-tokens-set-colors",
+  "digest": "sha256:d83d60fcbfa2f662",
+  "title": "set-colors",
+  "tagline": "Set the Color Palettes",
+  "nodes": [
+    {
+      "id": "sc-trig",
+      "row": 0,
+      "kind": "trigger",
+      "title": "Set or refine a palette",
+      "desc": "Selects colors for a live tokens theme. Each palette is derived from an OKLCH base color, which is assigned a position based on luminance, and the rest of the family is generated around it. ",
+      "lines": [3, 3],
+      "anchor": "description: Set a live-tokens theme's color: ten OKLCH base"
+    },
+    {
+      "id": "sc-anchor",
+      "row": 1,
+      "kind": "ref",
+      "title": "Look up the color anchor",
+      "desc": "The anchor keyword from create theme guides color selection.",
+      "lines": [19, 19],
+      "anchor": "Read the color intent and any anchor live-tokens-create-them",
+      "reference": "references/color-anchors.md"
+    },
+    {
+      "id": "sc-input",
+      "row": 2,
+      "kind": "step",
+      "title": "Write the base colors",
+      "desc": "Ten base colors and a scheme in one file, chosen by six rules. Keep the file for refinements.",
+      "lines": [20, 20],
+      "anchor": "Translate the intent into ten base colors with the framework",
+      "chips": [
+        {
+          "label": "Chroma budget",
+          "lines": [56, 68],
+          "anchor": "## Chroma budget",
+          "anchorEnd": "A good theme reads as 3 or 4 hue families on screen, never 1"
+        },
+        {
+          "label": "Role ranges",
+          "lines": [70, 96],
+          "anchor": "## Per-role ranges",
+          "anchorEnd": "Blue tints cap very low at high L (H 264 at L 0.95 barely re"
+        },
+        {
+          "label": "Mood dials",
+          "lines": [98, 104],
+          "anchor": "## Mood dials",
+          "anchorEnd": "Avoid mid-lightness yellow-green (H 100 to 120 at L 0.5 to 0"
+        },
+        {
+          "label": "Gamut guardrails",
+          "lines": [106, 113],
+          "anchor": "## Gamut guardrails",
+          "anchorEnd": "Peak chroma anchors: red H20 C 0.25 at L 0.63; orange H60 C "
+        },
+        {
+          "label": "Harmony",
+          "lines": [115, 121],
+          "anchor": "## Harmony",
+          "anchorEnd": "Drama or maximum contrast: complementary, triadic, or tetrad"
+        },
+        {
+          "label": "Canvas sky and shadows",
+          "lines": [123, 127],
+          "anchor": "## Canvas sky and shadows",
+          "anchorEnd": "Shadow opacity derives from Canvas lightness and re-derives "
+        }
+      ]
+    },
+    {
+      "id": "sc-cli",
+      "row": 3,
+      "kind": "cli",
+      "title": "Set colors",
+      "desc": "The engine derives the theme's color from the ten base colors and checks every text pair for WCAG AA contrast.",
+      "lines": [21, 21],
+      "anchor": "Run `npx live-tokens set-colors scratch/<slug>-base-colors.j"
+    },
+    {
+      "id": "sc-fail",
+      "row": 4,
+      "kind": "gate",
+      "title": "Correct the base colors",
+      "desc": "A text pair below WCAG AA fails the run. Exit 1 names the base color to change and how: raise its lightness or reduce its chroma.",
+      "lines": [22, 22],
+      "anchor": "Read the report. Exit 0 passes, and auto-corrected values co"
+    },
+    {
+      "id": "sc-reply",
+      "row": 5,
+      "kind": "step",
+      "title": "Reply with the result",
+      "desc": "Report the anchor, the scheme, the hue families, the Canvas base color, and any auto-correction.",
+      "lines": [22, 23],
+      "anchor": "Read the report. Exit 0 passes, and auto-corrected values co",
+      "anchorEnd": "Reply with the anchor if any, the scheme, the hue families, "
+    },
+    {
+      "id": "sc-verify",
+      "row": 6,
+      "kind": "done",
+      "title": "Verify the color",
+      "desc": "The CLI passes, the app shows the new palette, and the theme reads as edited.",
+      "lines": [143, 149],
+      "anchor": "## Verify",
+      "anchorEnd": "To revert, re-run with the previous base color file, or load"
+    }
+  ],
+  "edges": [
+    {
+      "to": "sc-anchor",
+      "from": "sc-trig"
+    },
+    {
+      "to": "sc-fail",
+      "from": "sc-cli",
+      "label": "exit 1"
+    },
+    {
+      "to": "sc-cli",
+      "from": "sc-fail",
+      "label": "rerun",
+      "back": true
+    },
+    {
+      "to": "sc-input",
+      "from": "sc-anchor"
+    },
+    {
+      "to": "sc-cli",
+      "from": "sc-input"
+    },
+    {
+      "to": "sc-reply",
+      "from": "sc-cli",
+      "label": "exit 0"
+    },
+    {
+      "to": "sc-verify",
+      "from": "sc-reply"
+    }
+  ]
+};

package/src/editor/skill-atlas/trees/set-geometry.ts

@@ -0,0 +1,136 @@
+import type { SkillTree } from '../types';
+
+export const setGeometry: SkillTree = {
+  "id": "live-tokens-set-geometry",
+  "digest": "sha256:fbe78a12bbd4791a",
+  "title": "set-geometry",
+  "tagline": "Set Spacing, Corner Radius, Line Weight",
+  "nodes": [
+    {
+      "id": "sg-trig",
+      "row": 0,
+      "kind": "trigger",
+      "title": "Set shape and spacing",
+      "desc": "Sets a theme's shape and spacing: corner radius, padding, gap, and border width, each moved along its scale per component.",
+      "lines": [3, 3],
+      "anchor": "description: Set a live-tokens theme's geometry: corner radi"
+    },
+    {
+      "id": "sg-anchor",
+      "row": 1,
+      "kind": "ref",
+      "title": "Read the geometry anchor",
+      "desc": "An anchor's entry overrides the idiom table.",
+      "lines": [14, 14],
+      "anchor": "Read the geometry intent and the anchor, when live-tokens-cr",
+      "reference": "references/geometry-anchors.md"
+    },
+    {
+      "id": "sg-input",
+      "row": 2,
+      "kind": "step",
+      "title": "Write the geometry",
+      "desc": "One file of changes, each global or targeted, setting a step or shifting by steps. Each idiom maps to a set of them, and every scale has a floor.",
+      "lines": [15, 15],
+      "anchor": "Write the ops file to `scratch/geometry-ops.json`.",
+      "chips": [
+        {
+          "label": "Idioms",
+          "lines": [44, 69],
+          "anchor": "## Idioms",
+          "anchorEnd": "Magnitude follows the qualifier. \"Slightly\" or \"a bit\" is 1 "
+        },
+        {
+          "label": "Compact containers before controls",
+          "lines": [71, 94],
+          "anchor": "## Compact containers before controls",
+          "anchorEnd": "] }"
+        },
+        {
+          "label": "Scales",
+          "lines": [97, 101],
+          "anchor": "## Scales",
+          "anchorEnd": "An alias off the subset spends its first step reaching the s"
+        },
+        {
+          "label": "Floors",
+          "lines": [103, 109],
+          "anchor": "## Floors",
+          "anchorEnd": "The floor guards `-padding` only. A 2px gap between an icon "
+        }
+      ]
+    },
+    {
+      "id": "sg-cli",
+      "row": 3,
+      "kind": "cli",
+      "title": "Run set-geometry",
+      "desc": "The command writes a buffer for every component the ops change.",
+      "lines": [16, 16],
+      "anchor": "Run `npx live-tokens set-geometry scratch/geometry-ops.json`"
+    },
+    {
+      "id": "sg-fail",
+      "row": 4,
+      "kind": "gate",
+      "title": "Correct the geometry",
+      "desc": "Exit 1 names the op or the input to fix.",
+      "lines": [18, 18],
+      "anchor": "When the CLI exits 1, fix the op or the input the message na"
+    },
+    {
+      "id": "sg-reply",
+      "row": 5,
+      "kind": "step",
+      "title": "Reply with the result",
+      "desc": "Report every alias that moved and any skip worth naming.",
+      "lines": [17, 19],
+      "anchor": "Read the report. It lists every changed alias, old and new, ",
+      "anchorEnd": "Reply with every alias that moved and any skip worth naming."
+    },
+    {
+      "id": "sg-verify",
+      "row": 6,
+      "kind": "done",
+      "title": "Verify the geometry",
+      "desc": "The app shows the new shape and buttons still read as buttons.",
+      "lines": [115, 121],
+      "anchor": "## Verify",
+      "anchorEnd": "To revert, run the inverse ops, or load the open theme to di"
+    }
+  ],
+  "edges": [
+    {
+      "to": "sg-anchor",
+      "from": "sg-trig"
+    },
+    {
+      "to": "sg-fail",
+      "from": "sg-cli",
+      "label": "exit 1"
+    },
+    {
+      "to": "sg-cli",
+      "from": "sg-fail",
+      "label": "rerun",
+      "back": true
+    },
+    {
+      "to": "sg-input",
+      "from": "sg-anchor"
+    },
+    {
+      "to": "sg-cli",
+      "from": "sg-input"
+    },
+    {
+      "to": "sg-reply",
+      "from": "sg-cli",
+      "label": "exit 0"
+    },
+    {
+      "to": "sg-verify",
+      "from": "sg-reply"
+    }
+  ]
+};