@runbooks/design 0.1.0

package/dist/render.test.d.ts

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

package/dist/render.test.js

@@ -0,0 +1,179 @@
+import { describe, it, expect } from "vitest";
+import { readdirSync, readFileSync } from "node:fs";
+import { join, dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { toGraph, topologicalOrder } from "@runbooks/graph";
+import { PALETTES } from "./tokens.js";
+import { renderGraph } from "./render.js";
+const CORPUS = resolve(dirname(fileURLToPath(import.meta.url)), "..", "..", "schema", "fixtures", "p1-valid");
+const corpus = readdirSync(CORPUS).map((name) => ({
+    name,
+    graph: toGraph(JSON.parse(readFileSync(join(CORPUS, name), "utf8"))),
+}));
+const THEMES = ["dark", "light"];
+/**
+ * §18.4 puts the graph above the fold. A graph that appears only after JavaScript loads
+ * is invisible to a crawler and to a reader on a slow connection during an incident,
+ * which is exactly when this page is opened.
+ */
+describe("the graph renders without JavaScript", () => {
+    it.each(corpus)("$name produces complete markup from a pure call", ({ graph }) => {
+        const { svg, list } = renderGraph(graph, { theme: "light" });
+        expect(svg).toMatch(/^<svg /);
+        expect(svg).toContain("</svg>");
+        for (const node of graph.nodes) {
+            expect(svg, `${node.id} is missing from the picture`).toContain(`data-node="${node.id}"`);
+            expect(list, `${node.id} is missing from the list`).toContain(`step-${node.id}`);
+        }
+    });
+    it.each(corpus)("$name renders identically twice", ({ graph }) => {
+        expect(renderGraph(graph, { theme: "dark" })).toEqual(renderGraph(graph, { theme: "dark" }));
+    });
+});
+/**
+ * The list is not a fallback, it is the accessible representation: the SVG is
+ * aria-hidden and this is what a screen reader reads. A procedure that cannot be read
+ * linearly is inaccessible.
+ */
+describe("the graph is also a structured list", () => {
+    it("hides the picture from assistive technology", () => {
+        const { svg } = renderGraph(corpus[0].graph, { theme: "light" });
+        expect(svg).toContain('aria-hidden="true"');
+        expect(svg).toContain('focusable="false"');
+    });
+    it.each(corpus)("$name announces kind, risk and where each step goes", ({ graph }) => {
+        const { list } = renderGraph(graph, { theme: "light" });
+        for (const node of graph.nodes) {
+            const entry = list.split("<li ").find((chunk) => chunk.includes(`step-${node.id}"`));
+            expect(entry).toContain(node.kind);
+            if (node.risk)
+                expect(entry).toContain(node.risk);
+            expect(entry).toMatch(/Goes |Terminal/);
+        }
+    });
+    it("names an approval gate in the list, not only as a mark", () => {
+        const graph = toGraph({
+            runbook: {
+                steps: [
+                    { id: "s1", kind: "action", title: "Drop it", risk: "destructive", requires_approval: true, next: "end:success" },
+                ],
+            },
+        });
+        expect(renderGraph(graph, { theme: "light" }).list).toContain("requires approval");
+    });
+});
+describe("keyboard traversal reaches every node, in topological order", () => {
+    it.each(corpus)("$name is focusable in order", ({ graph }) => {
+        const { svg } = renderGraph(graph, { theme: "light" });
+        const focusable = [...svg.matchAll(/data-node="([^"]+)" data-order="(\d+)"/g)];
+        expect(focusable).toHaveLength(graph.nodes.length);
+        const ordered = focusable
+            .sort((a, b) => Number(a[2]) - Number(b[2]))
+            .map((m) => m[1]);
+        expect(ordered).toEqual(topologicalOrder(graph));
+        expect(svg.match(/tabindex="0"/g)).toHaveLength(graph.nodes.length);
+    });
+    // A mini-graph in a card is decoration beside a link; making 7 nodes focusable inside
+    // every card would flood the tab order of the catalog.
+    it("takes the mini-graph out of the tab order", () => {
+        const { svg } = renderGraph(corpus[0].graph, { theme: "light", mode: "mini" });
+        expect(svg).not.toContain('tabindex="0"');
+    });
+});
+describe("mini mode stays legible at card size", () => {
+    it.each(corpus)("$name fits a card without dropping a node", ({ graph }) => {
+        const mini = renderGraph(graph, { theme: "light", mode: "mini" });
+        expect(mini.width).toBeLessThanOrEqual(320);
+        expect(mini.height).toBeLessThanOrEqual(200);
+        for (const node of graph.nodes)
+            expect(mini.svg).toContain(`data-node="${node.id}"`);
+    });
+    it("drops labels rather than shrinking them past reading", () => {
+        const mini = renderGraph(corpus[0].graph, { theme: "light", mode: "mini" });
+        expect(mini.svg).not.toContain("<text");
+    });
+    // The silhouette's job: show whether there is red in the procedure.
+    it("keeps risk colour in the silhouette", () => {
+        const graph = toGraph({
+            runbook: {
+                steps: [{ id: "s1", kind: "action", title: "Drop it", risk: "destructive", requires_approval: true, next: "end:success" }],
+            },
+        });
+        const mini = renderGraph(graph, { theme: "light", mode: "mini" });
+        expect(mini.svg).toContain("#96452F");
+    });
+});
+describe("motion and print", () => {
+    it("disables animation when the reader asks for none", () => {
+        expect(renderGraph(corpus[0].graph, { theme: "light" }).svg)
+            .toContain("prefers-reduced-motion: reduce");
+    });
+    it("carries a hatch per risk for print", () => {
+        const { svg } = renderGraph(corpus[0].graph, { theme: "light" });
+        expect(svg).toMatch(/data-hatch="[a-z-]+"/);
+        expect(svg).toContain("@media print");
+    });
+});
+describe("two graphs on one page do not collide", () => {
+    it("namespaces marker ids", () => {
+        const a = renderGraph(corpus[0].graph, { theme: "light", idPrefix: "a" });
+        const b = renderGraph(corpus[0].graph, { theme: "light", idPrefix: "b" });
+        expect(a.svg).toContain('id="a-arrow"');
+        expect(b.svg).toContain('id="b-arrow"');
+        expect(a.svg).not.toContain("b-arrow");
+    });
+});
+describe("both themes render", () => {
+    it.each(THEMES)("%s uses its own palette", (theme) => {
+        const { svg } = renderGraph(corpus[0].graph, { theme });
+        // Read from the palette rather than written again here: a hex in a test is a second
+        // copy of a decision, and the copy is the one that goes stale.
+        expect(svg).toContain(PALETTES[theme].background);
+    });
+});
+/**
+ * Risk survives the loss of colour (§18.2, D-02's hatching variants).
+ *
+ * Hue is risk's channel and paper does not have one. `RISK_HATCH` named a pattern per
+ * level and `data-hatch` carried the name for as long as the renderer has existed — and
+ * nothing painted one, while the print rule set `fill:none` on exactly those nodes. A
+ * printed procedure showed a destructive step and a read-only step as the same grey
+ * outline: the substitute was declared, and the thing it substitutes for was removed.
+ */
+describe("printing keeps the one property a reader must not miss", () => {
+    const drawn = (idPrefix) => renderGraph(toGraph({
+        runbook: {
+            steps: [
+                { id: "s1", kind: "check", title: "Look", risk: "read-only", expect: "ok", on_fail: "s9", next: "s2" },
+                { id: "s2", kind: "action", title: "Change it", risk: "reversible-write", next: "s3" },
+                { id: "s3", kind: "action", title: "Drop it", risk: "destructive", requires_approval: true, next: "s4" },
+                { id: "s4", kind: "action", title: "Wipe it", risk: "irreversible", requires_approval: true, next: "end:success" },
+                { id: "s9", kind: "escalate", title: "Escalate", to: "team:x" },
+            ],
+        },
+    }), { theme: "light", idPrefix }).svg;
+    const svg = drawn("g1");
+    it("marks every risk with the hatch the design package names for it", () => {
+        for (const hatch of ["none", "diagonal-thin", "diagonal-dense", "cross"]) {
+            expect(svg, `no node carries ${hatch}`).toContain(`data-hatch="${hatch}"`);
+        }
+    });
+    it.each(["diagonal-thin", "diagonal-dense", "cross"])("defines the %s pattern", (hatch) => {
+        expect(svg).toContain(`<pattern id="g1-hatch-${hatch}"`);
+    });
+    it.each(["diagonal-thin", "diagonal-dense", "cross"])("fills %s with it on paper", (hatch) => {
+        const print = /@media print\{(.*?)\}\}/s.exec(svg)?.[1] ?? "";
+        expect(print, "the print rule paints no pattern for this level").toContain(`[data-hatch="${hatch}"]{fill:url(#g1-hatch-${hatch})`);
+    });
+    it("leaves read-only unfilled, because its hatch is the absence of one", () => {
+        expect(svg).toMatch(/@media print\{\.runbook-graph \[data-hatch="none"\]\{fill:none\}/);
+    });
+    /*
+     * A catalog page holds twenty graphs. Bare ids would make the twentieth borrow the
+     * first one's fill, which is the defect that makes a shared `<defs>` worth checking.
+     */
+    it("names the patterns per graph, so two on a page do not collide", () => {
+        expect(drawn("g2")).toContain('<pattern id="g2-hatch-cross"');
+        expect(drawn("g2")).not.toContain("g1-hatch-");
+    });
+});

package/dist/specimen.d.ts

@@ -0,0 +1,2 @@
+import { type Theme } from "./tokens.js";
+export declare function specimenSheet(theme: Theme): string;

package/dist/specimen.gen.d.ts

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

package/dist/specimen.gen.js

@@ -0,0 +1,9 @@
+/** Regenerate the checked-in baselines: `pnpm --filter @runbooks/design exec tsx src/specimen.gen.ts` */
+import { writeFileSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import { specimenSheet } from "./specimen.js";
+const out = join(dirname(fileURLToPath(import.meta.url)), "..", "specimen");
+for (const theme of ["dark", "light"]) {
+    writeFileSync(join(out, `${theme}.svg`), specimenSheet(theme), "utf8");
+}

package/dist/specimen.js

@@ -0,0 +1,81 @@
+import { RISK_ORDER } from "@runbooks/schema";
+import { PALETTES, riskColor, RISK_LABELS, FONT_STACKS } from "./tokens.js";
+import { nodeShape, edgeStyle, stateStyle, badge } from "./primitives.js";
+const KINDS = ["start", "check", "action", "decision", "wait", "escalate", "end"];
+const EDGES = ["next", "branch", "on_fail", "rollback", "approval", "retry"];
+const STATES = ["not-reached", "current", "passed"];
+const BADGES = ["approval", "untrusted", "capability-mcp", "capability-cli", "capability-iam"];
+const W = 132;
+const H = 34;
+export function specimenSheet(theme) {
+    const p = PALETTES[theme];
+    const rows = [];
+    let y = 24;
+    rows.push(label(16, y, "kinds", p.textSecondary));
+    y += 12;
+    KINDS.forEach((kind, i) => {
+        const shape = nodeShape(kind, { width: W, height: H });
+        const x = 16 + (i % 4) * (W + 16);
+        const row = y + Math.floor(i / 4) * (H + 16);
+        rows.push(`<g transform="translate(${x} ${row})">` +
+            `<path d="${shape.path}" fill="${p.surface}" stroke="${p.text}" stroke-width="1.5"` +
+            `${shape.outlineDashed ? ' stroke-dasharray="5 3"' : ""}/>` +
+            (shape.detail ? `<path d="${shape.detail}" fill="${p.text}"/>` : "") +
+            `<text x="${W / 2}" y="${H / 2 + 4}" fill="${p.text}" font-size="12" text-anchor="middle" font-family='${FONT_STACKS.sans}'>${kind}</text>` +
+            `</g>`);
+    });
+    y += 2 * (H + 16) + 16;
+    rows.push(label(16, y, "risk", p.textSecondary));
+    y += 12;
+    RISK_ORDER.forEach((risk, i) => {
+        const x = 16 + i * (W + 16);
+        const shape = nodeShape("action", { width: W, height: H });
+        rows.push(`<g transform="translate(${x} ${y})">` +
+            `<path d="${shape.path}" fill="${p.surface}" stroke="${riskColor(risk, theme)}" stroke-width="2"/>` +
+            `<text x="${W / 2}" y="${H / 2 + 4}" fill="${p.text}" font-size="12" text-anchor="middle" font-family='${FONT_STACKS.sans}'>${RISK_LABELS[risk]}</text>` +
+            `</g>`);
+    });
+    y += H + 32;
+    rows.push(label(16, y, "state (weight and fill only, never hue)", p.textSecondary));
+    y += 12;
+    STATES.forEach((state, i) => {
+        const s = stateStyle(state);
+        const shape = nodeShape("action", { width: W, height: H });
+        rows.push(`<g transform="translate(${16 + i * (W + 16)} ${y})">` +
+            `<path d="${shape.path}" fill="${p.text}" fill-opacity="${s.fillOpacity}" stroke="${p.text}" stroke-width="${s.strokeWidth}"/>` +
+            `<text x="${W / 2}" y="${H / 2 + 4}" fill="${p.text}" font-size="11" text-anchor="middle" font-family='${FONT_STACKS.sans}'>${state}</text>` +
+            `</g>`);
+    });
+    y += H + 32;
+    rows.push(label(16, y, "edges", p.textSecondary));
+    y += 20;
+    EDGES.forEach((kind, i) => {
+        const e = edgeStyle(kind);
+        const row = y + i * 22;
+        const x1 = 96;
+        const x2 = x1 + 160;
+        const line = e.arc
+            ? `<path d="M ${x1} ${row} q 80 -26 ${x2 - x1} 0" fill="none" stroke="${p.text}" stroke-width="${e.width}"/>`
+            : `<line x1="${e.reversed ? x2 : x1}" y1="${row}" x2="${e.reversed ? x1 : x2}" y2="${row}" stroke="${p.text}" stroke-width="${e.width}"${e.dash ? ` stroke-dasharray="${e.dash}"` : ""}/>`;
+        const second = e.doubled
+            ? `<line x1="${x1}" y1="${row + 4}" x2="${x2}" y2="${row + 4}" stroke="${p.text}" stroke-width="${e.width}"/>`
+            : "";
+        rows.push(`<text x="16" y="${row + 4}" fill="${p.textSecondary}" font-size="12" font-family='${FONT_STACKS.mono}'>${kind}</text>${line}${second}`);
+    });
+    y += EDGES.length * 22 + 24;
+    rows.push(label(16, y, "badges", p.textSecondary));
+    y += 12;
+    BADGES.forEach((kind, i) => {
+        rows.push(`<g transform="translate(${16 + i * 48} ${y})">` +
+            `<path d="${badge(kind)}" fill="none" stroke="${p.text}" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round"/>` +
+            `</g>`);
+    });
+    y += 40;
+    return (`<svg xmlns="http://www.w3.org/2000/svg" width="640" height="${y}" viewBox="0 0 640 ${y}">` +
+        `<rect width="640" height="${y}" fill="${p.background}"/>` +
+        rows.join("") +
+        `</svg>\n`);
+}
+function label(x, y, text, fill) {
+    return `<text x="${x}" y="${y}" fill="${fill}" font-size="11" font-family='${FONT_STACKS.mono}'>${text}</text>`;
+}

package/dist/stylesheet.d.ts

@@ -0,0 +1,95 @@
+/**
+ * The tokens, as the stylesheet the pages actually get.
+ *
+ * D-01 produced `PALETTES`, `TYPE_SCALE`, `FONT_STACKS` and `NUMERIC_FEATURES`, and its
+ * contrast tests measured them against each other. Nothing consumed them. The site
+ * shipped with no stylesheet at all — default serif, no measure, no tabular figures — so
+ * every token in this package was a value the product had agreed on and never applied,
+ * and the tests passed because they were checking the agreement rather than the page.
+ *
+ * Emitted rather than written beside the tokens, for the reason the rest of this
+ * repository keeps arriving at: a hand-kept CSS file with `#141A1F` in it is a second
+ * copy of a decision, and the copy is the one that goes stale. Every colour, size and
+ * stack below is read from the token objects; a test asserts the output contains no
+ * literal that did not come from one.
+ *
+ * §18.2's prohibitions are kept the way that file keeps them — by having nothing to
+ * reach for. There is no shadow token, no gradient except the risk legend's, and no
+ * uppercase transform, so none of the three can be spelled here.
+ */
+import { type Theme } from "./tokens.js";
+/** Where the self-hosted faces are served from. */
+export declare const FONT_DIR = "/fonts";
+/**
+ * Where they are kept, relative to this package.
+ *
+ * Source, not build output: `apps/web/public` is emitted in its entirety and gitignored
+ * as such, so a font left there would vanish on a fresh clone and the site would render
+ * in the fallback stack with nothing failing. The package that declares the faces owns
+ * the files, and the catalog build copies them out with the rest of what it serves.
+ */
+export declare const FONT_SOURCE_DIR = "fonts";
+/**
+ * The faces, and only the ones the type scale asks for.
+ *
+ * 400 and 500 are the scale's two weights; 600 is what `strong` needs and italic is what
+ * `em` needs, and synthesising either from a regular face is how a careful type choice
+ * ends up looking careless. Six files, Latin1 subsets, ~124 kB in total.
+ */
+export declare const FACES: readonly [{
+    readonly family: "IBM Plex Sans";
+    readonly file: "IBMPlexSans-Regular-Latin1.woff2";
+    readonly weight: 400;
+    readonly style: "normal";
+}, {
+    readonly family: "IBM Plex Sans";
+    readonly file: "IBMPlexSans-Italic-Latin1.woff2";
+    readonly weight: 400;
+    readonly style: "italic";
+}, {
+    readonly family: "IBM Plex Sans";
+    readonly file: "IBMPlexSans-Medium-Latin1.woff2";
+    readonly weight: 500;
+    readonly style: "normal";
+}, {
+    readonly family: "IBM Plex Sans";
+    readonly file: "IBMPlexSans-SemiBold-Latin1.woff2";
+    readonly weight: 600;
+    readonly style: "normal";
+}, {
+    readonly family: "IBM Plex Mono";
+    readonly file: "IBMPlexMono-Regular-Latin1.woff2";
+    readonly weight: 400;
+    readonly style: "normal";
+}, {
+    readonly family: "IBM Plex Mono";
+    readonly file: "IBMPlexMono-SemiBold-Latin1.woff2";
+    readonly weight: 600;
+    readonly style: "normal";
+}];
+/**
+ * Upstream's own range for the Latin1 split, copied rather than narrowed.
+ *
+ * It carries U+2013-2014 and U+2018-201E and U+2026 — the dashes, the curly quotes and
+ * the ellipsis this catalog's prose is full of. A range invented here would be a
+ * subsetting decision made twice, and the half that is wrong shows up as one character in
+ * a different typeface in the middle of a sentence.
+ */
+export declare const LATIN1_RANGE: string;
+export interface StylesheetOptions {
+    /**
+     * Which theme the surface defaults to (§18.2, Q10). A viewer's explicit choice still
+     * wins: the default is a `prefers-color-scheme` question, not a lock, and
+     * `[data-theme]` overrides both.
+     */
+    readonly defaultTheme: Theme;
+}
+/**
+ * The whole stylesheet.
+ *
+ * Deliberately one string rather than a file Next imports. A generated file on disk is a
+ * file somebody edits, and then the tokens and the page disagree again with nothing to
+ * catch it. Inlined in the document head it also costs no second request and cannot
+ * flash unstyled, which on a static catalog of this size is the better trade anyway.
+ */
+export declare function stylesheet(options: StylesheetOptions): string;