@runbooks/design 0.1.0

package/dist/tokens.test.js

@@ -0,0 +1,125 @@
+import { describe, it, expect } from "vitest";
+import { readFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { RISK_ORDER } from "@runbooks/schema";
+import { EXEMPT_FROM_STROKE_FLOOR, PALETTES, RISK_COLORS, RISK_LABELS, DEFAULT_THEME, TYPE_SCALE, CONTRAST_FLOOR, meetsTextFloor, meetsStrokeFloor, riskLightnessOrder, riskColor, } from "./tokens.js";
+import { contrast } from "./color.js";
+const THEMES = ["dark", "light"];
+/**
+ * The floors from §18.2, asserted against every pairing the product actually uses
+ * rather than checked once by eye. Measuring them is how the visual specification's
+ * original palette was found to fail two of its own three stated properties.
+ */
+describe("contrast floors hold for every pairing in use", () => {
+    it.each(THEMES)("%s: text and secondary text clear 4.5:1", (theme) => {
+        const p = PALETTES[theme];
+        for (const ground of [p.background, p.surface]) {
+            expect(meetsTextFloor(p.text, ground), `text on ${ground}`).toBe(true);
+            expect(meetsTextFloor(p.textSecondary, ground), `secondary on ${ground}`).toBe(true);
+        }
+    });
+    // The trust accent is text, so it answers to the text floor. As specified it measured
+    // 4.23:1 on the dark ground.
+    it.each(THEMES)("%s: the trust accent clears the text floor", (theme) => {
+        const p = PALETTES[theme];
+        expect(contrast(p.trust, p.background)).toBeGreaterThanOrEqual(CONTRAST_FLOOR.text);
+    });
+    /**
+     * Every token in the palette, not only the risk colours.
+     *
+     * `EXEMPT_FROM_STROKE_FLOOR` says in its own comment that it exists "so the exemption is
+     * a decision rather than an oversight the contrast test quietly skips" — and nothing
+     * read it. The test below sweeps `RISK_ORDER` and stops, so every other token was
+     * skipped exactly as quietly as the comment feared, exempt or not.
+     *
+     * Measured before it was written: `surface` and `border` are the only two under 3:1, in
+     * both themes, which is what the exemption already claimed. So this passes today and the
+     * list is load-bearing — take a name out of it and this fails, which is the difference
+     * between a decision and a sentence.
+     */
+    it.each(THEMES)("%s: every palette colour clears the stroke floor on both grounds", (theme) => {
+        const p = PALETTES[theme];
+        // Both grounds, because content sits on both. The first version of this checked the
+        // page background only, and a card is `surface`: a colour can clear one and fail the
+        // other, and in the dark theme the two are far enough apart for that to happen —
+        // #5A6068 is 3.03:1 on the background and 2.76:1 on a card.
+        for (const [ground, against] of [["the page", p.background], ["a card", p.surface]]) {
+            for (const [name, value] of Object.entries(p)) {
+                if (typeof value !== "string" || !value.startsWith("#"))
+                    continue;
+                if (name === "background" || name === "surface")
+                    continue;
+                if (EXEMPT_FROM_STROKE_FLOOR.includes(name))
+                    continue;
+                expect(meetsStrokeFloor(value, against), `${name} in ${theme} is ${contrast(value, against).toFixed(2)}:1 against ${ground}, and is not exempt`).toBe(true);
+            }
+        }
+    });
+    it.each(THEMES)("%s: every risk colour clears the 3:1 stroke floor", (theme) => {
+        const p = PALETTES[theme];
+        for (const risk of RISK_ORDER) {
+            for (const ground of [p.background, p.surface]) {
+                expect(meetsStrokeFloor(riskColor(risk, theme), ground), `${risk} on ${ground} in ${theme}: ${contrast(riskColor(risk, theme), ground).toFixed(2)}:1`).toBe(true);
+            }
+        }
+    });
+});
+describe("the risk scale survives greyscale", () => {
+    // Monotonic in lightness is what makes the scale readable in black and white and
+    // under colour blindness. The original palette put read-only at 0.182 and destructive
+    // at 0.186 — the same colour, to a greyscale reader.
+    it.each(THEMES)("%s: severity reads as darker, in order", (theme) => {
+        expect(riskLightnessOrder(theme)).toEqual([...RISK_ORDER]);
+    });
+    it.each(THEMES)("%s: adjacent steps are separable, not merely ordered", (theme) => {
+        const order = riskLightnessOrder(theme);
+        for (let i = 1; i < order.length; i++) {
+            const ratio = contrast(riskColor(order[i - 1], theme), riskColor(order[i], theme));
+            expect(ratio, `${order[i - 1]} vs ${order[i]}`).toBeGreaterThan(1.15);
+        }
+    });
+    // A hue is never the sole carrier of meaning (§18.2 accessibility).
+    it("every risk has a text label", () => {
+        for (const risk of RISK_ORDER)
+            expect(RISK_LABELS[risk]).toMatch(/^[A-Z]{2,3}$/);
+    });
+    it("the ordering is identical in both themes", () => {
+        expect(riskLightnessOrder("dark")).toEqual(riskLightnessOrder("light"));
+    });
+});
+describe("colour never encodes status and risk at the same time (§18.2)", () => {
+    const source = readFileSync(join(dirname(fileURLToPath(import.meta.url)), "tokens.ts"), "utf8");
+    // A rule is better kept by having nothing to reach for. If a token for "current
+    // step" or "passed" ever appears, run state has taken the hue channel from risk.
+    it("defines no colour token for run or simulation state", () => {
+        expect(source).not.toMatch(/\b(current|passed|failed|active|running)Color\b/i);
+        expect(source).not.toMatch(/STATE_COLORS/);
+    });
+    it("defines no shadow token, so a canvas shadow cannot be reached for", () => {
+        expect(source).not.toMatch(/shadow/i);
+    });
+    it("defines no gradient token", () => {
+        expect(source).not.toMatch(/gradient/i);
+    });
+    it("defines no all-caps text style", () => {
+        expect(source).not.toMatch(/uppercase|textTransform/i);
+    });
+});
+describe("theme defaults follow exposure time without locking anyone in", () => {
+    it("defaults both surfaces to dark", () => {
+        expect(DEFAULT_THEME).toEqual({ canvas: "dark", catalog: "dark" });
+    });
+    it("offers both themes, so a viewer's choice can win", () => {
+        expect(Object.keys(PALETTES).sort()).toEqual(["dark", "light"]);
+        expect(Object.keys(RISK_COLORS).sort()).toEqual(["dark", "light"]);
+    });
+});
+describe("typography", () => {
+    it("caps body line length where it is a layout decision, not a per-page one", () => {
+        expect(TYPE_SCALE.body.maxLineLength).toBeLessThanOrEqual(75);
+    });
+    it("keeps a node label to two lines", () => {
+        expect(TYPE_SCALE.nodeLabel.maxLines).toBe(2);
+    });
+});

package/fonts/LICENSE.txt

@@ -0,0 +1,93 @@
+Copyright © 2017 IBM Corp. with Reserved Font Name "Plex"
+
+This Font Software is licensed under the SIL Open Font License, Version 1.1.
+
+This license is copied below, and is also available with a FAQ at: http://scripts.sil.org/OFL
+
+
+-----------------------------------------------------------
+SIL OPEN FONT LICENSE Version 1.1 - 26 February 2007
+-----------------------------------------------------------
+
+PREAMBLE
+The goals of the Open Font License (OFL) are to stimulate worldwide
+development of collaborative font projects, to support the font creation
+efforts of academic and linguistic communities, and to provide a free and
+open framework in which fonts may be shared and improved in partnership
+with others.
+
+The OFL allows the licensed fonts to be used, studied, modified and
+redistributed freely as long as they are not sold by themselves. The
+fonts, including any derivative works, can be bundled, embedded, 
+redistributed and/or sold with any software provided that any reserved
+names are not used by derivative works. The fonts and derivatives,
+however, cannot be released under any other type of license. The
+requirement for fonts to remain under this license does not apply
+to any document created using the fonts or their derivatives.
+
+DEFINITIONS
+"Font Software" refers to the set of files released by the Copyright
+Holder(s) under this license and clearly marked as such. This may
+include source files, build scripts and documentation.
+
+"Reserved Font Name" refers to any names specified as such after the
+copyright statement(s).
+
+"Original Version" refers to the collection of Font Software components as
+distributed by the Copyright Holder(s).
+
+"Modified Version" refers to any derivative made by adding to, deleting,
+or substituting -- in part or in whole -- any of the components of the
+Original Version, by changing formats or by porting the Font Software to a
+new environment.
+
+"Author" refers to any designer, engineer, programmer, technical
+writer or other person who contributed to the Font Software.
+
+PERMISSION & CONDITIONS
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of the Font Software, to use, study, copy, merge, embed, modify,
+redistribute, and sell modified and unmodified copies of the Font
+Software, subject to the following conditions:
+
+1) Neither the Font Software nor any of its individual components,
+in Original or Modified Versions, may be sold by itself.
+
+2) Original or Modified Versions of the Font Software may be bundled,
+redistributed and/or sold with any software, provided that each copy
+contains the above copyright notice and this license. These can be
+included either as stand-alone text files, human-readable headers or
+in the appropriate machine-readable metadata fields within text or
+binary files as long as those fields can be easily viewed by the user.
+
+3) No Modified Version of the Font Software may use the Reserved Font
+Name(s) unless explicit written permission is granted by the corresponding
+Copyright Holder. This restriction only applies to the primary font name as
+presented to the users.
+
+4) The name(s) of the Copyright Holder(s) or the Author(s) of the Font
+Software shall not be used to promote, endorse or advertise any
+Modified Version, except to acknowledge the contribution(s) of the
+Copyright Holder(s) and the Author(s) or with their explicit written
+permission.
+
+5) The Font Software, modified or unmodified, in part or in whole,
+must be distributed entirely under this license, and must not be
+distributed under any other license. The requirement for fonts to
+remain under this license does not apply to any document created
+using the Font Software.
+
+TERMINATION
+This license becomes null and void if any of the above conditions are
+not met.
+
+DISCLAIMER
+THE FONT SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT
+OF COPYRIGHT, PATENT, TRADEMARK, OR OTHER RIGHT. IN NO EVENT SHALL THE
+COPYRIGHT HOLDER BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+INCLUDING ANY GENERAL, SPECIAL, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL
+DAMAGES, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF THE USE OR INABILITY TO USE THE FONT SOFTWARE OR FROM
+OTHER DEALINGS IN THE FONT SOFTWARE.

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@runbooks/design",
+  "version": "0.1.0",
+  "private": false,
+  "type": "module",
+  "description": "Design tokens, graph visual primitives, and SVG rendering.",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "dependencies": {
+    "@runbooks/schema": "^0.1.0",
+    "@runbooks/graph": "^0.1.0"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/runbooks-directory/runbooks.directory"
+  },
+  "engines": {
+    "node": ">=20.11"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "dist",
+    "fonts",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc -b",
+    "test": "vitest run --passWithNoTests",
+    "lint": "eslint src"
+  }
+}