feat: give every Ekklesia screen one set of design tokens and elements
Modules have owned their own UI since ADR 0021, but the platform has never said what that UI should look like. Every screen here — the Dashboard shell, the display host, the module template — invented its own hex colours, font stack, spacing, and radii, and they already disagreed. A module author had no vocabulary for "the ordinary panel background", so the only available answer was to invent one, and two modules would invent two. Add `@ekklesia/design-tokens`: one validated, enumerable registry of semantic tokens. A token declares a name, label, description, and default value; its category and `--ekklesia-*` identifier are derived from the name, so it can never claim one category while being named for another. Construction rejects duplicates, malformed names, unknown categories, empty or overlong text, and any value that is not a bounded literal — no declaration terminator, rule block, comment, at-rule, `url(`, `!important`, escape, control character, or markup. A registry that constructs can therefore be emitted as CSS without escaping, because nothing needing escaping can be in it. That validation is also what makes a future theme editor implementable rather than aspirational. Add `@ekklesia/ui`: button, icon button, text input, select, checkbox, field wrapper, panel, dialog, tabs, table and list primitives, badge, toast, and empty/error/loading states — every value a token reference, with real `:focus-visible` treatment and status that never depends on colour alone. Deliberately small: an element earns its place when two consumers need it. The stylesheet is a string rather than a `.css` file so the identical bytes install into a document or an isolated artifact root, and so hover, disabled, and focus-visible are real CSS rather than JavaScript approximations of them. `pnpm boundaries` opens exactly two shared roles to modules, by name — every other role stays rejected — and pins both design packages to the bottom of the presentation stack. Both are browser-safe by construction, proven by a real compile of module-shaped source in which `process.env` must fail to typecheck. The shell installs the defaults at its document root for the Dashboard and the display; custom properties inherit into module artifacts, so a module reads `var(--ekklesia-…)` with nothing to import at run time and nothing for a host to forget to pass. Co-Authored-By: Claude Opus 5 <[email protected]>
This commit is contained in:
ekklesia
co-authored by
Claude Opus 5
Claude Opus 5
parent
b14613decd
commit
e03d38fcab
@@ -0,0 +1,52 @@
|
||||
import { readdir, readFile } from "node:fs/promises";
|
||||
import path from "node:path";
|
||||
import { fileURLToPath } from "node:url";
|
||||
import { describe, expect, it } from "vitest";
|
||||
|
||||
const packageDirectory = path.dirname(path.dirname(fileURLToPath(import.meta.url)));
|
||||
|
||||
async function sourceFiles(): Promise<readonly string[]> {
|
||||
const directory = path.join(packageDirectory, "src");
|
||||
const entries = await readdir(directory);
|
||||
return entries
|
||||
.filter((entry) => entry.endsWith(".ts"))
|
||||
.map((entry) => path.join(directory, entry));
|
||||
}
|
||||
|
||||
/**
|
||||
* The design contract is imported by the Dashboard shell, by module UI artifacts, and by contributed
|
||||
* renderers. It inherits exactly the rule ADR 0024 established for `@ekklesia/module-ui-sdk`: it
|
||||
* must not be able to pull a backend type graph — and with it Node's global declarations — into a
|
||||
* browser program.
|
||||
*/
|
||||
describe("the design token package stays browser-safe", () => {
|
||||
it("declares no runtime dependency at all", async () => {
|
||||
const manifest = JSON.parse(
|
||||
await readFile(path.join(packageDirectory, "package.json"), "utf8"),
|
||||
) as { dependencies?: Record<string, string>; peerDependencies?: Record<string, string> };
|
||||
|
||||
expect(manifest.dependencies).toBeUndefined();
|
||||
expect(manifest.peerDependencies).toBeUndefined();
|
||||
});
|
||||
|
||||
it("imports nothing outside its own source", async () => {
|
||||
for (const file of await sourceFiles()) {
|
||||
const source = await readFile(file, "utf8");
|
||||
const specifiers = [...source.matchAll(/from\s+"([^"]+)"/gmu)].map(([, specifier]) =>
|
||||
String(specifier),
|
||||
);
|
||||
|
||||
expect(specifiers.every((specifier) => specifier.startsWith("."))).toBe(true);
|
||||
}
|
||||
});
|
||||
|
||||
it("never names a Node built-in or reads the environment", async () => {
|
||||
for (const file of await sourceFiles()) {
|
||||
const source = await readFile(file, "utf8");
|
||||
|
||||
expect(source).not.toContain('"node:');
|
||||
expect(source).not.toContain("process.env");
|
||||
expect(source).not.toContain("globalThis.process");
|
||||
}
|
||||
});
|
||||
});
|
||||
@@ -0,0 +1,137 @@
|
||||
// @vitest-environment happy-dom
|
||||
import { describe, expect, it } from "vitest";
|
||||
import {
|
||||
DESIGN_TOKEN_CATEGORIES,
|
||||
DESIGN_TOKEN_STYLE_ATTRIBUTE,
|
||||
DESIGN_TOKEN_VARIABLE_PREFIX,
|
||||
designToken,
|
||||
ekklesiaDesignTokens,
|
||||
ekklesiaDesignTokenStylesheet,
|
||||
installEkklesiaDesignTokens,
|
||||
} from "../src/index.js";
|
||||
|
||||
describe("the Ekklesia design token registry", () => {
|
||||
it("is enumerable and deterministic", () => {
|
||||
const first = ekklesiaDesignTokens.list();
|
||||
const second = ekklesiaDesignTokens.list();
|
||||
|
||||
expect(first).toBe(second);
|
||||
expect(Object.isFrozen(first)).toBe(true);
|
||||
expect(first.length).toBeGreaterThan(0);
|
||||
expect(first.map((token) => token.name)).toEqual(second.map((token) => token.name));
|
||||
expect(ekklesiaDesignTokenStylesheet()).toBe(ekklesiaDesignTokenStylesheet());
|
||||
});
|
||||
|
||||
it("declares a unique name and CSS variable for every token", () => {
|
||||
const names = ekklesiaDesignTokens.list().map((token) => token.name);
|
||||
const variables = ekklesiaDesignTokens.list().map((token) => token.cssVariable);
|
||||
|
||||
expect(new Set(names).size).toBe(names.length);
|
||||
expect(new Set(variables).size).toBe(variables.length);
|
||||
expect(variables.every((variable) => variable.startsWith(DESIGN_TOKEN_VARIABLE_PREFIX))).toBe(
|
||||
true,
|
||||
);
|
||||
});
|
||||
|
||||
it("gives every token a human-readable label, description, and derived category", () => {
|
||||
for (const token of ekklesiaDesignTokens.list()) {
|
||||
expect(token.label.trim().length).toBeGreaterThan(0);
|
||||
expect(token.description.trim().length).toBeGreaterThan(0);
|
||||
expect(DESIGN_TOKEN_CATEGORIES).toContain(token.category);
|
||||
expect(token.name.startsWith(`${token.category}.`)).toBe(true);
|
||||
}
|
||||
});
|
||||
|
||||
it("covers the semantic families the platform promises", () => {
|
||||
const names = new Set(ekklesiaDesignTokens.list().map((token) => token.name));
|
||||
|
||||
for (const required of [
|
||||
"background.page",
|
||||
"background.canvas",
|
||||
"background.surface",
|
||||
"background.raised",
|
||||
"background.overlay",
|
||||
"background.inset",
|
||||
"text.primary",
|
||||
"text.secondary",
|
||||
"text.muted",
|
||||
"text.inverse",
|
||||
"text.success",
|
||||
"text.warning",
|
||||
"text.danger",
|
||||
"accent.base",
|
||||
"accent.focus",
|
||||
"border.base",
|
||||
"border.divider",
|
||||
"state.hover-background",
|
||||
"state.pressed-background",
|
||||
"state.selected-background",
|
||||
"state.disabled-opacity",
|
||||
"state.focus-visible-width",
|
||||
"typography.family-sans",
|
||||
"typography.size-md",
|
||||
"typography.weight-bold",
|
||||
"typography.line-height-normal",
|
||||
"typography.size-heading-1",
|
||||
"spacing.md",
|
||||
"radius.md",
|
||||
"shadow.md",
|
||||
"control.height-md",
|
||||
]) {
|
||||
expect(names).toContain(required);
|
||||
}
|
||||
});
|
||||
|
||||
it("pairs every status colour with a non-colour symbol", () => {
|
||||
for (const status of ["success", "warning", "danger", "info"]) {
|
||||
expect(ekklesiaDesignTokens.has(`status.${status}-background`)).toBe(true);
|
||||
expect(ekklesiaDesignTokens.has(`status.${status}-border`)).toBe(true);
|
||||
const symbol = ekklesiaDesignTokens.get(`status.${status}-symbol`);
|
||||
expect(symbol?.value.length).toBeGreaterThan(0);
|
||||
}
|
||||
});
|
||||
|
||||
it("hands component code a var() reference rather than a raw colour", () => {
|
||||
expect(designToken("text.primary")).toBe("var(--ekklesia-text-primary)");
|
||||
expect(ekklesiaDesignTokens.variable("text.primary")).toBe("--ekklesia-text-primary");
|
||||
});
|
||||
|
||||
it("emits a stylesheet declaring every registered token exactly once", () => {
|
||||
const stylesheet = ekklesiaDesignTokenStylesheet();
|
||||
|
||||
for (const token of ekklesiaDesignTokens.list()) {
|
||||
expect(stylesheet.split(`${token.cssVariable}:`).length).toBe(2);
|
||||
}
|
||||
});
|
||||
|
||||
it("installs the default theme at a document root exactly once and removes what it added", () => {
|
||||
const remove = installEkklesiaDesignTokens(document);
|
||||
const installedAgain = installEkklesiaDesignTokens(document);
|
||||
|
||||
expect(document.querySelectorAll(`style[${DESIGN_TOKEN_STYLE_ATTRIBUTE}]`).length).toBe(1);
|
||||
expect(
|
||||
document
|
||||
.querySelector(`style[${DESIGN_TOKEN_STYLE_ATTRIBUTE}]`)
|
||||
?.textContent?.includes("--ekklesia-background-page"),
|
||||
).toBe(true);
|
||||
|
||||
installedAgain();
|
||||
expect(document.querySelectorAll(`style[${DESIGN_TOKEN_STYLE_ATTRIBUTE}]`).length).toBe(1);
|
||||
|
||||
remove();
|
||||
remove();
|
||||
expect(document.querySelectorAll(`style[${DESIGN_TOKEN_STYLE_ATTRIBUTE}]`).length).toBe(0);
|
||||
});
|
||||
|
||||
it("installs host-scoped values into an isolated shadow root", () => {
|
||||
const host = document.createElement("div");
|
||||
document.body.appendChild(host);
|
||||
const shadow = host.attachShadow({ mode: "open" });
|
||||
|
||||
installEkklesiaDesignTokens(shadow, { scope: "host" });
|
||||
|
||||
const style = shadow.querySelector(`style[${DESIGN_TOKEN_STYLE_ATTRIBUTE}]`);
|
||||
expect(style?.textContent?.startsWith(":host {")).toBe(true);
|
||||
host.remove();
|
||||
});
|
||||
});
|
||||
@@ -0,0 +1,158 @@
|
||||
import { describe, expect, it } from "vitest";
|
||||
import {
|
||||
createDesignTokenRegistry,
|
||||
DESIGN_TOKEN_CATEGORIES,
|
||||
DESIGN_TOKEN_VALUE_MAX_LENGTH,
|
||||
DesignTokenError,
|
||||
type DesignTokenInput,
|
||||
} from "../src/index.js";
|
||||
|
||||
function tokens(...overrides: readonly Partial<DesignTokenInput>[]): readonly DesignTokenInput[] {
|
||||
return overrides.map((override) => ({
|
||||
description: "A token used by this test.",
|
||||
label: "Test token",
|
||||
name: "background.page",
|
||||
value: "#ffffff",
|
||||
...override,
|
||||
}));
|
||||
}
|
||||
|
||||
describe("design token validation", () => {
|
||||
it("accepts a minimal well-formed declaration and derives category and CSS variable", () => {
|
||||
const registry = createDesignTokenRegistry(tokens({ name: "spacing.2xs", value: "0.125rem" }));
|
||||
const token = registry.get("spacing.2xs");
|
||||
|
||||
expect(token).toEqual({
|
||||
category: "spacing",
|
||||
cssVariable: "--ekklesia-spacing-2xs",
|
||||
description: "A token used by this test.",
|
||||
label: "Test token",
|
||||
name: "spacing.2xs",
|
||||
value: "0.125rem",
|
||||
});
|
||||
expect(Object.isFrozen(token)).toBe(true);
|
||||
});
|
||||
|
||||
it("rejects a duplicate token name", () => {
|
||||
expect(() => createDesignTokenRegistry(tokens({}, {}))).toThrowError(
|
||||
expect.objectContaining({ code: "DESIGN_TOKEN_DUPLICATE" }),
|
||||
);
|
||||
});
|
||||
|
||||
it.each([
|
||||
["a single segment", "page"],
|
||||
["an empty name", ""],
|
||||
["an uppercase segment", "background.Page"],
|
||||
["an underscore", "background.page_alt"],
|
||||
["a trailing dot", "background.page."],
|
||||
["a space", "background.page alt"],
|
||||
])("rejects %s as a token name", (_label, name) => {
|
||||
expect(() => createDesignTokenRegistry(tokens({ name }))).toThrowError(
|
||||
expect.objectContaining({ code: "DESIGN_TOKEN_NAME_INVALID" }),
|
||||
);
|
||||
});
|
||||
|
||||
it("rejects a name whose first segment is not a known category", () => {
|
||||
expect(() => createDesignTokenRegistry(tokens({ name: "brand.primary" }))).toThrowError(
|
||||
expect.objectContaining({ code: "DESIGN_TOKEN_CATEGORY_UNKNOWN" }),
|
||||
);
|
||||
});
|
||||
|
||||
it.each([
|
||||
["a declaration terminator", "#fff; color: red"],
|
||||
["a rule block", "#fff } body { display: none"],
|
||||
["a comment", "#fff /* hidden */"],
|
||||
["an at-rule", "@import 'evil.css'"],
|
||||
["a url reference", "url(https://example.invalid/x.png)"],
|
||||
["an override", "#fff !important"],
|
||||
["a markup fragment", "</style><script>"],
|
||||
["an escape sequence", "\\0041"],
|
||||
["an empty value", " "],
|
||||
])("rejects %s as a token value", (_label, value) => {
|
||||
expect(() => createDesignTokenRegistry(tokens({ value }))).toThrowError(
|
||||
expect.objectContaining({ code: "DESIGN_TOKEN_VALUE_INVALID" }),
|
||||
);
|
||||
});
|
||||
|
||||
it("rejects an unbounded value", () => {
|
||||
expect(() =>
|
||||
createDesignTokenRegistry(tokens({ value: "a".repeat(DESIGN_TOKEN_VALUE_MAX_LENGTH + 1) })),
|
||||
).toThrowError(expect.objectContaining({ code: "DESIGN_TOKEN_VALUE_INVALID" }));
|
||||
});
|
||||
|
||||
it("rejects a control character hidden inside a value", () => {
|
||||
expect(() => createDesignTokenRegistry(tokens({ value: "#fff\u0007" }))).toThrowError(
|
||||
expect.objectContaining({ code: "DESIGN_TOKEN_VALUE_INVALID" }),
|
||||
);
|
||||
expect(() => createDesignTokenRegistry(tokens({ value: "#fff\nred" }))).toThrowError(
|
||||
expect.objectContaining({ code: "DESIGN_TOKEN_VALUE_INVALID" }),
|
||||
);
|
||||
});
|
||||
|
||||
it("rejects an empty or overlong label and description", () => {
|
||||
expect(() => createDesignTokenRegistry(tokens({ label: " " }))).toThrowError(
|
||||
expect.objectContaining({ code: "DESIGN_TOKEN_LABEL_INVALID" }),
|
||||
);
|
||||
expect(() => createDesignTokenRegistry(tokens({ description: "" }))).toThrowError(
|
||||
expect.objectContaining({ code: "DESIGN_TOKEN_DESCRIPTION_INVALID" }),
|
||||
);
|
||||
expect(() => createDesignTokenRegistry(tokens({ description: "d".repeat(241) }))).toThrowError(
|
||||
expect.objectContaining({ code: "DESIGN_TOKEN_DESCRIPTION_INVALID" }),
|
||||
);
|
||||
});
|
||||
|
||||
it("never echoes the rejected declaration in the error", () => {
|
||||
let caught: unknown;
|
||||
try {
|
||||
createDesignTokenRegistry(tokens({ value: "#fff; content: 'leak-me'" }));
|
||||
} catch (error) {
|
||||
caught = error;
|
||||
}
|
||||
|
||||
expect(caught).toBeInstanceOf(DesignTokenError);
|
||||
expect(String((caught as Error).message)).not.toContain("leak-me");
|
||||
expect(String((caught as Error).stack)).not.toContain("leak-me");
|
||||
});
|
||||
|
||||
it("fails a lookup closed for an unregistered or non-string name", () => {
|
||||
const registry = createDesignTokenRegistry(tokens({}));
|
||||
|
||||
expect(registry.get("nope.nope")).toBeUndefined();
|
||||
expect(registry.get(42)).toBeUndefined();
|
||||
expect(registry.has(undefined)).toBe(false);
|
||||
expect(() => registry.variable("nope.nope")).toThrowError(
|
||||
expect.objectContaining({ code: "DESIGN_TOKEN_UNKNOWN" }),
|
||||
);
|
||||
});
|
||||
|
||||
it("rejects a stylesheet scope outside the closed set", () => {
|
||||
const registry = createDesignTokenRegistry(tokens({}));
|
||||
|
||||
expect(() => registry.stylesheet("body" as "root")).toThrowError(
|
||||
expect.objectContaining({ code: "DESIGN_TOKEN_SCOPE_INVALID" }),
|
||||
);
|
||||
});
|
||||
|
||||
it("emits one rule per scope containing every declared token", () => {
|
||||
const registry = createDesignTokenRegistry(
|
||||
tokens({ name: "background.page", value: "#fff" }, { name: "text.primary", value: "#000" }),
|
||||
);
|
||||
|
||||
expect(registry.stylesheet()).toBe(
|
||||
":root {\n --ekklesia-background-page: #fff;\n --ekklesia-text-primary: #000;\n}\n",
|
||||
);
|
||||
expect(registry.stylesheet("host").startsWith(":host {")).toBe(true);
|
||||
});
|
||||
|
||||
it("groups tokens by category without a second source of truth", () => {
|
||||
const registry = createDesignTokenRegistry(
|
||||
tokens({ name: "background.page" }, { name: "text.primary", value: "#000" }),
|
||||
);
|
||||
|
||||
expect(registry.listByCategory("background").map((token) => token.name)).toEqual([
|
||||
"background.page",
|
||||
]);
|
||||
expect(registry.listByCategory("shadow")).toEqual([]);
|
||||
expect(DESIGN_TOKEN_CATEGORIES).toContain("background");
|
||||
});
|
||||
});
|
||||
Reference in New Issue
Block a user