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
@@ -24,8 +24,10 @@
    "typecheck": "tsc --noEmit --project tsconfig.json && tsc --noEmit --project tsconfig.test.json"
  },
  "dependencies": {
+    "@ekklesia/design-tokens": "workspace:*",
    "@ekklesia/module-ui-host": "workspace:*",
    "@ekklesia/module-ui-sdk": "workspace:*",
+    "@ekklesia/ui": "workspace:*",
    "react": "19.2.8",
    "react-dom": "19.2.8"
  },
@@ -1,4 +1,6 @@
+import { designToken } from "@ekklesia/design-tokens";
 import type { ModuleUiImporter } from "@ekklesia/module-ui-host";
+import { Button } from "@ekklesia/ui";
 import { type ReactElement, useCallback, useEffect, useRef, useState } from "react";
 import {
  HostAuthError,
@@ -103,51 +105,53 @@ export interface HostAppProps {
  readonly importModule?: ModuleUiImporter;
 }

+/**
+ * The shell's own chrome, expressed in the platform's global semantic tokens rather than in literal
+ * colours (ADR 0039). Nothing here is a brand decision any more: changing
+ * `--ekklesia-background-page` at the host root changes the Dashboard and every mounted module
+ * artifact together, because custom properties inherit through the artifacts' isolated roots.
+ */
 const shellStyles = {
-  action: {
-    background: "transparent",
-    border: "1px solid currentColor",
-    borderRadius: "0.25rem",
-    color: "inherit",
-    cursor: "pointer",
-    font: "inherit",
-    padding: "0.375rem 0.75rem",
+  actions: { display: "flex", gap: designToken("spacing.sm"), justifyContent: "center" },
+  aside: {
+    borderRight: `${designToken("border.width")} solid ${designToken("border.divider")}`,
+    minWidth: "13rem",
+    padding: designToken("spacing.lg"),
  },
-  actions: { display: "flex", gap: "0.5rem", justifyContent: "center" },
-  aside: { borderRight: "1px solid #e7e5e4", minWidth: "13rem", padding: "1rem" },
  groupLabel: {
-    color: "#78716c",
-    fontSize: "0.75rem",
+    color: designToken("text.muted"),
+    fontSize: designToken("typography.size-xs"),
    letterSpacing: "0.05em",
-    margin: "0 0 0.25rem",
+    margin: `0 0 ${designToken("spacing.xs")}`,
    textTransform: "uppercase",
  },
  header: {
    alignItems: "center",
-    borderBottom: "1px solid #e7e5e4",
+    borderBottom: `${designToken("border.width")} solid ${designToken("border.divider")}`,
    display: "flex",
-    fontWeight: 600,
+    fontWeight: designToken("typography.weight-bold"),
    gridColumn: "1 / -1",
    justifyContent: "space-between",
-    padding: "0.75rem 1rem",
+    padding: `${designToken("spacing.md")} ${designToken("spacing.lg")}`,
  },
  heading: { font: "inherit", margin: 0 },
  layout: {
-    color: "#1c1917",
+    background: designToken("background.page"),
+    color: designToken("text.primary"),
    display: "grid",
-    fontFamily: "system-ui, sans-serif",
+    fontFamily: designToken("typography.family-sans"),
    gridTemplateColumns: "auto 1fr",
    minHeight: "100vh",
  },
-  main: { padding: "1rem" },
+  main: { padding: designToken("spacing.lg") },
  message: {
-    color: "#57534e",
+    color: designToken("text.secondary"),
    display: "grid",
-    fontFamily: "system-ui, sans-serif",
-    gap: "0.75rem",
+    fontFamily: designToken("typography.family-sans"),
+    gap: designToken("spacing.md"),
    justifyItems: "center",
    margin: 0,
-    padding: "1rem",
+    padding: designToken("spacing.lg"),
    textAlign: "center",
  },
 } as const;
@@ -170,24 +174,16 @@ function ModuleButton(props: {
  readonly onSelect: () => void;
 }): ReactElement {
  return (
-    <button
+    <Button
      aria-current={props.selected ? "page" : undefined}
+      aria-pressed={props.selected}
      data-testid={`select-${props.entry.descriptor.id}`}
      onClick={props.onSelect}
-      style={{
-        background: props.selected ? "#e7e5e4" : "transparent",
-        border: "none",
-        borderRadius: "0.25rem",
-        cursor: "pointer",
-        font: "inherit",
-        padding: "0.375rem 0.5rem",
-        textAlign: "left",
-        width: "100%",
-      }}
-      type="button"
+      style={{ justifyContent: "flex-start", width: "100%" }}
+      variant="quiet"
    >
      {props.entry.name}
-    </button>
+    </Button>
  );
 }

@@ -491,14 +487,7 @@ export function HostApp(props: HostAppProps): ReactElement {
  }
  if (state.status === "failed") {
    return (
-      <HostMessage
-        actions={
-          <button onClick={retryBootstrap} style={shellStyles.action} type="button">
-            Retry
-          </button>
-        }
-        testId="host-error"
-      >
+      <HostMessage actions={<Button onClick={retryBootstrap}>Retry</Button>} testId="host-error">
        Ekklesia could not be reached.
      </HostMessage>
    );
@@ -511,12 +500,8 @@ export function HostApp(props: HostAppProps): ReactElement {
      <HostMessage
        actions={
          <div style={shellStyles.actions}>
-            <button onClick={() => void signOut()} style={shellStyles.action} type="button">
-              Retry sign out
-            </button>
-            <button onClick={retryBootstrap} style={shellStyles.action} type="button">
-              Return to Ekklesia
-            </button>
+            <Button onClick={() => void signOut()}>Retry sign out</Button>
+            <Button onClick={retryBootstrap}>Return to Ekklesia</Button>
          </div>
        }
        testId="host-sign-out-error"
@@ -529,14 +514,9 @@ export function HostApp(props: HostAppProps): ReactElement {
    return (
      <HostMessage
        actions={
-          <button
-            data-testid="host-logout"
-            onClick={() => void signOut()}
-            style={shellStyles.action}
-            type="button"
-          >
+          <Button data-testid="host-logout" onClick={() => void signOut()}>
            Sign out
-          </button>
+          </Button>
        }
        testId="host-access-denied"
      >
@@ -554,19 +534,14 @@ export function HostApp(props: HostAppProps): ReactElement {
    <div style={shellStyles.layout}>
      <header style={shellStyles.header}>
        <h1 style={shellStyles.heading}>Ekklesia</h1>
-        <button
-          data-testid="host-logout"
-          onClick={() => void signOut()}
-          style={shellStyles.action}
-          type="button"
-        >
+        <Button data-testid="host-logout" onClick={() => void signOut()}>
          Sign out
-        </button>
+        </Button>
      </header>
      <aside style={shellStyles.aside}>
        <DevicePanel config={config} />
        {entries.length === 0 && groups.length === 0 ? (
-          <p data-testid="host-empty" style={{ color: "#57534e", margin: 0 }}>
+          <p data-testid="host-empty" style={{ color: designToken("text.secondary"), margin: 0 }}>
            No installed module provides a user interface.
          </p>
        ) : (
@@ -1,3 +1,5 @@
+import { installEkklesiaDesignTokens } from "@ekklesia/design-tokens";
+import { EkklesiaUiStyles } from "@ekklesia/ui";
 import { createRoot } from "react-dom/client";
 import { type HostAuthLanding, readAuthLanding } from "../auth-protocol.js";
 import type { EkklesiaHostConfig } from "../host-protocol.js";
@@ -60,6 +62,24 @@ if (!container) {
  throw new Error("The Ekklesia shell requires a #ekklesia-host element.");
 }

+/**
+ * The host root installs the platform's default theme once, at the document (ADR 0039).
+ *
+ * This is what makes the tokens available to *everything* on the page, including each module UI
+ * artifact mounted inside its own isolated root: CSS custom properties inherit through a shadow
+ * boundary, so a module reads `var(--ekklesia-…)` without the host reaching into the artifact or the
+ * artifact importing the host. Only the values live here — the platform ships no theme editor, and
+ * an installation that wants different values overrides these declarations at its own root.
+ */
+installEkklesiaDesignTokens(document);
+
 createRoot(container).render(
-  authLanding ? <HostApp authLanding={authLanding} config={config} /> : <HostApp config={config} />,
+  <>
+    <EkklesiaUiStyles />
+    {authLanding ? (
+      <HostApp authLanding={authLanding} config={config} />
+    ) : (
+      <HostApp config={config} />
+    )}
+  </>,
 );
@@ -1,3 +1,5 @@
+import { designToken, installEkklesiaDesignTokens } from "@ekklesia/design-tokens";
+import { EkklesiaUiStyles } from "@ekklesia/ui";
 import { createRoot } from "react-dom/client";
 import type { EkklesiaHostConfig } from "../host-protocol.js";
 import { parseDisplayRoute } from "../host-protocol.js";
@@ -21,25 +23,32 @@ try {
  moduleId = undefined;
 }

+/** The display is its own host root, so it installs the same default theme the Dashboard does; a
+ * module's display artifact then inherits the tokens into its isolated root (ADR 0039). */
+installEkklesiaDesignTokens(document);
+
 createRoot(container).render(
-  moduleId ? (
-    <DisplayApp config={config} moduleId={moduleId} />
-  ) : (
-    <div
-      data-testid="display-route-invalid"
-      style={{
-        alignItems: "center",
-        color: "#57534e",
-        display: "flex",
-        fontFamily: "system-ui, sans-serif",
-        height: "100%",
-        justifyContent: "center",
-        minHeight: "100dvh",
-        padding: "1rem",
-        textAlign: "center",
-      }}
-    >
-      This display is unavailable.
-    </div>
-  ),
+  <>
+    <EkklesiaUiStyles />
+    {moduleId ? (
+      <DisplayApp config={config} moduleId={moduleId} />
+    ) : (
+      <div
+        data-testid="display-route-invalid"
+        style={{
+          alignItems: "center",
+          color: designToken("text.secondary"),
+          display: "flex",
+          fontFamily: designToken("typography.family-sans"),
+          height: "100%",
+          justifyContent: "center",
+          minHeight: "100dvh",
+          padding: designToken("spacing.lg"),
+          textAlign: "center",
+        }}
+      >
+        This display is unavailable.
+      </div>
+    )}
+  </>,
 );
@@ -22,7 +22,17 @@ const sourceDirectory = path.join(packageDirectory, "src");
 /** The complete set of packages this shell may reach for. `@ekklesia/module-ui-host` is the generic
 * loader and `@ekklesia/module-ui-sdk` is the browser-side contract; no other `@ekklesia/*` package
 * — and no module — may appear. */
-const ALLOWED_EKKLESIA_IMPORTS = new Set(["@ekklesia/module-ui-host", "@ekklesia/module-ui-sdk"]);
+/**
+ * The complete set of Ekklesia packages the shell may reach: the two browser contracts it mounts
+ * modules with, and the two design packages every Ekklesia screen is built from (ADR 0039). All
+ * four are browser-safe by construction and none of them names a module.
+ */
+const ALLOWED_EKKLESIA_IMPORTS = new Set([
+  "@ekklesia/design-tokens",
+  "@ekklesia/module-ui-host",
+  "@ekklesia/module-ui-sdk",
+  "@ekklesia/ui",
+]);

 async function sourceFiles(directory: string): Promise<string[]> {
  const entries = await readdir(directory, { withFileTypes: true });