@motion-proto/live-tokens 0.82.0 → 0.83.0

package/src/editor/component-editor/scaffolding/types.ts

@@ -1,14 +1,19 @@
-/** A component's catalogue entry: what it is, what to use it for, what not
-    to use it for, and what any guidance-bearing prop's values mean. Exported
-    as `catalogue` from the runtime file's `<script module>` block — the
-    Svelte compiler drops a leading HTML comment before it reaches the
-    running editor, so this is the one form every reader (CLI, registry,
-    consumer) can read. */
+/** A component's catalogue entry: what it is, what to use it for, what to use
+    instead, the rules of use, and what any guidance-bearing prop's values
+    mean. Exported as `catalogue` from the runtime file's `<script module>`
+    block — the Svelte compiler drops a leading HTML comment before it
+    reaches the running editor, so this is the one form every reader (CLI,
+    registry, consumer) can read. */
 export type CatalogueEntry = {
   /** One sentence: what the component is. */
   description: string;
-  useFor: string;
-  notFor: string;
+  /** The condition that makes this component the right one. */
+  whenToUse: string;
+  /** Each row rules the component out. `use` is the component id
+      (`table`, never `Table`) that fits instead. */
+  whenNotToUse: Array<{ when: string; use?: string }>;
+  /** Rules of use, one sentence each. */
+  constraints?: string[];
   /** Keyed by prop name; the value explains that prop's values. */
   props?: Record<string, string>;
 };

package/src/editor/core/sketch/sketchLayer.ts

