actual-css 0.11.0 → 0.12.0

package/src/tooling/penpot-plugin/plugin.js

@@ -0,0 +1,272 @@
+/*
+ * Penpot plugin: builds Actual CSS components from spec.json (written by
+ * `bun run export:design`) and binds them to the tokens imported from
+ * penpot/tokens.json.
+ *
+ * The spec holds measured values, not rules: each variant is one board with
+ * a flex layout and its texts, sized and painted as the browser rendered it.
+ * Only colors are bound to tokens. Literal values are set first and tokens
+ * applied on top, so a token the
+ * plugin API refuses leaves a correct-looking shape and a report line rather
+ * than a broken one. Tokens are applied before createComponent: the API drops
+ * token bindings on component children without an error (penpot/penpot#8520).
+ */
+penpot.ui.open("Actual CSS components", `ui.html?theme=${penpot.theme}`, {
+  width: 300,
+  height: 380,
+});
+
+penpot.ui.onMessage(async (message) => {
+  if (message?.type !== "build") return;
+  let text;
+  try {
+    text = await build(message.spec, message.font);
+  } catch (error) {
+    text = `Build failed: ${error?.message ?? error}`;
+  }
+  penpot.ui.sendMessage({ type: "report", text });
+});
+
+/* Tokens are applied by name; an active set wins over an inactive one with
+   the same token, like Penpot's own resolution. */
+function tokensByName() {
+  const tokens = new Map();
+  for (const set of penpot.library.local.tokens.sets) {
+    for (const token of set.tokens) {
+      if (!tokens.has(token.name) || set.active) tokens.set(token.name, token);
+    }
+  }
+  return tokens;
+}
+
+const COMPONENT_GAP = 64;
+const PAGE_NAME = "Actual CSS components";
+
+/* Main components live on their own page, the usual home of a library: the
+   variant sets are large (a Button is Intent × Variant × Size) and a working
+   page only needs instances, dragged from Assets. New shapes land on the
+   active page, so the page is opened (and awaited) before building. */
+async function openComponentsPage(log) {
+  try {
+    const page =
+      penpot.currentFile?.pages?.find((p) => p.name === PAGE_NAME) ?? penpot.createPage();
+    page.name = PAGE_NAME;
+    await penpot.openPage(page);
+  } catch (error) {
+    log.notes.push(
+      `Built on the current page: "${PAGE_NAME}" could not be opened (${error?.message ?? error}).`,
+    );
+  }
+}
+
+async function build(spec, fontName) {
+  const tokens = tokensByName();
+  const log = {
+    variants: 0,
+    applied: 0,
+    built: [],
+    missing: new Set(),
+    failed: new Set(),
+    notes: [],
+  };
+  if (tokens.size === 0) log.notes.push("No tokens found: import penpot/tokens.json first.");
+
+  const bind = (shape, value, properties) => {
+    if (!value?.token) return;
+    const token = tokens.get(value.token);
+    if (!token) {
+      log.missing.add(value.token);
+      return;
+    }
+    try {
+      shape.applyToken(token, properties);
+      log.applied += 1;
+    } catch (error) {
+      log.failed.add(`${token.type} → ${properties ?? "default"}: ${error?.message ?? error}`);
+    }
+  };
+
+  const font = fontName ? penpot.fonts.findByName(fontName) : null;
+  if (fontName && !font) log.notes.push(`Font "${fontName}" not found; Penpot's default is used.`);
+
+  await openComponentsPage(log);
+
+  // Right of whatever the page holds: a rebuild over a previous one reads as
+  // broken components (transparent boards show the old text through).
+  const existing = penpot.currentPage?.root?.children ?? [];
+  const origin = {
+    x: existing.length ? Math.max(...existing.map((s) => s.x + s.width)) + 200 : 0,
+    y: existing.length ? Math.min(...existing.map((s) => s.y)) : 0,
+  };
+
+  // Components side by side, each at the right of the previous one.
+  for (const component of spec.components) {
+    const shapes = buildComponent(component, { bind, font, log, origin });
+    origin.x = Math.max(...shapes.map((s) => s.x + s.width)) + COMPONENT_GAP;
+  }
+
+  // Show the result: the build lands at the page origin, often off screen.
+  try {
+    penpot.selection = log.built;
+    penpot.viewport.zoomIntoView(log.built);
+  } catch (error) {
+    log.notes.push(`Could not select the result: ${error?.message ?? error}`);
+  }
+
+  const names = spec.components.map((c) => c.name).join(", ");
+  return [
+    `${log.variants} variants built, ${log.applied} token bindings applied.`,
+    `${names}: built on the "${PAGE_NAME}" page and listed under Assets → Components.`,
+    "Drag an instance onto any page, then pick its Intent / Variant / Size in the right panel.",
+    "Check the bindings: Tokens → Themes → Mode / Dark repaints the components.",
+    ...log.notes,
+    log.missing.size ? `Missing tokens: ${[...log.missing].join(", ")}` : "",
+    log.failed.size ? `Refused bindings:\n- ${[...log.failed].join("\n- ")}` : "",
+  ]
+    .filter(Boolean)
+    .join("\n\n");
+}
+
+function paint({ hex, opacity }) {
+  return { fillColor: hex, fillOpacity: opacity };
+}
+
+/*
+ * Penpot lays a text out only after the plugin call returns: a new text reads
+ * 0×0, and flex places that empty box (a centred label then grows from the
+ * centre down-right). Each text gets the browser's box up front; the grow type
+ * then corrects the few pixels the design font differs by. Waiting for the
+ * layout inside the plugin never ends: it does not happen while we run.
+ */
+function buildText(spec, { column, font, bind }) {
+  const text = penpot.createText(spec.label);
+  if (font) {
+    const weight = String(spec.fontWeight);
+    const face = font.variants?.find((v) => v.fontWeight === weight && v.fontStyle === "normal");
+    font.applyToText(text, face);
+  }
+  text.fontSize = String(spec.fontSize);
+  text.fontWeight = String(spec.fontWeight);
+  text.lineHeight = String(spec.lineHeight);
+  text.fills = [paint(spec.color)];
+  if (spec.underline) text.textDecoration = "underline";
+  text.resize(Math.max(1, spec.width), Math.ceil(spec.fontSize * spec.lineHeight));
+  // In a column the text keeps its width and wraps (a card body); in a row
+  // it follows its label (a button, a badge).
+  text.growType = column ? "auto-height" : "auto-width";
+
+  bind(text, spec.color, ["fill"]);
+  return text;
+}
+
+function buildVariant(component, variant, { bind, font }) {
+  const { box } = variant;
+  const column = box.dir === "column";
+  const board = penpot.createBoard();
+  board.name = component.name;
+  board.fills = box.fill ? [paint(box.fill)] : [];
+  board.strokes = box.stroke
+    ? [
+        {
+          strokeColor: box.stroke.hex,
+          strokeOpacity: box.stroke.opacity,
+          strokeWidth: box.borderWidth,
+          strokeAlignment: "inner",
+          strokeStyle: "solid",
+        },
+      ]
+    : [];
+  board.borderRadius = box.radius;
+
+  const flex = board.addFlexLayout();
+  flex.dir = box.dir;
+  flex.alignItems = column ? "start" : "center";
+  flex.justifyContent = box.justify;
+  flex.rowGap = box.gap;
+  flex.columnGap = box.gap;
+  flex.leftPadding = box.padding.left;
+  flex.rightPadding = box.padding.right;
+  // A control's height is fixed and centres its row; the vertical padding is
+  // only what the browser needed to get there.
+  if (!box.fixedHeight) {
+    flex.topPadding = box.padding.top;
+    flex.bottomPadding = box.padding.bottom;
+  }
+
+  for (const spec of variant.texts) board.appendChild(buildText(spec, { column, font, bind }));
+
+  board.resize(box.width, box.height);
+  // Hug the label so the component grows when the text is edited, and let a
+  // content-height box follow its texts. Safe only because the texts already
+  // have their box: hugging a 0×0 text shrank every board to its padding.
+  if (box.hug) flex.horizontalSizing = "auto";
+  if (!box.fixedHeight) flex.verticalSizing = "auto";
+
+  // Colors only: they are what a theme switch repaints. Lengths stay literal
+  // (see design-components.js for why).
+  bind(board, box.fill, ["fill"]);
+  if (box.stroke) bind(board, box.stroke, ["strokeColor"]);
+  return board;
+}
+
+/* A single variant is a plain component. Several are laid out one row per
+   combination of the leading properties, one column per value of the last,
+   then combined into one variant set. Returns the shapes placed on the page. */
+function buildComponent(component, { bind, font, log, origin }) {
+  const gap = 16;
+  const last = component.properties.at(-1);
+  const perRow = new Set(component.variants.map((v) => v.props[last])).size;
+  let x = 0;
+  let y = 0;
+  let rowHeight = 0;
+
+  const boards = component.variants.map((variant, i) => {
+    const board = buildVariant(component, variant, { bind, font });
+    if (i > 0 && i % perRow === 0) {
+      x = 0;
+      y += rowHeight + gap;
+      rowHeight = 0;
+    }
+    board.x = origin.x + x;
+    board.y = origin.y + y;
+    x += board.width + gap;
+    rowHeight = Math.max(rowHeight, board.height);
+    log.variants += 1;
+    return board;
+  });
+
+  const library = penpot.library.local;
+  const created = boards.map((board) => library.createComponent([board]));
+  if (created.length === 1) {
+    log.built.push(...boards);
+    return boards;
+  }
+
+  try {
+    const [first, ...rest] = created.map((c) => c.mainInstance());
+    first.combineAsVariants(rest.map((shape) => shape.id));
+
+    const members = created.map((c) => library.components.find((m) => m.id === c.id) ?? c);
+    const { variants } = members[0];
+    while (variants.properties.length < component.properties.length) variants.addProperty();
+    component.properties.forEach((name, pos) => {
+      variants.renameProperty(pos, name);
+    });
+    members.forEach((member, i) => {
+      component.properties.forEach((name, pos) => {
+        member.setVariantProperty(pos, component.variants[i].props[name]);
+      });
+    });
+    // combineAsVariants wraps the main instances in the variant container.
+    // Painted with the theme page, so light-ink variants (outline, ghost,
+    // link in dark) sit on their own surface rather than on the canvas.
+    const container = first.parent ?? first;
+    if (container !== first) bind(container, { token: "surface" }, ["fill"]);
+    log.built.push(container);
+    return [container];
+  } catch (error) {
+    log.failed.add(`variants of ${component.name}: ${error?.message ?? error}`);
+    log.built.push(...boards);
+    return boards;
+  }
+}

