@repobit/dex-system-design 0.25.12 → 0.26.0

package/src/tokens/token-map.stories.js

@@ -0,0 +1,257 @@
+import { html } from 'lit';
+import { copyToken, docsPage, refSection, resolve } from './story-chrome.js';
+import { DOCS, analyse } from './token-map.js';
+import { BORDERS, SURFACES } from './token-purposes.js';
+/* The registry and the generated stylesheet themselves, not copies of them --
+   the same rule Foundations/Spacing/Rhythm follows. */
+import registry from '../../scripts/token-tiers.json';
+import tokensCss from './tokens.css?raw';
+
+export default {
+  title: 'Foundations/Token Map',
+  tags : ['autodocs']
+};
+
+/* Every file that might read a token, as raw text. Lazy, so the source only
+   loads when this page is opened. The blog's own token copies are left out:
+   they declare tokens, and a declaration is not a read. */
+const SOURCES = import.meta.glob([
+  '../components/**/*.js',
+  '../blog/**/*.{js,css}',
+  '!../blog/tokens.*',
+  '!../blog/tokens/**',
+  '!../blog/src/tokens/**',
+  './*.stories.js',
+  './story-chrome.js'
+], { query: '?raw', import: 'default' });
+
+/* Foundations/Surfaces renders its role tables from token-purposes.js, so the
+   tokens in those two tables are shown by the docs. The rest of that module is
+   description text for Figma, and naming a token in a description is not
+   reading it -- counting the whole module would hide --touch-target-spacing
+   and --content-width-max, which nothing reads. */
+const SURFACES_PAGE = [...SURFACES, ...BORDERS].map(r => `'${r.token}'`)
+  .join(' ');
+
+const ownerOf = path => {
+  if (path.endsWith('.stories.js') || path.startsWith('./')) return DOCS;
+  if (path.startsWith('../blog/')) return 'blog';
+  return path.split('/')[2] ?? path;
+};
+
+async function load() {
+  const entries = await Promise.all(Object.entries(SOURCES).map(async ([path, read]) => [path, await read()]));
+  const sources = { ...Object.fromEntries(entries), './surfaces-role-tables': SURFACES_PAGE };
+  return analyse({ cssText: tokensCss, registry, sources, ownerOf });
+}
+
+/* ------------------------------------------------------------------ cells - */
+
+const isColour = value => /^(#|rgb|hsl|color-mix)/.test(value);
+
+const swatch = token => html`<span
+  style="display:inline-block;width:var(--dimension-16);height:var(--dimension-16);vertical-align:middle;margin-right:var(--spacing-6);border-radius:var(--radius-sm);border:var(--border-width-1) solid var(--color-neutral-200);background:var(${token})"></span>`;
+
+const chainCell = row => html`<span class="mono">${row.chain.hops.slice(1).map(h => html` → ${h}`)}${row.chain.compound
+  ? html` <span class="muted">(combines several)</span>`
+  : ''}</span>`;
+
+const valueCell = row => {
+  const value = resolve(row.name);
+  return html`<span class="num">${isColour(value) ? swatch(row.name) : ''}${value}</span>`;
+};
+
+const readersCell = row => {
+  const owners = [...row.sourceReaders].sort();
+  const tokens = row.tokenReaders.size;
+  const reach = [...row.reachable].sort();
+  if (!owners.length && !tokens) {
+    return reach.length
+      ? html`<span class="muted">reachable via ${reach.join(', ')}</span>`
+      : html`<span class="unused">nothing</span>`;
+  }
+  return html`${owners.join(', ')}${tokens ? html`${owners.length ? ' · ' : ''}<span class="muted">${tokens} token${tokens === 1 ? '' : 's'}</span>` : ''}`;
+};
+
+const tokenList = rows => html`
+  <div class="table-scroll">
+    <table>
+      <caption>Tokens</caption>
+      <thead><tr><th scope="col">Token</th><th scope="col">Tier</th><th scope="col">Family</th><th scope="col">Value</th></tr></thead>
+      <tbody>${rows.map(r => html`<tr>
+        <td>${copyToken(r.name)}</td><td>${r.tier}</td>
+        <td class="mono">${r.family?.prefix}${r.family?.owner ? html` <span class="muted">(${r.family.owner})</span>` : ''}</td>
+        <td>${valueCell(r)}</td></tr>`)}</tbody>
+    </table>
+  </div>`;
+
+const collapsed = (summary, body) => html`<details class="usage"><summary>${summary}</summary>${body}</details>`;
+
+/* ------------------------------------------------------------------- page - */
+
+const GRAMMAR = [
+  ['primitive', '--{category}-{family}-{step}', '--color-blue-600, --spacing-16, --radius-lg'],
+  ['semantic', '--{category}-{role}-{variant}', '--color-text-primary, --status-error-fill, --typography-heading-h2-fontSize'],
+  ['component', '--{component}-{variant}-{property}-{state}', '--button-primary-background-hover']
+];
+
+export const TokenMap = (_args, { loaded: { map } }) => {
+  const { rows, flags } = map;
+  const tiers = Object.keys(registry.tiers);
+  const count = tier => rows.filter(r => r.tier === tier).length;
+  const STATES = ['default', 'hover', 'active', 'disabled'];
+  const states = STATES.map(s => [s, rows.filter(r => r.name.endsWith(`-${s}`)).length]);
+  /* both claims in the naming paragraph are computed, so neither can go stale */
+  /* default is left out: it is also a size and a variant name here
+     (--form-label-default-* sits beside -small and -large), so a default
+     before the property is not evidence of a state in the wrong place */
+  const midState = rows.filter(r => r.name.slice(2).split('-')
+    .slice(0, -1)
+    .some(seg => seg !== 'default' && STATES.includes(seg)) && r.tier === 'component');
+  const otherStates = rows.filter(r => /-(hovered|pressed|focused|selected)(-|$)/.test(r.name));
+  const judged = registry.families.filter(f => f.basis === 'judgement');
+
+  return docsPage({
+    title: 'Token map',
+    lede : `Every design token: which tier it is, what it resolves through, and who reads it. Generated
+            when this page opens, from tokens.css, scripts/token-tiers.json and the source of every
+            component, so nothing on it is transcribed and nothing on it can go stale.`,
+    note: html`<b>The findings are a report, not a gate.</b> Each kind below has been a decision in
+      this package at least once rather than a defect -- spacing tokens with no role above them, two
+      surfaces that share a grey on purpose -- and this page cannot tell which. It lists them so they
+      are seen. The one gate here is <code>check:token-tiers</code>, which only checks that every
+      token has a declared tier.<br />
+      <b>"Read" means named in source.</b> <code>var(--x)</code> counts, and so does a name held as
+      data (<code>token-scales.js</code> maps <code>color="muted"</code> to
+      <code>'--color-text-muted'</code>). A step a scale helper could build at runtime, like
+      <code>bd-h paddingBottom="16"</code>, is shown as <i>reachable</i>, not read. Stories count
+      separately: a token read only by documentation is not read by the product.`,
+    children: html`
+      ${refSection({
+        name    : 'Naming',
+        meta    : 'the shape each tier takes',
+        children: html`
+          <div class="table-scroll"><table>
+            <caption>Naming shape per tier</caption>
+            <thead><tr><th scope="col">Tier</th><th scope="col">Shape</th><th scope="col">Examples</th></tr></thead>
+            <tbody>${GRAMMAR.map(([t, shape, ex]) => html`<tr><td>${t}</td><td class="mono">${shape}</td><td class="mono">${ex}</td></tr>`)}</tbody>
+          </table></div>
+          <p style="max-width:70ch">
+            Segments are kebab-case. A segment that is a CSS property keeps the property's camelCase
+            (<code>fontSize</code>, <code>letterSpacing</code>), so the name says which property it is
+            for. State is the last segment, and the package uses four:
+            ${states.map(([s, n], i) => html`${i ? ', ' : ''}<code>${s}</code> (${n})`)}.
+            ${otherStates.length
+              ? html`<b>${otherStates.length} use another state word:</b> ${otherStates.map(r => r.name).join(', ')}.`
+              : html`No token uses <code>hovered</code>, <code>pressed</code>, <code>focused</code> or <code>selected</code>.`}
+            ${midState.length
+              ? html`<b>${midState.length} component tokens put the state before the property</b>,
+                  against the shape above: ${midState.map((r, i) => html`${i ? ', ' : ''}<code>${r.name}</code>`)}.
+                  <code>default</code> is not counted, because it is also a size and a variant name
+                  here: <code>--form-label-default-*</code> sits beside <code>-small</code> and
+                  <code>-large</code>.`
+              : ''}
+          </p>`
+      })}
+
+      ${refSection({
+        name    : 'Tiers',
+        meta    : `${rows.length} tokens · ${registry.families.length} families`,
+        children: html`
+          <p style="max-width:70ch">
+            ${tiers.map((t, i) => html`${i ? ' · ' : ''}<b>${count(t)}</b> ${t}`)}.
+            ${tiers.map(t => html`<br /><b>${t}</b> — ${registry.tiers[t]}`)}
+          </p>
+          <p style="max-width:70ch">
+            <b>${judged.length} families were placed by judgement</b> rather than by documentation or
+            convention, and are the weakest calls in the registry:
+            ${judged.map((f, i) => html`${i ? ', ' : ''}<code>${f.prefix}</code> (${f.tier})`)}.
+          </p>`
+      })}
+
+      ${refSection({
+        name    : 'Nothing reads these',
+        meta    : `${flags.unread.length} semantic or component tokens`,
+        children: html`
+          <p style="max-width:70ch">Not named by any component, the blog, or another token. This is the
+            finding that retired <code>display-hero</code> and <code>--status-brand-surface-strong</code>:
+            each was either deleted or found a consumer. A token here may also be kept on purpose -- that
+            is for its owner to say.</p>
+          ${tokenList(flags.unread)}`
+      })}
+
+      ${refSection({
+        name    : 'Read only by the documentation',
+        meta    : `${flags.docsOnly.length} tokens`,
+        children: tokenList(flags.docsOnly)
+      })}
+
+      ${refSection({
+        name    : 'One colour, one slot, several tones',
+        meta    : `${flags.sameSlot.length} slots`,
+        children: html`
+          <p style="max-width:70ch">Semantic tokens that differ only in the tone or variant segment and
+            resolve to the same primitive. Two tones that share every slot cannot be told apart by
+            colour; a slot like <code>-on-fill</code> is expected to repeat, because the fill beside it
+            carries the difference.</p>
+          <div class="table-scroll"><table>
+            <caption>Shared slots</caption>
+            <thead><tr><th scope="col">Slot</th><th scope="col">Primitive</th><th scope="col">Shared by</th></tr></thead>
+            <tbody>${flags.sameSlot.map(g => html`<tr>
+              <td class="mono">${g.pattern}</td>
+              <td class="num">${swatch(g.primitive)}${g.primitive}</td>
+              <td>${g.members.join(', ')}</td></tr>`)}</tbody>
+          </table></div>
+          ${collapsed(html`<span class="usage-count">${flags.sameRole.length}</span> pairs that share a value across two roles — expected`, html`
+            <ul>${flags.sameRole.map(p => html`<li>${p.a.name} = ${p.b.name} (${p.primitive})</li>`)}</ul>`)}`
+      })}
+
+      ${refSection({
+        name    : 'Component tokens that skip the semantic tier',
+        meta    : `${flags.tierSkips.reduce((n, g) => n + g.list.length, 0)} tokens · ${flags.inversions.length} inversions`,
+        children: html`
+          <p style="max-width:70ch">A component token whose first reference is a primitive. Grouped by the
+            primitive family it reaches, beside the semantic tokens that already sit above that family --
+            the roles it could have asked for. Where that count is zero there was no role to ask for,
+            and the skip is the design working. Where it is not zero, read the roles before calling it
+            a defect: <code>--spacing-*</code> has the two card roles above it, and that is not a
+            spacing vocabulary.</p>
+          <div class="table-scroll"><table>
+            <caption>Tier skips by primitive family</caption>
+            <thead><tr><th scope="col">Reaches</th><th scope="col">Tokens</th><th scope="col">Semantic tokens above it</th></tr></thead>
+            <tbody>${flags.tierSkips.map(g => html`<tr>
+              <td class="mono">${g.prefix}*</td>
+              <td>${collapsed(html`<span class="usage-count">${g.list.length}</span>`, html`
+                <ul>${g.list.map(s => html`<li>${s.row.name} → ${s.target.name}</li>`)}</ul>`)}</td>
+              <td class="num">${g.rolesAbove.length}</td></tr>`)}</tbody>
+          </table></div>`
+      })}
+
+      ${refSection({
+        name    : 'Listed for completeness',
+        meta    : 'expected, and kept visible',
+        children: html`
+          ${collapsed(html`<span class="usage-count">${flags.literalSemantics.length}</span> semantic tokens declared as a literal, with no primitive beneath`, tokenList(flags.literalSemantics))}
+          ${collapsed(html`<span class="usage-count">${flags.unreadAxes.length}</span> unread axes of a typography role whose other axes are read`, tokenList(flags.unreadAxes))}
+          ${collapsed(html`<span class="usage-count">${flags.reachableOnly.length}</span> steps a scale helper can build but nothing names`, tokenList(flags.reachableOnly))}
+          ${collapsed(html`<span class="usage-count">${flags.unreadSteps.length}</span> primitive steps nothing reads — a scale may be complete`, tokenList(flags.unreadSteps))}`
+      })}
+
+      ${refSection({
+        name    : 'Every token',
+        meta    : 'by family',
+        children: registry.families.map(f => {
+          const members = rows.filter(r => r.family === f);
+          return collapsed(html`<span class="mono">${f.prefix}*</span> <span class="muted">${f.tier} · ${members.length}</span>`, html`
+            <div class="table-scroll"><table>
+              <caption>${f.prefix}</caption>
+              <thead><tr><th scope="col">Token</th><th scope="col">Resolves through</th><th scope="col">Value</th><th scope="col">Read by</th></tr></thead>
+              <tbody>${members.map(r => html`<tr>
+                <td>${copyToken(r.name)}</td><td>${chainCell(r)}</td><td>${valueCell(r)}</td><td>${readersCell(r)}</td></tr>`)}</tbody>
+            </table></div>`);
+        })
+      })}`
+  });
+};
+TokenMap.storyName = 'Token map';
+TokenMap.loaders = [async () => ({ map: await load() })];

package/src/tokens/token-purposes.js

@@ -0,0 +1,266 @@
+/**
+ * What each semantic token is FOR, in one place.
+ *
+ * Roles are described by the job they do, not by the colour they currently
+ * resolve to. The swatch on a docs page is there to recognise one on screen;
+ * it is never the reason to choose one.
+ *
+ * Two readers: Foundations/Surfaces renders SURFACES and BORDERS, and
+ * scripts/figma-variable-descriptions.mjs turns every entry here into the
+ * description a designer sees in Figma's variable picker. Writing the
+ * sentence once is the point -- a second hand-kept copy in Figma is how a
+ * library goes on describing a role code has changed.
+ *
+ * Not a story file: Storybook only globs *.stories.js. Pure data, so it
+ * imports under Node.
+ */
+
+export const SURFACES = [
+  {
+    token   : '--color-surface-default',
+    purpose : 'The page, canvas or component ground. The thing other things sit on.',
+    use     : 'The base of a page, a section, or a component that is not itself a distinct object.',
+    avoid   : 'A card or tile that needs to read as its own object — that is surface-container.',
+    relation: 'The reference point. Every other surface is described by how far it sits from this one.',
+    example : 'Page background, modal body, the ground inside a section wrapper.',
+    theme   : 'Whatever the page ground is in the active theme. On dark it is the dark ground, not white.'
+  },
+  {
+    token   : '--color-surface-container',
+    purpose : 'The ground a self-contained content object sits on, one step off the page, so it reads as its own object without needing a border or a shadow. The step is real but faint: Foundations/Surfaces, A card\'s ground and its edge.',
+    use     : 'A card, tile, panel or bounded section that should read as a distinct object on the page.',
+    avoid   : 'The page itself (surface-default); a low-emphasis grouping wash (surface-subtle); a disabled or pressed state (surface-muted); anything on dark (surface-inverse); brand or status meaning.',
+    relation: 'One step from default, and closer to it than subtle is. Container is the ground of an object; subtle is a wash behind a group.',
+    example : 'Card and tile surfaces, feature panels, quote cards.',
+    theme   : 'Adjacent to but distinguishable from surface-default. On dark that means one step lighter than the page, not a fixed grey.'
+  },
+  {
+    token   : '--color-surface-subtle',
+    purpose : 'A low-emphasis background that groups content without making it an object.',
+    use     : 'A band or wash behind several things that already belong together.',
+    avoid   : 'The ground of a single self-contained object — that is container.',
+    relation: 'Further from default than container. Recedes rather than stands out.',
+    example : 'A grouping band behind a row of items.',
+    theme   : 'A recessive wash relative to the page ground.'
+  },
+  {
+    token   : '--color-surface-muted',
+    purpose : 'A state surface: the thing is present but not currently active.',
+    use     : 'Pressed, inactive or de-emphasised states.',
+    avoid   : 'Resting surfaces. If nothing is in a state, this is the wrong family.',
+    relation: 'Shares its value with surface-disabled today; the meanings differ, so do not treat them as interchangeable.',
+    example : 'A pressed toggle track, a de-emphasised row.',
+    theme   : 'A state step away from the surface it applies to.'
+  },
+  {
+    token   : '--color-surface-disabled',
+    purpose : 'The surface of a control that cannot currently be used.',
+    use     : 'Disabled controls only.',
+    avoid   : 'Anything a user can still operate.',
+    relation: 'Same value as muted today, different meaning. Disabled is exempt from contrast minimums; muted is not.',
+    example : 'A disabled input or button ground.',
+    theme   : 'Reads as unavailable in the active theme.'
+  },
+  {
+    token   : '--color-surface-pressed',
+    purpose : 'The ground of a control while it is held down, when surface-muted is already its hover.',
+    use     : 'The pressed state of a control whose hover is surface-muted.',
+    avoid   : 'A resting or hovered ground; a pressed action fill, which is the action ramp.',
+    relation: 'One step further from the page than muted, the way a press follows a hover.',
+    example : 'bd-back while pressed.',
+    theme   : 'A state step past muted in the active theme. On dark, lighter than muted, not darker.'
+  },
+  {
+    token   : '--color-surface-inverse',
+    purpose : 'A ground that flips the text polarity: content on it uses the inverse text roles.',
+    use     : 'Dark panels inside a light page, tooltips, inverted sections.',
+    avoid   : 'Ordinary surfaces. Choosing this changes which text roles are legible.',
+    relation: 'Not a step on the default-container-subtle ladder; it is the other side of it.',
+    example : 'Tooltip body. Not a video or terminal frame: those stay dark in every theme, and read surface-media.',
+    theme   : 'Inverts with the theme: on a dark theme this is the light ground.'
+  },
+  {
+    token   : '--color-surface-media',
+    purpose : 'The frame around media: a video letterbox, a terminal panel. Dark in every theme.',
+    use     : 'A ground that must stay dark because what it frames is dark. Its ink is text-on-media.',
+    avoid   : 'A dark panel that should flip with the theme, such as a tooltip: that is surface-inverse.',
+    relation: 'Same value as surface-inverse in light; the two part ways in a dark theme, where inverse turns light and media does not.',
+    example : 'bd-video-player and bd-video letterboxes, the bd-terminal-message panel.',
+    theme   : 'Fixed: the same near-black in every theme.'
+  },
+  {
+    token   : '--color-surface-brand',
+    purpose : 'A surface whose job is to carry brand identity.',
+    use     : 'Large brand areas, such as a footer masthead band.',
+    avoid   : 'Anything blue that is not making a brand statement. An indicator, a badge, a selected row and a switch track are all blue and none of them are brand surfaces.',
+    relation: 'A meaning, not a colour. Matching the brand primitive by eye is not evidence.',
+    example : 'The coloured band at the top of the footer.',
+    theme   : 'Follows the brand, not the neutral ramp.'
+  },
+  {
+    token   : '--color-surface-info',
+    purpose : 'The tint an informational message sits on.',
+    use     : 'Informational banners and callouts.',
+    avoid   : 'Decorative blue backgrounds with no message semantics.',
+    relation: 'One of the four status tints, each paired with a matching text role.',
+    example : 'An informational banner ground.',
+    theme   : 'A readable informational tint against its paired text role.'
+  },
+  {
+    token   : '--color-surface-success',
+    purpose : 'The tint a success message sits on.',
+    use     : 'Confirmation and success states.',
+    avoid   : 'Decorative green.',
+    relation: 'Paired with the matching success text role; the pair is measured together.',
+    example : 'A success banner ground.',
+    theme   : 'A readable success tint against its paired text role.'
+  },
+  {
+    token   : '--color-surface-warning',
+    purpose : 'The tint a warning message sits on.',
+    use     : 'Cautionary states.',
+    avoid   : 'Decorative yellow.',
+    relation: 'Paired with the matching warning text role.',
+    example : 'A warning banner ground.',
+    theme   : 'A readable warning tint against its paired text role.'
+  },
+  {
+    token   : '--color-surface-error',
+    purpose : 'The tint an error message sits on.',
+    use     : 'Error and destructive-outcome states.',
+    avoid   : 'Decorative red.',
+    relation: 'Paired with the matching error text role.',
+    example : 'An error banner ground.',
+    theme   : 'A readable error tint against its paired text role.'
+  }
+];
+
+export const BORDERS = [
+  {
+    token  : '--color-border-subtle',
+    purpose: 'A decorative hairline between things that already belong together.',
+    use    : 'Separating rows or cells inside one object.',
+    avoid  : 'The edge of anything actionable. It sits below the 3:1 that WCAG 1.4.11 asks of a UI component, on purpose.'
+  },
+  {
+    token  : '--color-border-default',
+    purpose: 'The boundary of an object or control.',
+    use    : 'Inputs, bounded controls, the edge of a component.',
+    avoid  : 'Content separation inside a component — that is a divider job.'
+  },
+  {
+    token  : '--color-border-strong',
+    purpose: 'A boundary that has to assert itself.',
+    use    : 'High-emphasis edges.',
+    avoid  : 'Ordinary component edges, which would flatten the emphasis.'
+  },
+  {
+    token  : '--color-border-brand',
+    purpose: 'A boundary carrying brand emphasis.',
+    use    : 'Brand-emphasised edges.',
+    avoid  : 'Focus. Focus has its own tokens and must not be expressed as a border role.'
+  },
+  {
+    token  : '--color-border-disabled',
+    purpose: 'The edge of a control that cannot be used.',
+    use    : 'Disabled controls.',
+    avoid  : 'Anything operable.'
+  }
+];
+
+/* The two border roles the Surfaces table does not list, worded from
+   CLAUDE.md's "A card's ground and its edge". */
+export const CARD_EDGES = [
+  {
+    token  : '--color-border-container',
+    purpose: 'The edge of a card that sits on a tinted section.',
+    use    : 'A card on a tinted band, paired with surface-default as its ground.',
+    avoid  : 'A card on the page ground: there the surface-container step is the separation and an edge is redundant. On a surface-muted band this edge is the same colour as the band and disappears.'
+  },
+  {
+    token  : '--color-border-container-inverse',
+    purpose: 'The edge of a container that sits on an inverse surface.',
+    use    : 'Bounding an object on a dark ground.',
+    avoid  : 'Light surfaces.'
+  }
+];
+
+/* Text. Hierarchy and state, from Foundations/Color/Responsibilities. */
+export const TEXT = [
+  { token: '--color-text-primary', purpose: 'Default ink on a light surface: headings and body copy.', avoid: 'Inverse surfaces, where text-inverse takes over.' },
+  { token: '--color-text-secondary', purpose: 'Supporting copy under a title.', avoid: 'A disabled control: disabled is a state, not a quieter step.' },
+  { token: '--color-text-muted', purpose: 'Metadata, captions and timestamps.', avoid: 'A disabled control: disabled is a state, not a quieter step.' },
+  { token: '--color-text-subtle', purpose: 'The quietest readable step of the hierarchy, on the page or a card.', avoid: 'A band (surface-subtle, surface-muted) or a status tint: use text-muted there, because subtle cannot clear 4.5:1 on them. A disabled control: disabled is a state, not a quieter step.' },
+  { token: '--color-text-disabled', purpose: 'STATE: text on a control the user cannot operate. Exempt from contrast minimums only because it is disabled.', avoid: 'Quiet content that is still usable. Loading is not disabled.' },
+  { token: '--color-text-inverse', purpose: 'High-emphasis text on an inverse surface.', avoid: 'Light surfaces.' },
+  { token: '--color-text-muted-inverse', purpose: 'Everything subordinate on an inverse surface. The light-side secondary, muted and subtle roles fail contrast there.', avoid: 'Light surfaces.' },
+  { token: '--color-text-on-media', purpose: 'Ink on surface-media: a video control glyph, a terminal\'s command lines. White in every theme, fixed with its ground.', avoid: 'Text on an inverse surface (text-inverse), which flips in a dark theme.' },
+  { token: '--color-text-on-media-muted', purpose: 'The quieter ink on surface-media, such as a terminal\'s subdued lines.', avoid: 'Subordinate text on an inverse surface: that is text-muted-inverse, which flips.' },
+  { token: '--color-text-brand', purpose: 'Brand-coloured ink, such as a link at rest. One step darker than action-primary, because blue-500 fails on any tint.', avoid: 'The fill of an interactive element at a state: that is the action ramp.' },
+  { token: '--color-text-brand-hover', purpose: 'Brand text under the pointer: a hovered link or citation reference.', avoid: 'A button fill. It used to be --color-action-primary-active, and a fill and a text colour part ways in a dark theme.' },
+  { token: '--color-text-success', purpose: 'Success text, paired with surface-success. Offered as color="success" on bd-h and bd-p.', avoid: 'Feedback inside a component (a badge, tag or alert): that is status-success-text.' },
+  { token: '--color-text-warning', purpose: 'Warning text, paired with surface-warning. Offered as color="warning" on bd-h and bd-p.', avoid: 'Feedback inside a component: that is status-warning-text.' },
+  { token: '--color-text-error', purpose: 'Error text, paired with surface-error.', avoid: 'Feedback inside a component: that is status-error-text.' }
+];
+
+/* Actions: a state ramp, not a colour. Let the state pick the token. */
+export const ACTION = [
+  { token: '--color-action-primary', purpose: 'The fill of a primary interactive element at rest.', avoid: 'Brand identity. Action and brand share a value at this step and diverge after it.' },
+  { token: '--color-action-primary-hover', purpose: 'The same element, hovered.', avoid: 'Any blue that is not a hover state. There is no hover-blue role.' },
+  { token: '--color-action-primary-active', purpose: 'The same element, pressed.', avoid: 'A selected or current item: that is an indicator.' },
+  { token: '--color-action-accent', purpose: 'The fill of a conversion action at rest.', avoid: 'Errors and destructive outcomes, which are status-error.' },
+  { token: '--color-action-accent-hover', purpose: 'The conversion action, hovered.', avoid: 'Anything that is not a hover state.' },
+  { token: '--color-action-accent-active', purpose: 'The conversion action, pressed.', avoid: 'Anything that is not a pressed state.' },
+  { token: '--color-action-secondary', purpose: 'The neutral action fill: a secondary button at rest, and a ghost button while pressed.', avoid: 'A dark ground for content (surface-inverse), or near-black ink (text-primary). Matching neutral-950 by value is not evidence.' },
+  { token: '--color-action-secondary-hover', purpose: 'The neutral action, hovered.', avoid: 'Anything that is not a hover state.' },
+  { token: '--color-action-secondary-active', purpose: 'The neutral action, pressed.', avoid: 'Anything that is not a pressed state.' },
+  { token: '--color-action-on-fill', purpose: 'Ink on an action fill: a button label, a checkmark, a radio dot, a switch thumb. White in every theme.', avoid: 'Text on an inverse surface (text-inverse) or the page colour (surface-default): both happen to be white here, and both flip in a dark theme.' }
+];
+
+/* Status: feedback state, owned by bd-badge, bd-tag and bd-alert. One slot
+   per weight of a tone, from the comment above the block in tokens.js. */
+export const STATUS_SLOTS = {
+  'text'          : 'ink on a tinted chip (badge shade, tag)',
+  'surface'       : 'the light tint (tag, alert). A tag sits here so its border reads',
+  'surface-strong': 'the heavier tint a borderless badge sits on, so a badge and a tag of one tone read apart',
+  'border'        : 'the hairline around a tag',
+  'accent'        : 'the saturated step (badge dot, alert rule)',
+  'fill'          : 'a saturated chip (badge fill)',
+  'on-fill'       : 'the ink on that saturated chip'
+};
+export const STATUS_TONES = {
+  neutral: { label: 'Neutral', note: '' },
+  brand  : { label: 'Brand', note: 'Brand has no surface-strong: it would be info\'s blue-100, and a brand badge would read as info. Brand and info differ only in accent, so never choose between them by colour.' },
+  info   : { label: 'Info', note: 'Info and brand differ only in accent, so never choose between them by colour.' },
+  success: { label: 'Success', note: '' },
+  warning: { label: 'Warning', note: '' },
+  error  : { label: 'Error', note: '' }
+};
+
+/* The rest of the semantic set Figma carries. */
+export const OTHER = [
+  { prefix: '--icon-', purpose: 'The size of an icon glyph, from the scale every icon is sized from. Size only: an icon takes its colour from the text around it.' },
+  { prefix: '--grid-container-max-', purpose: 'The page column\'s maximum width at this breakpoint. A section never declares its own width; it composes the ensemble column.' },
+  { prefix: '--grid-padding-', purpose: 'The page column\'s gutter at the viewport edge, at this breakpoint. The column is the viewport minus twice this.' },
+  { prefix: '--grid-gutter-', purpose: 'The space between grid columns at this breakpoint.' },
+  { prefix: '--grid-columns', purpose: 'The number of columns in the page grid.' },
+  { prefix: '--touch-target-size', purpose: 'The minimum comfortable hit area for a control (WCAG 2.5.8).' },
+  { prefix: '--touch-target-spacing', purpose: 'The minimum space between two touch targets.' },
+  { prefix: '--content-width-readable', purpose: 'A comfortable reading measure for running text.' },
+  { prefix: '--content-width-max', purpose: 'The widest a content region may grow.' },
+  { prefix: '--transition-duration-', purpose: 'A motion duration step. Anything animated must respect prefers-reduced-motion.' }
+];
+
+/** { purpose, use?, avoid? } for a token, or null when nothing is written. */
+export function purposeOf(token) {
+  const row = [...SURFACES, ...BORDERS, ...CARD_EDGES, ...TEXT, ...ACTION].find(r => r.token === token);
+  if (row) return { purpose: row.purpose, use: row.use, avoid: row.avoid };
+  const status = token.match(/^--status-([a-z]+)-(.+)$/);
+  if (status && STATUS_TONES[status[1]] && STATUS_SLOTS[status[2]]) {
+    const tone = STATUS_TONES[status[1]];
+    const slot = STATUS_SLOTS[status[2]];
+    return { purpose: `${tone.label} feedback: ${slot}.${tone.note ? ` ${tone.note}` : ''}`, avoid: 'Decoration. A status role means state; a colour that carries no message belongs to the general --color-* family.' };
+  }
+  const other = OTHER.find(o => token.startsWith(o.prefix));
+  return other ? { purpose: other.purpose } : null;
+}