@terpjs/contract 0.6.1 → 0.8.0

package/src/tokens.manifest.test.js

@@ -0,0 +1,166 @@
+import fs from "node:fs";
+import { fileURLToPath } from "node:url";
+
+import { describe, expect, it } from "vitest";
+
+import { parseRules } from "./css-rules.js";
+
+// The published token manifest: the same tokens as machine-readable data.
+//
+// It exists because three consumers could not get the list any other way. A theme editor had
+// to hard-code its own copy — `tokens.json` is Style-Dictionary-shaped and was never exported
+// from the package, only the compiled CSS was. An agent editing a theme had to infer names
+// from whatever it found in `node_modules`, with no way to tell which tokens are safe to theme
+// or which must stay legible against which. A human had no list at all.
+//
+// A manifest that disagrees with the stylesheet beside it is worse than none, because it is
+// the copy a tool trusts. So it is generated in the same run from the same sources, and these
+// tests hold the two together.
+
+const here = (name) => fileURLToPath(new URL(name, import.meta.url));
+
+const manifest = JSON.parse(fs.readFileSync(here("./tokens.manifest.json"), "utf8"));
+const tokensCss = fs.readFileSync(here("./tokens.css"), "utf8");
+const pairsSource = JSON.parse(fs.readFileSync(here("../token-pairs.json"), "utf8"));
+const registry = JSON.parse(fs.readFileSync(here("../themes.json"), "utf8"));
+
+const rules = parseRules(tokensCss);
+const declarationsFor = (selector) =>
+  rules.find((rule) => rule.selector === selector).declarations;
+const base = declarationsFor(":root");
+
+/** Each theme's own block: the base on `:root`, every other on its attribute selector. */
+const blocks = new Map(
+  registry.themes.map((theme) => [
+    theme.name,
+    theme.name === registry.base ? base : declarationsFor(`[data-theme='${theme.name}']`),
+  ]),
+);
+
+const tokenByName = new Map(manifest.tokens.map((token) => [token.name, token]));
+
+describe("token manifest", () => {
+  it("names exactly the tokens the base root declares", () => {
+    // Either direction is a real failure: a token missing from the manifest is invisible to
+    // every tool that reads it, and a token in the manifest that the sheet does not declare
+    // is a control that would silently do nothing.
+    const manifestNames = manifest.tokens.map((token) => token.name).sort();
+    expect(manifestNames).toEqual([...base.keys()].sort());
+  });
+
+  it("publishes the theme list the sheet was generated from", () => {
+    // This is the list a consumer builds a theme picker from, and the set of keys a `values`
+    // map is allowed to use. A manifest naming a theme the sheet has no block for would hand
+    // a tool a theme it cannot apply.
+    expect(manifest.base).toBe(registry.base);
+    expect(manifest.systemDark).toBe(registry.systemDark);
+    expect(manifest.themes).toEqual(
+      registry.themes.map(({ name, label, appearance, description }) => ({
+        name,
+        label,
+        appearance,
+        description,
+      })),
+    );
+    for (const theme of manifest.themes) {
+      expect(blocks.has(theme.name), `${theme.name} has no block in the sheet`).toBe(true);
+    }
+  });
+
+  it("records the value each token resolves to, in every theme", () => {
+    // `values` carries only the themes that declare the token; a theme absent from it inherits
+    // the base value. That is the cascade stated as data, so both halves are checked: a
+    // recorded value must match the theme's own block, and an omission must mean the block
+    // really does not declare it.
+    for (const token of manifest.tokens) {
+      for (const [name, block] of blocks) {
+        const recorded = token.values[name];
+        if (recorded === undefined) {
+          expect(
+            block.has(token.name),
+            `${token.name} is omitted for ${name} but ${name} declares it`,
+          ).toBe(false);
+        } else {
+          expect(recorded, `${token.name} in ${name}`).toBe(block.get(token.name));
+        }
+      }
+      // The base value is never omitted: it is what every other theme falls back to.
+      expect(token.values[registry.base], `${token.name} base value`).toBe(
+        base.get(token.name),
+      );
+      expect(Object.keys(token.values)[0], `${token.name} value order`).toBe(registry.base);
+    }
+  });
+
+  it("names no theme in a values map that the theme list omits", () => {
+    const known = new Set(manifest.themes.map((theme) => theme.name));
+    for (const token of manifest.tokens) {
+      expect(
+        Object.keys(token.values).filter((name) => !known.has(name)),
+        token.name,
+      ).toEqual([]);
+    }
+  });
+
+  it("marks a token themeable exactly when some non-base theme overrides it", () => {
+    // This is the flag an editor uses to decide whether to offer a per-theme control, so
+    // getting it wrong means either a missing control or one that has no effect.
+    const overlays = registry.themes.filter((theme) => theme.name !== registry.base);
+    for (const token of manifest.tokens) {
+      const overridden = overlays.some((theme) => blocks.get(theme.name).has(token.name));
+      expect(token.themeable, `${token.name} themeable`).toBe(overridden);
+      // Geometry is declared once and inherited, so a non-themeable token carries exactly one
+      // value. A themeable one carries every theme's, because each theme is a full colour set.
+      expect(Object.keys(token.values), `${token.name} values`).toHaveLength(
+        overridden ? registry.themes.length : 1,
+      );
+    }
+  });
+
+  it("gives every token a category from its source family", () => {
+    // `zIndex.base` flattens to `--z-index-base`; splitting the CSS name would call its
+    // family `z`, which is why the category comes from the source tree instead.
+    const categories = new Set(manifest.tokens.map((token) => token.category));
+    expect(categories.has("z")).toBe(false);
+    expect(categories.has("zIndex")).toBe(true);
+    for (const token of manifest.tokens) {
+      expect(token.category, token.name).toBeTruthy();
+    }
+  });
+
+  it("publishes the pairings the contrast gate enforces, unchanged", () => {
+    // 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", () => {
+    // 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);
+    }
+  });
+
+  it("says it is generated", () => {
+    // The file is committed, so the next person to open it needs to know editing it is futile.
+    expect(manifest.$comment).toContain("Generated");
+    expect(manifest.$comment).toContain("build-tokens.mjs");
+  });
+});

