@runbooks/design 0.1.0

package/dist/stylesheet.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/stylesheet.test.js

@@ -0,0 +1,265 @@
+import { describe, it, expect } from "vitest";
+import { readFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+/** Up from packages/design/src, the way the other tests in this package find the repo. */
+const ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "..", "..", "..");
+import { stylesheet, FACES, FONT_DIR, LATIN1_RANGE, PALETTES, RISK_COLORS, TYPE_SCALE, FONT_STACKS, NUMERIC_FEATURES, DEFAULT_THEME, } from "./index.js";
+const css = stylesheet({ defaultTheme: DEFAULT_THEME.catalog });
+/**
+ * The tokens existed, their contrast was measured, and no page had a stylesheet — so
+ * every value in this package was an agreement the product had made with itself. These
+ * assert the agreement reaches a document.
+ */
+describe("the stylesheet is the tokens and nothing invented", () => {
+    it("uses no colour that is not a token", () => {
+        const known = new Set([
+            ...Object.values(PALETTES).flatMap((palette) => Object.values(palette)),
+            ...Object.values(RISK_COLORS).flatMap((scale) => Object.values(scale)),
+        ].map((value) => value.toLowerCase()));
+        const used = [...css.matchAll(/#[0-9a-fA-F]{3,8}\b/g)].map((match) => match[0].toLowerCase());
+        expect(used.length, "the stylesheet has no colours at all").toBeGreaterThan(0);
+        for (const colour of new Set(used)) {
+            expect(known.has(colour), `${colour} is in the stylesheet and in no token`).toBe(true);
+        }
+    });
+    it("carries every step of the type scale", () => {
+        for (const [name, step] of Object.entries(TYPE_SCALE)) {
+            const kebab = name.replace(/[A-Z]/g, (letter) => `-${letter.toLowerCase()}`);
+            expect(css, `${name} has no size`).toContain(`--rb-${kebab}-size:${step.size}px`);
+            expect(css, `${name} has no leading`).toContain(`--rb-${kebab}-leading:${step.leading}px`);
+        }
+    });
+    it("caps the measure at the scale's line length rather than a per-page choice", () => {
+        expect(css).toContain(`--rb-measure:${TYPE_SCALE.body.maxLineLength}ch`);
+        expect(css).toMatch(/p,li\{ ?max-width:var\(--rb-measure\)/);
+    });
+    it("uses the token font stacks, so the fallback is the one that was chosen", () => {
+        expect(css).toContain(`--rb-sans:${FONT_STACKS.sans}`);
+        expect(css).toContain(`--rb-mono:${FONT_STACKS.mono}`);
+    });
+    it("turns tabular figures on where numbers appear in sequence", () => {
+        expect(css).toContain(`font-variant-numeric:${NUMERIC_FEATURES}`);
+        for (const selector of ["body", "table", "code,kbd,pre,samp"]) {
+            const block = new RegExp(`${selector.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}\\{[^}]*font-variant-numeric`);
+            expect(css, `${selector} does not set tabular figures`).toMatch(block);
+        }
+    });
+});
+/** §18.2's prohibitions, kept by having nothing to reach for. */
+describe("the prohibited list cannot be spelled here", () => {
+    it("has no shadow", () => {
+        expect(css).not.toMatch(/box-shadow|text-shadow|drop-shadow/);
+    });
+    it("has no gradient", () => {
+        expect(css).not.toMatch(/linear-gradient|radial-gradient|conic-gradient/);
+    });
+    it("has no uppercase transform", () => {
+        expect(css).not.toMatch(/text-transform\s*:\s*uppercase/);
+    });
+});
+/**
+ * Q10's answer, made operative: each surface has a default, and a viewer's explicit
+ * choice wins. A theme that could only be a default would be the lock Q10 refused.
+ */
+describe("both themes are reachable and a choice wins", () => {
+    it("emits the default palette on :root", () => {
+        const light = PALETTES[DEFAULT_THEME.catalog];
+        expect(css).toContain(`--rb-background:${light.background}`);
+    });
+    it("offers the other one, reachable by choosing it", () => {
+        const other = DEFAULT_THEME.catalog === "light" ? "dark" : "light";
+        expect(css).toContain(PALETTES[other].background);
+    });
+    it("does not hand the default to an operating-system setting", () => {
+        // Following prefers-color-scheme made the default whatever the desktop happened to
+        // be, so the site had one look on one machine and another on the next. Q10 refused a
+        // lock, not a default: the toggle below still wins, in either direction.
+        expect(css).not.toMatch(/@media \(prefers-color-scheme/);
+    });
+    it("lets an explicit choice override both, in either direction", () => {
+        expect(css).toMatch(/:root\[data-theme="light"\]/);
+        expect(css).toMatch(/:root\[data-theme="dark"\]/);
+    });
+    it("declares color-scheme, so form controls follow the page", () => {
+        expect(css).toMatch(/color-scheme:/);
+    });
+});
+/**
+ * What the stylesheet can promise on its own. That the files it names are served is the
+ * app's side of the same claim, and is asserted in apps/web/src/fonts.test.ts — this
+ * package does not know where a catalog puts its public directory.
+ */
+describe("the faces it names are the ones the scale needs", () => {
+    it("declares a face for each weight the scale asks for", () => {
+        const weights = new Set(Object.values(TYPE_SCALE).map((step) => step.weight));
+        for (const weight of weights) {
+            expect(FACES.some((face) => face.family === "IBM Plex Sans" && face.weight === weight), `no sans face at weight ${weight}, which the type scale asks for`).toBe(true);
+        }
+    });
+    it("points at each by the path it is served from", () => {
+        for (const face of FACES) {
+            expect(css).toContain(`url("${FONT_DIR}/${face.file}") format("woff2")`);
+        }
+    });
+    it("subsets by upstream's own range rather than one invented here", () => {
+        // The characters this catalog's prose is actually full of.
+        for (const codepoint of ["U+2013-2014", "U+201C-201E", "U+2026"]) {
+            expect(LATIN1_RANGE, `${codepoint} is outside the subset and will fall back mid-sentence`)
+                .toContain(codepoint);
+        }
+        expect(css.match(/unicode-range:/g)?.length).toBe(FACES.length);
+    });
+    it("swaps rather than blocking, so text is readable before the face arrives", () => {
+        expect(css.match(/font-display:swap/g)?.length).toBe(FACES.length);
+    });
+});
+/**
+ * The decision record and the code agree about what the default is.
+ *
+ * `docs/decisions/Q10-theme-per-surface.md` said the catalog defaults light for two days
+ * after it started defaulting dark. A decision file is what somebody reads to find out
+ * what was decided and why; one that describes the opposite of what runs sends them
+ * looking for a bug that is not there, or worse, to "restore" the behaviour it describes.
+ */
+describe("the theme decision says what the code does", () => {
+    const record = readFileSync(join(ROOT, "docs", "decisions", "Q10-theme-per-surface.md"), "utf8");
+    it.each(["canvas", "catalog"])("names %s's actual default", (surface) => {
+        const theme = DEFAULT_THEME[surface];
+        // The word appears near the surface it belongs to, rather than anywhere in the file.
+        expect(record.toLowerCase(), `${surface} defaults ${theme} and the record does not say so`)
+            .toMatch(new RegExp(`(both surfaces|${surface})[^.]{0,120}\\b${theme}\\b`, "i"));
+    });
+    it("still records the rule that outlived the default", () => {
+        // The lock is what Q10 refused, and that has not changed.
+        expect(record).toMatch(/neither is a lock/i);
+        expect(record).toMatch(/toggle/i);
+    });
+    it("does not describe the operating system as deciding it", () => {
+        expect(css, "the stylesheet took the default from the desktop again").not.toMatch(/@media \(prefers-color-scheme/);
+    });
+});
+/**
+ * §18.4: the hero fits the first screen.
+ *
+ * A width cap is not enough for a graph laid out top to bottom — scaled to the column it is
+ * still a thousand pixels tall, and everything the page says goes under it. The hero had no
+ * rule of its own until the layout turned vertical and it stopped being a poster.
+ */
+describe("the home page hero", () => {
+    it("is bounded by height, not only by width", () => {
+        expect(css, "no rule for the hero graph").toMatch(/\.hero-graph svg\{[^}]*max-height/);
+    });
+    /**
+     * Width leads and height follows, with the height still capped so the hero stays above
+     * the fold. It was the other way round, and a graph fitted by height left half of its
+     * column empty beside a tall procedure.
+     */
+    it("lets the width lead, with the height still capped", () => {
+        const rule = /\.hero-graph svg\{([^}]*)\}/.exec(css)?.[1] ?? "";
+        expect(rule).toContain("width:100%");
+        expect(rule).toContain("height:auto");
+        expect(rule, "nothing keeps the hero above the fold").toContain("max-height:");
+    });
+});
+/**
+ * §18.4 on a phone: the graph is a card and the full-screen view is where it is read.
+ *
+ * Seventy per cent of the viewport is most of a phone, so a reader who came for the steps
+ * meets a picture to scroll past. The card's job there is the silhouette's — that the
+ * procedure branches and that there is red in it — and reading belongs to full screen,
+ * which keeps the whole viewport.
+ */
+describe("the graph on a narrow screen", () => {
+    const narrow = css.slice(css.indexOf("@media (max-width:700px)"));
+    it("bounds the card well under the viewport", () => {
+        expect(narrow).toMatch(/\[data-slot="frame"\]\{ max-height:34vh/);
+    });
+    it("gives full screen the whole viewport anyway", () => {
+        expect(narrow).toMatch(/:fullscreen \[data-slot="frame"\]\{ max-height:none/);
+    });
+    it("lets the controls wrap rather than squeezing their targets", () => {
+        expect(narrow).toMatch(/\[data-slot="controls"\]\{ flex-wrap:wrap/);
+    });
+    /** The targets themselves are already 44px under a coarse pointer; this keeps that true. */
+    it("keeps the 44px floor for a thumb", () => {
+        expect(css).toMatch(/@media \(pointer:coarse\)\{[\s\S]*?min-height:44px/);
+    });
+});
+/**
+ * The rules that make a narrow screen readable, none of which was asserted.
+ *
+ * Four media queries carried the whole of the small-screen design and no test named one:
+ * the record page's two columns collapsing to one, the catalog's doing the same, the
+ * graph viewer giving back height and dropping a hint about a pointer nobody on a phone
+ * has, and motion being cut for a reader who asked for that. A stylesheet is text here —
+ * the viewport question is still open (D-05) and nothing in this repository can measure a
+ * rendered phone — so the text is what can honestly be checked, and it was not.
+ */
+describe("the small-screen rules exist and say what they must", () => {
+    /** Every block opened by this query, by brace depth: two may share a width. */
+    const blocks = (query) => {
+        const out = [];
+        for (let from = css.indexOf(query); from !== -1; from = css.indexOf(query, from + 1)) {
+            let depth = 0;
+            for (let i = from; i < css.length; i++) {
+                if (css[i] === "{")
+                    depth++;
+                else if (css[i] === "}" && --depth === 0) {
+                    out.push(css.slice(from, i + 1));
+                    break;
+                }
+            }
+        }
+        return out;
+    };
+    /** One media block, by brace depth, so an assertion cannot match the next block down. */
+    const block = (query) => {
+        const start = css.indexOf(query);
+        expect(start, `${query} is not in the stylesheet at all`).toBeGreaterThan(-1);
+        let depth = 0;
+        for (let i = start; i < css.length; i++) {
+            if (css[i] === "{")
+                depth++;
+            else if (css[i] === "}") {
+                depth--;
+                if (depth === 0)
+                    return css.slice(start, i + 1);
+            }
+        }
+        throw new Error(`${query} is never closed`);
+    };
+    it("collapses the record page to one column, and unsticks it with it", () => {
+        // By what it names, not by which comes first: a tool page opens a block at this width
+        // too, and `block` returning the first one made this assert about the wrong layout the
+        // day a second one was added.
+        // Every block at this width, not the first one that names the layout: since the phone
+        // pass there are two — the one that collapses the columns and the one that releases the
+        // sticky column, which has to come after the rule it takes back.
+        const narrow = blocks("@media (max-width:1100px)")
+            .filter((rule) => rule.includes('data-layout="record"'))
+            .join("\n");
+        expect(narrow, "no narrow-screen rule mentions the record layout").not.toBe("");
+        expect(narrow).toMatch(/\[data-layout="record"\]\{ grid-template-columns:minmax\(0,1fr\)/);
+        // Any column that stays stuck once it is full-width covers the one under it. Asked of
+        // every child rather than of the graph column: the half that sticks is the prose, and
+        // naming the other one was a rule that could not have caught the column it was for.
+        expect(narrow).toMatch(/\[data-layout="record"\]>\*\{[^}]*position:static/);
+    });
+    it("collapses the catalog to one column", () => {
+        expect(block("@media (max-width:820px)")).toMatch(/\[data-layout="catalog"\]\{ grid-template-columns:minmax\(0,1fr\)/);
+    });
+    it("gives the viewer back height on a phone and drops the pointer hint", () => {
+        // Two blocks share this width; the one that matters is the one naming the viewer.
+        const viewer = blocks("@media (max-width:600px)").find((rule) => rule.includes("graph-viewer"));
+        expect(viewer, "no narrow-screen rule mentions the graph viewer").toBeDefined();
+        expect(viewer).toMatch(/\[data-slot="frame"\]\{ max-height:60vh/);
+        expect(viewer).toMatch(/\[data-slot="hint"\]\{ display:none/);
+    });
+    it("cuts motion for a reader who asked for that", () => {
+        const still = block("@media (prefers-reduced-motion:reduce)");
+        expect(still).toMatch(/animation-duration:0\.01ms !important/);
+        expect(still).toMatch(/transition-duration:0\.01ms !important/);
+        expect(still).toMatch(/scroll-behavior:auto !important/);
+    });
+});

package/dist/text.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Measuring a label without a browser.
+ *
+ * The renderer is a pure function that runs in the build, in the CLI's SVG export and in
+ * a test — none of which has a text engine. Labels were therefore not measured at all:
+ * every node was 168px wide and every title was cut at 28 characters, which at 13px is
+ * about 175px, so the longest labels ran out past both edges of their own box. "Confirm
+ * the node is NotReady" was drawn as "onfirm the node is NotRead".
+ *
+ * An approximation is enough, because it is used to *reserve* space. The advances below
+ * are IBM Plex Sans at 1em, rounded, grouped by the classes that actually differ; the
+ * error against the real face is a few percent and the padding absorbs it. Being slightly
+ * generous is the safe direction: a box wider than its text is tidy, a box narrower than
+ * its text is broken.
+ */
+export declare function advance(character: string, size: number): number;
+export declare function measure(text: string, size: number): number;
+/**
+ * Break a label into at most `maxLines`, at word boundaries, and say how wide it needs.
+ *
+ * A word longer than the line is broken rather than allowed to overflow — a URL or a
+ * `kafka-consumer-groups` has to go somewhere, and running past the outline is the one
+ * option that makes the picture wrong rather than merely tight.
+ */
+export declare function wrap(text: string, size: number, maxWidth: number, maxLines: number): {
+    readonly lines: readonly string[];
+    readonly width: number;
+};

package/dist/text.js

@@ -0,0 +1,89 @@
+/**
+ * Measuring a label without a browser.
+ *
+ * The renderer is a pure function that runs in the build, in the CLI's SVG export and in
+ * a test — none of which has a text engine. Labels were therefore not measured at all:
+ * every node was 168px wide and every title was cut at 28 characters, which at 13px is
+ * about 175px, so the longest labels ran out past both edges of their own box. "Confirm
+ * the node is NotReady" was drawn as "onfirm the node is NotRead".
+ *
+ * An approximation is enough, because it is used to *reserve* space. The advances below
+ * are IBM Plex Sans at 1em, rounded, grouped by the classes that actually differ; the
+ * error against the real face is a few percent and the padding absorbs it. Being slightly
+ * generous is the safe direction: a box wider than its text is tidy, a box narrower than
+ * its text is broken.
+ */
+/** Advance widths in ems, by character class. */
+const NARROW = new Set("iljtIfr.,:;'\"`!|[](){}/\\-");
+const WIDE = new Set("mwMW@%");
+const CAPS = /[A-Z0-9]/;
+export function advance(character, size) {
+    if (character === " ")
+        return 0.26 * size;
+    if (NARROW.has(character))
+        return 0.32 * size;
+    if (WIDE.has(character))
+        return 0.86 * size;
+    if (CAPS.test(character))
+        return 0.62 * size;
+    return 0.53 * size;
+}
+export function measure(text, size) {
+    let total = 0;
+    for (const character of text)
+        total += advance(character, size);
+    return total;
+}
+/**
+ * Break a label into at most `maxLines`, at word boundaries, and say how wide it needs.
+ *
+ * A word longer than the line is broken rather than allowed to overflow — a URL or a
+ * `kafka-consumer-groups` has to go somewhere, and running past the outline is the one
+ * option that makes the picture wrong rather than merely tight.
+ */
+export function wrap(text, size, maxWidth, maxLines) {
+    const words = text.split(/\s+/).filter(Boolean);
+    const lines = [];
+    let current = "";
+    const push = () => {
+        if (current)
+            lines.push(current);
+        current = "";
+    };
+    for (const word of words) {
+        const candidate = current ? `${current} ${word}` : word;
+        if (measure(candidate, size) <= maxWidth) {
+            current = candidate;
+            continue;
+        }
+        push();
+        if (measure(word, size) <= maxWidth) {
+            current = word;
+            continue;
+        }
+        // A single word too long for the line: break it where it stops fitting.
+        let piece = "";
+        for (const character of word) {
+            if (measure(piece + character, size) > maxWidth) {
+                lines.push(piece);
+                piece = character;
+            }
+            else {
+                piece += character;
+            }
+        }
+        current = piece;
+    }
+    push();
+    if (lines.length <= maxLines) {
+        return { lines, width: Math.max(0, ...lines.map((line) => measure(line, size))) };
+    }
+    // Past the line budget the last line is elided, never a middle one: a reader who sees
+    // an ellipsis knows there is more, and one who sees a clipped word does not.
+    const kept = lines.slice(0, maxLines);
+    let last = kept[maxLines - 1] ?? "";
+    while (last.length > 1 && measure(`${last}…`, size) > maxWidth)
+        last = last.slice(0, -1);
+    kept[maxLines - 1] = `${last.trimEnd()}…`;
+    return { lines: kept, width: Math.max(0, ...kept.map((line) => measure(line, size))) };
+}

package/dist/tokens.d.ts

@@ -0,0 +1,104 @@
+import type { Risk } from "@runbooks/schema";
+export type Surface = "canvas" | "catalog";
+export type Theme = "light" | "dark";
+export interface Palette {
+    readonly background: string;
+    readonly surface: string;
+    readonly border: string;
+    readonly text: string;
+    readonly textSecondary: string;
+    readonly trust: string;
+}
+export declare const PALETTES: Readonly<Record<Theme, Palette>>;
+/**
+ * The risk scale, tuned per theme.
+ *
+ * The visual specification asked for one palette used everywhere, monotonic in
+ * lightness so it survives greyscale, and meeting a 3:1 stroke floor. Measured, its
+ * values satisfy none of those three at once, and the three cannot all hold: a single
+ * palette cannot clear 3:1 against both a near-black and a near-white ground while
+ * spanning enough lightness to be legible in greyscale. See
+ * docs/decisions/Q10-theme-per-surface.md.
+ *
+ * What is preserved is what the scale is *for*: severity always reads as darker, the
+ * ordering is identical in both themes, and the hue families are unchanged. What varies
+ * is only the rendering, and a card is read in one theme at a time — so a silhouette
+ * remains comparable to every other silhouette the same reader sees.
+ *
+ * Monotonic in lightness within each theme, and always duplicated by a text label: a
+ * hue is never the sole carrier of meaning.
+ */
+export declare const RISK_COLORS: Readonly<Record<Theme, Readonly<Record<Risk, string>>>>;
+export declare function riskColor(risk: Risk, theme: Theme): string;
+export declare const RISK_LABELS: Readonly<Record<Risk, string>>;
+/**
+ * Q10: each surface has a default, and a viewer's explicit choice wins.
+ *
+ * §18.2's reasoning is about exposure time — hours in the editor, minutes in the catalog
+ * — and that is a good reason for a *default*, not for a lock. Forcing a theme on
+ * someone who needs the other one is an accessibility failure, and the functional
+ * argument does not survive contact with that. Reasoning:
+ * docs/decisions/Q10-theme-per-surface.md.
+ */
+export declare const DEFAULT_THEME: Readonly<Record<Surface, Theme>>;
+export declare const TYPE_SCALE: {
+    readonly pageTitle: {
+        readonly size: 32;
+        readonly leading: 38;
+        readonly weight: 500;
+    };
+    readonly sectionTitle: {
+        readonly size: 20;
+        readonly leading: 28;
+        readonly weight: 500;
+    };
+    readonly body: {
+        readonly size: 15;
+        readonly leading: 24;
+        readonly weight: 400;
+        readonly maxLineLength: 75;
+    };
+    readonly nodeLabel: {
+        readonly size: 13;
+        readonly leading: 16;
+        readonly weight: 500;
+        readonly maxLines: 2;
+    };
+    readonly meta: {
+        readonly size: 13;
+        readonly leading: 18;
+        readonly weight: 400;
+    };
+    readonly code: {
+        readonly size: 13;
+        readonly leading: 20;
+        readonly weight: 400;
+        readonly mono: true;
+    };
+};
+export declare const FONT_STACKS: {
+    readonly sans: "\"IBM Plex Sans\", system-ui, -apple-system, \"Segoe UI\", sans-serif";
+    readonly mono: "\"IBM Plex Mono\", ui-monospace, \"SF Mono\", Menlo, monospace";
+};
+/** Numerals are tabular wherever numbers appear in sequence. */
+export declare const NUMERIC_FEATURES: "tabular-nums";
+export declare const NODE_RADIUS = 2;
+/**
+ * Contrast floors from §18.2. Asserted in tests against every pairing the product
+ * actually uses, rather than checked once by eye.
+ */
+export declare const CONTRAST_FLOOR: {
+    readonly text: 4.5;
+    readonly stroke: 3;
+};
+export declare function meetsTextFloor(foreground: string, background: string): boolean;
+export declare function meetsStrokeFloor(stroke: string, background: string): boolean;
+/** Risks ordered lightest to darkest within a theme. Should always equal RISK_ORDER. */
+export declare function riskLightnessOrder(theme: Theme): Risk[];
+/**
+ * Borders are dividers, not node strokes, and are exempt from the 3:1 stroke floor by
+ * design: a divider that met it would be a rule, and §18.2 separates by border *and*
+ * background rather than by shouting. Stated here so the exemption is a decision rather
+ * than an oversight the contrast test quietly skips.
+ */
+export declare const EXEMPT_FROM_STROKE_FLOOR: readonly ["border", "surface"];

package/dist/tokens.js

@@ -0,0 +1,142 @@
+/**
+ * Design tokens.
+ *
+ * The rule that shapes this file: **colour never encodes status and risk at the same
+ * time** (RUNBOOK.md §18.2). Risk owns the hue channel. Simulation and run state are
+ * expressed by stroke weight and background fill, and there is deliberately no token
+ * for a state colour — a rule is better kept by having nothing to reach for.
+ */
+import { contrast, lightness } from "./color.js";
+export const PALETTES = {
+    /**
+     * Dark, and the catalog's default.
+     *
+     * Measured, not chosen by eye — which is the same rule that caught the visual
+     * specification's own palette failing two of its three stated properties. Text reads
+     * 17.2:1 on the ground and 15.7:1 on a surface, secondary text 7.9:1 and 7.2:1, and the
+     * trust accent 11.4:1 against a floor of 4.5.
+     */
+    dark: {
+        background: "#0B0F14",
+        surface: "#131A23",
+        border: "#243444",
+        text: "#E8F4FF",
+        textSecondary: "#93A9BF",
+        trust: "#3DE0B0",
+    },
+    light: {
+        background: "#F7F6F3",
+        surface: "#FFFFFF",
+        border: "#D8D5CE",
+        text: "#141A1F",
+        textSecondary: "#6B7278",
+        trust: "#2F6B57",
+    },
+};
+/**
+ * The risk scale, tuned per theme.
+ *
+ * The visual specification asked for one palette used everywhere, monotonic in
+ * lightness so it survives greyscale, and meeting a 3:1 stroke floor. Measured, its
+ * values satisfy none of those three at once, and the three cannot all hold: a single
+ * palette cannot clear 3:1 against both a near-black and a near-white ground while
+ * spanning enough lightness to be legible in greyscale. See
+ * docs/decisions/Q10-theme-per-surface.md.
+ *
+ * What is preserved is what the scale is *for*: severity always reads as darker, the
+ * ordering is identical in both themes, and the hue families are unchanged. What varies
+ * is only the rendering, and a card is read in one theme at a time — so a silhouette
+ * remains comparable to every other silhouette the same reader sees.
+ *
+ * Monotonic in lightness within each theme, and always duplicated by a text label: a
+ * hue is never the sole carrier of meaning.
+ */
+export const RISK_COLORS = {
+    dark: {
+        /**
+         * Tuned against the node surface, not the page background: a node stroke is drawn on
+         * the surface, and the surface is the lighter of the two, so it is the ground that
+         * decides.
+         *
+         * Saturated, because on a near-black ground that is what stays legible at a stroke
+         * width — and because a risk scale is the one place in this design where colour is
+         * doing work. It is still the same four values in the same order, still monotonic in
+         * lightness, and still duplicated by a text label: severity reads as darker even in
+         * greyscale, and adjacent steps separate at 1.5:1 against a floor of 1.15.
+         */
+        "read-only": "#AEF4FF",
+        "reversible-write": "#E8B62C",
+        destructive: "#FF6A28",
+        irreversible: "#E81E57",
+    },
+    light: {
+        "read-only": "#598FA6",
+        "reversible-write": "#906F30",
+        destructive: "#96452F",
+        irreversible: "#702835",
+    },
+};
+export function riskColor(risk, theme) {
+    return RISK_COLORS[theme][risk];
+}
+export const RISK_LABELS = {
+    "read-only": "RO",
+    "reversible-write": "RW",
+    destructive: "DEL",
+    irreversible: "IRR",
+};
+/**
+ * Q10: each surface has a default, and a viewer's explicit choice wins.
+ *
+ * §18.2's reasoning is about exposure time — hours in the editor, minutes in the catalog
+ * — and that is a good reason for a *default*, not for a lock. Forcing a theme on
+ * someone who needs the other one is an accessibility failure, and the functional
+ * argument does not survive contact with that. Reasoning:
+ * docs/decisions/Q10-theme-per-surface.md.
+ */
+export const DEFAULT_THEME = {
+    canvas: "dark",
+    // Dark on both surfaces. §18.2 argued the catalog's default from exposure time — minutes
+    // rather than hours — and that argument was always about a *default*, never a lock.
+    // Q10's answer is unchanged and is what makes this a data change: a viewer's explicit
+    // choice still wins, in either direction, and the light palette is still measured and
+    // still shipped.
+    catalog: "dark",
+};
+export const TYPE_SCALE = {
+    pageTitle: { size: 32, leading: 38, weight: 500 },
+    sectionTitle: { size: 20, leading: 28, weight: 500 },
+    body: { size: 15, leading: 24, weight: 400, maxLineLength: 75 },
+    nodeLabel: { size: 13, leading: 16, weight: 500, maxLines: 2 },
+    meta: { size: 13, leading: 18, weight: 400 },
+    code: { size: 13, leading: 20, weight: 400, mono: true },
+};
+export const FONT_STACKS = {
+    sans: '"IBM Plex Sans", system-ui, -apple-system, "Segoe UI", sans-serif',
+    mono: '"IBM Plex Mono", ui-monospace, "SF Mono", Menlo, monospace',
+};
+/** Numerals are tabular wherever numbers appear in sequence. */
+export const NUMERIC_FEATURES = "tabular-nums";
+export const NODE_RADIUS = 2;
+/**
+ * Contrast floors from §18.2. Asserted in tests against every pairing the product
+ * actually uses, rather than checked once by eye.
+ */
+export const CONTRAST_FLOOR = { text: 4.5, stroke: 3 };
+export function meetsTextFloor(foreground, background) {
+    return contrast(foreground, background) >= CONTRAST_FLOOR.text;
+}
+export function meetsStrokeFloor(stroke, background) {
+    return contrast(stroke, background) >= CONTRAST_FLOOR.stroke;
+}
+/** Risks ordered lightest to darkest within a theme. Should always equal RISK_ORDER. */
+export function riskLightnessOrder(theme) {
+    return Object.keys(RISK_COLORS[theme]).sort((a, b) => lightness(RISK_COLORS[theme][b]) - lightness(RISK_COLORS[theme][a]));
+}
+/**
+ * Borders are dividers, not node strokes, and are exempt from the 3:1 stroke floor by
+ * design: a divider that met it would be a rule, and §18.2 separates by border *and*
+ * background rather than by shouting. Stated here so the exemption is a decision rather
+ * than an oversight the contrast test quietly skips.
+ */
+export const EXEMPT_FROM_STROKE_FLOOR = ["border", "surface"];

package/dist/tokens.test.d.ts

@@ -0,0 +1 @@
+export {};