actual-css 0.13.0 → 0.14.0

package/src/tooling/design-tokens.js

@@ -1,7 +1,8 @@
 /*
- * Design-tool token export: resolves a theme's tokens in headless Chrome and
- * writes them for Figma (DTCG files, one per mode) and Penpot (one token file
- * with its sets and themes).
+ * Design-tool token export: resolves a theme's tokens in headless Chrome into
+ * a target-neutral model, then writes them for Figma, Penpot, and a portable
+ * DTCG profile. Figma and Penpot get the compromises their importers need; the
+ * DTCG profile stays spec-conformant (correct $types, 6-digit `hex`).
  *
  * Values are read from the browser, never from the CSS text: tokens are built
  * with light-dark(), color-mix() and var() chains that only the browser
@@ -56,8 +57,9 @@ export const THEME_COLORS = [
   "backdrop-fill",
 ];
 
-/* Mode-independent tokens by role. The role tells a design tool where a value
-   applies (Penpot token types); every role but font-weight is a length. */
+/* Mode-independent tokens by role. The role drives the DTCG type (see
+   DTCG_TYPE) and the Penpot type; length roles plus font-weight are the ones
+   Figma and Penpot read, the rest are DTCG-only. */
 export const FOUNDATIONS = {
   spacing: [
     "space-10",
@@ -89,32 +91,23 @@ export const FOUNDATIONS = {
     "font-weight-semibold",
     "font-weight-bold",
   ],
+  "font-family": ["font-sans", "font-mono"],
+  duration: ["duration", "duration-fast", "duration-slow", "duration-spin", "duration-shimmer"],
+  "cubic-bezier": ["ease-enter", "ease-exit"],
+  number: ["line-height", "line-height-tight", "line-height-relaxed"],
 };
 
 /* Every custom property declared by the core token files is exported or
    listed here (tests/design-tokens.test.js), so a new token cannot silently
    stay out of the design tools. */
 export const NOT_EXPORTED = {
-  "font stack; a design tool font token holds one family": ["font-sans", "font-mono"],
   "internal 0/1 weights selecting a control step; the steps are exported": [
     "control-step-sm",
     "control-step-md",
     "control-step-lg",
   ],
-  "no design tool equivalent": [
+  "no DTCG type that keeps its meaning": [
     "font-width",
-    "line-height",
-    "line-height-tight",
-    "line-height-relaxed",
-    "shadow",
-    "shadow-popout",
-    "duration",
-    "duration-fast",
-    "duration-slow",
-    "duration-spin",
-    "duration-shimmer",
-    "ease-enter",
-    "ease-exit",
     "viewport-block",
     "viewport-inline",
     "z-sticky",
@@ -125,6 +118,7 @@ export const NOT_EXPORTED = {
     "icon-close",
     "icon-plus",
   ],
+  "composite DTCG types the export does not build yet": ["shadow", "shadow-popout"],
   "input of a derived value": [
     "backdrop-color",
     "backdrop-opacity",
@@ -142,6 +136,7 @@ export const NOT_EXPORTED = {
     "danger-soft-fg",
     "neutral-soft-fg",
   ],
+  "fallback-only state hook, read at the point of use": ["state-selected-text"],
   "internal or plumbing": [
     "density-space",
     "disabled-opacity",
@@ -152,10 +147,13 @@ export const NOT_EXPORTED = {
   ],
 };
 
+// Length roles carry a px value plus the CSS source; every other role carries
+// one scalar read as-is and parsed by role (see PARSE).
+const LENGTH_ROLES = ["spacing", "radius", "border-width", "font-size", "size", "offset"];
+const RAW_ROLES = ["font-family", "duration", "cubic-bezier", "number"];
+const LENGTHS = LENGTH_ROLES.flatMap((role) => FOUNDATIONS[role]);
 const WEIGHTS = FOUNDATIONS["font-weight"];
-const LENGTHS = Object.entries(FOUNDATIONS).flatMap(([role, names]) =>
-  role === "font-weight" ? [] : names,
-);
+const RAWS = RAW_ROLES.flatMap((role) => FOUNDATIONS[role]);
 const ROLE_OF = new Map(
   Object.entries(FOUNDATIONS).flatMap(([role, names]) => names.map((n) => [n, role])),
 );
@@ -220,7 +218,7 @@ export async function coreTokenCss() {
  * what light-dark() resolves against. Colors go through color-mix(in srgb) so
  * every color syntax computes to the same `color(srgb r g b / a)` form.
  */
-function readIslands({ css, islands, colors, lengths, weights }) {
+function readIslands({ css, islands, colors, lengths, weights, raws }) {
   const style = document.createElement("style");
   style.textContent = css;
   document.head.append(style);
@@ -236,7 +234,7 @@ function readIslands({ css, islands, colors, lengths, weights }) {
     document.body.append(island);
 
     const computed = getComputedStyle(probe);
-    const values = { colors: {}, lengths: {}, weights: {}, missing: [] };
+    const values = { colors: {}, lengths: {}, weights: {}, raws: {}, missing: [] };
     const read = (name) => {
       const raw = computed.getPropertyValue(`--${name}`).trim();
       if (!raw) values.missing.push(name);
@@ -260,6 +258,10 @@ function readIslands({ css, islands, colors, lengths, weights }) {
       const raw = read(name);
       if (raw) values.weights[name] = Number(raw);
     }
+    for (const name of raws) {
+      const raw = read(name);
+      if (raw) values.raws[name] = raw;
+    }
     values.scheme = getComputedStyle(island).colorScheme;
     result.push(values);
     island.remove();
@@ -295,6 +297,7 @@ export async function resolveTokens({ css, theme = null, aliasSources = [] }) {
     colors: [],
     lengths: [],
     weights: [],
+    raws: [],
   });
   const schemes = declared.scheme.split(/\s+/).filter((s) => s === "light" || s === "dark");
   const islands = (schemes.length > 0 ? schemes : ["light"]).map((mode) => ({
@@ -309,6 +312,7 @@ export async function resolveTokens({ css, theme = null, aliasSources = [] }) {
     colors: THEME_COLORS,
     lengths: LENGTHS,
     weights: WEIGHTS,
+    raws: RAWS,
   });
   const missing = [...new Set(read.flatMap((values) => values.missing))];
   if (missing.length > 0) {
@@ -321,9 +325,13 @@ export async function resolveTokens({ css, theme = null, aliasSources = [] }) {
       Object.fromEntries(Object.entries(read[i].colors).map(([n, c]) => [n, parseSrgb(c)])),
     ]),
   );
-  // Geometry does not follow the color scheme; the first mode is the reference.
-  const [{ lengths, weights }] = read;
-  return { islands, modes, lengths, weights, aliases: aliasCandidates(...aliasSources) };
+  // Geometry and the raw foundations do not follow the color scheme; the first
+  // mode is the reference.
+  const [{ lengths, weights, raws }] = read;
+  const extras = Object.fromEntries(
+    Object.entries(raws).map(([name, raw]) => [name, PARSE[ROLE_OF.get(name)](raw)]),
+  );
+  return { islands, modes, lengths, weights, extras, aliases: aliasCandidates(...aliasSources) };
 }
 
 export function parseSrgb(value) {
@@ -336,14 +344,60 @@ export function parseSrgb(value) {
   };
 }
 
+/* Raw foundation readers. Each role maps to one parser, so a value the browser
+   reports in an unexpected shape fails loudly instead of exporting garbage. */
+export function parseDuration(value) {
+  const match = value.match(/^([\d.]+)(ms|s)$/);
+  if (!match) throw new Error(`Unexpected duration: ${value}`);
+  return { value: Number(match[1]), unit: match[2] };
+}
+
+export function parseCubicBezier(value) {
+  const match = value.match(/^cubic-bezier\(([^)]+)\)$/);
+  const numbers = match?.[1].split(",").map((n) => Number(n.trim()));
+  if (numbers?.length !== 4 || numbers.some(Number.isNaN)) {
+    throw new Error(`Unexpected cubic-bezier: ${value}`);
+  }
+  return numbers;
+}
+
+export function parseFontFamily(value) {
+  return value
+    .split(",")
+    .map((family) => family.trim().replace(/^["']|["']$/g, ""))
+    .filter(Boolean);
+}
+
+export function parseNumber(value) {
+  const n = Number(value);
+  if (Number.isNaN(n)) throw new Error(`Unexpected number: ${value}`);
+  return n;
+}
+
+const PARSE = {
+  "font-family": parseFontFamily,
+  duration: parseDuration,
+  "cubic-bezier": parseCubicBezier,
+  number: parseNumber,
+};
+
 const round = (n) => Math.round(n * 10000) / 10000;
 
+const byte = (n) =>
+  Math.round(n * 255)
+    .toString(16)
+    .padStart(2, "0");
+
+/* DTCG color `hex` is a 6-digit fallback: alpha is carried separately, and the
+   spec requires the hex itself to be 6 digits. */
+export function hexRgbOf({ components }) {
+  return `#${components.map(byte).join("")}`;
+}
+
+/* The CSS-fidelity form: keeps alpha in the hex for Penpot and for comparing
+   colors across modes (two colors that share RGB but not alpha must differ). */
 export function hexOf({ components, alpha }) {
-  const byte = (n) =>
-    Math.round(n * 255)
-      .toString(16)
-      .padStart(2, "0");
-  return `#${components.map(byte).join("")}${alpha < 1 ? byte(alpha) : ""}`;
+  return `${hexRgbOf({ components })}${alpha < 1 ? byte(alpha) : ""}`;
 }
 
 const colorsEqual = (a, b) =>
@@ -357,11 +411,12 @@ function aliasOf(name, valueSets, aliases, same) {
 }
 
 /*
- * The target-neutral model both writers read: per mode, each color is
- * `{ alias }` or `{ color, hex }`; each foundation carries its role and is
- * `{ alias }`, `{ px, css }` or `{ weight }`.
+ * The target-neutral model the writers read: per mode, each color is
+ * `{ alias }` or `{ color, hex }` (hex 6-digit, the DTCG form); each
+ * foundation carries its role and is `{ alias }`, `{ px, css }`, `{ weight }`
+ * or `{ value }` for the raw roles.
  */
-export function linkTokens({ modes, lengths, weights, aliases }) {
+export function linkTokens({ modes, lengths, weights, extras = {}, aliases }) {
   const modeSets = Object.values(modes);
   const linkedModes = Object.fromEntries(
     Object.entries(modes).map(([mode, colors]) => [
@@ -369,7 +424,7 @@ export function linkTokens({ modes, lengths, weights, aliases }) {
       Object.fromEntries(
         Object.entries(colors).map(([name, color]) => {
           const alias = aliasOf(name, modeSets, aliases, colorsEqual);
-          return [name, alias ? { alias } : { color, hex: hexOf(color) }];
+          return [name, alias ? { alias } : { color, hex: hexRgbOf(color) }];
         }),
       ),
     ]),
@@ -383,6 +438,9 @@ export function linkTokens({ modes, lengths, weights, aliases }) {
   for (const [name, weight] of Object.entries(weights)) {
     foundations[name] = { role: "font-weight", weight };
   }
+  for (const [name, value] of Object.entries(extras)) {
+    foundations[name] = { role: ROLE_OF.get(name), value };
+  }
   return { modes: linkedModes, foundations };
 }
 
@@ -411,13 +469,73 @@ export function toFigma({ modes, foundations }, recipes = {}) {
   }
 
   files.foundations = Object.fromEntries(
-    Object.entries(foundations).map(([name, token]) => {
+    Object.entries(foundations).flatMap(([name, token]) => {
       // `number`, not DTCG `fontWeight`: Figma's import drops fontWeight
       // tokens, and a number variable is what binds to a text layer's weight.
-      if (token.role === "font-weight") return [name, { $type: "number", $value: token.weight }];
+      if (token.role === "font-weight") {
+        return [[name, { $type: "number", $value: token.weight }]];
+      }
+      // Figma reads dimensions only; the raw roles stay in the DTCG profile.
+      if (!LENGTH_ROLES.includes(token.role)) return [];
       const $value = token.alias ? `{${token.alias}}` : { value: token.px, unit: "px" };
       const doc = { $type: "dimension", $value };
       if (token.css) doc.$extensions = { [EXTENSION]: { css: token.css } };
+      return [[name, doc]];
+    }),
+  );
+  return files;
+}
+
+/* DTCG `$type` per role. Figma keeps its own adaptations (a font weight as a
+   number); the neutral profile uses the type the spec defines. */
+const DTCG_TYPE = {
+  spacing: "dimension",
+  radius: "dimension",
+  "border-width": "dimension",
+  "font-size": "dimension",
+  size: "dimension",
+  offset: "dimension",
+  "font-weight": "fontWeight",
+  "font-family": "fontFamily",
+  duration: "duration",
+  "cubic-bezier": "cubicBezier",
+  number: "number",
+};
+
+function dtcgValue(token) {
+  if (token.alias) return `{${token.alias}}`;
+  if (token.role === "font-weight") return token.weight;
+  if (LENGTH_ROLES.includes(token.role)) return { value: token.px, unit: "px" };
+  return token.value;
+}
+
+/*
+ * DTCG: the portable profile. Same file split as Figma, but every foundation
+ * keeps its spec type (`fontWeight`, `duration`, `cubicBezier`, `fontFamily`,
+ * `number`), colors carry a 6-digit `hex` with alpha separate, and dimensions
+ * keep their CSS value in `$extensions`. No tool adaptation: any DTCG reader
+ * can import it.
+ */
+export function toDtcg({ modes, foundations }, recipes = {}) {
+  const files = {};
+  for (const [mode, colors] of Object.entries(modes)) {
+    files[mode] = Object.fromEntries(
+      Object.entries({ ...colors, ...recipes[mode] }).map(([name, token]) => [
+        name,
+        {
+          $type: "color",
+          $value: token.alias
+            ? `{${token.alias}}`
+            : { colorSpace: "srgb", ...token.color, hex: token.hex },
+        },
+      ]),
+    );
+  }
+
+  files.foundations = Object.fromEntries(
+    Object.entries(foundations).map(([name, token]) => {
+      const doc = { $type: DTCG_TYPE[token.role], $value: dtcgValue(token) };
+      if (token.css) doc.$extensions = { [EXTENSION]: { css: token.css } };
       return [name, doc];
     }),
   );
@@ -449,10 +567,12 @@ const PENPOT_THEME_GROUP = "Mode";
 export function toPenpot({ modes, foundations }, recipes = {}) {
   const doc = {
     foundations: Object.fromEntries(
-      Object.entries(foundations).map(([name, token]) => {
+      Object.entries(foundations).flatMap(([name, token]) => {
         const $type = PENPOT_TYPES[token.role];
-        if (token.alias) return [name, { $type, $value: `{${token.alias}}` }];
-        return [name, { $type, $value: token.weight ?? `${token.px}px` }];
+        // Penpot reads the roles it types; the DTCG-only roles stay out.
+        if (!$type) return [];
+        if (token.alias) return [[name, { $type, $value: `{${token.alias}}` }]];
+        return [[name, { $type, $value: token.weight ?? `${token.px}px` }]];
       }),
     ),
   };
@@ -461,7 +581,7 @@ export function toPenpot({ modes, foundations }, recipes = {}) {
     Object.fromEntries(
       Object.entries(colors).map(([name, token]) => [
         name,
-        { $type: "color", $value: token.alias ? `{${token.alias}}` : token.hex },
+        { $type: "color", $value: token.alias ? `{${token.alias}}` : hexOf(token.color) },
       ]),
     );
   const schemes = Object.keys(modes);

package/src/tooling/theme-contrast.js

@@ -5,17 +5,25 @@
  * (`bun run report:theme-contrast`).
  *
  * Measured per island (one per color scheme the theme declares):
- *   - soft ink against the resting and the hovered soft fill (4.5:1)
+ *   - soft ink against the resting and the hovered soft fill (4.5:1), on each
+ *     surface a soft element sits on
+ *   - the solid pairs, -fg on the intent fill (4.5:1); a fill painted by a
+ *     background-image reads n/a
+ *   - selected ink on those surfaces: the current nav link at rest and on
+ *     hover, the selected tab and the current step number (4.5:1), and the
+ *     current step's ring (3:1)
  *   - the focus line against --surface and --surface-solid (3:1)
  *   - the invalid-field focus line against the field's own background (3:1)
  *   - --surface-solid-fg on --surface-solid (4.5:1)
- * A pair involving a translucent color has no ratio until it is composited
- * over its backdrop, so it reads n/a instead of a number.
+ * Soft fills are translucent, so each is composited over the surface under it
+ * before it is measured: the pair is what the page displays, not the token.
+ * A surface that is itself translucent (a glass theme) has no defined
+ * backdrop, so its pairs read n/a instead of a number.
  *
  * Bun only: Bun.WebView drives the browser.
  */
 import { fileURLToPath } from "node:url";
-import { contrast, RASTERIZE } from "./color.js";
+import { composite, contrast, RASTERIZE } from "./color.js";
 import { inlineImports } from "./css-bundle.js";
 import { themeNameOf } from "./design-tokens.js";
 
@@ -23,6 +31,11 @@ const FRAMEWORK = fileURLToPath(new URL("../css/actual.full.css", import.meta.ur
 
 export const INTENTS = ["primary", "secondary", "success", "warning", "danger", "neutral"];
 
+/* The surfaces a soft badge or button is expected to sit on. --surface-subtle
+   is usually the binding one: a translucent fill over it ends darker in light
+   and lighter in dark than over --surface. */
+export const SURFACES = ["surface", "surface-raised", "surface-subtle"];
+
 /* Badges state .soft explicitly: a theme may fill badges by default
    (bootstrap-v6), which would measure a solid pair against the soft hover.
    The theme name is read from a file by a regex, so it never enters this
@@ -30,9 +43,23 @@ export const INTENTS = ["primary", "secondary", "success", "warning", "danger",
    "light" or "dark". */
 function islandMarkup(id, scheme) {
   const style = scheme ? ` style="color-scheme: ${scheme}"` : "";
+  const softPairs = SURFACES.map(
+    (surface) => `<div data-surface="${surface}" style="background: var(--${surface})">
+      ${INTENTS.map((i) => `<span class="badge soft ${i}" data-badge="${i}">t</span>`).join("")}
+      ${INTENTS.map((i) => `<button class="btn soft ${i}" data-hover="${i}" type="button">t</button>`).join("")}
+      <nav class="navbar" aria-label="t">
+        <a class="nav-link" href="#t" aria-current="page" data-selected="nav">t</a>
+        <a class="nav-link" href="#t" aria-current="page" data-selected="nav-hover">t</a>
+      </nav>
+      <div class="tabs" role="tablist">
+        <button class="tab" role="tab" aria-selected="true" type="button" data-selected="tab">t</button>
+      </div>
+      <ol class="steps"><li aria-current="step" data-selected="step"><span class="step-label">t</span></li></ol>
+    </div>`,
+  ).join("");
   return `<div${style} id="${id}">
-    ${INTENTS.map((i) => `<span class="badge soft ${i}" data-badge="${i}">t</span>`).join("")}
-    ${INTENTS.map((i) => `<button class="btn soft ${i}" data-hover="${i}" type="button">t</button>`).join("")}
+    ${softPairs}
+    ${INTENTS.map((i) => `<button class="btn solid ${i}" data-solid="${i}" type="button">t</button>`).join("")}
     <span data-pair="focus-surface" style="color: var(--focus); background: var(--surface)"></span>
     <span data-pair="focus-solid" style="color: var(--focus); background: var(--surface-solid)"></span>
     <span data-pair="inverse" style="color: var(--surface-solid-fg); background: var(--surface-solid)"></span>
@@ -91,7 +118,7 @@ export async function measureContrast({ css, themes, label = "default" }) {
   const { root } = await view.cdp("DOM.getDocument");
   const { nodeIds } = await view.cdp("DOM.querySelectorAll", {
     nodeId: root.nodeId,
-    selector: "[data-hover]",
+    selector: '[data-hover], [data-selected="nav-hover"]',
   });
   for (const nodeId of nodeIds) {
     await view.cdp("CSS.forcePseudoState", { nodeId, forcedPseudoClasses: ["hover"] });
@@ -109,30 +136,101 @@ export async function measureContrast({ css, themes, label = "default" }) {
         const fg = el.dataset.pair === "invalid-field" ? cs(el).borderBlockEndColor : cs(el).color;
         pairs[el.dataset.pair] = { fg: rgba(fg), bg: rgba(cs(el).backgroundColor) };
       }
+      // A solid fill painted by a background-image (a gradient theme) has no
+      // single color to measure: it is reported, not sampled.
+      const solid = {};
+      for (const el of island.querySelectorAll("[data-solid]")) {
+        solid[el.dataset.solid] =
+          cs(el).backgroundImage === "none"
+            ? { fg: rgba(cs(el).color), bg: rgba(cs(el).backgroundColor) }
+            : null;
+      }
       const soft = {};
-      for (const el of island.querySelectorAll("[data-badge]")) {
-        const hover = island.querySelector('[data-hover="' + el.dataset.badge + '"]');
-        soft[el.dataset.badge] = {
-          fg: rgba(cs(el).color),
-          rest: rgba(cs(el).backgroundColor),
-          hover: rgba(cs(hover).backgroundColor),
+      // Fills from the surface down to the element, outermost first: the stack
+      // the page composites under a selected ink.
+      const layers = (surface, el) => {
+        const chain = [];
+        for (let n = el; n !== surface.parentElement; n = n.parentElement) chain.unshift(n);
+        return chain.map((n) => rgba(cs(n).backgroundColor));
+      };
+      for (const surface of island.querySelectorAll("[data-surface]")) {
+        const fills = {};
+        for (const el of surface.querySelectorAll("[data-badge]")) {
+          const hover = surface.querySelector('[data-hover="' + el.dataset.badge + '"]');
+          fills[el.dataset.badge] = {
+            fg: rgba(cs(el).color),
+            rest: rgba(cs(el).backgroundColor),
+            hover: rgba(cs(hover).backgroundColor),
+          };
+        }
+        const selected = {};
+        for (const el of surface.querySelectorAll("[data-selected]")) {
+          const kind = el.dataset.selected;
+          if (kind === "step") {
+            // The number and ring live on the marker pseudo; the ring reads
+            // against what is under the step, the number against the marker.
+            const marker = getComputedStyle(el, "::before");
+            const under = layers(surface, el);
+            selected[kind] = {
+              layers: [...under, rgba(marker.backgroundColor)],
+              fg: rgba(marker.color),
+              ring: { layers: under, fg: rgba(marker.borderTopColor) },
+            };
+          } else {
+            selected[kind] = { layers: layers(surface, el), fg: rgba(cs(el).color) };
+          }
+        }
+        soft[surface.dataset.surface] = {
+          backdrop: rgba(cs(surface).backgroundColor),
+          fills,
+          selected,
         };
       }
-      return { pairs, soft };
+      return { pairs, soft, solid };
     });
   })()`);
 
   return islands.map(({ theme, scheme }, i) => {
-    const { pairs, soft } = colors[i];
+    const { pairs, soft, solid } = colors[i];
     const pair = (key) => ratio(pairs[key].fg, pairs[key].bg);
+    // Fill over the surface, then ink over the fill: the colors the page shows.
+    const shown = (fg, fill, backdrop) => {
+      const bg = composite(fill, backdrop);
+      return ratio(composite(fg, bg), bg);
+    };
+    const stacked = ({ layers, fg }) => {
+      const [base, ...rest] = layers;
+      const bg = rest.reduce((under, fill) => composite(fill, under), base);
+      return ratio(composite(fg, bg), bg);
+    };
     return {
       theme,
       scheme,
-      soft: INTENTS.map((intent) => ({
+      solid: INTENTS.map((intent) => ({
         intent,
-        rest: ratio(soft[intent].fg, soft[intent].rest),
-        hover: ratio(soft[intent].fg, soft[intent].hover),
+        value: solid[intent] ? ratio(solid[intent].fg, solid[intent].bg) : null,
       })),
+      // Selected ink on a regular surface (--state-selected-text): text needs
+      // 4.5:1, the current step's ring is a non-text accent at 3:1.
+      selected: SURFACES.flatMap((surface) => {
+        const { selected } = soft[surface];
+        return [
+          { kind: "nav link", surface, min: 4.5, value: stacked(selected.nav) },
+          { kind: "nav link hover", surface, min: 4.5, value: stacked(selected["nav-hover"]) },
+          { kind: "tab", surface, min: 4.5, value: stacked(selected.tab) },
+          { kind: "step number", surface, min: 4.5, value: stacked(selected.step) },
+          { kind: "step ring", surface, min: 3, value: stacked(selected.step.ring) },
+        ];
+      }),
+      soft: SURFACES.flatMap((surface) => {
+        const { backdrop, fills } = soft[surface];
+        return INTENTS.map((intent) => ({
+          intent,
+          surface,
+          rest: shown(fills[intent].fg, fills[intent].rest, backdrop),
+          hover: shown(fills[intent].fg, fills[intent].hover, backdrop),
+        }));
+      }),
       focusSurface: pair("focus-surface"),
       focusSolid: pair("focus-solid"),
       invalidFocus: pair("invalid-field"),
@@ -167,15 +265,46 @@ export function formatContrast(rows) {
   const flag = (cells, min) => (cells.some((c) => c.miss) ? `  <-- under ${min}` : "");
   const lines = [];
 
-  lines.push("Soft pair contrast (ink vs resting / hovered fill), needs 4.5:1.", "");
-  lines.push(`${"theme".padEnd(width)}  scheme  intent       rest     hover`);
+  lines.push(
+    "Soft pair contrast (ink vs resting / hovered fill, composited on each surface), needs 4.5:1.",
+    "",
+  );
+  lines.push(`${"theme".padEnd(width)}  scheme  surface         intent       rest     hover`);
   for (const row of rows) {
-    for (const { intent, rest, hover } of row.soft) {
+    for (const { intent, surface, rest, hover } of row.soft) {
       // Both states gate: the hovered fill is usually the closer one, but a
       // theme can invert that, and a 1:1 resting pair once passed silently.
       const cells = [cell(rest, 4.5), cell(hover, 4.5)];
       lines.push(
-        `${head(row)}  ${intent.padEnd(9)} ${cells[0].text.padStart(8)}  ${cells[1].text.padStart(8)}${flag(cells, 4.5)}`,
+        `${head(row)}  ${surface.padEnd(15)} ${intent.padEnd(9)} ${cells[0].text.padStart(8)}  ${cells[1].text.padStart(8)}${flag(cells, 4.5)}`,
+      );
+    }
+  }
+
+  lines.push(
+    "",
+    "Solid pair contrast (-fg on the intent fill), needs 4.5:1. n/a: a gradient fill, not sampled.",
+    "",
+  );
+  lines.push(`${"theme".padEnd(width)}  scheme  intent       ratio`);
+  for (const row of rows) {
+    for (const { intent, value } of row.solid ?? []) {
+      const c = cell(value, 4.5);
+      lines.push(`${head(row)}  ${intent.padEnd(9)} ${c.text.padStart(8)}${flag([c], 4.5)}`);
+    }
+  }
+
+  lines.push(
+    "",
+    "Selected ink on a surface (--state-selected-text), text 4.5:1, step ring 3:1.",
+    "",
+  );
+  lines.push(`${"theme".padEnd(width)}  scheme  surface         selected          ratio`);
+  for (const row of rows) {
+    for (const { kind, surface, min, value } of row.selected ?? []) {
+      const c = cell(value, min);
+      lines.push(
+        `${head(row)}  ${surface.padEnd(15)} ${kind.padEnd(15)} ${c.text.padStart(8)}${flag([c], min)}`,
       );
     }
   }