package/src/tokens.themes.test.js

@@ -0,0 +1,177 @@
+import fs from "node:fs";
+import { fileURLToPath } from "node:url";
+
+import { describe, expect, it } from "vitest";
+
+import { parseRules } from "./css-rules.js";
+
+// The token sheet's theme structure. `tokens.guard.test.ts` in react-core proves every
+// `var(--x)` names a property the sheet declares *somewhere*; that is a spelling check and
+// it is blind to which block declares what. This file proves the blocks agree.
+//
+// Five shapes have to hold, and each one fails silently in the browser rather than
+// loudly at build time — which is why they are gates and not review items:
+//
+//   1. A colour a theme forgets falls through to the base value, so one element renders
+//      light-on-light under a dark theme. Every theme is a full set of colours, and the
+//      sheet has one block per theme plus the `prefers-color-scheme` copy of the OS dark
+//      theme, so a new colour has as many places to land as there are themes.
+//   2. The OS-preference block is duplicated from the `systemDark` theme by the generator.
+//      Drift between them means the OS preference and the explicit toggle disagree — the same
+//      app renders two different darks depending on how the user got there.
+//   3. Geometry (space, radius, font, shadow) is deliberately declared once, in `:root`,
+//      and inherited by every theme. That is the correct cascade and it must stay
+//      that way: a `--space-4` that appears in one theme only is a theme that
+//      silently re-spaces itself.
+//   4. Every theme declares `color-scheme` matching its declared appearance, or native chrome
+//      the framework cannot restyle — the `<select>` popup, a native scrollbar, a caret —
+//      renders from the wrong palette.
+//   5. The OS-preference block must not match a root that pinned a theme. This is the one
+//      that was a live defect: the selector was `:root:not([data-theme='light'])`, which was
+//      equivalent while light and dark were the only themes, and which outranks
+//      `[data-theme='contrast']` on specificity — so pinning any theme other than light got
+//      the dark colours laid over it whenever the OS preferred dark.
+//
+// Regenerate the sheet with `npm run -w @terpjs/contract tokens` after editing `themes.json`
+// or any theme source; CI diffs the result, so these tests and the committed artifact move
+// together.
+
+const here = (name) => fileURLToPath(new URL(name, import.meta.url));
+
+const tokensCss = fs.readFileSync(here("./tokens.css"), "utf8");
+const registry = JSON.parse(fs.readFileSync(here("../themes.json"), "utf8"));
+
+const BASE = registry.themes.find((theme) => theme.name === registry.base);
+const OVERLAYS = registry.themes.filter((theme) => theme.name !== registry.base);
+
+/** The base theme lives on `:root`; every other theme on its own attribute selector. */
+const BASE_SELECTOR = ":root";
+const selectorFor = (theme) => `[data-theme='${theme.name}']`;
+/** The `@media (prefers-color-scheme: dark)` copy of the `systemDark` theme. */
+const SYSTEM_DARK_SELECTOR = ":root:not([data-theme])";
+
+const rules = parseRules(tokensCss);
+
+/** The one rule whose selector is exactly `selector`. */
+function ruleFor(selector) {
+  const matches = rules.filter((rule) => rule.selector === selector);
+  if (matches.length !== 1) {
+    throw new Error(
+      `expected exactly one \`${selector}\` rule in tokens.css, found ${matches.length}`,
+    );
+  }
+  return matches[0];
+}
+
+const declarationsFor = (selector) => ruleFor(selector).declarations;
+
+const base = declarationsFor(BASE_SELECTOR);
+const isColour = (token) => token.startsWith("--color-");
+
+/** Every theme block that is a set of colour overrides — i.e. all but the base. */
+const overlayCases = OVERLAYS.map((theme) => ({
+  ...theme,
+  selector: selectorFor(theme),
+}));
+
+describe("token sheet themes", () => {
+  it("parses the sheet it is asserting about", () => {
+    // A parser that silently found nothing would make every test below vacuously true, and a
+    // theme in the registry that the generator never emitted would make its own cases vanish
+    // rather than fail — so the selector list is asserted whole, in order.
+    expect(rules.map((rule) => rule.selector)).toEqual([
+      BASE_SELECTOR,
+      ...OVERLAYS.map(selectorFor),
+      SYSTEM_DARK_SELECTOR,
+    ]);
+    expect(base.size).toBeGreaterThan(0);
+    expect([...base.keys()].filter(isColour).length).toBeGreaterThan(0);
+  });
+
+  it("ships more than a light and a dark theme", () => {
+    // The point of the semantic token layer is that a third theme is expressible without
+    // re-deriving every mapping by hand. One that ships only light and dark has not been
+    // proven, so this holds the floor the layer was built to clear.
+    expect(registry.themes.length).toBeGreaterThanOrEqual(3);
+    const appearances = new Set(registry.themes.map((theme) => theme.appearance));
+    // Both polarities represented: a set of dark variants would not exercise the layer any
+    // harder than dark alone did.
+    expect([...appearances].sort()).toEqual(["dark", "light"]);
+  });
+
+  it("registers every theme source that exists on disk", () => {
+    // A `tokens.<name>.json` nobody registered compiles to nothing and is invisible: no
+    // block, no gate, no manifest entry. Registration is explicit on purpose, so the failure
+    // mode is a file that silently does nothing rather than a stray file becoming a theme.
+    const registered = new Set(registry.themes.map((theme) => theme.source));
+    const onDisk = fs
+      .readdirSync(here(".."))
+      .filter((name) => /^tokens(\.[a-z0-9-]+)?\.json$/.test(name));
+    expect(onDisk.filter((name) => !registered.has(name))).toEqual([]);
+  });
+
+  it.each(overlayCases)("declares every base colour in $selector", ({ selector }) => {
+    // A colour the theme omits inherits the base value: one light-on-light element.
+    const theme = declarationsFor(selector);
+    const missing = [...base.keys()].filter(
+      (token) => isColour(token) && !theme.has(token),
+    );
+    expect(missing).toEqual([]);
+  });
+
+  it.each(overlayCases)("declares no token the base omits in $selector", ({ selector }) => {
+    // A theme-only token has no base value to fall back to, so the base render is the one
+    // that breaks — and `tokens.guard.test.ts` cannot see it, because the token *is*
+    // declared somewhere in the sheet.
+    const theme = declarationsFor(selector);
+    const orphans = [...theme.keys()].filter((token) => !base.has(token));
+    expect(orphans).toEqual([]);
+  });
+
+  it.each(overlayCases)("leaves geometry to the base root in $selector", ({ selector }) => {
+    // Space, radius, font and shadow are theme-invariant by design: declared once and
+    // inherited. Re-declaring one in a single theme is how a theme quietly grows its
+    // own spacing scale.
+    const theme = declarationsFor(selector);
+    const geometry = [...theme.keys()].filter((token) => !isColour(token));
+    expect(geometry).toEqual([]);
+  });
+
+  it.each([{ name: BASE.name, appearance: BASE.appearance, selector: BASE_SELECTOR }, ...overlayCases])(
+    "opts native chrome into the $appearance palette in $selector",
+    ({ appearance, selector }) => {
+      // Without `color-scheme`, native chrome the framework cannot restyle stays in OS-light
+      // rendering under a dark theme — a white `<select>` popup over a black page.
+      expect(ruleFor(selector).properties.get("color-scheme")).toBe(appearance);
+    },
+  );
+
+  it("copies the systemDark theme into the OS-preference block verbatim", () => {
+    // They are generated from one source and duplicated. Drift means the OS preference and
+    // the explicit toggle render different darks in the same app.
+    const systemDark = registry.themes.find((theme) => theme.name === registry.systemDark);
+    expect(systemDark, `systemDark "${registry.systemDark}" must be a registered theme`).toBeDefined();
+    const explicit = declarationsFor(selectorFor(systemDark));
+    const byPreference = declarationsFor(SYSTEM_DARK_SELECTOR);
+    expect([...byPreference.entries()]).toEqual([...explicit.entries()]);
+    expect(ruleFor(SYSTEM_DARK_SELECTOR).properties.get("color-scheme")).toBe(
+      systemDark.appearance,
+    );
+  });
+
+  it("lets the OS preference apply only to a root with no theme pinned", () => {
+    // The defect a third theme exposed. `:root:not([data-theme='light'])` matches
+    // `[data-theme='contrast']` and beats it on specificity, so an app that pinned a theme
+    // got the OS dark colours laid over it. Matching the *absence* of the attribute is the
+    // only form that stays correct as themes are added, so it is pinned here by shape rather
+    // than left to the generator's comment.
+    const guarded = rules.filter((rule) => rule.selector === SYSTEM_DARK_SELECTOR);
+    expect(guarded).toHaveLength(1);
+    for (const theme of registry.themes) {
+      expect(
+        SYSTEM_DARK_SELECTOR.includes(`'${theme.name}'`),
+        `the OS-preference selector must not name the ${theme.name} theme`,
+      ).toBe(false);
+    }
+  });
+});