package/src/tooling/penpot-plugin/ui.html

@@ -0,0 +1,58 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <title>Actual CSS components</title>
+    <script>
+      /* Penpot passes its own theme (light/dark); the system colors below
+         follow it through color-scheme. */
+      document.documentElement.style.colorScheme =
+        new URLSearchParams(location.search).get("theme") === "light" ? "light" : "dark";
+    </script>
+    <style>
+      body {
+        background: Canvas;
+        color: CanvasText;
+        margin: 0;
+        padding: 12px;
+        font: 13px/1.4 system-ui, sans-serif;
+      }
+      label {
+        display: block;
+        margin-block-end: 8px;
+      }
+      input {
+        inline-size: 100%;
+        box-sizing: border-box;
+      }
+      pre {
+        white-space: pre-wrap;
+        font-size: 12px;
+      }
+    </style>
+  </head>
+  <body>
+    <p>Import <code>penpot/tokens.json</code> first (Tokens → Tools → Import).</p>
+    <label>
+      Font family
+      <input id="font" value="Inter" />
+    </label>
+    <button id="build" type="button">Build components</button>
+    <pre id="report"></pre>
+    <script>
+      /* The spec is written next to this page by `bun run export:design`. */
+      const report = document.getElementById("report");
+      document.getElementById("build").addEventListener("click", async () => {
+        report.textContent = "Building…";
+        const spec = await fetch("spec.json").then((response) => response.json());
+        parent.postMessage(
+          { type: "build", spec, font: document.getElementById("font").value.trim() },
+          "*",
+        );
+      });
+      window.addEventListener("message", (event) => {
+        if (event.data?.type === "report") report.textContent = event.data.text;
+      });
+    </script>
+  </body>
+</html>

