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]>
2026-08-27 06:59:44 -05:00
parent b14613decd
commit e03d38fcab
64 changed files with 3697 additions and 105 deletions
@@ -52,7 +52,8 @@ describe("repository dependency boundaries", () => {
    ["module-ui-imports-core", "modules-use-public-platform-contracts"],
    ["module-ui-bundler-plugin", "modules-do-not-own-ui"],
    ["module-imports-ui-host", "modules-use-public-platform-contracts"],
-    ["module-imports-ui-package", "modules-use-public-platform-contracts"],
+    ["module-imports-surface-sdk", "modules-use-public-platform-contracts"],
+    ["design-package-depends-upward", "design-packages-depend-downward-only"],
    ["cross-package-relative", "workspace-imports-use-public-exports"],
    ["cycle", "no-circular-source-dependencies"],
  ])("rejects %s", async (fixture, expectedRule) => {
@@ -123,6 +124,40 @@ describe("repository dependency boundaries", () => {
    expect(result.violations).toEqual([]);
  });

+  it("accepts a module consuming the approved design packages", async () => {
+    // ADR 0039 opens exactly two shared roles to module UI — `design-tokens` and `ui` — so two
+    // modules' screens can look like one product. Both are browser-safe by construction, so this
+    // adds no path from module UI to a backend type graph.
+    const result = await checkBoundaries(path.join(fixtures, "module-uses-design-packages"));
+
+    expect(result.violations).toEqual([]);
+  });
+
+  it("keeps every other shared role out of module packages", async () => {
+    // The relaxation above is a named allowlist, not "browser-safe shared packages are fine": a
+    // surface SDK, an API client, and an auth client all stay rejected.
+    const result = await checkBoundaries(path.join(fixtures, "module-imports-surface-sdk"));
+
+    expect(result.violations.map((violation) => violation.rule)).toEqual([
+      "modules-use-public-platform-contracts",
+      "modules-use-public-platform-contracts",
+    ]);
+  });
+
+  it("keeps the design packages at the bottom of the presentation stack", async () => {
+    // Neither may reach an API client, an auth client, the contracts barrel, or an implementation
+    // layer: a design package that could would put all of it inside every module artifact that
+    // renders a button.
+    const result = await checkBoundaries(path.join(fixtures, "design-package-depends-upward"));
+
+    expect(result.violations.map((violation) => violation.rule)).toEqual([
+      "design-packages-depend-downward-only",
+      "design-packages-depend-downward-only",
+      "design-packages-depend-downward-only",
+      "design-packages-depend-downward-only",
+    ]);
+  });
+
  it("keeps the host loader out of module packages", async () => {
    // `@ekklesia/module-ui-host` is host infrastructure. A module that depended on it would bundle
    // loader code into its own artifact and blur the author/host split (ADR 0024), so the
@@ -0,0 +1,11 @@
+{
+  "name": "@ekklesia/api-client",
+  "version": "0.0.0",
+  "type": "module",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "ekklesia": {
+    "layer": "api-client"
+  }
+}
@@ -0,0 +1 @@
+export const client = "client";
@@ -0,0 +1,14 @@
+{
+  "name": "@ekklesia/design-tokens",
+  "version": "0.0.0",
+  "type": "module",
+  "dependencies": {
+    "@ekklesia/api-client": "workspace:*"
+  },
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "ekklesia": {
+    "layer": "design-tokens"
+  }
+}
@@ -0,0 +1,3 @@
+import { client } from "@ekklesia/api-client";
+
+export const invalidDesignTokenDependency = client;
@@ -2,6 +2,9 @@
  "name": "@ekklesia/ui",
  "version": "0.0.0",
  "type": "module",
+  "dependencies": {
+    "@ekklesia/api-client": "workspace:*"
+  },
  "exports": {
    ".": "./src/index.ts"
  },
@@ -0,0 +1,3 @@
+import { client } from "@ekklesia/api-client";
+
+export const invalidUiDependency = client;
@@ -3,7 +3,7 @@
  "version": "0.0.0",
  "type": "module",
  "dependencies": {
-    "@ekklesia/ui": "workspace:*"
+    "@ekklesia/surface-sdk": "workspace:*"
  },
  "exports": {
    ".": "./src/index.ts"
@@ -0,0 +1,3 @@
+import { renderer } from "@ekklesia/surface-sdk";
+
+export const invalidModuleSurfaceDependency = renderer;
@@ -0,0 +1,11 @@
+{
+  "name": "@ekklesia/surface-sdk",
+  "version": "0.0.0",
+  "type": "module",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "ekklesia": {
+    "layer": "surface-sdk"
+  }
+}
@@ -0,0 +1 @@
+export const renderer = "renderer";
@@ -1,3 +0,0 @@
-import { button } from "@ekklesia/ui";
-
-export const invalidModuleUiDependency = button;
@@ -1 +0,0 @@
-export const button = "button";
@@ -0,0 +1,13 @@
+{
+  "name": "@ekklesia/module-calendar",
+  "version": "0.0.0",
+  "type": "module",
+  "dependencies": {
+    "@ekklesia/design-tokens": "workspace:*",
+    "@ekklesia/ui": "workspace:*",
+    "react": "19.2.8"
+  },
+  "exports": {
+    ".": "./src/index.ts"
+  }
+}
@@ -0,0 +1 @@
+export const calendar = "calendar";
@@ -0,0 +1,5 @@
+import { designToken } from "@ekklesia/design-tokens";
+import { Button } from "@ekklesia/ui";
+
+export const accent = designToken("accent.base");
+export const action = Button;
@@ -0,0 +1,11 @@
+{
+  "name": "@ekklesia/design-tokens",
+  "version": "0.0.0",
+  "type": "module",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "ekklesia": {
+    "layer": "design-tokens"
+  }
+}
@@ -0,0 +1,3 @@
+export function designToken(name: string): string {
+  return `var(--ekklesia-${name})`;
+}
@@ -0,0 +1,14 @@
+{
+  "name": "@ekklesia/ui",
+  "version": "0.0.0",
+  "type": "module",
+  "dependencies": {
+    "@ekklesia/design-tokens": "workspace:*"
+  },
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "ekklesia": {
+    "layer": "ui"
+  }
+}
@@ -0,0 +1,3 @@
+import { designToken } from "@ekklesia/design-tokens";
+
+export const Button = designToken("accent.base");