package/themes.json

@@ -0,0 +1,43 @@
+{
+  "$comment": "The shipped themes, as data. `scripts/build-tokens.mjs` compiles one stylesheet block per entry and publishes the same list in the token manifest; `src/tokens.themes.test.js` holds every entry to completeness and `src/tokens.contrast.test.js` holds every entry to WCAG AA, or to `minimumContrast` where an entry sets a higher floor. Registration is explicit rather than a glob over `tokens.*.json`, because four things about a theme cannot be inferred from its file: which theme the OS dark preference selects, whether a theme reads as light or dark to native chrome, what contrast it promises, and what to call it. A theme is added by writing its overlay and adding it here — nothing else, and the gates refuse it if the overlay is incomplete or illegible.",
+  "base": "light",
+  "systemDark": "dark",
+  "themes": [
+    {
+      "name": "light",
+      "label": "Light",
+      "appearance": "light",
+      "source": "tokens.json",
+      "description": "The default. Carries every token, including the geometry the other themes inherit."
+    },
+    {
+      "name": "dark",
+      "label": "Dark",
+      "appearance": "dark",
+      "source": "tokens.dark.json",
+      "description": "The slate-neutral dark counterpart to light, and the theme the OS dark preference selects."
+    },
+    {
+      "name": "midnight",
+      "label": "Midnight",
+      "appearance": "dark",
+      "source": "tokens.midnight.json",
+      "description": "A near-black dark for low light and OLED displays: cooler neutrals, a deeper canvas than dark, and a deeper accent that holds a white label at AA."
+    },
+    {
+      "name": "twilight",
+      "label": "Twilight",
+      "appearance": "dark",
+      "source": "tokens.twilight.json",
+      "description": "A warm violet-tinted dark. Its neutrals sit in a different hue family from dark and midnight, which is what proves a theme is a palette rather than a lightness setting."
+    },
+    {
+      "name": "contrast",
+      "label": "High contrast",
+      "appearance": "light",
+      "source": "tokens.contrast.json",
+      "minimumContrast": 7,
+      "description": "A high-contrast light theme: white surfaces, near-black text, darkened accents and visible borders. Every declared text pairing reaches AAA, not just AA. Not wired to `prefers-contrast: more` — that needs a dark high-contrast counterpart first, or a user who asked for both more contrast and dark would be handed a light theme."
+    }
+  ]
+}