package/src/tooling/theme-contrast.js

@@ -0,0 +1,209 @@
+/*
+ * 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. */
+function islandMarkup(id, attribute, scheme) {
+  const style = scheme ? ` style="color-scheme: ${scheme}"` : "";
+  return `<div data-theme="${attribute}"${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 default theme, read
+ * through its light and dark boundaries; a named theme is read in each scheme
+ * its `color-scheme` declares. Returns one row per island.
+ */
+export async function measureContrast({ css, themes }) {
+  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) => {
+    const style = document.createElement("style");
+    style.textContent = css + "\\n* { transition-duration: 0s !important; }";
+    document.head.append(style);
+
+    const schemesOf = (attribute) => {
+      const probe = document.createElement("div");
+      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((theme) =>
+      theme === null
+        ? ["light", "dark"].map((scheme) => ({ theme: "default", scheme, attribute: scheme, pin: false }))
+        : schemesOf(theme).map((scheme, _, all) => ({ theme, scheme, attribute: theme, pin: all.length > 1 })),
+    );
+  })(${JSON.stringify(css)}, ${JSON.stringify(themes)})`);
+
+  const markup = islands
+    .map((island, i) =>
+      islandMarkup(`island-${i}`, island.attribute, island.pin ? island.scheme : null),
+    )
+    .join("\n");
+  await view.evaluate(`document.body.insertAdjacentHTML("beforeend", ${JSON.stringify(markup)})`);
+
+  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.
+ */
+export async function measureThemeFile({ themeFile, name }) {
+  const themeCss = themeFile ? await inlineImports(themeFile) : "";
+  const theme = themeFile ? (name ?? themeNameOf(themeCss)) : null;
+  const css = `${await inlineImports(FRAMEWORK)}\n${themeCss}`;
+  return measureContrast({ css, themes: [theme] });
+}
+
+/* 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;
-}