@repobit/dex-system-design 0.25.12 → 1.0.0

package/src/tokens/surfaces.stories.js

@@ -0,0 +1,224 @@
+import { html } from 'lit';
+import { docsPage, refSection, resolve, toHex } from './story-chrome.js';
+/* The role text lives in token-purposes.js, so the Figma variable
+   descriptions are generated from the same sentences this page shows. */
+import { BORDERS, SURFACES } from './token-purposes.js';
+
+export default {
+  title: 'Foundations/Surfaces',
+  tags : ['autodocs']
+};
+
+const swatch = (token) => {
+  const value = resolve(token);
+  return html`<span
+    style="display:inline-block;width:var(--spacing-40);height:var(--spacing-24);
+           border-radius:var(--radius-sm);vertical-align:middle;
+           border:var(--border-width-1) solid var(--color-border-subtle);
+           background:${value}"
+    title="${toHex(value) || value}"
+  ></span>`;
+};
+
+const roleTable = (rows, kind, caption) => html`
+  <div class="table-scroll">
+    <table>
+      <caption>${caption}</caption>
+      <thead>
+      <tr>
+        <th scope="col">Role</th>
+        <th scope="col">Preview</th>
+        <th scope="col">Purpose</th>
+        <th scope="col">Use when</th>
+        <th scope="col">Do not use when</th>
+        ${kind === 'surface'
+          ? html`<th scope="col">Relationship</th><th scope="col">Theme expectation</th>`
+          : ''}
+      </tr>
+    </thead>
+    <tbody>
+      ${rows.map(
+        (r) => html`
+        <tr>
+          <td><code>${r.token}</code></td>
+          <td>${swatch(r.token)}</td>
+          <td>${r.purpose}</td>
+          <td>${r.use}</td>
+          <td>${r.avoid}</td>
+          ${kind === 'surface'
+            ? html`<td>${r.relation}</td><td>${r.theme}</td>`
+            : ''}
+        </tr>`
+      )}
+    </tbody>
+    </table>
+  </div>
+`;
+
+export const Surfaces = () =>
+  docsPage({
+    title: 'Surfaces',
+    lede : `A surface role says what a background is for. It does not say what colour it is
+            today, and choosing one by finding the nearest current value is how the wrong role
+            gets picked. Identify the job first; the role then decides the value, and the theme
+            decides it again.`,
+    note: html`<b>Same value is not same meaning.</b> Several roles resolve to the same
+            primitive right now — muted and disabled, for instance. They are different
+            questions and will not necessarily stay equal.`,
+    children: html`
+      ${refSection({
+        name    : 'Choosing a background',
+        meta    : 'in order',
+        children: html`
+        <ol class="docs-list">
+          <li>Is it the page, section or component ground? <code>--color-surface-default</code></li>
+          <li>Is it a self-contained object — a card, tile or panel? Ask what it sits on first.
+              On the page ground, <code>--color-surface-container</code> and no edge. On a
+              tinted section, <code>--color-surface-default</code> with a
+              <code>--border-width-1 solid --color-border-container</code> edge, because no
+              tonal step is available against a tint. See below.</li>
+          <li>Is it a low-emphasis wash grouping several things? <code>--color-surface-subtle</code></li>
+          <li>Is it a state — pressed, inactive? <code>--color-surface-muted</code>. Held down, where muted is already the hover? <code>--color-surface-pressed</code>. Disabled? <code>--color-surface-disabled</code></li>
+          <li>Does content on it need inverse text? <code>--color-surface-inverse</code></li>
+          <li>Is it making a brand statement? <code>--color-surface-brand</code></li>
+          <li>Does it carry a message? The matching status surface.</li>
+        </ol>
+        <p>
+          If two answers seem to fit, the earlier one usually wins: the ladder runs from the
+          page outward, and most surfaces are nearer the page than authors expect.
+        </p>`
+      })}
+
+      ${refSection({
+        name    : 'Surface roles',
+        meta    : `${SURFACES.length} roles`,
+        children: roleTable(SURFACES, 'surface', 'Surface roles, what each is for, and how it should behave under a theme')
+      })}
+
+      ${refSection({
+        name    : 'Default, container and subtle',
+        meta    : 'the distinction authors get wrong',
+        children: html`
+        <p>
+          These three are the ones worth being precise about, because they are adjacent and
+          the difference is about role rather than appearance.
+        </p>
+        <ul class="docs-list">
+          <li><b>Default</b> is the ground. Things sit <i>on</i> it.</li>
+          <li><b>Container</b> is the ground of a thing that sits on the page. A card uses it so
+              that it reads as an object without needing a border or a shadow to say so — as
+              long as the page is what it sits on.</li>
+          <li><b>Subtle</b> is a wash <i>behind</i> a group. It recedes; it is not the ground of
+              any single object.</li>
+        </ul>
+        <p>
+          An author who can answer <q>is this an object, or the space behind several objects?</q>
+          never needs to look at the values.
+        </p>
+        <h3 style="font-size: var(--typography-fontSize-base); margin: var(--spacing-32) 0 var(--spacing-8)">
+          A card's ground and its edge
+        </h3>
+        <p>
+          Two answers, and which applies depends on what the card sits on. <b>On the page
+          ground</b> — <code>--color-surface-container</code>, and no edge: the tonal step is
+          the separation, which is what the role is for, and a border there is redundant with
+          the role's own purpose. <b>On a tinted section</b> —
+          <code>--color-surface-default</code> plus a <code>--border-width-1 solid
+          --color-border-container</code> edge, because there is no tonal step available
+          against a tint and the edge earns its keep.
+        </p>
+        <p>
+          This was read off the components rather than decided in advance, and it is checkable:
+          of the eleven card-shaped objects — the ones
+          <code>scripts/card-shapes.json</code> lists, which is now what makes the count
+          checkable — six sit on the page ground with no edge, four sit on a
+          tinted or inverted ground and draw one, and exactly one does neither. Bento and the
+          Carousel item were the two that disagreed, and they were changed rather than the rule.
+          The Awards feature card moved the other way when its section gained a blue-50
+          band: on the page ground its tonal step was the separation, and on a tint it
+          was not — 1.034:1, across a hue change rather than a lightness step — so it
+          took the second clause and now reads 1.08:1 with a 1.192:1 edge.
+        </p>
+        <p>
+          <b>The one exception is recorded.</b> The new-pricing card keeps
+          <code>--color-surface-container</code> and draws an edge on it, because it has no
+          wrapper of its own to carry a band — its container belongs to the page — so inverting
+          to white would put a white card on a white page. The edge is the half of the rule that
+          is safe on its own, and it triples the delta to 1.233:1. That is the shape an exception
+          should have: the rule named, the reason measured, the alternative said out loud.
+        </p>
+        <p>
+          <b>Two qualifications, both measured, and both found by the Pricing card.</b>
+        </p>
+        <p>
+          <b>The step is quieter than the sentence above implies.</b>
+          <code>--color-surface-default</code>, <code>-container</code> and <code>-subtle</code>
+          measure 1.000, 1.044 and 1.121 against the page — three named grounds inside a 12%
+          band. On the page ground the step is real but faint, so an edge there is redundant
+          rather than useless. Where a card must be <i>sharp</i> — adjacent cards in a
+          comparison set, say — the step alone will not do it, and the answer is the second
+          clause, a tinted band with edges, not a stronger border on the first.
+        </p>
+        <p>
+          <b>The second clause breaks on one tint.</b> <code>--color-border-container</code>
+          <i>is</i> <code>--color-neutral-100</code>, and so is
+          <code>--color-surface-muted</code>. On a muted band the rule's own edge is the same
+          colour as the band and disappears at 1.000:1. The card is then defined by its tonal
+          step alone, which on that band is the strongest of the three at 1.287:1 — so the
+          result is acceptable, but the edge is decoration. On a <code>-container</code>,
+          <code>-subtle</code> or status-tinted band the edge reads normally. Pick the band
+          before picking the edge.
+        </p>
+        <p>
+          <b>Revisit this when a card needs an edge for a reason the tonal step cannot
+          carry</b> — a selected or focused card, a card over an image, a card that must read
+          on both grounds. That is a new need rather than a violation, and the rule should grow
+          to name it rather than be worked around.
+        </p>
+        <p>
+          <b>Container means a visual container for content.</b> It has nothing to do with CSS
+          container queries or any layout API.
+        </p>`
+      })}
+
+      ${refSection({
+        name    : 'Borders, dividers and focus',
+        meta    : 'three different jobs',
+        children: html`
+        <ul class="docs-list">
+          <li><b>A border</b> bounds an object. It says where a thing ends.</li>
+          <li><b>A divider</b> separates regions of content. Reach for
+              <code>bd-divider-horizontal</code> when the line is a separator between regions.
+              A layout border-top that participates in a grid row is a boundary, not a
+              separator, and native CSS is the right tool for it — do not convert one into a
+              divider for the sake of reuse.</li>
+          <li><b>A focus indicator</b> communicates keyboard focus. It has its own tokens and is
+              never a border role. Do not express focus by swapping a border colour.</li>
+          <li><b>A status border</b> communicates state and belongs with the status family.</li>
+        </ul>
+        ${roleTable(BORDERS, 'border', 'Border roles and what each one bounds')}`
+      })}
+
+      ${refSection({
+        name    : 'Elevation',
+        meta    : 'purpose, not appearance',
+        children: html`
+        <p>
+          Pick a shadow because of what it means, not because it looks close. The shadow scale
+          is a set of effect levels; the meanings below are what should drive the choice.
+        </p>
+        <ul class="docs-list">
+          <li><b>Resting elevation</b> — a surface raised at rest. Rare here: no audited card
+              uses one. A container surface is usually the better way to make an object read as
+              an object.</li>
+          <li><b>Interaction lift</b> — a shadow that appears on hover or drag. It belongs with a
+              transform and must be reducible under prefers-reduced-motion.</li>
+          <li><b>Overlay</b> — modals, popovers, dropdowns and tooltips, which sit above the page
+              and need to look like it.</li>
+          <li><b>Inset border effects</b> — an inset shadow used to draw a hairline without
+              affecting layout. This is a border technique, not elevation, and most of the
+              inset shadows in this package are exactly that.</li>
+        </ul>`
+      })}
+    `
+  });