package/token-pairs.json

@@ -0,0 +1,252 @@
+{
+  "$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",
+      "label": "body text on a card",
+      "fg": "--color-neutral-900",
+      "bg": "--color-neutral-0",
+      "layer": "primitive"
+    },
+    {
+      "id": "body-on-canvas-primitive",
+      "label": "body text on the canvas",
+      "fg": "--color-neutral-900",
+      "bg": "--color-neutral-50",
+      "layer": "primitive"
+    },
+    {
+      "id": "muted-on-card",
+      "label": "muted text on a card",
+      "fg": "--color-neutral-600",
+      "bg": "--color-neutral-0",
+      "layer": "primitive"
+    },
+    {
+      "id": "muted-on-canvas-primitive",
+      "label": "muted text on the canvas",
+      "fg": "--color-neutral-600",
+      "bg": "--color-neutral-50",
+      "layer": "primitive"
+    },
+    {
+      "id": "primary-button-label",
+      "label": "primary button label",
+      "fg": "--color-brand-primary-contrast",
+      "bg": "--color-brand-primary",
+      "layer": "primitive"
+    },
+    {
+      "id": "success-badge",
+      "label": "success badge",
+      "fg": "--color-status-success",
+      "bg": "--color-status-success-soft",
+      "layer": "primitive"
+    },
+    {
+      "id": "warning-badge",
+      "label": "warning badge",
+      "fg": "--color-status-warning",
+      "bg": "--color-status-warning-soft",
+      "layer": "primitive"
+    },
+    {
+      "id": "danger-badge",
+      "label": "danger badge",
+      "fg": "--color-status-danger",
+      "bg": "--color-status-danger-soft",
+      "layer": "primitive"
+    },
+    {
+      "id": "info-badge",
+      "label": "info badge",
+      "fg": "--color-status-info",
+      "bg": "--color-status-info-soft",
+      "layer": "primitive"
+    },
+    {
+      "id": "body-on-surface",
+      "label": "body text on a surface",
+      "fg": "--color-fg-default",
+      "bg": "--color-bg-surface",
+      "layer": "semantic"
+    },
+    {
+      "id": "body-on-canvas",
+      "label": "body text on the canvas",
+      "fg": "--color-fg-default",
+      "bg": "--color-bg-canvas",
+      "layer": "semantic"
+    },
+    {
+      "id": "body-on-raised",
+      "label": "body text on a raised surface",
+      "fg": "--color-fg-default",
+      "bg": "--color-bg-raised",
+      "layer": "semantic"
+    },
+    {
+      "id": "muted-on-surface",
+      "label": "muted text on a surface",
+      "fg": "--color-fg-muted",
+      "bg": "--color-bg-surface",
+      "layer": "semantic"
+    },
+    {
+      "id": "muted-on-canvas",
+      "label": "muted text on the canvas",
+      "fg": "--color-fg-muted",
+      "bg": "--color-bg-canvas",
+      "layer": "semantic"
+    },
+    {
+      "id": "subtle-on-surface",
+      "label": "subtle text on a surface",
+      "fg": "--color-fg-subtle",
+      "bg": "--color-bg-surface",
+      "layer": "semantic"
+    },
+    {
+      "id": "accent-on-surface",
+      "label": "accent text on a surface",
+      "fg": "--color-fg-accent",
+      "bg": "--color-bg-surface",
+      "layer": "semantic"
+    },
+    {
+      "id": "accent-on-soft",
+      "label": "accent text on the accent wash",
+      "fg": "--color-fg-accent",
+      "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",
+      "fg": "--color-sidebar-fg",
+      "bg": "--color-sidebar-bg",
+      "layer": "semantic"
+    },
+    {
+      "id": "sidebar-muted-text",
+      "label": "sidebar muted text",
+      "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"
+    }
+  ]
+}