actual-css 0.11.1 → 0.13.0

package/src/tooling/color.js

@@ -0,0 +1,65 @@
+/*
+ * sRGB color math shared by `actual-css contrast`, the repository reports and
+ * the browser tests.
+ * Colors are [r, g, b, a] byte arrays as returned by RASTERIZE in the page;
+ * plain [r, g, b] triplets are accepted and treated as opaque.
+ */
+
+/*
+ * Page-side rasterizer, injected into a view.evaluate() program as
+ * `const rgba = ${RASTERIZE};`. getComputedStyle returns color-mix() and
+ * light-dark() results as oklab() or color(), so a 1x1 canvas turns any
+ * computed color into sRGB bytes. Alpha is kept so contrast() can refuse a
+ * translucent color instead of measuring it as if it were opaque.
+ */
+export const RASTERIZE = `(() => {
+  const canvas = Object.assign(document.createElement("canvas"), { width: 1, height: 1 });
+  const ctx = canvas.getContext("2d", { willReadFrequently: true });
+  return (value) => {
+    ctx.clearRect(0, 0, 1, 1);
+    ctx.fillStyle = value;
+    ctx.fillRect(0, 0, 1, 1);
+    return [...ctx.getImageData(0, 0, 1, 1).data];
+  };
+})()`;
+
+/* 0.04045 is the sRGB (IEC 61966-2-1) threshold and the one WCAG 2.2 defines.
+   WCAG 2.0/2.1 printed 0.03928, from an older sRGB draft. No 8-bit channel
+   falls between the two (10/255 = 0.0392, 11/255 = 0.0431), so ratios are
+   identical either way. */
+const toLinear = (byte) => {
+  const c = byte / 255;
+  return c <= 0.04045 ? c / 12.92 : ((c + 0.055) / 1.055) ** 2.4;
+};
+
+/* WCAG 2 relative luminance. */
+export const luminance = ([r, g, b]) =>
+  0.2126 * toLinear(r) + 0.7152 * toLinear(g) + 0.0722 * toLinear(b);
+
+/* WCAG 2 contrast ratio, 1 to 21. The formula has no alpha: a translucent
+   color must be composited over its real background before it is measured. */
+export function contrast(a, b) {
+  if (a[3] < 255 || b[3] < 255) {
+    throw new Error(`contrast() needs opaque colors, got [${a}] and [${b}]`);
+  }
+  const [hi, lo] = [luminance(a), luminance(b)].sort((x, y) => y - x);
+  return (hi + 0.05) / (lo + 0.05);
+}
+
+/* OKLCH of an sRGB color: L 0-1, C chroma, h degrees. */
+export function oklch([r, g, b]) {
+  const [lr, lg, lb] = [r, g, b].map(toLinear);
+  const l = Math.cbrt(0.4122214708 * lr + 0.5363325363 * lg + 0.0514459929 * lb);
+  const m = Math.cbrt(0.2119034982 * lr + 0.6806995451 * lg + 0.1073969566 * lb);
+  const s = Math.cbrt(0.0883024619 * lr + 0.2817188376 * lg + 0.6299787005 * lb);
+  const L = 0.2104542553 * l + 0.793617785 * m - 0.0040720468 * s;
+  const A = 1.9779984951 * l - 2.428592205 * m + 0.4505937099 * s;
+  const B = 0.0259040371 * l + 0.7827717662 * m - 0.808675766 * s;
+  return { L, C: Math.hypot(A, B), h: ((Math.atan2(B, A) * 180) / Math.PI + 360) % 360 };
+}
+
+/* Shortest arc between two hues, in degrees. */
+export const hueDistance = (a, b) => {
+  const d = Math.abs(a - b) % 360;
+  return d > 180 ? 360 - d : d;
+};

package/src/tooling/design-export.js