package/src/tokens/text-on-surface.stories.js

@@ -0,0 +1,164 @@
+import { html } from 'lit';
+import { contrast, docsPage, levelBadge, refSection, resolve, toHex } from './story-chrome.js';
+
+export default {
+  title: 'Foundations/Text on a surface',
+  tags : ['autodocs']
+};
+
+/* The grounds text actually lands on in this package. Two families name some of
+   the same values -- the surface roles and the status roles -- which is exactly
+   why a pairing can look considered and still have been measured against
+   nothing. */
+const GROUNDS = [
+  { token: '--color-surface-default', note: 'the page ground' },
+  { token: '--color-surface-container', note: 'a card or tile' },
+  { token: '--color-surface-subtle', note: 'a wash behind a group' },
+  { token: '--status-brand-surface', note: 'the brand tint, and the same value as surface-info' },
+  { token: '--status-success-surface', note: 'the success tint' },
+  { token: '--status-warning-surface', note: 'the warning tint' },
+  { token: '--status-error-surface', note: 'the error tint' }
+];
+
+/* Roles that are legitimately used for text somewhere in the package. */
+const INKS = [
+  '--color-text-primary',
+  '--color-text-secondary',
+  '--color-text-muted',
+  '--color-text-subtle',
+  '--color-text-brand',
+  '--status-brand-text',
+  '--color-action-accent'
+];
+
+const cell = (ink, ground) => {
+  const ratio = contrast(resolve(ink), resolve(ground));
+  const rounded = Math.round(ratio * 100) / 100;
+  return html`
+    <td style="background:${resolve(ground)};color:${resolve(ink)};padding:var(--spacing-8)">
+      <span style="font-size:var(--typography-fontSize-xs)">Aa ${rounded}</span>
+      ${levelBadge(ratio)}
+    </td>`;
+};
+
+export const TextOnSurface = () =>
+  docsPage({
+    title: 'Text on a surface',
+    lede : `A text role is only legible against a particular ground, and the ground is not
+            always the one it was measured on. Every pairing below is measured live from
+            the tokens, so this page cannot drift from them.`,
+    note: html`<b>A pass on white is not a pass anywhere.</b>
+            <code>--color-text-subtle</code> reaches 4.5:1 on the page ground and falls
+            under it on every tint in this table. That is the same trap
+            <code>--color-blue-500</code> already carries a warning for, and it is how
+            three components ended up below AA with tokens that looked deliberate.`,
+    children: html`
+      ${refSection({
+        name    : 'Every role against every ground',
+        meta    : `${INKS.length} roles x ${GROUNDS.length} grounds`,
+        children: html`
+        <p>
+          The badge is the level the pair reaches for <b>normal-size body text</b>.
+          <code>18pt</code> means it only clears the lower bar that large text and
+          non-text UI are held to — at body size it fails.
+        </p>
+        <div class="table-scroll">
+          <table>
+            <caption>Contrast of each text role against each surface it may sit on</caption>
+            <thead>
+              <tr>
+                <th scope="col">Text role</th>
+                ${GROUNDS.map(g => html`<th scope="col"><code>${g.token.replace('--color-', '').replace('--status-', '')}</code></th>`)}
+              </tr>
+            </thead>
+            <tbody>
+              ${INKS.map(ink => html`
+                <tr>
+                  <td><code>${ink}</code></td>
+                  ${GROUNDS.map(g => cell(ink, g.token))}
+                </tr>`)}
+            </tbody>
+          </table>
+        </div>`
+      })}
+
+      ${refSection({
+        name    : 'The grounds',
+        meta    : 'what each one is for',
+        children: html`
+        <div class="table-scroll">
+          <table>
+            <caption>Surface tokens used as a text ground, and their current values</caption>
+            <thead>
+              <tr><th scope="col">Token</th><th scope="col">Value</th><th scope="col">What it is</th></tr>
+            </thead>
+            <tbody>
+              ${GROUNDS.map(g => html`
+                <tr>
+                  <td><code>${g.token}</code></td>
+                  <td class="num">${toHex(resolve(g.token))}</td>
+                  <td>${g.note}</td>
+                </tr>`)}
+            </tbody>
+          </table>
+        </div>`
+      })}
+
+      ${refSection({
+        name    : 'Choosing',
+        meta    : 'in order',
+        children: html`
+        <ol class="docs-list">
+          <li>Decide what the text <i>is</i> — body, supporting, a label, a link, a status
+              message. That picks the family.</li>
+          <li>Find the ground it will actually sit on, which is often a tint rather than
+              the page.</li>
+          <li>Read the pair off this table. If it does not reach
+              <code>AA</code> at the size you are using, take the next step up in the
+              same family rather than a colour from another one.</li>
+        </ol>
+        <p>
+          Supporting metadata that failed on a tint went from
+          <code>--color-text-subtle</code> to <code>--color-text-muted</code>, and a
+          brand-coloured eyebrow went from a lighter blue to
+          <code>--color-text-brand</code>. Both are one step inside the family that
+          already described the text; neither needed a new token.
+        </p>`
+      })}
+      ${refSection({
+        name    : 'The inverse side',
+        meta    : 'two steps, not a mirror of the light hierarchy',
+        children: html`
+          <p>
+            The table above is the light side. On an inverse surface the same hierarchy does
+            not exist and cannot be borrowed: <code>--color-text-secondary</code>,
+            <code>-muted</code> and <code>-subtle</code> measure 1.91, 2.73 and 3.85 against
+            <code>--color-surface-inverse</code>, so every one of them is unusable there.
+          </p>
+          <p>
+            There are exactly two inverse text roles.
+            <code>--color-text-inverse</code> is high emphasis, and
+            <code>--color-text-muted-inverse</code> is everything subordinate to it. Two
+            components had built the second one separately -- one with a white alpha, one with
+            a neutral step -- before it was named.
+          </p>
+          <div style="background: var(--color-surface-inverse); padding: var(--spacing-24); border-radius: var(--radius-lg); max-width: 52ch">
+            <p style="margin: 0 0 var(--spacing-8); color: var(--color-text-inverse)">
+              High emphasis on an inverse surface — 17.97:1
+            </p>
+            <p style="margin: 0; color: var(--color-text-muted-inverse); font-size: var(--typography-fontSize-sm)">
+              Subordinate on an inverse surface — 7.92:1
+            </p>
+          </div>
+          <p>
+            <b>An inverse ground is not always flat, and arithmetic is not measurement.</b> A
+            gradient or an image has a lightest point, and that point is the one that decides —
+            but which point the text actually sits on is a question about layout, not about the
+            stops. bd-cta-banner sets white at 60% opacity over a blue gradient, and calculating
+            against its lightest stop predicts 2.13:1. Sampling the pixels behind the rendered
+            text gives 4.46:1, because the radial highlight sits at <code>78% -10%</code> and is
+            mostly outside the banner. Sample the ground; do not infer it.
+          </p>`
+      })}
+    `
+  });

