@calliopelabs/ui 0.12.0 → 0.14.0

package/dist/theme/mappings/render.js

@@ -0,0 +1,520 @@
+import { block } from "../css.js";
+import { ACCENTS, GROUNDS } from "../tokens.js";
+import { ACCENT_KEYS, COLOR_TOKENS, DEFAULT_ACCENT, DEFAULT_GROUND, FONTS, GROUND_KEYS, allPalettes, flatten, fontFamily, parseColor, splitByAccent, staticNumbers, } from "./palette.js";
+import { JUPYTERLAB, JUPYTERLAB_STATIC, PLAIN, PLAIN_STATIC, VSCODE, VSCODE_STATIC, } from "./targets.js";
+const GENERATED = "Generated by `npm run theme` from the design tokens (tokens/*.json). Do not edit by hand.";
+/**
+ * A CSS target: `:root` paints the default ground and accent, each
+ * `[data-ground]` block paints its ground with the default accent, and each
+ * `[data-ground][data-accent]` block repaints what moves with the accent.
+ * The ground carries the mode, so no `data-mode` is needed; appearance.js
+ * from the CSS layer stamps the same attributes.
+ */
+function renderCss(options) {
+    const palettes = allPalettes();
+    const values = (ground, accent) => Object.fromEntries(options.rows.map((r) => [r.variable, palettes[ground][accent][r.token]]));
+    const split = splitByAccent(values);
+    const scheme = (ground) => options.colorScheme ? [["color-scheme", GROUNDS[ground].mode]] : [];
+    const groundDecls = (ground) => [
+        ...scheme(ground),
+        ...Object.entries({
+            ...split.ground[ground],
+            ...split.accent[ground][DEFAULT_ACCENT],
+        }).sort((a, b) => order(a[0]) - order(b[0])),
+    ];
+    const order = (variable) => options.rows.findIndex((r) => r.variable === variable);
+    const selector = (s) => [s, ...(options.also?.(s) ?? [])].join(",\n");
+    const blocks = [
+        `/*\n * ${options.title}\n * ${GENERATED}\n *\n${options.intro
+            .split("\n")
+            .map((line) => (line ? ` * ${line}` : " *"))
+            .join("\n")}\n */`,
+        block(":root", [
+            ...options.statics.map((s) => [s.variable, s.value]),
+            ...groundDecls(DEFAULT_GROUND),
+        ], `Default: ${GROUNDS[DEFAULT_GROUND].label} ground, ${ACCENTS[DEFAULT_ACCENT].label} accent`),
+        ...(options.extra?.(groundDecls) ?? []),
+    ];
+    for (const ground of GROUND_KEYS) {
+        const { label, mode } = GROUNDS[ground];
+        const base = `[data-ground="${ground}"]`;
+        blocks.push(block(selector(base), groundDecls(ground), `Ground: ${label} (${mode})`));
+        for (const accent of ACCENT_KEYS) {
+            const decls = Object.entries(split.accent[ground][accent]);
+            if (decls.length === 0)
+                continue;
+            blocks.push(block(selector(`${base}[data-accent="${accent}"]`), decls.sort((a, b) => order(a[0]) - order(b[0])), `Accent: ${ACCENTS[accent].label} on ${label}`));
+        }
+    }
+    return `${blocks.join("\n\n")}\n`;
+}
+export function renderJupyterLabCss() {
+    return renderCss({
+        title: "@calliopelabs/ui tokens for JupyterLab (--jp-*).",
+        intro: `Load after JupyterLab's own theme variables (a theme extension's
+variables.css, or a stylesheet the server adds to the lab page). With no
+data-ground, the ground follows JupyterLab's own theme: Black under a dark
+theme, Paper under a light one (data-jp-theme-light on <body>). Set
+data-ground (and data-accent) on <html> to choose one. See README.jupyterlab.md.`,
+        rows: JUPYTERLAB,
+        statics: JUPYTERLAB_STATIC,
+        also: (s) => [`${s} [data-jp-theme-light]`],
+        extra: (decls) => [
+            block('[data-jp-theme-light="true"]', decls("paper"), "No data-ground under a light JupyterLab theme: Paper"),
+        ],
+    });
+}
+export function renderVsCodeCss() {
+    return renderCss({
+        title: "@calliopelabs/ui tokens as VS Code webview fallbacks (--vscode-*).",
+        intro: `Inside a VS Code webview the host sets every --vscode-* variable
+inline on <html>, so the editor's theme wins and these never show. Outside
+VS Code (a browser preview, Storybook, a test) they stand in, so a webview
+written against --vscode-* looks like Calliope AI. data-ground and
+data-accent on <html> choose the ground and accent. See README.vscode.md.`,
+        rows: VSCODE,
+        statics: VSCODE_STATIC,
+    });
+}
+export function renderPlainCss() {
+    return renderCss({
+        title: "@calliopelabs/ui tokens as plain CSS variables.",
+        intro: `Every colour token under its own name as a concrete value (no var()
+chains, no color-mix, no product machinery), plus corners, motion and type.
+For static sites and apps that only read variables. data-ground and
+data-accent on <html> (or any element) choose the ground and accent.
+See README.plain.md.`,
+        rows: PLAIN,
+        statics: PLAIN_STATIC,
+        colorScheme: true,
+    });
+}
+/* Python ------------------------------------------------------------------ */
+const py = (value) => {
+    if (typeof value === "string")
+        return JSON.stringify(value);
+    if (typeof value === "number")
+        return String(value);
+    if (Array.isArray(value))
+        return `(${value.map(py).join(", ")}${value.length === 1 ? "," : ""})`;
+    throw new Error(`no Python literal for ${String(value)}`);
+};
+function pyDict(entries, indent) {
+    const pad = " ".repeat(indent);
+    if (entries.length === 0)
+        return "{}";
+    return `{\n${entries.map(([k, v]) => `${pad}    ${JSON.stringify(k)}: ${v},`).join("\n")}\n${pad}}`;
+}
+export function renderPython() {
+    const palettes = allPalettes();
+    const rgb = (g, a) => Object.fromEntries(COLOR_TOKENS.map((t) => {
+        const c = flatten(palettes[g][a], t);
+        return [t, py([c.r, c.g, c.b])];
+    }));
+    const alpha = (g, a) => Object.fromEntries(COLOR_TOKENS.flatMap((t) => {
+        const c = parseColor(palettes[g][a][t]);
+        return c.a === 1 ? [] : [[t, py([c.r, c.g, c.b, c.a])]];
+    }));
+    const nested = (split) => [
+        pyDict(GROUND_KEYS.map((g) => [g, pyDict(Object.entries(split.ground[g]), 4)]), 0),
+        pyDict(GROUND_KEYS.map((g) => [
+            g,
+            pyDict(ACCENT_KEYS.map((a) => [
+                a,
+                pyDict(Object.entries(split.accent[g][a]), 8),
+            ]), 4),
+        ]), 0),
+    ];
+    const [groundRgb, accentRgb] = nested(splitByAccent(rgb));
+    const [groundRgba, accentRgba] = nested(splitByAccent(alpha));
+    const { radius, motion } = staticNumbers();
+    return `"""@calliopelabs/ui tokens for Python, as RGB triplets.
+
+${GENERATED}
+
+Every colour token of every ground and family accent, as the preset paints it
+with no product brand. Translucent tokens (hairlines, tints) are given two
+ways: rgb() lays them on their surface (sidebar-* on the sidebar, the rest on
+the background) for targets with no alpha, and rgba() keeps the alpha.
+
+    from calliope_tokens import rgb, triplet, palette
+
+    rgb("background", "charcoal")           # (14, 15, 16)
+    triplet("primary", "paper", "copper")   # "156 87 48", for rgb(var(--x) / 0.2)
+    palette("emerald")                      # {"background": (5, 11, 8), ...}
+
+See README.python.md.
+"""
+
+from __future__ import annotations
+
+GROUNDS: dict[str, str] = ${pyDict(GROUND_KEYS.map((g) => [g, py(GROUNDS[g].mode)]), 0)}
+"""Every ground and its mode ("dark" or "light")."""
+
+ACCENTS: tuple[str, ...] = ${py([...ACCENT_KEYS])}
+"""The family accents."""
+
+TOKENS: tuple[str, ...] = (
+${COLOR_TOKENS.map((t) => `    ${JSON.stringify(t)},`).join("\n")}
+)
+"""Every colour token, by its CSS name without the leading dashes."""
+
+DEFAULT_GROUND = ${py(DEFAULT_GROUND)}
+DEFAULT_ACCENT = ${py(DEFAULT_ACCENT)}
+
+RADIUS_PX = ${radius}
+MOTION_MS: dict[str, int] = ${pyDict(Object.entries(motion).map(([k, v]) => [k, String(v)]), 0)}
+FONTS: dict[str, str] = ${pyDict(Object.entries(FONTS).map(([k, v]) => [k, py(v)]), 0)}
+"""CSS font stacks, as the preset sets --font-sans, --font-mono and --font-head."""
+
+Triplet = tuple[int, int, int]
+Rgba = tuple[int, int, int, float]
+
+# Per ground: what every accent agrees on. Per ground and accent: the rest.
+_GROUND_RGB: dict[str, dict[str, Triplet]] = ${groundRgb}
+
+_ACCENT_RGB: dict[str, dict[str, dict[str, Triplet]]] = ${accentRgb}
+
+# Translucent tokens only, with their alpha.
+_GROUND_RGBA: dict[str, dict[str, Rgba]] = ${groundRgba}
+
+_ACCENT_RGBA: dict[str, dict[str, dict[str, Rgba]]] = ${accentRgba}
+
+
+def _check(ground: str, accent: str) -> None:
+    if ground not in GROUNDS:
+        raise KeyError(f"unknown ground {ground!r}; one of {', '.join(GROUNDS)}")
+    if accent not in ACCENTS:
+        raise KeyError(f"unknown accent {accent!r}; one of {', '.join(ACCENTS)}")
+
+
+def palette(ground: str = DEFAULT_GROUND, accent: str = DEFAULT_ACCENT) -> dict[str, Triplet]:
+    """Every token of a ground and accent, as opaque RGB triplets."""
+    _check(ground, accent)
+    return {**_GROUND_RGB[ground], **_ACCENT_RGB[ground][accent]}
+
+
+def rgb(token: str, ground: str = DEFAULT_GROUND, accent: str = DEFAULT_ACCENT) -> Triplet:
+    """One token as an opaque (r, g, b), translucent ones laid on their surface."""
+    values = palette(ground, accent)
+    if token not in values:
+        raise KeyError(f"unknown token {token!r}")
+    return values[token]
+
+
+def rgba(token: str, ground: str = DEFAULT_GROUND, accent: str = DEFAULT_ACCENT) -> Rgba:
+    """One token as (r, g, b, alpha), keeping a translucent token's alpha."""
+    _check(ground, accent)
+    translucent = {**_GROUND_RGBA[ground], **_ACCENT_RGBA[ground][accent]}
+    if token in translucent:
+        return translucent[token]
+    r, g, b = rgb(token, ground, accent)
+    return (r, g, b, 1.0)
+
+
+def triplet(token: str, ground: str = DEFAULT_GROUND, accent: str = DEFAULT_ACCENT) -> str:
+    """One token as "R G B", the channel form CSS reads in rgb(var(--x) / alpha)."""
+    return " ".join(str(c) for c in rgb(token, ground, accent))
+
+
+def hex(token: str, ground: str = DEFAULT_GROUND, accent: str = DEFAULT_ACCENT) -> str:  # noqa: A001
+    """One token as opaque "#rrggbb"."""
+    return "#" + "".join(f"{c:02x}" for c in rgb(token, ground, accent))
+`;
+}
+/* React Native ------------------------------------------------------------ */
+const camel = (token) => token.replace(/-([a-z0-9])/g, (_, c) => c.toUpperCase());
+function jsObject(entries, indent) {
+    const pad = " ".repeat(indent);
+    if (entries.length === 0)
+        return "{}";
+    return `{\n${entries.map(([k, v]) => `${pad}  ${/^[a-zA-Z_$][\w$]*$/.test(k) ? k : JSON.stringify(k)}: ${v},`).join("\n")}\n${pad}}`;
+}
+export function renderNativeJs() {
+    const palettes = allPalettes();
+    const split = splitByAccent((g, a) => Object.fromEntries(COLOR_TOKENS.map((t) => [camel(t), palettes[g][a][t]])));
+    const { radius, motion } = staticNumbers();
+    const entries = (o) => Object.entries(o).map(([k, v]) => [k, JSON.stringify(v)]);
+    return `/*
+ * @calliopelabs/ui tokens for React Native.
+ * ${GENERATED}
+ *
+ * Colours are strings React Native's StyleSheet takes as they are (#rrggbb
+ * or rgba()), keyed in camelCase. palette(ground, accent) gives one ground
+ * and accent; each ground is also exported by name with the default accent.
+ * See README.native.md.
+ */
+
+export const GROUNDS = Object.freeze(${jsObject(GROUND_KEYS.map((g) => [
+        g,
+        `Object.freeze({ label: ${JSON.stringify(GROUNDS[g].label)}, mode: ${JSON.stringify(GROUNDS[g].mode)} })`,
+    ]), 0)});
+
+export const ACCENTS = Object.freeze(${JSON.stringify([...ACCENT_KEYS])});
+
+export const DEFAULT_GROUND = ${JSON.stringify(DEFAULT_GROUND)};
+export const DEFAULT_ACCENT = ${JSON.stringify(DEFAULT_ACCENT)};
+
+export const radius = ${radius};
+export const motion = Object.freeze(${jsObject(Object.entries(motion).map(([k, v]) => [k, String(v)]), 0)});
+export const fonts = Object.freeze(${jsObject(Object.entries(FONTS).map(([k, v]) => [
+        k,
+        JSON.stringify(fontFamily(v)),
+    ]), 0)});
+
+const byGround = ${jsObject(GROUND_KEYS.map((g) => [g, jsObject(entries(split.ground[g]), 2)]), 0)};
+
+const byAccent = ${jsObject(GROUND_KEYS.map((g) => [
+        g,
+        jsObject(ACCENT_KEYS.map((a) => [a, jsObject(entries(split.accent[g][a]), 4)]), 2),
+    ]), 0)};
+
+export function palette(ground = DEFAULT_GROUND, accent = DEFAULT_ACCENT) {
+  if (!Object.prototype.hasOwnProperty.call(byGround, ground)) {
+    throw new Error("unknown ground " + ground);
+  }
+  if (ACCENTS.indexOf(accent) < 0) throw new Error("unknown accent " + accent);
+  return Object.freeze(Object.assign({}, byGround[ground], byAccent[ground][accent]));
+}
+
+${GROUND_KEYS.map((g) => `export const ${g} = palette(${JSON.stringify(g)});`).join("\n")}
+`;
+}
+export function renderNativeDts() {
+    return `/*
+ * @calliopelabs/ui tokens for React Native: types.
+ * ${GENERATED}
+ */
+
+export type Ground = ${GROUND_KEYS.map((g) => JSON.stringify(g)).join(" | ")};
+export type Accent = ${ACCENT_KEYS.map((a) => JSON.stringify(a)).join(" | ")};
+export type Mode = "dark" | "light";
+
+/** Every colour token of one ground and accent, as #rrggbb or rgba(). */
+export interface Palette {
+${COLOR_TOKENS.map((t) => `  readonly ${camel(t)}: string;`).join("\n")}
+}
+
+export declare const GROUNDS: Readonly<Record<Ground, { readonly label: string; readonly mode: Mode }>>;
+export declare const ACCENTS: readonly Accent[];
+export declare const DEFAULT_GROUND: ${JSON.stringify(DEFAULT_GROUND)};
+export declare const DEFAULT_ACCENT: ${JSON.stringify(DEFAULT_ACCENT)};
+
+/** The corners setting, in points. */
+export declare const radius: number;
+/** Motion durations, in milliseconds. */
+export declare const motion: Readonly<{ fast: number; base: number; slow: number }>;
+/** Font family names; the app loads the fonts. */
+export declare const fonts: Readonly<{ sans: string; mono: string; head: string }>;
+
+export declare function palette(ground?: Ground, accent?: Accent): Palette;
+
+${GROUND_KEYS.map((g) => `export declare const ${g}: Palette;`).join("\n")}
+`;
+}
+/* READMEs ----------------------------------------------------------------- */
+function table(rows, statics) {
+    const sample = allPalettes()[DEFAULT_GROUND][DEFAULT_ACCENT];
+    const light = allPalettes().paper[DEFAULT_ACCENT];
+    const lines = [
+        "| Variable | Library token | Black, green | Paper, green | Note |",
+        "| --- | --- | --- | --- | --- |",
+        ...rows.map((r) => `| \`${r.variable}\` | \`--${r.token}\` | \`${sample[r.token]}\` | \`${light[r.token]}\` | ${r.note ?? ""} |`),
+        ...statics.map((s) => `| \`${s.variable}\` | \`${s.from}\` | \`${s.value}\` | same | Every ground |`),
+    ];
+    return lines.join("\n");
+}
+const GROUND_LIST = GROUND_KEYS.map((g) => `\`${g}\` (${GROUNDS[g].mode})`).join(", ");
+const ACCENT_LIST = ACCENT_KEYS.map((a) => `\`${a}\``).join(", ");
+const SELECTING = `Grounds: ${GROUND_LIST}. Accents: ${ACCENT_LIST}. The ground carries the mode, so there is no \`data-mode\`; \`:root\` paints \`${DEFAULT_GROUND}\` with \`${DEFAULT_ACCENT}\`. The CSS layer's \`appearance.js\` stamps the same \`data-ground\` and \`data-accent\` attributes from the person's stored choice.`;
+const FOOTER = `Generated by \`npm run theme\` from the design tokens (\`tokens/*.json\`), like the preset; a test holds every value to the preset's on every ground and accent.`;
+export function renderReadmes() {
+    return {
+        "README.md": `# @calliopelabs/ui tokens
+
+The family's tokens for stacks that cannot use the Tailwind preset or the CSS layer, generated from the same token table. Each value is what the preset paints on that ground with that accent and no product brand.
+
+| File | For | Guide |
+| --- | --- | --- |
+| \`jupyterlab.css\` | JupyterLab and Jupyter Notebook 7 (\`--jp-*\`) | [README.jupyterlab.md](README.jupyterlab.md) |
+| \`vscode.css\` | VS Code webviews outside VS Code (\`--vscode-*\` fallbacks) | [README.vscode.md](README.vscode.md) |
+| \`tokens.py\` | Python (the installer): RGB triplets and accessors | [README.python.md](README.python.md) |
+| \`tokens.native.js\`, \`tokens.native.d.ts\` | React Native | [README.native.md](README.native.md) |
+| \`plain.css\` | Sites and apps that read plain variables (Cykick) | [README.plain.md](README.plain.md) |
+
+Server-rendered apps that want the components as well take the CSS layer (\`@calliopelabs/ui/css/*\`) instead.
+
+${FOOTER}
+`,
+        "README.jupyterlab.md": `# JupyterLab: \`jupyterlab.css\`
+
+Maps the library tokens onto JupyterLab's theme variables, for JupyterLab 4 and Notebook 7 (JunoHub's lab).
+
+## Use
+
+In a theme extension, import it after the stock variables in the theme's \`style/variables.css\`:
+
+\`\`\`css
+@import "@jupyterlab/theme-dark-extension/style/variables.css";
+@import "@calliopelabs/ui/tokens/jupyterlab.css";
+\`\`\`
+
+Or, without an extension, serve the file and add it to the lab page after JupyterLab's styles (a \`custom.css\`, or the page template).
+
+With no \`data-ground\`, the ground follows JupyterLab's own theme switch: Black under a dark theme, Paper under a light one (JupyterLab sets \`data-jp-theme-light\` on \`<body>\`). To choose, set \`data-ground\` and \`data-accent\` on \`<html>\`; pick a ground whose mode matches the JupyterLab theme you load:
+
+\`\`\`js
+document.documentElement.dataset.ground = "charcoal";
+document.documentElement.dataset.accent = "copper";
+\`\`\`
+
+${SELECTING}
+
+Left as JupyterLab ships them: syntax colours (\`--jp-mirror-editor-*\`), the search highlight, collaborator and completer colours, scrollbars, font sizes, and the red "warn" dialog button set, whose white label the family's dark danger red cannot carry.
+
+## Mapping
+
+Layout colours run from the page (0) outwards; font colours from strongest (0) to faintest (3); state colours from text (0) and marks (1) to the tinted hairline (2) and the fill (3).
+
+${table(JUPYTERLAB, JUPYTERLAB_STATIC)}
+
+${FOOTER}
+`,
+        "README.vscode.md": `# VS Code webviews: \`vscode.css\`
+
+Calliope AI values for the \`--vscode-*\` variables a webview reads ([theme colour ids](https://code.visualstudio.com/api/references/theme-color), dots as dashes).
+
+## Use
+
+Link it in the webview's HTML before the webview's own styles:
+
+\`\`\`html
+<link rel="stylesheet" href="\${webview.asWebviewUri(vscodeCss)}" />
+\`\`\`
+
+Inside VS Code the host sets every \`--vscode-*\` variable inline on \`<html>\`, so the editor's theme always wins and these never show. Outside VS Code (a browser preview of the webview, Storybook, a test in jsdom) they stand in, so a webview written against \`--vscode-*\` renders in the family's colours.
+
+To go the other way, and paint the library's own tokens from the editor's theme with these as the fallback, read them through:
+
+\`\`\`css
+:root {
+  --background: var(--vscode-editor-background);
+  --foreground: var(--vscode-foreground);
+  --primary: var(--vscode-button-background);
+}
+\`\`\`
+
+${SELECTING}
+
+VS Code's \`--vscode-font-size\` and \`--vscode-editor-font-size\` are left to the host. Left alone: colours the family has no hue for (\`charts.blue\`, \`charts.purple\`, \`charts.orange\`; info is green) and scrollbars.
+
+## Mapping
+
+${table(VSCODE, VSCODE_STATIC)}
+
+${FOOTER}
+`,
+        "README.python.md": `# Python: \`tokens.py\`
+
+Every colour token of every ground and accent as RGB triplets, with a few accessors. Standard library only, Python 3.9 and up.
+
+## Use
+
+Copy (vendor) the file into the package under a module name of your choice, for example \`calliope_tokens.py\`:
+
+\`\`\`sh
+cp node_modules/@calliopelabs/ui/dist/tokens/tokens.py installer/wizard/calliope_tokens.py
+\`\`\`
+
+\`\`\`python
+from calliope_tokens import GROUNDS, palette, rgb, rgba, triplet, hex
+
+rgb("background", "charcoal")          # (14, 15, 16)
+triplet("primary", "paper", "copper")  # "156 87 48"
+rgba("border", "black")                # (255, 255, 255, 0.1)
+hex("border", "black")                 # "#1a1a1a", laid on the background
+palette("emerald", "ice")              # {"background": (5, 11, 8), ...}
+\`\`\`
+
+\`triplet\` is the \`R G B\` channel form CSS reads in \`rgb(var(--x-rgb) / 0.18)\`, so a stylesheet built in Python can take any alpha of any token:
+
+\`\`\`python
+css = "\\n".join(f"  --{name}-rgb: {' '.join(map(str, value))};" for name, value in palette(ground).items())
+\`\`\`
+
+Tokens are named as in CSS, without the dashes: \`background\`, \`card\`, \`primary\`, \`primary-foreground\`, \`muted-foreground\`, \`border\`, \`ring\`, \`success\`, \`success-fg\`, \`danger-bg\` and so on (\`TOKENS\` lists them all). Translucent tokens (hairlines, tints) come two ways: \`rgb\`, \`triplet\`, \`hex\` and \`palette\` lay them on their surface (\`sidebar-*\` on the sidebar, the rest on the background), for targets with no alpha; \`rgba\` keeps the alpha. \`RADIUS_PX\`, \`MOTION_MS\` and \`FONTS\` carry the rest.
+
+${SELECTING.replace(/ The CSS layer.*$/, "")}
+
+${FOOTER}
+`,
+        "README.native.md": `# React Native: \`tokens.native.js\`
+
+Every colour token of every ground and accent as objects React Native's \`StyleSheet\` takes as they are (\`#rrggbb\` or \`rgba()\`), keyed in camelCase, with types.
+
+## Use
+
+\`\`\`ts
+import { palette, charcoal, radius, fonts, GROUNDS } from "@calliopelabs/ui/tokens/native";
+
+const c = palette("paper", "copper");
+const styles = StyleSheet.create({
+  screen: { flex: 1, backgroundColor: c.background },
+  title: { color: c.foreground, fontFamily: fonts.head },
+  button: { backgroundColor: c.primary, borderRadius: radius },
+  buttonLabel: { color: c.primaryForeground },
+  hint: { color: c.mutedForeground },
+});
+
+// charcoal is palette("charcoal") with the default accent.
+const statusBar = GROUNDS.charcoal.mode === "dark" ? "light-content" : "dark-content";
+\`\`\`
+
+Each ground is exported by name (\`${GROUND_KEYS.join("`, `")}\`) with the default accent; \`palette(ground, accent)\` gives any combination and throws on an unknown one. Keys follow the CSS names in camelCase: \`background\`, \`card\`, \`primary\`, \`primaryForeground\`, \`mutedForeground\`, \`border\`, \`ring\`, \`chart1\`, \`sidebarAccent\`, \`success\`, \`successFg\`, \`dangerBg\` and so on. \`radius\` is in points, \`motion\` in milliseconds, and \`fonts\` holds family names; the app loads the fonts (IBM Plex Sans, IBM Plex Mono, DM Sans).
+
+The package is ESM; Metro resolves the \`@calliopelabs/ui/tokens/native\` subpath through \`exports\` (on by default since React Native 0.79). Or copy the two files into the app.
+
+${SELECTING.replace(/ The ground carries.*$/, "")}
+
+${FOOTER}
+`,
+        "README.plain.md": `# Plain CSS: \`plain.css\`
+
+Every colour token under its own name (\`--background\`, \`--primary\`, \`--success-fg\`, ...) as a concrete value, plus \`--radius\`, \`--motion-*\` and \`--font-sans\`, \`--font-mono\`, \`--font-head\`. No \`var()\` chains, no \`color-mix\`, no product or brand machinery, and \`color-scheme\` set per ground: for static sites and apps that only read variables (Cykick, the marketing sites).
+
+## Use
+
+\`\`\`html
+<html data-ground="charcoal" data-accent="ice">
+  <link rel="stylesheet" href="/static/calliope/plain.css" />
+\`\`\`
+
+\`\`\`css
+body { background: var(--background); color: var(--foreground); font-family: var(--font-sans); }
+.button { background: var(--primary); color: var(--primary-foreground); border-radius: var(--radius); }
+\`\`\`
+
+Any element can carry the attributes, so a section can sit on another ground. ${SELECTING}
+
+When to take the CSS layer (\`@calliopelabs/ui/css/tokens.css\`) instead: when the page needs product brands (the branded sidebar, a product's own accent), a custom accent colour, density or corners settings, or the class-based components. \`plain.css\` carries the family accents only.
+
+## Variables
+
+${table(PLAIN, PLAIN_STATIC)}
+
+${FOOTER}
+`,
+    };
+}
+/** Every generated file under src/tokens/, by file name. */
+export function renderTokenFiles() {
+    return {
+        "jupyterlab.css": renderJupyterLabCss(),
+        "vscode.css": renderVsCodeCss(),
+        "plain.css": renderPlainCss(),
+        "tokens.py": renderPython(),
+        "tokens.native.js": renderNativeJs(),
+        "tokens.native.d.ts": renderNativeDts(),
+        ...renderReadmes(),
+    };
+}