@@ -31,7 +31,7 @@ const PLUGIN = fileURLToPath(new URL("./penpot-plugin/", import.meta.url));
  */
 export async function exportDesign({ themeFile, name, out }) {
   const themeCss = themeFile ? await inlineImports(themeFile) : "";
-  const theme = themeFile ? (name ?? themeNameOf(themeCss)) : null;
+  const theme = themeFile ? themeNameOf(themeCss, name) : null;
   const css = `${await inlineImports(FRAMEWORK)}\n${themeCss}`;
 
   const resolved = await resolveTokens({

package/src/tooling/design-tokens.js

@@ -42,8 +42,10 @@ export const THEME_COLORS = [
   "text-subtle",
   "heading",
   "border",
+  "border-control",
   "focus",
   "hover-overlay",
+  "hover-overlay-solid",
   "shadow-color",
   "selection-bg",
   "selection-fg",
@@ -65,6 +67,9 @@ export const FOUNDATIONS = {
     "space-50",
     "space-60",
     "gap",
+    "control-pad-x-sm",
+    "control-pad-x-md",
+    "control-pad-x-lg",
     "control-pad-x",
   ],
   radius: ["radius-sm", "radius", "radius-lg", "radius-full"],
@@ -91,9 +96,13 @@ export const FOUNDATIONS = {
    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": [
     "font-width",
-    "font-width-dense",
     "line-height",
     "line-height-tight",
     "line-height-relaxed",
@@ -123,7 +132,6 @@ export const NOT_EXPORTED = {
     "soft-border-mix",
     "soft-hover-alpha",
     "soft-fg-mix",
-    "focus-outline",
     "focus-outline-color",
   ],
   "soft recipe, exported with the components": [
@@ -154,7 +162,9 @@ const ROLE_OF = new Map(
 
 const DECLARATION_RE = /(?<![-\w])--([a-z0-9-]+)\s*:\s*([^;{}]*);/gi;
 const ALIAS_RE = /^var\(\s*--([a-z0-9-]+)\s*\)$/i;
-const THEME_NAME_RE = /\[data-theme="([^"]+)"\]/g;
+// Every valid spelling — either quote, a bare ident, whitespace inside the
+// brackets, an i/s flag: a missed name falls back to the :root theme silently.
+const THEME_NAME_RE = /\[\s*data-theme\s*=\s*(?:(["'])([^"']+)\1|([-\w]+))\s*(?:[is]\s*)?\]/gi;
 
 export function declaredTokens(css) {
   return new Set([...stripComments(css).matchAll(DECLARATION_RE)].map((m) => m[1]));
@@ -175,17 +185,29 @@ export function aliasCandidates(...sources) {
   return aliases;
 }
 
-/* The one data-theme value a theme file declares, light/dark excluded. */
-export function themeNameOf(css) {
+/* The one data-theme value a theme file declares, light/dark excluded. null
+   when it declares none: the theme is written on :root, the application's
+   own sheet rather than an island. An explicit name must be one the file
+   declares: an island no rule matches would measure the framework defaults
+   and report them as the theme (a typo passed silently). */
+export function themeNameOf(css, explicit) {
   const names = new Set(
-    [...css.matchAll(THEME_NAME_RE)].map((m) => m[1]).filter((n) => n !== "light" && n !== "dark"),
+    // Comments stripped: a selector quoted in a doc comment is not a theme.
+    [...stripComments(css).matchAll(THEME_NAME_RE)]
+      .map((m) => m[2] ?? m[3])
+      .filter((n) => n !== "light" && n !== "dark"),
   );
-  if (names.size !== 1) {
+  if (explicit != null) {
+    if (names.has(explicit)) return explicit;
+    const found = names.size ? `it declares ${[...names].join(", ")}` : "it declares none";
+    throw new Error(`The theme declares no [data-theme="${explicit}"]; ${found}.`);
+  }
+  if (names.size > 1) {
     throw new Error(
-      `Expected one [data-theme="…"] name in the theme, found ${names.size === 0 ? "none" : [...names].join(", ")}; pass the name explicitly.`,
+      `Expected one [data-theme="…"] name in the theme, found ${[...names].join(", ")}; pass the name explicitly.`,
     );
   }
-  return [...names][0];
+  return names.size === 1 ? [...names][0] : null;
 }
 
 export async function coreTokenCss() {
@@ -238,7 +260,7 @@ function readIslands({ css, islands, colors, lengths, weights }) {
       const raw = read(name);
       if (raw) values.weights[name] = Number(raw);
     }
-    values.scheme = attribute ? getComputedStyle(island).colorScheme : null;
+    values.scheme = getComputedStyle(island).colorScheme;
     result.push(values);
     island.remove();
   }
@@ -258,31 +280,28 @@ const evaluateIslands = (input) => inPage(readIslands, input);
 
 /*
  * Resolves one theme. `css` is the full stylesheet (framework + theme, imports
- * inlined). Without `theme`, the default theme is read through its light and
- * dark boundaries. A named theme exports the schemes it declares: `light dark`
- * gives two modes, anything else one. `islands` is returned so component
- * measurements read the same boundaries.
+ * inlined). Without `theme`, the theme is the root's — the default one, or an
+ * application theme written on :root. The theme exports the schemes it
+ * declares: `light dark` gives two modes, anything else one. `islands` is
+ * returned so component measurements read the same boundaries.
  */
-export async function resolveTokens({ css, theme, aliasSources = [] }) {
-  let islands = [
-    { mode: "light", attribute: "light" },
-    { mode: "dark", attribute: "dark" },
-  ];
-  if (theme) {
-    const [declared] = await evaluateIslands({
-      css,
-      islands: [{ attribute: theme }],
-      colors: [],
-      lengths: [],
-      weights: [],
-    });
-    const schemes = declared.scheme.split(/\s+/).filter((s) => s === "light" || s === "dark");
-    islands = (schemes.length > 0 ? schemes : ["light"]).map((mode) => ({
-      mode,
-      attribute: theme,
-      scheme: mode,
-    }));
-  }
+export async function resolveTokens({ css, theme = null, aliasSources = [] }) {
+  // A root island carries no data-theme: the core redeclares the default
+  // palette on [data-theme="light"|"dark"], which would mask a :root theme.
+  // Pinning color-scheme alone is what picks the light-dark() side.
+  const [declared] = await evaluateIslands({
+    css,
+    islands: [{ attribute: theme }],
+    colors: [],
+    lengths: [],
+    weights: [],
+  });
+  const schemes = declared.scheme.split(/\s+/).filter((s) => s === "light" || s === "dark");
+  const islands = (schemes.length > 0 ? schemes : ["light"]).map((mode) => ({
+    mode,
+    attribute: theme,
+    scheme: mode,
+  }));
 
   const read = await evaluateIslands({
     css,

package/src/tooling/theme-contrast.js

@@ -0,0 +1,217 @@
+/*
+ * Theme contrast report: the pairs a theme author tunes by hand, measured in
+ * headless Chrome on the theme's own boundaries. Shared by the CLI
+ * (`actual-css contrast`) and the repository report over the presets
+ * (`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)
+ *   - 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.
+ *
+ * Bun only: Bun.WebView drives the browser.
+ */
+import { fileURLToPath } from "node:url";
+import { contrast, RASTERIZE } from "./color.js";
+import { inlineImports } from "./css-bundle.js";
+import { themeNameOf } from "./design-tokens.js";
+
+const FRAMEWORK = fileURLToPath(new URL("../css/actual.full.css", import.meta.url));
+
+export const INTENTS = ["primary", "secondary", "success", "warning", "danger", "neutral"];
+
+/* 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
+   markup: measureContrast() sets it through dataset. `scheme` is only ever
+   "light" or "dark". */
+function islandMarkup(id, scheme) {
+  const style = scheme ? ` style="color-scheme: ${scheme}"` : "";
+  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("")}
+    <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>
+    <input class="input" aria-invalid="true" data-pair="invalid-field" aria-label="t">
+  </div>`;
+}
+
+const ratio = (fg, bg) => (fg[3] < 255 || bg[3] < 255 ? null : contrast(fg, bg));
+
+/*
+ * Measures each theme of `themes` (data-theme values) in `css`, the full
+ * stylesheet with imports inlined. `null` stands for the root's theme — the
+ * default one, or an application theme written on :root — labelled `label`.
+ * Each theme is read in every scheme its `color-scheme` declares. Returns one
+ * row per island.
+ */
+export async function measureContrast({ css, themes, label = "default" }) {
+  await using view = new Bun.WebView({ backend: "chrome" });
+  await view.navigate("about:blank");
+
+  // Transitions off: a forced :hover must compute its end state at once.
+  const islands = await view.evaluate(`((css, themes, label) => {
+    const style = document.createElement("style");
+    style.textContent = css + "\\n* { transition-duration: 0s !important; }";
+    document.head.append(style);
+
+    // A root island carries no data-theme: the core redeclares the default
+    // palette on [data-theme="light"|"dark"], which would mask a :root theme.
+    // Pinning color-scheme alone is what picks the light-dark() side.
+    const schemesOf = (attribute) => {
+      const probe = document.createElement("div");
+      if (attribute) probe.dataset.theme = attribute;
+      document.body.append(probe);
+      const declared = getComputedStyle(probe).colorScheme.split(/\\s+/);
+      probe.remove();
+      const schemes = declared.filter((s) => s === "light" || s === "dark");
+      return schemes.length > 0 ? schemes : ["light"];
+    };
+
+    return themes.flatMap((attribute) =>
+      schemesOf(attribute).map((scheme) => ({ theme: attribute ?? label, scheme, attribute })),
+    );
+  })(${JSON.stringify(css)}, ${JSON.stringify(themes)}, ${JSON.stringify(label)})`);
+
+  const markup = islands.map((island, i) => islandMarkup(`island-${i}`, island.scheme)).join("\n");
+  const attributes = islands.map((island) => island.attribute);
+  await view.evaluate(`((markup, attributes) => {
+    document.body.insertAdjacentHTML("beforeend", markup);
+    attributes.forEach((attribute, i) => {
+      if (attribute) document.getElementById("island-" + i).dataset.theme = attribute;
+    });
+  })(${JSON.stringify(markup)}, ${JSON.stringify(attributes)})`);
+
+  await view.cdp("DOM.enable");
+  await view.cdp("CSS.enable");
+  const { root } = await view.cdp("DOM.getDocument");
+  const { nodeIds } = await view.cdp("DOM.querySelectorAll", {
+    nodeId: root.nodeId,
+    selector: "[data-hover]",
+  });
+  for (const nodeId of nodeIds) {
+    await view.cdp("CSS.forcePseudoState", { nodeId, forcedPseudoClasses: ["hover"] });
+  }
+
+  const colors = await view.evaluate(`(() => {
+    const rgba = ${RASTERIZE};
+    return [...document.querySelectorAll("[id^=island-]")].map((island) => {
+      const cs = (el) => getComputedStyle(el);
+      const pairs = {};
+      for (const el of island.querySelectorAll("[data-pair]")) {
+        // The invalid field's block-end border carries --form-invalid-border,
+        // the hook its focus outline reads, even on an underline-only theme
+        // (material) whose other sides are clear.
+        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) };
+      }
+      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),
+        };
+      }
+      return { pairs, soft };
+    });
+  })()`);
+
+  return islands.map(({ theme, scheme }, i) => {
+    const { pairs, soft } = colors[i];
+    const pair = (key) => ratio(pairs[key].fg, pairs[key].bg);
+    return {
+      theme,
+      scheme,
+      soft: INTENTS.map((intent) => ({
+        intent,
+        rest: ratio(soft[intent].fg, soft[intent].rest),
+        hover: ratio(soft[intent].fg, soft[intent].hover),
+      })),
+      focusSurface: pair("focus-surface"),
+      focusSolid: pair("focus-solid"),
+      invalidFocus: pair("invalid-field"),
+      inverse: pair("inverse"),
+    };
+  });
+}
+
+/*
+ * Measures one theme file over the framework, or the default theme without
+ * `themeFile`. `name` overrides the data-theme name read from the file; a file
+ * that declares none is a :root theme.
+ */
+export async function measureThemeFile({ themeFile, name }) {
+  const themeCss = themeFile ? await inlineImports(themeFile) : "";
+  const theme = themeFile ? themeNameOf(themeCss, name) : null;
+  const css = `${await inlineImports(FRAMEWORK)}\n${themeCss}`;
+  return measureContrast({ css, themes: [theme], label: themeFile ? ":root" : "default" });
+}
+
+/* Text tables for `rows`, and the number of pairs under their threshold. */
+export function formatContrast(rows) {
+  let misses = 0;
+  const cell = (value, min) => {
+    if (value === null) return { text: "n/a", miss: false };
+    const miss = value < min;
+    if (miss) misses += 1;
+    return { text: `${value.toFixed(2)}:1`, miss };
+  };
+  const width = Math.max(5, ...rows.map((row) => row.theme.length));
+  const head = (row) => `${row.theme.padEnd(width)}  ${row.scheme.padEnd(6)}`;
+  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`);
+  for (const row of rows) {
+    for (const { intent, 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)}`,
+      );
+    }
+  }
+
+  const single = (title, key, min) => {
+    lines.push("", title, "");
+    lines.push(`${"theme".padEnd(width)}  scheme   ratio`);
+    for (const row of rows) {
+      const c = cell(row[key], min);
+      lines.push(`${head(row)}  ${c.text.padStart(8)}${flag([c], min)}`);
+    }
+  };
+
+  lines.push("", "Focus line contrast (--focus vs --surface / --surface-solid), needs 3:1.", "");
+  lines.push(`${"theme".padEnd(width)}  scheme   surface     solid`);
+  for (const row of rows) {
+    const cells = [cell(row.focusSurface, 3), cell(row.focusSolid, 3)];
+    lines.push(
+      `${head(row)}  ${cells[0].text.padStart(8)}  ${cells[1].text.padStart(8)}${flag(cells, 3)}`,
+    );
+  }
+
+  // Documented exception (focus.css): an invalid field focuses in
+  // --form-invalid-border. The line is inset, so it reads against the
+  // field's own background, not the surface around it.
+  single(
+    "Invalid focus line contrast (--form-invalid-border vs field), needs 3:1.",
+    "invalidFocus",
+    3,
+  );
+  // Tooltip and status-bar text sit on this pair.
+  single(
+    "Inverse text contrast (--surface-solid-fg vs --surface-solid), needs 4.5:1.",
+    "inverse",
+    4.5,
+  );
+
+  return { text: lines.join("\n"), misses };
+}

package/docs/pages/patterns/actions.md

@@ -1,52 +0,0 @@
-# Actions
-
-Use `.actions` for a semantic list of actions.
-
-It removes native list chrome and provides a baseline row layout (`display: flex`, wrap, shared gap). Compose with layout primitives only when you need a different direction or distribution.
-
-```html demo
-<div class="stack">
-  <menu class="actions cluster">
-    <li><button class="btn primary" type="button">Save</button></li>
-    <li><button class="btn outline" type="button">Cancel</button></li>
-  </menu>
-
-  <menu class="actions stack">
-    <li><a class="btn primary" href="/billing">Update billing</a></li>
-    <li><a href="/support">Contact support</a></li>
-  </menu>
-</div>
-```
-
-Use `.actions` for:
-
-- dialog actions
-- alert actions
-- card actions
-- toolbar actions
-- form submit/cancel groups
-
-Use layout primitives for contextual spacing.
-
-```html demo
-<div class="alert warning stack">
-  <p>Your billing method has expired.</p>
-
-  <menu class="actions cluster">
-    <li><a class="btn danger sm" href="/billing">Update billing</a></li>
-    <li><a href="/support">Contact support</a></li>
-  </menu>
-</div>
-```
-
-Prefer composition over making each component reimplement action-list layout.
-
-```css
-/* Avoid */
-.alert > menu {
-  display: flex;
-  gap: var(--space-20);
-  padding: 0;
-  list-style: none;
-}
-```

package/src/css/components/actions.css

@@ -1,27 +0,0 @@
-/*
- * Actions — a horizontal action-button cluster.
- *
- * Docs: docs/pages/patterns/actions.md
- *
- * Composes with .btn (or any inline element) and feeds layout via the shared
- * --gap token.
- *
- * Internal:
- * --gap (local value for the shared gap token)
- */
-.actions {
-  --gap: var(--space-20);
-
-  display: flex;
-  flex-direction: row;
-  flex-wrap: wrap;
-  align-items: center;
-  gap: var(--gap);
-  margin: 0;
-  padding: 0;
-  list-style: none;
-}
-
-.actions > li {
-  margin: 0;
-}