package/src/tokens/token-map.js

@@ -0,0 +1,220 @@
+/**
+ * The analysis behind Foundations/Token Map, kept free of Lit and the DOM so
+ * the same functions run in Storybook and under Node: the page renders what
+ * this returns, and nothing on the page is transcribed by hand.
+ *
+ * Inputs are text, not live objects: the generated tokens.css, the tier
+ * registry in scripts/token-tiers.json, and the raw source of every file that
+ * might read a token. Component CSS sits inside shadow roots, which is why the
+ * other Foundations pages can only count token-to-token references; reading the
+ * source is what lets this page say which component reads a token.
+ *
+ * Not a story file: Storybook only globs *.stories.js.
+ */
+
+/** Blank comments, keeping offsets, so commented-out CSS is never read. */
+export const blankComments = text =>
+  text.replace(/\/\*[\s\S]*?\*\//g, c => c.replace(/[^\n]/g, ' '));
+
+/** name -> raw declared value, in declaration order. */
+export function declarationsFrom(cssText) {
+  const out = new Map();
+  for (const m of blankComments(cssText).matchAll(/(?:^|[\s;{])(--[A-Za-z0-9-]+)\s*:\s*([^;]*);/g)) {
+    if (!out.has(m[1])) out.set(m[1], m[2].replace(/\s+/g, ' ').trim());
+  }
+  return out;
+}
+
+/** Every custom property a value refers to. */
+export const refsOf = value => [...value.matchAll(/var\(\s*(--[A-Za-z0-9-]+)/g)].map(m => m[1]);
+
+/** The family a token belongs to: the longest matching registry prefix. */
+export function familyOf(token, families) {
+  let best = null;
+  for (const f of families) {
+    if (token.startsWith(f.prefix) && (!best || f.prefix.length > best.prefix.length)) best = f;
+  }
+  return best;
+}
+
+/**
+ * The alias chain from a token down to its value. Follows the reference while
+ * the value is exactly one var(); a value that combines references
+ * (color-mix, a shorthand, a clamp) ends the chain and is reported as compound.
+ */
+export function chainOf(token, decls) {
+  const hops = [token];
+  let value = decls.get(token);
+  while (value !== undefined) {
+    const only = value.match(/^var\(\s*(--[A-Za-z0-9-]+)\s*\)$/);
+    if (!only || !decls.has(only[1]) || hops.includes(only[1])) break;
+    hops.push(only[1]);
+    value = decls.get(only[1]);
+  }
+  const compound = value !== undefined && refsOf(value).length > 0;
+  return { hops, value: value ?? '', compound };
+}
+
+/**
+ * Who reads each token, from raw source text keyed by path.
+ *
+ * Three ways a token is read, and all three are real in this package:
+ *   var(--x)           the ordinary case
+ *   '--x'              a name held as data -- token-scales.js maps
+ *                      color="muted" to '--color-text-muted' this way
+ *   '--spacing-'       a prefix the scale helpers complete at runtime, so a
+ *                      step may be read without its full name appearing
+ * The third is reported separately: it says a token can be reached, not that
+ * anything reaches it.
+ */
+export function consumersFrom(sources, ownerOf) {
+  const readers = new Map();
+  const prefixes = new Map();
+  const add = (map, key, owner) => {
+    if (!map.has(key)) map.set(key, new Set());
+    map.get(key).add(owner);
+  };
+  for (const [path, raw] of Object.entries(sources)) {
+    const text = blankComments(raw);
+    const owner = ownerOf(path);
+    for (const m of text.matchAll(/var\(\s*(--[A-Za-z0-9-]+)/g)) add(readers, m[1], owner);
+    for (const m of text.matchAll(/['"`](--[A-Za-z0-9-]*[A-Za-z0-9])['"`]/g)) add(readers, m[1], owner);
+    /* documentation looks tokens up by prefix to list them, which is not a
+       product being able to reach one */
+    if (owner === DOCS) continue;
+    for (const m of text.matchAll(/['"`](--[A-Za-z0-9-]+-)['"`$]/g)) add(prefixes, m[1], owner);
+    for (const m of text.matchAll(/var\(\s*(--[A-Za-z0-9-]+-)\$\{/g)) add(prefixes, m[1], owner);
+  }
+  return { readers, prefixes };
+}
+
+const TIER_RANK = { primitive: 0, semantic: 1, component: 2 };
+
+/** The owner name ownerOf() should return for documentation sources. */
+export const DOCS = 'stories';
+
+/**
+ * Everything the page shows. `sources` is { path: text }; `ownerOf` turns a
+ * path into the name shown in "read by".
+ */
+export function analyse({ cssText, registry, sources, ownerOf }) {
+  const decls = declarationsFrom(cssText);
+  const families = registry.families;
+  const { readers, prefixes } = consumersFrom(sources, ownerOf);
+
+  const byToken = new Map();
+  for (const [name, value] of decls) {
+    const family = familyOf(name, families);
+    const chain = chainOf(name, decls);
+    const tokenReaders = new Set();
+    for (const [other, v] of decls) if (other !== name && refsOf(v).includes(name)) tokenReaders.add(other);
+    const reachable = new Set();
+    for (const [prefix, owners] of prefixes) if (name.startsWith(prefix)) owners.forEach(o => reachable.add(o));
+    byToken.set(name, {
+      name,
+      value,
+      family,
+      tier         : family?.tier ?? 'unassigned',
+      chain,
+      tokenReaders,
+      sourceReaders: readers.get(name) ?? new Set(),
+      reachable
+    });
+  }
+
+  const rows = [...byToken.values()];
+  const roleOf = name => name.replace(/-[A-Za-z]+$/, '');
+
+  /* Tier skips: a component token whose first hop is a primitive. Grouped by
+     the primitive family reached, because the answer differs by family: a
+     colour primitive has semantic roles above it that the token could have
+     asked for, and --spacing-* has none -- its roles were deleted on purpose.
+     Inversions: a token whose first hop is a HIGHER tier than itself. */
+  const tierSkips = new Map();
+  const inversions = [];
+  for (const r of rows) {
+    const firstHop = r.chain.hops[1] ?? refsOf(r.value)[0];
+    const target = firstHop && byToken.get(firstHop);
+    if (!target) continue;
+    if (r.tier === 'component' && target.tier === 'primitive') {
+      const key = target.family.prefix;
+      if (!tierSkips.has(key)) tierSkips.set(key, []);
+      tierSkips.get(key).push({ row: r, target });
+    }
+    if (TIER_RANK[target.tier] > TIER_RANK[r.tier]) inversions.push({ row: r, target });
+  }
+  /* For each skipped-to family, the semantic tokens that do sit above it --
+     the roles a skipping token could have asked for instead. A count, not a
+     verdict: --spacing-* has two (the card roles), and that is not a spacing
+     vocabulary. */
+  const rolesAbove = prefix => rows.filter(r => r.tier === 'semantic' &&
+    r.chain.hops.slice(1).some(h => byToken.get(h)?.family?.prefix === prefix));
+  const skips = [...tierSkips].map(([prefix, list]) => ({ prefix, list, rolesAbove: rolesAbove(prefix) }))
+    .sort((a, b) => b.list.length - a.list.length);
+
+  /* Unread, split by what it means:
+       unread           semantic or component, and nothing reads it -- the
+                        case that retired display-hero and two status tokens
+       docsOnly         read by a story and nothing else
+       unreadAxes       one axis of a typography role whose other axes are
+                        read; a role declares five and a consumer may want two
+       reachableOnly    nothing names it, but a scale helper can build its name
+       unreadSteps      a primitive step nothing reads; a scale is allowed to
+                        be complete */
+  const unread = [];
+  const docsOnly = [];
+  const unreadAxes = [];
+  const reachableOnly = [];
+  const unreadSteps = [];
+  const productRead = r => r.tokenReaders.size > 0 || [...r.sourceReaders].some(o => o !== DOCS);
+  for (const r of rows) {
+    if (productRead(r)) continue;
+    if (r.reachable.size) { reachableOnly.push(r); continue; }
+    if (r.sourceReaders.has(DOCS)) { docsOnly.push(r); continue; }
+    if (r.tier === 'primitive') { unreadSteps.push(r); continue; }
+    const isRoleAxis = r.tier === 'semantic' && r.name.startsWith('--typography-');
+    const siblingRead = isRoleAxis && rows.some(o => o !== r && roleOf(o.name) === roleOf(r.name) && productRead(o));
+    (siblingRead ? unreadAxes : unread).push(r);
+  }
+
+  /* semantic tokens declared as a literal: no primitive beneath them */
+  const literalSemantics = rows.filter(r => r.tier === 'semantic' && refsOf(r.value).length === 0);
+
+  /* Same colour, two semantic names in one family, differing in exactly one
+     segment. Split by WHICH segment differs:
+       sameSlot   a middle segment -- --status-brand-surface and
+                  --status-info-surface: one slot, two tones, one colour. This
+                  is the kind that collided twice.
+       sameRole   the last segment -- --color-surface-muted and -disabled: two
+                  jobs that happen to share a value, which CLAUDE.md says is
+                  expected and must not drive a choice. Listed, not flagged. */
+  const slots = new Map();
+  const sameRole = [];
+  const colour = rows.filter(r => r.tier === 'semantic' && !r.chain.compound &&
+    byToken.get(r.chain.hops.at(-1))?.family?.prefix?.startsWith('--color-') &&
+    byToken.get(r.chain.hops.at(-1))?.tier === 'primitive');
+  const segs = n => n.slice(2).split('-');
+  for (let i = 0; i < colour.length; i++) {
+    for (let j = i + 1; j < colour.length; j++) {
+      const a = colour[i], b = colour[j];
+      if (a.family !== b.family || a.chain.hops.at(-1) !== b.chain.hops.at(-1)) continue;
+      const sa = segs(a.name), sb = segs(b.name);
+      if (sa.length !== sb.length) continue;
+      const diff = sa.map((s, k) => s !== sb[k]);
+      if (diff.filter(Boolean).length !== 1) continue;
+      if (diff.at(-1)) { sameRole.push({ a, b, primitive: a.chain.hops.at(-1) }); continue; }
+      /* one line per slot: --status-*-surface -> blue-50: brand, info */
+      const k = diff.indexOf(true);
+      const pattern = `--${sa.map((s, n) => (n === k ? '*' : s)).join('-')}`;
+      const key = `${pattern}|${a.chain.hops.at(-1)}`;
+      if (!slots.has(key)) slots.set(key, { pattern, primitive: a.chain.hops.at(-1), members: new Set() });
+      slots.get(key).members.add(sa[k]).add(sb[k]);
+    }
+  }
+  const sameSlot = [...slots.values()].map(g => ({ ...g, members: [...g.members] }));
+
+  return {
+    rows, decls,
+    flags: { tierSkips: skips, inversions, unread, docsOnly, unreadAxes, reachableOnly, unreadSteps, literalSemantics, sameSlot, sameRole }
+  };
+}