package/dist/theme/mappings/targets.d.ts

@@ -0,0 +1,43 @@
+import { type ColorToken } from "./palette.js";
+/**
+ * The mapping tables: which library token each target variable takes. One
+ * row per variable; the note says why when the match is not one to one.
+ * The READMEs print these tables, and the tests check every row's value
+ * against the preset on every ground and accent.
+ */
+export interface Row {
+    variable: string;
+    token: ColorToken;
+    note?: string;
+}
+/** A target variable set once, the same on every ground (type, corners). */
+export interface StaticRow {
+    variable: string;
+    value: string;
+    from: string;
+}
+/**
+ * JupyterLab theme variables (`@jupyterlab/theme-light-extension` and
+ * `theme-dark-extension`, `style/variables.css`). Layout colours run from
+ * the page (0) outwards; font colours from strongest (0) to faintest (3);
+ * brand and state colours from the strong end (0, 1) to the pale tint (3).
+ * Left alone: syntax colours (`--jp-mirror-editor-*`), the search
+ * highlight, collaborator and completer colours, and the red "warn" button
+ * set, whose white label the family's dark danger red cannot carry.
+ */
+export declare const JUPYTERLAB: readonly Row[];
+export declare const JUPYTERLAB_STATIC: readonly StaticRow[];
+/**
+ * VS Code theme colours as a webview sees them: `--vscode-` and the colour
+ * id with dots as dashes (https://code.visualstudio.com/api/references/theme-color).
+ * Inside VS Code the host sets these inline on <html>, so they win and the
+ * webview follows the editor's theme; outside it (a browser preview,
+ * Storybook, a test) these values stand in. Left alone: colours the family
+ * has no hue for (`charts.blue`, `charts.purple`, `charts.orange`) and
+ * scrollbars.
+ */
+export declare const VSCODE: readonly Row[];
+export declare const VSCODE_STATIC: readonly StaticRow[];
+/** Plain: every colour token under its own name, as concrete values. */
+export declare const PLAIN: readonly Row[];
+export declare const PLAIN_STATIC: readonly StaticRow[];