@@ -186,7 +186,7 @@ const PART_SPECS: readonly PartSpec[] = [
   { sel: '.image-lightbox-thumb', stem: 'imagelightbox-tile', positioned: true, clips: true },
   // A fixed full-viewport scrim behind the open modal; no border of its own.
   {
-    sel: '.image-lightbox-overlay', fill: 'var(--imagelightbox-overlay-surface)',
+    sel: '.image-lightbox-overlay', fill: 'var(--imagelightbox-scrim-surface)',
     stroke: 'transparent', positioned: true, unmasked: true,
   },
   // Close and the two nav chevrons all carry this class; each is fixed and

package/src/editor/core/themes/migrations/2026-09-20-imagelightbox-scrim.ts

@@ -0,0 +1,28 @@
+import type { Migration } from './index';
+
+/**
+ * One word for the layer that dims the page (2026-09-20).
+ *
+ * Dialog called it a scrim and read the `--scrim-*` scale; ImageLightbox called
+ * the same layer an overlay and mixed its own colour. The token scale settles
+ * the word, so the key reads `-scrim-surface`. The chrome tokens keep their own
+ * names: they paint the toolbar, not the layer behind it.
+ */
+const RENAMES: Record<string, string> = {
+  '--imagelightbox-overlay-surface': '--imagelightbox-scrim-surface',
+};
+
+export const componentMigration_2026_09_20_imagelightboxScrim: Migration = {
+  id: '2026-09-20-imagelightbox-scrim',
+  fromVersion: 35,
+  toVersion: 36,
+  appliesTo: 'component-config',
+  apply(rawVars, meta) {
+    if (meta.component !== 'imagelightbox') return { ...rawVars };
+    const out: Record<string, string> = {};
+    for (const [key, value] of Object.entries(rawVars)) {
+      out[RENAMES[key] ?? key] = value;
+    }
+    return out;
+  },
+};

package/src/editor/core/themes/migrations/index.ts

@@ -79,6 +79,7 @@ import { componentMigration_2026_09_13_selectedState } from './2026-09-13-select
 import { componentMigration_2026_09_13_hairline } from './2026-09-13-hairline';
 import { componentMigration_2026_09_13_indicator } from './2026-09-13-indicator';
 import { componentMigration_2026_09_13_sectiondividerSurface } from './2026-09-13-sectiondivider-surface';
+import { componentMigration_2026_09_20_imagelightboxScrim } from './2026-09-20-imagelightbox-scrim';
 import { componentMigration_2026_09_13_cornerbadgePrefix } from './2026-09-13-cornerbadge-prefix';
 import { componentMigration_2026_09_13_toggleLabel } from './2026-09-13-toggle-label';
 import { componentMigration_2026_09_13_collapsiblesectionOpen } from './2026-09-13-collapsiblesection-open';
@@ -132,6 +133,7 @@ export const MIGRATIONS: Migration[] = [
   componentMigration_2026_09_13_toggleLabel,
   componentMigration_2026_09_13_collapsiblesectionOpen,
   componentMigration_2026_09_13_badgeBrand,
+  componentMigration_2026_09_20_imagelightboxScrim,
 ];
 
 function countFor(kind: 'colors-and-type' | 'component-config'): number {

package/src/editor/docs/content/creating-components.md

@@ -46,6 +46,9 @@ component in the editor and confirm everything works.
 
 - A runtime component whose editable properties default to your theme tokens.
 - An editor entry that appears under **Custom** in the `/live-tokens/components` view.
+- A catalogue entry in the runtime file that says what the component is for and
+  what to use instead. `npx live-tokens components` prints it, and the skills
+  read it when they choose a component for a page.
 - The naming and wiring handled for you, so the component fits the system.
 
 Advanced authors who want to write a component by hand can read the naming and

package/src/editor/docs/content.generated.ts

@@ -3,7 +3,7 @@
 
 export const docContent: Record<string, string> = {
   "01-overview": "# Overview\n\nLiveTokens is a design system for building Svelte microsites quickly. You\nstyle your site by editing tokens and components in a live editor. When it looks right, you save the theme and ship it.\n\n## How it works\n\n- The editor runs in your dev server, on top of your real pages. You style in\n  context, not in a separate sandbox.\n- Every change updates a CSS variable, so the page repaints instantly. No\n  reload, no build step.\n- Saving writes a small JSON file into your project. Shipping bakes your chosen\n  theme into a plain CSS file that the build bundles.\n- The editor is dev-only. Production ships plain CSS variables and the\n  components you used, nothing else.\n\n## What you can edit\n\n- **Tokens**: the design-system primitives, colour palettes, type, spacing,\n  radius, shadow, and gradients, that apply across your whole site.\n- **Components**: the package ships about 25 editable components (Button,\n  IconButton, Card, Dialog, Table, and more). You style components by changing\n  the tokens assigned to each property.\n\n## Where to go next\n\n- **[Getting started](getting-started.md)**: scaffold a project and make your\n  first edit.\n- **[Editing tokens](editing-tokens.md)**: a tour of the editor.\n- **[Sketch mode](sketch-mode.md)**: redraw the page by hand.\n- **[Themes](themes-workflow.md)**: save, switch, and ship.\n- **[Creating components](creating-components.md)**: make your own components\n  editable.\n",
-  "creating-components": "# Creating components\n\nThe package ships about 25 editable components. When you need one it doesn't\nhave, you can make your own Svelte component editable, so anyone using the\neditor can re-point its colours, type, and spacing without touching code.\n\nThe simplest way is to ask Claude. The package bundles a Claude Code skill that\nknows the conventions, writes the files, and checks the result for you.\n\n## Install the skills\n\n```bash\nnpx @motion-proto/live-tokens setup-claude\n```\n\nThis copies the bundled skills into your project's `.claude/skills/`. Once\nthey're there, Claude Code picks them up automatically.\n\n## Browse the skill atlas\n\nThe package also ships a Skill Atlas component: a diagram of the reasoning\nbehind each bundled skill, with its `SKILL.md` and reference files alongside\nso you can see exactly which lines drive which step. Import it from\n`@motion-proto/live-tokens/skill-atlas` and mount it on a route of your own:\n\n```js\n'/skills': {\n  lazy: () => import('@motion-proto/live-tokens/skill-atlas'),\n},\n```\n\n## Ask for a component\n\nDescribe what you want in plain English. Phrases like these trigger the skill:\n\n- \"Add a Toggle component to live-tokens\"\n- \"Make this Svelte component editable in the live-tokens editor\"\n- \"Create a Stat component with a value and a label\"\n\nClaude asks any clarifying questions it needs (which variants, which states,\nwhich parts), then writes the component, registers it with the editor, and runs\nits verification checklist. When it finishes, open `/live-tokens/components` to see your new\ncomponent in the editor and confirm everything works.\n\n## What you get\n\n- A runtime component whose editable properties default to your theme tokens.\n- An editor entry that appears under **Custom** in the `/live-tokens/components` view.\n- The naming and wiring handled for you, so the component fits the system.\n\nAdvanced authors who want to write a component by hand can read the naming and\nstate-model conventions shipped in the package\n(`src/system/styles/CONVENTIONS.md` and the skill's own `SKILL.md`).\n",
+  "creating-components": "# Creating components\n\nThe package ships about 25 editable components. When you need one it doesn't\nhave, you can make your own Svelte component editable, so anyone using the\neditor can re-point its colours, type, and spacing without touching code.\n\nThe simplest way is to ask Claude. The package bundles a Claude Code skill that\nknows the conventions, writes the files, and checks the result for you.\n\n## Install the skills\n\n```bash\nnpx @motion-proto/live-tokens setup-claude\n```\n\nThis copies the bundled skills into your project's `.claude/skills/`. Once\nthey're there, Claude Code picks them up automatically.\n\n## Browse the skill atlas\n\nThe package also ships a Skill Atlas component: a diagram of the reasoning\nbehind each bundled skill, with its `SKILL.md` and reference files alongside\nso you can see exactly which lines drive which step. Import it from\n`@motion-proto/live-tokens/skill-atlas` and mount it on a route of your own:\n\n```js\n'/skills': {\n  lazy: () => import('@motion-proto/live-tokens/skill-atlas'),\n},\n```\n\n## Ask for a component\n\nDescribe what you want in plain English. Phrases like these trigger the skill:\n\n- \"Add a Toggle component to live-tokens\"\n- \"Make this Svelte component editable in the live-tokens editor\"\n- \"Create a Stat component with a value and a label\"\n\nClaude asks any clarifying questions it needs (which variants, which states,\nwhich parts), then writes the component, registers it with the editor, and runs\nits verification checklist. When it finishes, open `/live-tokens/components` to see your new\ncomponent in the editor and confirm everything works.\n\n## What you get\n\n- A runtime component whose editable properties default to your theme tokens.\n- An editor entry that appears under **Custom** in the `/live-tokens/components` view.\n- A catalogue entry in the runtime file that says what the component is for and\n  what to use instead. `npx live-tokens components` prints it, and the skills\n  read it when they choose a component for a page.\n- The naming and wiring handled for you, so the component fits the system.\n\nAdvanced authors who want to write a component by hand can read the naming and\nstate-model conventions shipped in the package\n(`src/system/styles/CONVENTIONS.md` and the skill's own `SKILL.md`).\n",
   "editing-tokens": "# Editing tokens\n\nA tour of the editor. The page behind it repaints on every change; saving\nwrites a theme file you can reload later.\n\nThe editor has four views:\n\n- **Tokens**: the design-system primitives (colour, type, spacing, and so on).\n  They apply everywhere your site uses them.\n- **Color Wheel**: the harmony wheel, the palette curves, and the story your colours\n  tell across a page.\n- **Components**: per-component editors. Re-Assign what tokens a component uses\n  without changing the underlying system.\n- **Sketchstyle**: an effect layer that redraws the page by hand. See\n  [Sketch mode](sketch-mode.md).\n\nThis page covers **Tokens**. For components, see\n[Creating components](creating-components.md).\n\n## Palettes\n\nMost colour work happens here. Each palette (Brand, Accent, Neutral, Canvas,\nSuccess, Warning, Info, Danger, and a few more) has:\n\n- **Base colour.** Pick a hex; the palette derives an 11-step ramp (100 to 950)\n  from it.\n- **Curves.** Three curves shape the ramp, in stack order: Hue, Saturation,\n  Lightness. Drag the handles to bias it warmer or cooler, more or less\n  saturated, darker or lighter. Hue drifts the ramp's temperature without\n  moving contrast, because OKLCH hue rotation is close to lightness-preserving.\n  It holds ±45 degrees; a bigger shift belongs on the base colour or the\n  harmony axis.\n- **Overrides.** Lock a single step to a hand-picked hex when the curve doesn't\n  land where you want.\n\nEditing a palette base ripples through every colour that depends on it, in real\ntime. Colours use OKLCH, so the ramp stays perceptually even across hues\nwithout muddy mid-tones.\n\n## Type\n\n- **Fonts.** Add sources from Google Fonts, Adobe (Typekit), a CSS URL, or an\n  inline `@font-face`. The font loads in the page as soon as you add it.\n- **Stacks.** Named font cascades you reference by token, such as a display\n  stack and a body stack.\n- **Sizes and weights.** A t-shirt scale (xs, sm, md, lg, xl, 2xl…) for size and\n  a numeric scale (100 to 900) for weight.\n\n## Spacing, radius, shadow\n\nNumeric scales with a slider per step.\n\n- **Spacing**: the padding, gap, and margin scale.\n- **Radius**: none through full.\n- **Shadow**: colour, offset, blur, spread, and opacity per step, with stacked\n  shadows supported.\n\nChange a step and every element using it repaints.\n\n## Washes and gradients\n\n- **Scrims** are translucent layers that dim what sits behind them, like the\n  one a dialog draws over the page. Set a colour and opacity per stop.\n- **Tints** are the opposite operation: they shade the surface they sit on\n  rather than dimming what is behind it, which is what a hover needs.\n- **Gradients** are reusable gradient tokens with a stop list and direction, for\n  hero panels and accent backgrounds.\n\n## Columns\n\nThe page-grid overlay. Set column count, gutter, and outer margin, and toggle\nthe visual guide with `Cmd/Ctrl+G`. Pages built on the column system reflow\nlive.\n\n## Saving\n\nThe editor saves to your browser continuously, so work survives a reload\nmid-edit. Writing a file is a separate step: the **Theme** panel at the foot of\nthe sidebar has **Save**, **Save As**, and **Load**, and each theme is one JSON\nfile under `src/live-tokens/data/themes/`.\n\nThe header gives you undo/redo (`Cmd/Ctrl+Z`, `Cmd/Ctrl+Shift+Z`). You can keep\nmany themes side by side; one is open at a time, and only **Adopt** publishes\none. See [Themes](themes-workflow.md) for the full lifecycle.\n",
   "getting-started": "# Getting started\n\nScaffold a live token site in a moments. You need Node 20 or later, a\npackage manager (npm, pnpm, or yarn), and a browser. Open claude code in your repo and start building.\n\n## Scaffold a new app\n\n```bash\nnpm create @motion-proto/live-tokens@latest my-app\ncd my-app\nnpm install\nnpm run dev\n```\n\nOpen the URL Vite prints (usually `http://localhost:5173`). You get a\none-page Svelte + Vite app that depends on the published package, with the\neditor wired up and the full component set ready to import.\n\n`npx @motion-proto/live-tokens create my-app` runs the same scaffold without\nthe initialiser package.\n\n### What the scaffold gives you\n\nEvery editable file lives under `src/` and is committed, so `npm install` and\nversion upgrades never touch your styles. The package code stays in\n`node_modules`.\n\n| Path | What it is |\n|------|------------|\n| `src/pages/Home.svelte` | The starter page. Replace it with your own content. |\n| `src/App.svelte` | Your routes. `<LiveTokensRouter>` adds dev-only routes under a reserved `/live-tokens/*` namespace: `/live-tokens/editor`, `/live-tokens/components`, and `/live-tokens/docs`. |\n| `src/system/styles/tokens.css` | Your base token vocabulary, hand-authored. |\n| `src/styles/site.css` | Themed page typography, yours to edit. |\n\n## Your first edit\n\n1. Run `npm run dev` and open the home page.\n2. Click **Open Token Editor**, or visit `/live-tokens/editor`. The editor opens beside\n   the page.\n3. Open **Palettes**, pick **Brand**, and change the base hex. The page\n   repaints as you type.\n4. In the **Theme** panel at the foot of the sidebar, choose **Save As**. Your\n   theme appears as JSON under `src/live-tokens/data/themes/`.\n5. Reload. The editor reopens on your theme, so the page returns as you left\n   it.\n\n## What you just changed\n\nEvery edit sets a CSS custom property on `:root`. Your components read those\nproperties through `var(--...)`. There is no token build step and no\npreprocessor rewriting your code: the page renders against plain CSS variables\nthe editor swaps live.\n\nTo ship, click **Adopt** in the Theme panel. That saves the open theme and bakes\nit into `src/live-tokens/data/tokens.generated.css`, which your build bundles\nalongside `tokens.css`. Adopt is the only action that changes what your site\nships, so try any theme you like first. The editor itself never reaches\nproduction.\n\nAlready have a Svelte 5 + Vite app? The\n[README](https://github.com/motionproto/live-tokens#readme) covers installing\ninto an existing project.\n\n## Where to go next\n\n- **[Editing tokens](editing-tokens.md)**: a tour of the editor.\n- **[Themes](themes-workflow.md)**: save, switch, and ship.\n- **[Creating components](creating-components.md)**: make your own component\n  editable.\n",
   "light-and-dark": "# Light and dark\n\nSome things on a page cannot be written as a token. A wordmark drawn in white\ndisappears on a pale theme. Ink that multiplies onto paper vanishes on a dark\none. A photograph behind a headline is dark no matter what the palette says.\n\nEach of those needs the same fact first: which way does the surface behind this\nthing lean? One attribute carries it.\n\n## The attribute\n\n`data-backdrop` is either `light` or `dark`, and it does two things at once: it\nselects, so a rule can key on it, and it sets `color-scheme`, so every\n`light-dark()` under it resolves the half that reads.\n\n```css\n.title {\n  color: light-dark(var(--color-black), var(--color-white));\n}\n```\n\nThat line is right on both sides of the theme, and it is right inside a dark\nsection on a pale page, because the nearest `color-scheme` wins.\n\n## Stating it\n\nPut it in the markup when the surface knows its own tone — a hero over a\nphotograph, a plate that stays pale in every theme:\n\n```svelte\n<div class=\"hero-panel\" data-backdrop=\"dark\">\n```\n\nA stated tone beats any measurement, and it inherits, so everything inside the\npanel resolves against it.\n\n## Measuring it\n\nWhere the tone is a property of the theme rather than of the markup, let it be\nmeasured:\n\n```svelte\n<script>\n  import { backdrop } from '@motion-proto/live-tokens/backdrop';\n</script>\n\n<section use:backdrop>\n```\n\nThe action reads whatever actually paints behind the element — the nearest\nancestor with an opaque fill, averaged across its gradient stops, falling back\nto the theme's `--page-bg` — and stamps the answer. It re-reads when the theme\nchanges, which the editor does by rewriting custom properties with no reload,\nso the stamp follows a live edit.\n\nThe page itself is stamped for you: the build bakes the production theme's\npolarity into `tokens.generated.css`, so the first paint is already right, and\n`syncDocumentBackdrop()` keeps `<html>` current as themes switch.\n\n```ts\nimport { syncDocumentBackdrop } from '@motion-proto/live-tokens/backdrop';\n\nsyncDocumentBackdrop();\n```\n\n## Reading it from JavaScript\n\nAnything that paints outside CSS — a canvas, a WebGL uniform, an `<img>` that\ncomes in two versions — asks the same question through the same module:\n\n```ts\nimport { isLightBackdrop, watchBackdrop, cssColorToHex } from '@motion-proto/live-tokens/backdrop';\n\nconst stop = watchBackdrop(logoEl, {\n  stamp: false,\n  onChange: (polarity) => (src = polarity === 'light' ? darkMark : lightMark),\n});\n```\n\n`isLightBackdrop(el)` answers once. `watchBackdrop` keeps answering and returns\na stop function. `cssColorToHex` resolves any CSS colour — including the\n`oklch()` a token holds — to a hex a non-CSS consumer can take.\n\n## What it does not do\n\nPolarity is a property of a surface, not of a component, so nothing is stamped\nfor you below `<html>`: a section that needs an answer either states one or asks\nfor one. And a measurement reads the paint at the moment it runs — an element\nthat scrolls from a pale section onto a dark one keeps the answer it was given.\nState the tone on each section instead.\n",

package/src/editor/skill-atlas/SkillAtlas.svelte

@@ -3,6 +3,7 @@
   import { navigate } from '../core/routing/router';
   import Button from '../../system/components/Button.svelte';
   import TabBar from '../../system/components/TabBar.svelte';
+  import SkillValue from './SkillValue.svelte';
   import SourcePane from './SourcePane.svelte';
   import TreeCanvas from './TreeCanvas.svelte';
   import { linkHash, linkTargets, resolveLink } from './atlasLink';
@@ -12,23 +13,35 @@
 
   // `#set-type` opens that skill and `#set-type/write-the-font-pairing/voice`
   // also selects that block, so a link can hand someone one step of one tree.
+  const VALUE_TAB = 'measured-value';
+  const firstSkill = Object.keys(skillTrees)[0];
+
+  function isValueHash(hash: string) {
+    return hash === `#${VALUE_TAB}`;
+  }
+
   const linked = resolveLink(window.location.hash, skillTrees);
-  let active = $state(linked?.skill ?? Object.keys(skillTrees)[0]);
+  let active = $state(
+    isValueHash(window.location.hash) ? VALUE_TAB : (linked?.skill ?? firstSkill),
+  );
   let selection: Selection | null = $state(linked?.target ?? null);
   /** Which of the skill's documents the source pane shows. */
   let doc: string = $state(SKILL_DOC);
 
-  let tree = $derived(skillTrees[active]);
-  let docs = $derived(skillDocs[active]);
+  // The value tab has no tree; the panes it hides keep reading a real skill.
+  let skill = $derived(active === VALUE_TAB ? firstSkill : active);
+  let tree = $derived(skillTrees[skill]);
+  let docs = $derived(skillDocs[skill]);
   let lines = $derived(docs[doc] ?? docs[SKILL_DOC]);
   let siblings = $derived(Object.keys(docs).filter((name) => name !== SKILL_DOC));
 
-  let tabs = $derived(
-    Object.entries(skillTrees).map(([id, t]) => ({
+  let tabs = $derived([
+    ...Object.entries(skillTrees).map(([id, t]) => ({
       id,
       label: `${t.title}\n${skillDocs[id][SKILL_DOC].length} lines`,
     })),
-  );
+    { id: VALUE_TAB, label: 'Measured value\n1 eval' },
+  ]);
 
   let docTabs = $derived(
     Object.keys(docs).map((name) => ({
@@ -52,6 +65,10 @@
   }
 
   function shareSelection() {
+    if (active === VALUE_TAB) {
+      history.replaceState(null, '', `${window.location.pathname}#${VALUE_TAB}`);
+      return;
+    }
     const target = linkTargets(tree).find((t) => t.key === selection?.key) ?? null;
     history.replaceState(null, '', `${window.location.pathname}${linkHash(active, target)}`);
   }
@@ -94,6 +111,12 @@
   }
 
   function openLink(hash: string) {
+    if (isValueHash(hash)) {
+      active = VALUE_TAB;
+      selection = null;
+      doc = SKILL_DOC;
+      return;
+    }
     const link = resolveLink(hash, skillTrees);
     if (!link) return;
     active = link.skill;
@@ -134,38 +157,42 @@
     <TabBar {tabs} value={active} onchange={changeTab} />
   </div>
 
-  <div class="split">
-    <section class="pane" aria-label="{tree.id} decision tree">
-      <div class="pane-head">
-        <span class="pane-title">{tree.id}</span>
-        <span class="pane-note">{tree.nodes.length} steps</span>
-      </div>
-      <div class="pane-body" bind:this={treePane}>
-        <h2 class="tagline">{tree.tagline}</h2>
-
-        <TreeCanvas {tree} selected={selection?.key ?? null} onselect={selectTarget} onopen={openDoc} />
-      </div>
-    </section>
-
-    <section class="pane pane-source" aria-label="{tree.id} source">
-      <div class="pane-head">
-        <span class="pane-title">{tree.id}/{doc}</span>
-        <span class="pane-note">{lines.length} lines</span>
-      </div>
-      <div class="doc-tabs">
-        <TabBar tabs={docTabs} value={doc} onchange={openDoc} />
-      </div>
-      <div class="pane-body" bind:this={sourcePane}>
-        <SourcePane
-          {lines}
-          {siblings}
-          highlight={doc === SKILL_DOC ? (selection?.lines ?? null) : null}
-          onpick={selectFromLine}
-          onopen={openDoc}
-        />
-      </div>
-    </section>
-  </div>
+  {#if active === VALUE_TAB}
+    <SkillValue />
+  {:else}
+    <div class="split">
+      <section class="pane" aria-label="{tree.id} decision tree">
+        <div class="pane-head">
+          <span class="pane-title">{tree.id}</span>
+          <span class="pane-note">{tree.nodes.length} steps</span>
+        </div>
+        <div class="pane-body" bind:this={treePane}>
+          <h2 class="tagline">{tree.tagline}</h2>
+
+          <TreeCanvas {tree} selected={selection?.key ?? null} onselect={selectTarget} onopen={openDoc} />
+        </div>
+      </section>
+
+      <section class="pane pane-source" aria-label="{tree.id} source">
+        <div class="pane-head">
+          <span class="pane-title">{tree.id}/{doc}</span>
+          <span class="pane-note">{lines.length} lines</span>
+        </div>
+        <div class="doc-tabs">
+          <TabBar tabs={docTabs} value={doc} onchange={openDoc} />
+        </div>
+        <div class="pane-body" bind:this={sourcePane}>
+          <SourcePane
+            {lines}
+            {siblings}
+            highlight={doc === SKILL_DOC ? (selection?.lines ?? null) : null}
+            onpick={selectFromLine}
+            onopen={openDoc}
+          />
+        </div>
+      </section>
+    </div>
+  {/if}
 </div>
 
 <style>

package/src/editor/skill-atlas/SkillValue.svelte

@@ -0,0 +1,202 @@
+<script lang="ts">
+  import Table from '../../system/components/Table.svelte';
+  import { pickComponentEval } from './evalResults';
+
+  const result = pickComponentEval;
+  const [withSkills, without] = result.arms;
+  const difference = (withSkills.score - without.score).toFixed(2);
+</script>
+
+<article class="skill-value" aria-labelledby="skill-value-title">
+  <div class="measure">
+    <p class="eyebrow">Measured value</p>
+    <h2 id="skill-value-title">The skills make an agent faster. The component entries make it right.</h2>
+    <p class="lead">
+      An eval asked an agent to choose a component for twelve requirements, three times with the
+      skills loaded and three times with none. Every run that finished chose all twelve correctly,
+      in both arms. The skills changed the cost of getting there.
+    </p>
+  </div>
+
+  <div class="results">
+    <Table>
+      <table>
+        <thead>
+          <tr>
+            <th scope="col"><span class="visually-hidden">Arm</span></th>
+            <th scope="col">Score</th>
+            <th scope="col">Requirements right</th>
+            <th scope="col">Ran the catalogue command</th>
+            <th scope="col">Turns</th>
+            <th scope="col">Seconds</th>
+          </tr>
+        </thead>
+        <tbody>
+          {#each result.arms as arm (arm.label)}
+            <tr>
+              <td class="arm">{arm.label}</td>
+              <td>{arm.score.toFixed(2)}</td>
+              <td>{arm.rowsRight}</td>
+              <td>{arm.ranCatalogue}</td>
+              <td>{arm.turns}</td>
+              <td>{arm.seconds}</td>
+            </tr>
+          {/each}
+        </tbody>
+      </table>
+    </Table>
+  </div>
+
+  <div class="measure">
+    <h3>Accuracy comes from the component</h3>
+    <p>
+      Each component file carries its own entry: <code>whenToUse</code> states the condition that
+      makes it right, and <code>whenNotToUse</code> lists the conditions that rule it out, each with
+      the component to use in its place. An agent with no skills opened the component files, found
+      those entries, and made the same twelve choices, including the two requirements nothing
+      shipped fits and the destructive action that belongs in a Dialog.
+    </p>
+
+    <h3>Efficiency comes from the skill</h3>
+    <p>
+      The pick-component skill sends the agent to one command,
+      <code>npx live-tokens components --json</code>, which returns every entry at once. With the
+      skills the agent answered in {withSkills.turns} turns and under a minute. Without them it
+      never found the command, read files one at a time for {without.turns} turns, and one of its
+      three runs reached the five minute limit before it answered.
+    </p>
+
+    <h3>Method</h3>
+    <ul>
+      <li>Case <code>{result.id}</code>, run on {result.date}.</li>
+      <li>Twelve requirements: ten with one right component, two that nothing shipped fits.</li>
+      <li>Three runs per arm. The runner adds the arm without skills on its own.</li>
+      <li>
+        Each requirement has its own pattern grader, so a failure names its row. One more grader
+        checks that the agent ran the catalogue command.
+      </li>
+      <li>
+        The score is the share of graders that pass. The difference of {difference} comes from one
+        timeout and from the catalogue-command grader. No finished run chose a wrong component.
+      </li>
+    </ul>
+
+    <h3>Limits</h3>
+    <p>
+      Three runs per arm is a small sample, and one timeout moves the score a long way. The twelve
+      requirements each have a clear answer in the entries. A harder case, where two components
+      both fit, has not been measured.
+    </p>
+  </div>
+</article>
+
+<style>
+  /* The atlas locks to the viewport on desktop, so the report scrolls itself. */
+  .skill-value {
+    flex: 1 1 auto;
+    min-height: 0;
+    overflow-y: auto;
+    padding-bottom: var(--space-48);
+    color: var(--text-secondary);
+  }
+
+  .measure {
+    max-width: 70ch;
+  }
+
+  .results {
+    max-width: 110ch;
+    margin: var(--space-32) 0 var(--space-40);
+  }
+
+  .eyebrow {
+    margin: 0 0 var(--space-8);
+    font-family: var(--eyebrow-font-family);
+    font-size: var(--eyebrow-font-size);
+    font-weight: var(--eyebrow-font-weight);
+    line-height: var(--eyebrow-line-height);
+    letter-spacing: var(--eyebrow-letter-spacing);
+    text-transform: var(--eyebrow-text-transform);
+    color: var(--text-tertiary);
+  }
+
+  h2 {
+    margin: 0 0 var(--space-24);
+    font-family: var(--heading-lg-font-family);
+    font-size: var(--heading-lg-font-size);
+    font-weight: var(--heading-lg-font-weight);
+    line-height: var(--heading-lg-line-height);
+    letter-spacing: var(--heading-lg-letter-spacing);
+    color: var(--text-primary);
+  }
+
+  h3 {
+    margin: var(--space-40) 0 var(--space-12);
+    font-family: var(--heading-sm-font-family);
+    font-size: var(--heading-sm-font-size);
+    font-weight: var(--heading-sm-font-weight);
+    line-height: var(--heading-sm-line-height);
+    letter-spacing: var(--heading-sm-letter-spacing);
+    color: var(--text-primary);
+  }
+
+  .measure > h3:first-child {
+    margin-top: 0;
+  }
+
+  p,
+  li {
+    font-family: var(--body-md-font-family);
+    font-size: var(--body-md-font-size);
+    font-weight: var(--body-md-font-weight);
+    line-height: var(--body-md-line-height);
+    letter-spacing: var(--body-md-letter-spacing);
+  }
+
+  p {
+    margin: 0 0 var(--space-16);
+  }
+
+  .lead {
+    margin-bottom: 0;
+    color: var(--text-primary);
+  }
+
+  ul {
+    margin: 0;
+    padding-left: var(--space-24);
+  }
+
+  li + li {
+    margin-top: var(--space-8);
+  }
+
+  code {
+    font-family: var(--code-font-family);
+    font-size: var(--code-font-size);
+    font-weight: var(--code-font-weight);
+    line-height: var(--code-line-height);
+    letter-spacing: var(--code-letter-spacing);
+    background: var(--tint-low);
+    padding-inline: var(--space-4);
+    border-radius: var(--radius-sm);
+    /* The code face joins `--` into one dash, and a line may break between the
+       two hyphens. Either misprints a CLI flag. */
+    font-variant-ligatures: none;
+    white-space: nowrap;
+  }
+
+  .results td.arm {
+    color: var(--text-primary);
+    white-space: nowrap;
+  }
+
+  .visually-hidden {
+    position: absolute;
+    width: 1px;
+    height: 1px;
+    overflow: hidden;
+    clip-path: inset(50%);
+    white-space: nowrap;
+  }
+</style>

package/src/editor/skill-atlas/evalResults.ts

@@ -0,0 +1,46 @@
+/** One arm of an eval: the same case run with the skills loaded, or without them. */
+export interface EvalArm {
+  label: string;
+  score: number;
+  rowsRight: string;
+  ranCatalogue: string;
+  turns: string;
+  seconds: string;
+}
+
+export interface EvalResult {
+  id: string;
+  date: string;
+  packageVersion: string;
+  runsPerArm: number;
+  requirements: number;
+  arms: [withSkills: EvalArm, without: EvalArm];
+}
+
+// Recorded by hand from `npm run eval` in the live-tokens repository. The
+// evals do not ship, so the page cannot read a result file at runtime.
+export const pickComponentEval: EvalResult = {
+  id: 'outcome-pick-component',
+  date: '2026-09-20',
+  packageVersion: '0.82.0, plus the unreleased catalogue entry',
+  runsPerArm: 3,
+  requirements: 12,
+  arms: [
+    {
+      label: 'With the skills',
+      score: 1,
+      rowsRight: '12 of 12 in all 3 runs',
+      ranCatalogue: '3 of 3 runs',
+      turns: '9 to 10',
+      seconds: '42 to 58',
+    },
+    {
+      label: 'Without',
+      score: 0.62,
+      rowsRight: '12 of 12 in the 2 runs that finished',
+      ranCatalogue: '0 of 3 runs',
+      turns: '15 to 16',
+      seconds: '70 to 72, and one run timed out at 300',
+    },
+  ],
+};