@terpjs/contract 0.7.0 → 0.8.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@terpjs/contract",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "type": "module",
   "description": "Terp frontend contract \u2014 the OpenAPI-generated TypeScript client, design tokens, and the stack-agnostic module/route/nav + auth types.",
   "exports": {

package/scripts/build-tokens.mjs

@@ -205,6 +205,9 @@ const manifest = {
     themeable: overlays.some((theme) => sources.get(theme.name).has(name)),
   })),
   textPairs: pairs.textPairs,
+  // Both sections, because a consumer that can only see the text pairings would read the
+  // absence of a boundary pairing as "no requirement" rather than "held elsewhere".
+  nonTextPairs: pairs.nonTextPairs,
 };
 
 writeFileSync(
@@ -213,5 +216,6 @@ writeFileSync(
 );
 console.log(
   `wrote src/tokens.manifest.json (${manifest.tokens.length} tokens, ` +
-    `${manifest.themes.length} themes, ${manifest.textPairs.length} pairs)`,
+    `${manifest.themes.length} themes, ${manifest.textPairs.length} text pairs, ` +
+    `${manifest.nonTextPairs.length} non-text pairs)`,
 );

package/src/tokens.contrast.test.js

@@ -29,6 +29,15 @@ const AA_NORMAL_TEXT = 4.5;
 /** WCAG 2.1 AAA, normal-size text — the bar a theme named for contrast has to clear. */
 const AAA_NORMAL_TEXT = 7;
 
+/**
+ * WCAG 2.1 SC 1.4.11, non-text contrast: the bar for a control's visual boundary and for a
+ * state or focus indicator. Flat across every theme, including the one that raises its text
+ * floor to AAA, because WCAG defines no AAA tier for non-text contrast — `minimumContrast` in
+ * themes.json is a promise about reading, and inventing a stricter non-text bar from it would
+ * be this file asserting a standard nobody wrote.
+ */
+const UI_COMPONENT = 3;
+
 /**
  * Pairings the framework renders as text, read from the shared data file.
  *
@@ -41,7 +50,30 @@ const AAA_NORMAL_TEXT = 7;
  * `id` is the stable key — labels intentionally repeat across the primitive and semantic
  * layers ("body text on the canvas" describes both), so only the id can identify a pairing.
  */
-const TEXT_PAIRS = JSON.parse(fs.readFileSync(here("../token-pairs.json"), "utf8")).textPairs;
+const PAIRS = JSON.parse(fs.readFileSync(here("../token-pairs.json"), "utf8"));
+const TEXT_PAIRS = PAIRS.textPairs;
+
+/**
+ * Pairings the framework renders as a boundary or an indicator rather than as text, from the
+ * same file, held to {@link UI_COMPONENT} instead of AA.
+ *
+ * The section exists because three measured ratios had nowhere to live and so were recorded as
+ * prose in `styles.ts` — the shared focus ring, the border that says which layout toggle is
+ * active, and the neutral-300 control outline. A number in a comment is not a gate: the focus
+ * ring shipped at 1.67:1 for exactly as long as its value was only ever read by a person.
+ *
+ * What is deliberately NOT here is as load-bearing as what is. The focus ring's translucent
+ * box-shadow halo is excluded: the opaque outline is the indicator SC 1.4.11 measures, and the
+ * halo is reinforcement around it — declaring the halo would assert a ratio WCAG does not ask
+ * for, which is the same reason dividers are absent from `textPairs`. The active toggle's
+ * neutral-100 fill is excluded for the same reason, at 1.10, and it is why that rule carries a
+ * border at all rather than a wash. And neither the toggle's border against the toolbar band
+ * nor the focus ring on a card is an entry, because both name the same two tokens as the TEXT
+ * pairing `accent-on-surface` — measuring one pairing twice under two names would make the
+ * ratchet lie about how much is covered, and here the other name is held to a stricter bar.
+ * `declares no pairing the text section already holds to a stricter bar` enforces that.
+ */
+const NON_TEXT_PAIRS = PAIRS.nonTextPairs;
 
 
 /**
@@ -69,6 +101,41 @@ const TEXT_PAIRS = JSON.parse(fs.readFileSync(here("../token-pairs.json"), "utf8
  */
 const BELOW_AA = new Map([]);
 
+/**
+ * Non-text pairings that do not reach 3:1 today, with the ratio measured when they were
+ * recorded. Same ratchet contract as {@link BELOW_AA}: a floor may only rise, and a pairing
+ * that reaches the bar must leave the table.
+ *
+ * Every entry is the same defect. `--color-neutral-300` is the control outline — the border on
+ * an input, a secondary button, a card, a combobox, a menu, the layout toggles — and against
+ * the surfaces those controls sit on it measures 1.42 to 2.36, so a bordered control's edge is
+ * effectively invisible to anyone who needs the boundary in order to see the control. That is a
+ * genuine SC 1.4.11 failure in four of the five themes, deliberately recorded rather than
+ * fixed: the fix is the token value, and moving it repaints every bordered control in the
+ * package, which is a decision about how the framework looks and not a side effect of adding a
+ * gate. The contrast theme already clears it at 10.37, which is what shows the fix is a value
+ * and not a structure.
+ *
+ * Unlike {@link BELOW_AA} the entries are not confined to the themes that predate the gate, and
+ * pretending otherwise would be the dishonest option — every palette inherited the same
+ * 300-step boundary, so the defect is one token's value seen five times rather than five
+ * independent mistakes. The guard below is therefore different in kind: the allowance may name
+ * only the control-boundary pairings. A new pairing cannot be added to it at all.
+ */
+const BELOW_UI = new Map([
+  ["dark/control-boundary-on-canvas", 2.3559],
+  ["dark/control-boundary-on-surface", 1.9305],
+  ["light/control-boundary-on-canvas", 1.419],
+  ["light/control-boundary-on-surface", 1.4847],
+  ["midnight/control-boundary-on-canvas", 1.6826],
+  ["midnight/control-boundary-on-surface", 1.5506],
+  ["twilight/control-boundary-on-canvas", 1.982],
+  ["twilight/control-boundary-on-surface", 1.7807],
+]);
+
+/** The only pairings {@link BELOW_UI} is allowed to name. */
+const CONTROL_BOUNDARY_IDS = ["control-boundary-on-canvas", "control-boundary-on-surface"];
+
 /** The declarations of the one rule whose selector is exactly `selector`. */
 function declarationsFor(selector) {
   const matches = parseRules(tokensCss).filter((rule) => rule.selector === selector);
@@ -126,16 +193,26 @@ function contrastRatio(a, b) {
 const floorFor = (name) =>
   registry.themes.find((theme) => theme.name === name)?.minimumContrast ?? AA_NORMAL_TEXT;
 
-/** Every pairing, in every registered theme, tagged with its `BELOW_AA` key. */
-const cases = Object.entries(THEMES).flatMap(([theme, declarations]) =>
-  TEXT_PAIRS.map((pair) => ({
-    ...pair,
-    theme,
-    declarations,
-    key: `${theme}/${pair.id}`,
-    floor: floorFor(theme),
-  })),
-);
+/**
+ * Every pairing in *list*, in every registered theme, tagged with its ratchet key and the
+ * ratio it has to reach.
+ *
+ * Shared by both suites because they differ in exactly one thing — the bar — and writing the
+ * fan-out twice is how the two would drift into measuring different theme sets.
+ */
+const casesFor = (list, floorOf) =>
+  Object.entries(THEMES).flatMap(([theme, declarations]) =>
+    list.map((pair) => ({
+      ...pair,
+      theme,
+      declarations,
+      key: `${theme}/${pair.id}`,
+      floor: floorOf(theme),
+    })),
+  );
+
+/** Every text pairing, in every registered theme, tagged with its `BELOW_AA` key. */
+const cases = casesFor(TEXT_PAIRS, floorFor);
 
 /** The measured ratio for one case, with the painted values for the failure message. */
 function measure({ fg, bg, declarations }) {
@@ -152,6 +229,11 @@ function measure({ fg, bg, declarations }) {
 const meetsAa = cases.filter(({ key }) => !BELOW_AA.has(key));
 const knownGaps = cases.filter(({ key }) => BELOW_AA.has(key));
 
+/** The same three lists for the non-text section. Its bar is flat, so every floor is the same. */
+const uiCases = casesFor(NON_TEXT_PAIRS, () => UI_COMPONENT);
+const meetsUi = uiCases.filter(({ key }) => !BELOW_UI.has(key));
+const uiGaps = uiCases.filter(({ key }) => BELOW_UI.has(key));
+
 describe("token sheet text contrast", () => {
   it("measures a known ratio correctly", () => {
     // The calculator itself needs a fixture, or a subtly wrong exponent would move every
@@ -162,11 +244,14 @@ describe("token sheet text contrast", () => {
     expect(contrastRatio("#767676", "#ffffff")).toBeCloseTo(4.5422, 4);
   });
 
-  it("gives every pairing a unique id", () => {
+  it("gives every pairing a unique id, across both sections", () => {
     // The id is the ratchet key and the manifest's handle. A duplicate would silently make
     // one pairing's allowance apply to another, and labels cannot substitute — they repeat
     // across the primitive and semantic layers on purpose.
-    const ids = TEXT_PAIRS.map((pair) => pair.id);
+    //
+    // Both sections at once, because the two ratchets key the same way: `light/x` has to name
+    // one pairing whichever table it appears in, or an allowance would apply the wrong bar.
+    const ids = [...TEXT_PAIRS, ...NON_TEXT_PAIRS].map((pair) => pair.id);
     expect(ids.filter((id) => !id)).toEqual([]);
     expect(new Set(ids).size).toBe(ids.length);
   });
@@ -242,3 +327,69 @@ describe("token sheet text contrast", () => {
     },
   );
 });
+
+describe("token sheet non-text contrast", () => {
+  it("declares no pairing the text section already holds to a stricter bar", () => {
+    // The guard this section was one review away from needing. `focus-ring-on-surface` shipped
+    // here naming --color-fg-accent on --color-bg-surface, which is exactly what the text
+    // pairing `accent-on-surface` already holds to 4.5 — so the non-text case could never fail
+    // unless the stricter one had failed first, and its only effect was to make the section
+    // look like it covered one surface more than it did. The ring on a card is still measured;
+    // it is measured by the entry that would go red first.
+    //
+    // Compared on token NAMES rather than values on purpose: `body-on-card` and
+    // `body-on-surface` resolve to identical values in every theme and are both declared,
+    // because a theme author retargeting the semantic alias needs the alias measured too. That
+    // is the file working as intended; two names for one pair inside one bar is not.
+    const textPairKeys = new Set(TEXT_PAIRS.map((pair) => `${pair.fg} on ${pair.bg}`));
+    const restated = NON_TEXT_PAIRS.filter((pair) =>
+      textPairKeys.has(`${pair.fg} on ${pair.bg}`),
+    ).map((pair) => pair.id);
+    expect(restated).toEqual([]);
+  });
+
+  it("covers every registered theme once per pairing", () => {
+    // Narrower than its namesake in the text suite on purpose: that one also proves each theme
+    // RESOLVED, which is the failure mode that looks like coverage, and it proves it for the
+    // shared THEMES map this suite reads. Re-asserting it here would be a second copy of one
+    // fact. What is not covered there is the empty-list case — with no pairings the count check
+    // would read 0 === 0 and pass — so that is the assertion this one adds.
+    expect(NON_TEXT_PAIRS.length).toBeGreaterThan(0);
+    expect(uiCases).toHaveLength(registry.themes.length * NON_TEXT_PAIRS.length);
+  });
+
+  it("holds every pairing in exactly one of the two sets", () => {
+    expect(meetsUi.length + uiGaps.length).toBe(uiCases.length);
+    expect(uiGaps).toHaveLength(BELOW_UI.size);
+    const known = new Set(uiCases.map(({ key }) => key));
+    expect([...BELOW_UI.keys()].filter((key) => !known.has(key))).toEqual([]);
+    expect([...BELOW_UI.keys()]).toEqual([...BELOW_UI.keys()].sort());
+  });
+
+  it("lets the allowance name the control boundary and nothing else", () => {
+    // The one guard that keeps this from becoming a general amnesty. BELOW_AA restricts its
+    // allowance by THEME, which works there because a new theme has no excuse to ship below AA.
+    // That reasoning does not transfer: this defect is one token value that every palette
+    // inherited, so it shows up in themes that postdate the gate through no fault of their own.
+    // Restricting by PAIRING instead says the same thing the theme rule says — no new debt —
+    // without pretending the existing debt is older than it is.
+    const idOf = (key) => key.slice(key.indexOf("/") + 1);
+    expect([...BELOW_UI.keys()].filter((key) => !CONTROL_BOUNDARY_IDS.includes(idOf(key)))).toEqual(
+      [],
+    );
+  });
+
+  it.each(meetsUi)("$theme: $id ($label) reaches $floor:1 as a non-text pairing", (testCase) => {
+    const { ratio, painted } = measure(testCase);
+    expect(ratio, painted).toBeGreaterThanOrEqual(testCase.floor);
+  });
+
+  it.each(uiGaps)("$theme: $id ($label) is a known non-text gap, held at its floor", (testCase) => {
+    const { ratio, painted } = measure(testCase);
+    const floor = BELOW_UI.get(testCase.key);
+    expect(ratio, `${painted} regressed below its recorded floor`).toBeGreaterThanOrEqual(floor);
+    expect(ratio, `${painted} now reaches 3:1 — remove it from BELOW_UI`).toBeLessThan(
+      UI_COMPONENT,
+    );
+  });
+});

package/src/tokens.css

@@ -39,7 +39,6 @@
   --color-fg-muted: #475569;
   --color-fg-subtle: #64748b;
   --color-fg-accent: #1d4ed8;
-  --color-fg-on-brand: #ffffff;
   --color-border-default: #e2e8f0;
   --color-border-strong: #cbd5e1;
   --color-border-subtle: #f1f5f9;
@@ -72,6 +71,12 @@
   --space-12: 3rem;
   --space-16: 4rem;
   --space-20: 5rem;
+  --density-control-min-height: 2.25rem;
+  --density-cell-pad-y: 0.75rem;
+  --density-cell-pad-x: 0.75rem;
+  --density-compact-control-min-height: 2rem;
+  --density-compact-cell-pad-y: 0.5rem;
+  --density-compact-cell-pad-x: 0.5rem;
   --radius-sm: 0.25rem;
   --radius-md: 0.5rem;
   --radius-lg: 0.75rem;
@@ -157,7 +162,6 @@
   --color-fg-muted: #b4c0d0;
   --color-fg-subtle: #94a3b8;
   --color-fg-accent: #60a5fa;
-  --color-fg-on-brand: #ffffff;
   --color-border-default: #334155;
   --color-border-strong: #475569;
   --color-border-subtle: #263449;
@@ -212,7 +216,6 @@
   --color-fg-muted: #9aa4b2;
   --color-fg-subtle: #8b949e;
   --color-fg-accent: #58a6ff;
-  --color-fg-on-brand: #ffffff;
   --color-border-default: #30363d;
   --color-border-strong: #484f58;
   --color-border-subtle: #21262d;
@@ -267,7 +270,6 @@
   --color-fg-muted: #b9aecd;
   --color-fg-subtle: #a294bd;
   --color-fg-accent: #a78bfa;
-  --color-fg-on-brand: #ffffff;
   --color-border-default: #3a3350;
   --color-border-strong: #4d4468;
   --color-border-subtle: #2d2740;
@@ -322,7 +324,6 @@
   --color-fg-muted: #141414;
   --color-fg-subtle: #1f1f1f;
   --color-fg-accent: #0842a0;
-  --color-fg-on-brand: #ffffff;
   --color-border-default: #595959;
   --color-border-strong: #000000;
   --color-border-subtle: #767676;
@@ -377,7 +378,6 @@
     --color-fg-muted: #b4c0d0;
     --color-fg-subtle: #94a3b8;
     --color-fg-accent: #60a5fa;
-    --color-fg-on-brand: #ffffff;
     --color-border-default: #334155;
     --color-border-strong: #475569;
     --color-border-subtle: #263449;

package/src/tokens.manifest.json

@@ -419,18 +419,6 @@
       },
       "themeable": true
     },
-    {
-      "name": "--color-fg-on-brand",
-      "category": "color",
-      "values": {
-        "light": "#ffffff",
-        "dark": "#ffffff",
-        "midnight": "#ffffff",
-        "twilight": "#ffffff",
-        "contrast": "#ffffff"
-      },
-      "themeable": true
-    },
     {
       "name": "--color-border-default",
       "category": "color",
@@ -751,6 +739,54 @@
       },
       "themeable": false
     },
+    {
+      "name": "--density-control-min-height",
+      "category": "density",
+      "values": {
+        "light": "2.25rem"
+      },
+      "themeable": false
+    },
+    {
+      "name": "--density-cell-pad-y",
+      "category": "density",
+      "values": {
+        "light": "0.75rem"
+      },
+      "themeable": false
+    },
+    {
+      "name": "--density-cell-pad-x",
+      "category": "density",
+      "values": {
+        "light": "0.75rem"
+      },
+      "themeable": false
+    },
+    {
+      "name": "--density-compact-control-min-height",
+      "category": "density",
+      "values": {
+        "light": "2rem"
+      },
+      "themeable": false
+    },
+    {
+      "name": "--density-compact-cell-pad-y",
+      "category": "density",
+      "values": {
+        "light": "0.5rem"
+      },
+      "themeable": false
+    },
+    {
+      "name": "--density-compact-cell-pad-x",
+      "category": "density",
+      "values": {
+        "light": "0.5rem"
+      },
+      "themeable": false
+    },
     {
       "name": "--radius-sm",
       "category": "radius",
@@ -1248,6 +1284,13 @@
       "bg": "--color-brand-primary-soft",
       "layer": "semantic"
     },
+    {
+      "id": "muted-on-soft",
+      "label": "muted text on the accent wash",
+      "fg": "--color-fg-muted",
+      "bg": "--color-brand-primary-soft",
+      "layer": "semantic"
+    },
     {
       "id": "sidebar-text",
       "label": "sidebar text",
@@ -1261,6 +1304,113 @@
       "fg": "--color-sidebar-muted",
       "bg": "--color-sidebar-bg",
       "layer": "semantic"
+    },
+    {
+      "id": "muted-on-tone-neutral",
+      "label": "muted text on a neutral-toned row or card",
+      "fg": "--color-fg-muted",
+      "bg": "--color-neutral-100",
+      "layer": "semantic"
+    },
+    {
+      "id": "muted-on-tone-info",
+      "label": "muted text on an info-toned row or card",
+      "fg": "--color-fg-muted",
+      "bg": "--color-status-info-soft",
+      "layer": "semantic"
+    },
+    {
+      "id": "muted-on-tone-success",
+      "label": "muted text on a success-toned row or card",
+      "fg": "--color-fg-muted",
+      "bg": "--color-status-success-soft",
+      "layer": "semantic"
+    },
+    {
+      "id": "muted-on-tone-warning",
+      "label": "muted text on a warning-toned row or card",
+      "fg": "--color-fg-muted",
+      "bg": "--color-status-warning-soft",
+      "layer": "semantic"
+    },
+    {
+      "id": "muted-on-tone-danger",
+      "label": "muted text on a danger-toned row or card",
+      "fg": "--color-fg-muted",
+      "bg": "--color-status-danger-soft",
+      "layer": "semantic"
+    }
+  ],
+  "nonTextPairs": [
+    {
+      "id": "focus-ring-on-canvas",
+      "label": "the focus indicator on the canvas",
+      "fg": "--color-fg-accent",
+      "bg": "--color-bg-canvas",
+      "layer": "semantic"
+    },
+    {
+      "id": "active-toggle-border",
+      "label": "the border marking which layout toggle is active",
+      "fg": "--color-fg-accent",
+      "bg": "--color-neutral-100",
+      "layer": "semantic"
+    },
+    {
+      "id": "subtle-glyph-on-tone-neutral",
+      "label": "an icon button's glyph on a neutral wash",
+      "fg": "--color-fg-subtle",
+      "bg": "--color-neutral-100",
+      "layer": "semantic"
+    },
+    {
+      "id": "subtle-glyph-on-tone-info",
+      "label": "an icon button's glyph on an info row",
+      "fg": "--color-fg-subtle",
+      "bg": "--color-status-info-soft",
+      "layer": "semantic"
+    },
+    {
+      "id": "subtle-glyph-on-tone-success",
+      "label": "an icon button's glyph on a success row",
+      "fg": "--color-fg-subtle",
+      "bg": "--color-status-success-soft",
+      "layer": "semantic"
+    },
+    {
+      "id": "subtle-glyph-on-tone-warning",
+      "label": "an icon button's glyph on a warning row",
+      "fg": "--color-fg-subtle",
+      "bg": "--color-status-warning-soft",
+      "layer": "semantic"
+    },
+    {
+      "id": "subtle-glyph-on-tone-danger",
+      "label": "an icon button's glyph on a danger row",
+      "fg": "--color-fg-subtle",
+      "bg": "--color-status-danger-soft",
+      "layer": "semantic"
+    },
+    {
+      "id": "subtle-glyph-on-focus-wash",
+      "label": "an icon button's glyph on a focused clickable row",
+      "fg": "--color-fg-subtle",
+      "bg": "--color-brand-primary-soft",
+      "layer": "semantic"
+    },
+    {
+      "id": "control-boundary-on-surface",
+      "label": "a control's outline on a card",
+      "fg": "--color-neutral-300",
+      "bg": "--color-neutral-0",
+      "layer": "primitive"
+    },
+    {
+      "id": "control-boundary-on-canvas",
+      "label": "a control's outline on the canvas",
+      "fg": "--color-neutral-300",
+      "bg": "--color-neutral-50",
+      "layer": "primitive"
     }
   ]
 }

package/src/tokens.manifest.test.js

@@ -132,10 +132,27 @@ describe("token manifest", () => {
     // The manifest is a claim about what is guaranteed; the gate is what guarantees it. If
     // the two lists could differ, the published claim would be unverified.
     expect(manifest.textPairs).toEqual(pairsSource.textPairs);
+    expect(manifest.nonTextPairs).toEqual(pairsSource.nonTextPairs);
+  });
+
+  it("publishes both sections, so a missing one cannot read as no requirement", () => {
+    // `nonTextPairs` reached the manifest by being added to the builder's literal, which is a
+    // line that can be deleted without any other test noticing: a consumer would then see only
+    // the text pairings and read the absence of a boundary pairing as "nothing is required
+    // here" rather than "held in a section you were not given". Both sections are named
+    // explicitly rather than derived, because deriving them from the source file is what the
+    // assertion above already does — this one is about the shape the package publishes.
+    expect(Array.isArray(manifest.textPairs)).toBe(true);
+    expect(Array.isArray(manifest.nonTextPairs)).toBe(true);
+    expect(manifest.nonTextPairs.length).toBeGreaterThan(0);
   });
 
   it("references only tokens that exist, in both directions of every pairing", () => {
-    for (const pair of manifest.textPairs) {
+    // Both sections. A typo in a token name is the failure this catches, and it is the only
+    // check that catches it for a pairing naming a token the sheet declares nowhere — the
+    // contrast gate would report it as an undefined declaration, which reads as a sheet
+    // problem rather than as a pairing problem.
+    for (const pair of [...manifest.textPairs, ...manifest.nonTextPairs]) {
       expect(tokenByName.has(pair.fg), `${pair.id} fg ${pair.fg}`).toBe(true);
       expect(tokenByName.has(pair.bg), `${pair.id} bg ${pair.bg}`).toBe(true);
     }

package/token-pairs.json

@@ -1,5 +1,5 @@
 {
-  "$comment": "Foreground/background pairings the framework renders as text, as data. Two consumers read this: tokens.contrast.test.js holds each pairing to WCAG 2.1 AA, and the generated token manifest publishes them so a theme editor or an agent can tell which tokens must stay legible against which. Decorative boundaries are deliberately absent — WCAG sets no ratio for a divider, and asserting one would teach the next reader to ignore this file. Names are CSS custom properties because that is the vocabulary a theme author writes and a manifest consumer reads.",
+  "$comment": "Token pairings the framework renders, as data, in two sections held to two different bars. `textPairs` are foreground/background pairs painted as TEXT and held to WCAG 2.1 AA for normal text; `nonTextPairs` are the visual boundaries and state indicators SC 1.4.11 asks 3:1 of — a focus indicator, the border that says which control is active, the outline of a control against its surface. Two consumers read both: tokens.contrast.test.js measures each pairing at its own bar, and the generated token manifest publishes them so a theme editor or an agent can tell which tokens must stay legible against which. A pair of token names appears in one section only: the text bar is the stricter of the two, so restating a text pairing under a non-text name would add a case that cannot fail unless the stricter one already has, and would overstate how much the ratchets cover. Purely decorative marks stay absent from both sections — WCAG sets no ratio for a divider or for an aria-hidden ornament, and asserting one would teach the next reader to ignore this file. Names are CSS custom properties because that is the vocabulary a theme author writes and a manifest consumer reads.",
   "textPairs": [
     {
       "id": "body-on-card",
@@ -120,6 +120,13 @@
       "bg": "--color-brand-primary-soft",
       "layer": "semantic"
     },
+    {
+      "id": "muted-on-soft",
+      "label": "muted text on the accent wash",
+      "fg": "--color-fg-muted",
+      "bg": "--color-brand-primary-soft",
+      "layer": "semantic"
+    },
     {
       "id": "sidebar-text",
       "label": "sidebar text",
@@ -133,6 +140,113 @@
       "fg": "--color-sidebar-muted",
       "bg": "--color-sidebar-bg",
       "layer": "semantic"
+    },
+    {
+      "id": "muted-on-tone-neutral",
+      "label": "muted text on a neutral-toned row or card",
+      "fg": "--color-fg-muted",
+      "bg": "--color-neutral-100",
+      "layer": "semantic"
+    },
+    {
+      "id": "muted-on-tone-info",
+      "label": "muted text on an info-toned row or card",
+      "fg": "--color-fg-muted",
+      "bg": "--color-status-info-soft",
+      "layer": "semantic"
+    },
+    {
+      "id": "muted-on-tone-success",
+      "label": "muted text on a success-toned row or card",
+      "fg": "--color-fg-muted",
+      "bg": "--color-status-success-soft",
+      "layer": "semantic"
+    },
+    {
+      "id": "muted-on-tone-warning",
+      "label": "muted text on a warning-toned row or card",
+      "fg": "--color-fg-muted",
+      "bg": "--color-status-warning-soft",
+      "layer": "semantic"
+    },
+    {
+      "id": "muted-on-tone-danger",
+      "label": "muted text on a danger-toned row or card",
+      "fg": "--color-fg-muted",
+      "bg": "--color-status-danger-soft",
+      "layer": "semantic"
+    }
+  ],
+  "nonTextPairs": [
+    {
+      "id": "focus-ring-on-canvas",
+      "label": "the focus indicator on the canvas",
+      "fg": "--color-fg-accent",
+      "bg": "--color-bg-canvas",
+      "layer": "semantic"
+    },
+    {
+      "id": "active-toggle-border",
+      "label": "the border marking which layout toggle is active",
+      "fg": "--color-fg-accent",
+      "bg": "--color-neutral-100",
+      "layer": "semantic"
+    },
+    {
+      "id": "subtle-glyph-on-tone-neutral",
+      "label": "an icon button's glyph on a neutral wash",
+      "fg": "--color-fg-subtle",
+      "bg": "--color-neutral-100",
+      "layer": "semantic"
+    },
+    {
+      "id": "subtle-glyph-on-tone-info",
+      "label": "an icon button's glyph on an info row",
+      "fg": "--color-fg-subtle",
+      "bg": "--color-status-info-soft",
+      "layer": "semantic"
+    },
+    {
+      "id": "subtle-glyph-on-tone-success",
+      "label": "an icon button's glyph on a success row",
+      "fg": "--color-fg-subtle",
+      "bg": "--color-status-success-soft",
+      "layer": "semantic"
+    },
+    {
+      "id": "subtle-glyph-on-tone-warning",
+      "label": "an icon button's glyph on a warning row",
+      "fg": "--color-fg-subtle",
+      "bg": "--color-status-warning-soft",
+      "layer": "semantic"
+    },
+    {
+      "id": "subtle-glyph-on-tone-danger",
+      "label": "an icon button's glyph on a danger row",
+      "fg": "--color-fg-subtle",
+      "bg": "--color-status-danger-soft",
+      "layer": "semantic"
+    },
+    {
+      "id": "subtle-glyph-on-focus-wash",
+      "label": "an icon button's glyph on a focused clickable row",
+      "fg": "--color-fg-subtle",
+      "bg": "--color-brand-primary-soft",
+      "layer": "semantic"
+    },
+    {
+      "id": "control-boundary-on-surface",
+      "label": "a control's outline on a card",
+      "fg": "--color-neutral-300",
+      "bg": "--color-neutral-0",
+      "layer": "primitive"
+    },
+    {
+      "id": "control-boundary-on-canvas",
+      "label": "a control's outline on the canvas",
+      "fg": "--color-neutral-300",
+      "bg": "--color-neutral-50",
+      "layer": "primitive"
     }
   ]
 }

package/tokens.contrast.json

@@ -40,8 +40,7 @@
       "default": { "value": "#000000" },
       "muted": { "value": "#141414" },
       "subtle": { "value": "#1f1f1f" },
-      "accent": { "value": "#0842a0" },
-      "onBrand": { "value": "#ffffff" }
+      "accent": { "value": "#0842a0" }
     },
     "border": {
       "default": { "value": "#595959" },

package/tokens.dark.json

@@ -40,8 +40,7 @@
       "default": { "value": "#f1f5f9" },
       "muted": { "value": "#b4c0d0" },
       "subtle": { "value": "#94a3b8" },
-      "accent": { "value": "#60a5fa" },
-      "onBrand": { "value": "#ffffff" }
+      "accent": { "value": "#60a5fa" }
     },
     "border": {
       "default": { "value": "#334155" },

package/tokens.json

@@ -40,8 +40,7 @@
       "default": { "value": "#0f172a" },
       "muted": { "value": "#475569" },
       "subtle": { "value": "#64748b" },
-      "accent": { "value": "#1d4ed8" },
-      "onBrand": { "value": "#ffffff" }
+      "accent": { "value": "#1d4ed8" }
     },
     "border": {
       "default": { "value": "#e2e8f0" },
@@ -88,6 +87,24 @@
     "16": { "value": "4rem" },
     "20": { "value": "5rem" }
   },
+  "density": {
+    "control": {
+      "minHeight": { "value": "2.25rem" }
+    },
+    "cell": {
+      "padY": { "value": "0.75rem" },
+      "padX": { "value": "0.75rem" }
+    },
+    "compact": {
+      "control": {
+        "minHeight": { "value": "2rem" }
+      },
+      "cell": {
+        "padY": { "value": "0.5rem" },
+        "padX": { "value": "0.5rem" }
+      }
+    }
+  },
   "radius": {
     "sm": { "value": "0.25rem" },
     "md": { "value": "0.5rem" },

package/tokens.midnight.json

@@ -40,8 +40,7 @@
       "default": { "value": "#f0f6fc" },
       "muted": { "value": "#9aa4b2" },
       "subtle": { "value": "#8b949e" },
-      "accent": { "value": "#58a6ff" },
-      "onBrand": { "value": "#ffffff" }
+      "accent": { "value": "#58a6ff" }
     },
     "border": {
       "default": { "value": "#30363d" },

package/tokens.twilight.json

@@ -40,8 +40,7 @@
       "default": { "value": "#f6f3fa" },
       "muted": { "value": "#b9aecd" },
       "subtle": { "value": "#a294bd" },
-      "accent": { "value": "#a78bfa" },
-      "onBrand": { "value": "#ffffff" }
+      "accent": { "value": "#a78bfa" }
     },
     "border": {
       "default": { "value": "#3a3350" },