From e03d38fcabe32c80812ca32048cec0d80620d7fe Mon Sep 17 00:00:00 2001 From: ekklesia Date: Thu, 27 Aug 2026 06:59:44 -0500 Subject: [PATCH] feat: give every Ekklesia screen one set of design tokens and elements MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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 --- CONTRIBUTING.md | 5 + .../0039-shared-design-tokens-and-elements.md | 156 +++++ docs/architecture/decisions/README.md | 1 + docs/architecture/repository-boundaries.md | 25 +- docs/module-development/README.md | 66 ++- packages/design-tokens/package.json | 32 + packages/design-tokens/src/index.ts | 3 + packages/design-tokens/src/install.ts | 72 +++ packages/design-tokens/src/registry.ts | 550 +++++++++++++++++ packages/design-tokens/src/token.ts | 282 +++++++++ .../tests/browser-safety.test.ts | 52 ++ packages/design-tokens/tests/registry.test.ts | 137 +++++ packages/design-tokens/tests/token.test.ts | 158 +++++ packages/design-tokens/tsconfig.build.json | 13 + packages/design-tokens/tsconfig.json | 8 + packages/design-tokens/tsconfig.test.json | 8 + packages/module-ui-sdk/src/host-context.ts | 13 +- packages/ui/package.json | 42 ++ packages/ui/src/EkklesiaUiStyles.tsx | 20 + packages/ui/src/class-names.ts | 11 + packages/ui/src/controls.tsx | 152 +++++ packages/ui/src/data.tsx | 91 +++ packages/ui/src/feedback.tsx | 161 +++++ packages/ui/src/index.ts | 76 +++ packages/ui/src/styles.ts | 556 ++++++++++++++++++ packages/ui/src/surfaces.tsx | 211 +++++++ packages/ui/tests/browser-boundary.test.ts | 46 ++ .../ui/tests/browser-boundary/node-global.tsx | 9 + .../ui/tests/browser-boundary/supported.tsx | 21 + .../tsconfig.node-global.json | 5 + .../browser-boundary/tsconfig.supported.json | 5 + packages/ui/tests/elements.test.tsx | 258 ++++++++ packages/ui/tests/tokens.test.ts | 84 +++ packages/ui/tsconfig.build.json | 13 + packages/ui/tsconfig.json | 8 + packages/ui/tsconfig.test.json | 9 + packages/ui/vitest.config.ts | 9 + pnpm-lock.yaml | 64 ++ scripts/check-boundaries.ts | 37 +- surfaces/shell/package.json | 2 + surfaces/shell/src/browser/HostApp.tsx | 105 ++-- surfaces/shell/src/browser/main.tsx | 22 +- surfaces/shell/src/display/main.tsx | 49 +- surfaces/shell/tests/modularity.test.ts | 12 +- tests/boundaries.test.ts | 37 +- .../packages/api-client/package.json | 11 + .../packages/api-client/src/index.ts | 1 + .../packages/design-tokens/package.json | 14 + .../packages/design-tokens/src/index.ts | 3 + .../packages/ui/package.json | 3 + .../packages/ui/src/index.ts | 3 + .../modules/calendar/package.json | 2 +- .../modules/calendar/src/index.ts | 3 + .../packages/surface-sdk/package.json | 11 + .../packages/surface-sdk/src/index.ts | 1 + .../modules/calendar/src/index.ts | 3 - .../packages/ui/src/index.ts | 1 - .../modules/calendar/package.json | 13 + .../modules/calendar/src/index.ts | 1 + .../modules/calendar/src/ui/index.tsx | 5 + .../packages/design-tokens/package.json | 11 + .../packages/design-tokens/src/index.ts | 3 + .../packages/ui/package.json | 14 + .../packages/ui/src/index.ts | 3 + 64 files changed, 3697 insertions(+), 105 deletions(-) create mode 100644 docs/architecture/decisions/0039-shared-design-tokens-and-elements.md create mode 100644 packages/design-tokens/package.json create mode 100644 packages/design-tokens/src/index.ts create mode 100644 packages/design-tokens/src/install.ts create mode 100644 packages/design-tokens/src/registry.ts create mode 100644 packages/design-tokens/src/token.ts create mode 100644 packages/design-tokens/tests/browser-safety.test.ts create mode 100644 packages/design-tokens/tests/registry.test.ts create mode 100644 packages/design-tokens/tests/token.test.ts create mode 100644 packages/design-tokens/tsconfig.build.json create mode 100644 packages/design-tokens/tsconfig.json create mode 100644 packages/design-tokens/tsconfig.test.json create mode 100644 packages/ui/package.json create mode 100644 packages/ui/src/EkklesiaUiStyles.tsx create mode 100644 packages/ui/src/class-names.ts create mode 100644 packages/ui/src/controls.tsx create mode 100644 packages/ui/src/data.tsx create mode 100644 packages/ui/src/feedback.tsx create mode 100644 packages/ui/src/index.ts create mode 100644 packages/ui/src/styles.ts create mode 100644 packages/ui/src/surfaces.tsx create mode 100644 packages/ui/tests/browser-boundary.test.ts create mode 100644 packages/ui/tests/browser-boundary/node-global.tsx create mode 100644 packages/ui/tests/browser-boundary/supported.tsx create mode 100644 packages/ui/tests/browser-boundary/tsconfig.node-global.json create mode 100644 packages/ui/tests/browser-boundary/tsconfig.supported.json create mode 100644 packages/ui/tests/elements.test.tsx create mode 100644 packages/ui/tests/tokens.test.ts create mode 100644 packages/ui/tsconfig.build.json create mode 100644 packages/ui/tsconfig.json create mode 100644 packages/ui/tsconfig.test.json create mode 100644 packages/ui/vitest.config.ts create mode 100644 tests/fixtures/boundaries/design-package-depends-upward/packages/api-client/package.json create mode 100644 tests/fixtures/boundaries/design-package-depends-upward/packages/api-client/src/index.ts create mode 100644 tests/fixtures/boundaries/design-package-depends-upward/packages/design-tokens/package.json create mode 100644 tests/fixtures/boundaries/design-package-depends-upward/packages/design-tokens/src/index.ts rename tests/fixtures/boundaries/{module-imports-ui-package => design-package-depends-upward}/packages/ui/package.json (69%) create mode 100644 tests/fixtures/boundaries/design-package-depends-upward/packages/ui/src/index.ts rename tests/fixtures/boundaries/{module-imports-ui-package => module-imports-surface-sdk}/modules/calendar/package.json (78%) create mode 100644 tests/fixtures/boundaries/module-imports-surface-sdk/modules/calendar/src/index.ts create mode 100644 tests/fixtures/boundaries/module-imports-surface-sdk/packages/surface-sdk/package.json create mode 100644 tests/fixtures/boundaries/module-imports-surface-sdk/packages/surface-sdk/src/index.ts delete mode 100644 tests/fixtures/boundaries/module-imports-ui-package/modules/calendar/src/index.ts delete mode 100644 tests/fixtures/boundaries/module-imports-ui-package/packages/ui/src/index.ts create mode 100644 tests/fixtures/boundaries/module-uses-design-packages/modules/calendar/package.json create mode 100644 tests/fixtures/boundaries/module-uses-design-packages/modules/calendar/src/index.ts create mode 100644 tests/fixtures/boundaries/module-uses-design-packages/modules/calendar/src/ui/index.tsx create mode 100644 tests/fixtures/boundaries/module-uses-design-packages/packages/design-tokens/package.json create mode 100644 tests/fixtures/boundaries/module-uses-design-packages/packages/design-tokens/src/index.ts create mode 100644 tests/fixtures/boundaries/module-uses-design-packages/packages/ui/package.json create mode 100644 tests/fixtures/boundaries/module-uses-design-packages/packages/ui/src/index.ts diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 1833ffc..8aa8986 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -42,6 +42,11 @@ pnpm infrastructure:config the v6 manifest declares via `@ekklesia/module-ui-build` (ADR 0023/0033). Module authors write no bundler configuration, and styling is React inline style objects only for now. Both roles use the same UI SDK context with no presentation-mode flag. +- A module may also consume exactly two shared design packages — `@ekklesia/design-tokens` and + `@ekklesia/ui` (ADR 0039) — so two modules' screens look like one product. That is a named + allowlist: every other shared role (`api-client`, `auth-client`, `surface-sdk`, `module-ui-host`) + stays rejected inside a module. Reference registered semantic tokens; never define an + `--ekklesia-*` custom property of your own. - Module UI reaches its host only through `@ekklesia/module-ui-sdk` — never `@ekklesia/module-ui-host`, which is the host-side loader — and asks the host for its own API by relative path — never by constructing `/api/v1/modules//...`, which is Ekklesia's diff --git a/docs/architecture/decisions/0039-shared-design-tokens-and-elements.md b/docs/architecture/decisions/0039-shared-design-tokens-and-elements.md new file mode 100644 index 0000000..1e11c1b --- /dev/null +++ b/docs/architecture/decisions/0039-shared-design-tokens-and-elements.md @@ -0,0 +1,156 @@ +# 0039: Shared design tokens and foundational elements + +- Status: Accepted +- Date: 2026-08-27 +- Supersedes: none +- Related: [ADR 0021](0021-modules-as-hostable-products.md), + [ADR 0022](0022-module-ui-authoring-and-host-contract.md), + [ADR 0024](0024-browser-safe-ui-sdk-and-host-loader.md), + [ADR 0026](0026-minimal-ekklesia-module-ui-host.md), + [ADR 0033](0033-display-kiosk-host-contract.md) + +## Context + +ADR 0021 made a module an independently versioned product that owns its own UI, and ADR 0022 chose +React as the way to author it. Since then the platform has been able to *mount* a module's screen but +has said nothing at all about what that screen should look like. The consequences are now concrete: + +- Every screen in this repository — the Dashboard shell, the display host, the module template — + hardcodes its own hex colours, font stack, spacing, and radii. They already disagree with each + other. +- A module author has no vocabulary for "the ordinary panel background" or "the danger text colour", + so the only available answer is to invent one. Two modules will invent two. +- Deferred repeatedly and named in ADR 0022, ADR 0023, and ADR 0033's deferral lists: "a design + system, component library, or theme/design-token contract." +- A theme editor is a real product requirement for a church platform, and it is only implementable + if the values it would edit are enumerable with human-readable names — which is a property of the + *contract*, not something that can be retrofitted onto a pile of literals. + +The constraint that shapes everything below is ADR 0024's browser boundary. Whatever the shared +design layer is, module UI imports it, so it must not be able to pull a backend type graph — and with +it Node's global declarations — into a browser program. + +## Decision + +Add two shared browser-safe packages and open exactly two boundary roles to module UI. + +### `@ekklesia/design-tokens` — the semantic token registry + +A dependency-free package (like `@ekklesia/module-ui-sdk`, and for the same reason) holding one +validated registry of **semantic** tokens: `background.page`, `text.danger`, `state.hover-background`, +`typography.size-heading-1`, and so on. Nothing is named for the colour it currently happens to be, +because the point is that a value can change without a consumer's meaning changing with it. + +Each token declares a name, a human-readable label, a description, and a default value. Its +**category and CSS custom-property name are derived** from the name rather than declared, so a token +can never claim one category while being named for another, and there is exactly one spelling of +`--ekklesia-`. That is what makes the registry enumerable: a future theme editor reads +`list()`, groups by `category`, labels each field with `label`, explains it with `description`, and +needs no second source of truth. + +Construction validates every rule rather than leaving it to review: an invalid or single-segment +name, an unknown category, a malformed derived identifier, an empty or overlong label or description, +a duplicate name, and a value that is not a **bounded literal** each throw. A value may not contain a +declaration terminator, a rule block, a comment, an at-rule, `url(`, `!important`, a backslash +escape, a control character, or markup, and is length-bounded. A registry that constructs is +therefore a registry that can be emitted as CSS without escaping, because nothing needing escaping +can be in it. + +The registry emits its defaults as one CSS rule, scoped to `:root` or `:host` — a closed set, never a +caller-supplied selector, since an arbitrary selector string is exactly the unbounded value the +package refuses everywhere else. + +### `@ekklesia/ui` — the foundational elements + +A small React package whose every colour, type, spacing, radius, shadow, and interaction state is a +`var(--ekklesia-…)` reference. It contains the set a real module dashboard cannot be built without: +button and icon button, text input, select, checkbox, field wrapper, panel, dialog, tabs, table and +list primitives, badge, toast presentation, and empty/error/loading states, with `:focus-visible` +focus treatment on every interactive element. + +Each element is a thin, accessible shell over the real HTML element rather than a re-implementation +of it, so native attributes, form association, and assistive-technology semantics pass straight +through. **This is deliberately not a large catalogue**: an element earns its place when two +independent consumers need the same one. + +**Status is never signalled by colour alone.** Every status family carries a symbol token beside its +colours, and the elements render it. A status that is only red is invisible to a person who cannot +distinguish it, and unreadable on a projector or a washed-out lobby screen (WCAG 2.2 §1.4.1). + +### The stylesheet is a string, not a `.css` file + +These elements are mounted in two very different places: a document (the Dashboard shell, a +standalone host page) and an isolated root (a module's own artifact). A `.css` file would need a +bundler on both sides and a served asset on one of them. A string is installed into whichever root +the caller actually has, with identical bytes — and it is what lets `:focus-visible`, `:hover`, and +`:disabled` be real CSS rather than JavaScript approximations of them, which is the difference +between a focus treatment that works for a keyboard user and one that only looks like it does. + +`` renders that string into whichever root its React tree lives in. There is +deliberately no `document.head` hoisting and no `precedence` attribute: hoisting an isolated +artifact's styles into the host document is precisely the leak the platform must not have. + +### Modules consume tokens; they never invent global ones + +A module may reference any registered token and may derive **private, differently-prefixed aliases** +from them inside its own artifact. A module may not define an `--ekklesia-*` custom property: that +would add a global theme variable outside the registry, which a theme editor could never enumerate +and another module could unknowingly depend on. The typed `designToken(name)` reference makes an +unregistered name a compile error and a runtime failure. + +### The boundary opens by name, not by category + +`pnpm boundaries` adds `design-tokens` and `ui` to the shared roles a module may depend on. It is a +named allowlist, not "browser-safe shared packages are fine": `api-client`, `auth-client`, +`surface-sdk`, and `module-ui-host` all stay rejected for modules, and `contracts`/`module-sdk` +remain excluded from surfaces for the reason ADR 0024 measured. + +The two new packages are pinned at the bottom of the presentation stack by their own rule: +`design-tokens` may depend on nothing but dev-time tooling, and `ui` may depend on `design-tokens` +and dev-time tooling. A design package that could reach an API client would put that client inside +every module artifact that renders a button. + +### The host installs the theme once, at its root + +`surfaces/shell` installs the default token values at the document for both the Dashboard and the +display application. CSS custom properties inherit through a shadow boundary, so every module +artifact — including one mounted in an isolated root — reads `var(--ekklesia-…)` without the host +reaching into the artifact or the artifact importing the host. + +## Consequences + +- Two packages exist where none did; both are browser-safe by construction and proven so by a real + compile of module-shaped source under the exact project a module uses for UI, where `process.env` + must fail to typecheck. +- The Dashboard shell and display host no longer hardcode a colour, and a module can match them. +- A theme editor becomes implementable without a contract change: the values it would edit are + already enumerable, labelled, described, categorised, and validated. +- A module now has more it *may* import. The allowlist is exactly two roles and is enforced, with + fixtures proving both the acceptance and the continued rejection of everything else. +- Every module artifact bundles its own copy of the elements, exactly as it already bundles React + (ADR 0023). That cost is accepted for now and is optimisable later without a contract change, + because the contract is still a mount function. + +## Alternatives + +- **Ship a full design system.** Rejected: a large catalogue is a large maintenance and review + surface, and most of it would be speculative. The set here is what a real module dashboard needs. +- **Put the tokens in `@ekklesia/module-ui-sdk`.** Rejected: that package is the *host contract*, and + a host that renders nothing still has to satisfy it. Design values are not something a host + supplies, and merging them would make the mount ABI carry a theme. +- **Expose tokens through `ModuleUiHostContext`.** Rejected: a host handing a module a token map + makes every module re-implement styling from data, and makes the tokens a runtime negotiation + rather than inherited CSS. Custom properties already inherit into artifacts for free. +- **Ship a `.css` file.** Rejected for this pass: it forces a bundler and a served asset on every + consumer, including the isolated artifacts that most need the styles. A *module's own* stylesheets + are a separate question — the module's build already exists to compile them — and are decided by + their own ADR. +- **A theme editor now.** Deferred deliberately. The registry is the prerequisite; the editor needs + persistence, an authorization story, per-installation overrides, and a preview surface, none of + which exist. + +## Deferred + +A theme editor, a brand builder, per-installation persisted overrides, a dark theme or any second +theme, density modes, an icon set, charting, layout primitives beyond what the elements need, a +documentation site, and a focus-trap utility. diff --git a/docs/architecture/decisions/README.md b/docs/architecture/decisions/README.md index 7d9e901..94dede6 100644 --- a/docs/architecture/decisions/README.md +++ b/docs/architecture/decisions/README.md @@ -47,3 +47,4 @@ ADRs capture durable choices that affect more than one package or phase. - [0036: A display device is its own principal, paired by an administrator](0036-managed-device-identity-and-pairing.md) — Accepted - [0037: Outbound email is a host-provided transport, and SMTP is its first provider](0037-host-provided-outbound-email.md) — Accepted - [0038: Email verification and password recovery, with a trusted-bootstrap exception](0038-email-verification-and-password-recovery.md) — Accepted +- [0039: Shared design tokens and foundational elements](0039-shared-design-tokens-and-elements.md) — Accepted diff --git a/docs/architecture/repository-boundaries.md b/docs/architecture/repository-boundaries.md index fcfb45b..00f7062 100644 --- a/docs/architecture/repository-boundaries.md +++ b/docs/architecture/repository-boundaries.md @@ -7,7 +7,7 @@ These rules map platform ownership to filesystem and package boundaries. The exe | --- | --- | --- | | `apps/*` | Thin deployable composition roots | Public Core APIs, generated bootstrap, or a surface as required by the app | | `core` | Feature-agnostic platform implementations | Public contracts and external infrastructure libraries | -| `modules/*` | Domain capability, data, and the module's own UI | Module SDK, module UI SDK, public contracts, React, and external backend libraries | +| `modules/*` | Domain capability, data, and the module's own UI | Module SDK, module UI SDK, the approved design packages, public contracts, React, and external backend libraries | | `surfaces/*` | The application shell, UI, renderers, navigation, and interaction | Surface SDK, API/auth clients, the module UI SDK and host loader, design packages, and a browser framework | | `builders/*` | Declarative surface composition tooling | Builder/surface SDKs and public contracts | | `packages/*` | Explicitly scoped SDKs, contracts, clients, design, testing, or tooling | Only dependencies appropriate to the package's declared level | @@ -22,8 +22,8 @@ These rules map platform ownership to filesystem and package boundaries. The exe module may therefore contain `.tsx` source and depend on `react`, `react-dom`, and `@ekklesia/module-ui-sdk`. It still cannot contain `.jsx`, stylesheets, single-file components, Astro/Marko/MDX/HTML views, or SVG presentation assets, and cannot depend on any other UI framework - (including `react-router-dom`, `react-native`, and `@vitejs/plugin-react`) or on shared UI-role - packages. A module needs no bundler plugin: `@ekklesia/module-ui-build` — a `tooling` package, + (including `react-router-dom`, `react-native`, and `@vitejs/plugin-react`) or on any shared role + beyond the two approved design packages named below. A module needs no bundler plugin: `@ekklesia/module-ui-build` — a `tooling` package, a role modules could already depend on — owns the entire module UI build ([ADR 0023](decisions/0023-module-ui-build-pipeline.md)). An unsupported framework aliased behind an allowed name is resolved and rejected by its real target. @@ -31,6 +31,21 @@ These rules map platform ownership to filesystem and package boundaries. The exe import Core, an app, a surface, a builder, or another module. It also may not import `@ekklesia/module-ui-host`: that package is host infrastructure, and a module bundling the loader would blur the author/host split ([ADR 0024](decisions/0024-browser-safe-ui-sdk-and-host-loader.md)). +- A module may consume exactly two shared **design** roles: `design-tokens` (`@ekklesia/design-tokens`) + and `ui` (`@ekklesia/ui`), added by + [ADR 0039](decisions/0039-shared-design-tokens-and-elements.md). This is a named allowlist, not a + general "browser-safe shared packages are fine" relaxation: `api-client`, `auth-client`, + `surface-sdk`, and `module-ui-host` remain rejected inside a module. Both approved packages are + browser-safe by construction — `design-tokens` has no dependencies at all and `ui` depends only on + it — so a module UI file that imports them still cannot typecheck `process.env`, proven by a real + compile under the exact browser project a module uses. Both are also pinned at the bottom of the + presentation stack by `design-packages-depend-downward-only`: neither may reach an implementation + layer, an API/auth client, or the backend contracts barrel, because a design package that could + would put all of it inside every module artifact that renders a button. +- A module **references** registered global semantic tokens and may derive private, + differently-prefixed aliases from them inside its own artifact. It may never define an + `--ekklesia-*` custom property: that would invent a global theme variable outside the registry, + which a future theme editor could not enumerate and another module could unknowingly depend on. - `@ekklesia/module-ui-sdk` has no dependencies at all, and `@ekklesia/module-ui-host` depends only on it. Both are browser-safe by construction: neither can pull a backend type graph — and with it Node's global declarations — into browser code. Core still owns the containing @@ -96,6 +111,10 @@ These rules map platform ownership to filesystem and package boundaries. The exe direct table imports and foreign keys. Modules may not import another module's Drizzle tables, columns, relations, schema entrypoint, or migration internals. +The design packages are covered the same way: one fixture proves a module may depend on both, one +proves every other shared role stays rejected, and one proves neither design package may depend +upward. + The boundary test suite includes intentionally invalid fixture graphs. This proves that the guard rejects every currently machine-checkable repository rule even before production packages fill every directory. The UI guard rejects component, view, template, stylesheet, shared UI-role, and diff --git a/docs/module-development/README.md b/docs/module-development/README.md index 3952f61..3e8da61 100644 --- a/docs/module-development/README.md +++ b/docs/module-development/README.md @@ -281,9 +281,15 @@ artifact is the role selection. | `permissions` | `has(permissionId)` — a presentation hint, never a security check | | `realtime` | `subscribe(channel, handlers)` against **your own** module's live state — see [Realtime state](#realtime-state) | -Navigation, host theme and design tokens, module configuration, organization context, and -diagnostics reporting are **not** in the contract yet. They need designs that do not exist, and a -speculative field frozen into a public contract is harder to remove than to add. +Navigation, module configuration, organization context, and diagnostics reporting are **not** in the +contract. They need designs that do not exist, and a speculative field frozen into a public contract +is harder to remove than to add. + +The host **theme** is deliberately not a context member either, and that is not a gap: design tokens +reach your artifact as inherited CSS custom properties rather than as data (ADR 0039). You import +`@ekklesia/design-tokens` and write `var(--ekklesia-…)`; the host installs the values at its own +root. Nothing is negotiated at run time, so there is no token map to keep in sync and no host that +can forget to pass one. ### Never build your own API URL @@ -413,6 +419,58 @@ loads several React copies, and artifacts are large (the template's is roughly 5 an operator can review it). That is accepted for now and can be optimized later **without changing the contract**, because the contract is a mount function rather than a component. +### Design tokens and shared elements + +Your UI may import two shared design packages, and only those two +([ADR 0039](../architecture/decisions/0039-shared-design-tokens-and-elements.md)): + +| Package | What it is | +| --- | --- | +| `@ekklesia/design-tokens` | The platform's global semantic theme — a validated, enumerable registry of named values and the `var(--ekklesia-…)` references for them | +| `@ekklesia/ui` | The foundational Ekklesia elements, every one of them built from those tokens | + +```tsx +import { designToken } from "@ekklesia/design-tokens"; +import { Badge, Button, EkklesiaUiStyles, Panel } from "@ekklesia/ui"; + +export function Slides({ context }: { readonly context: ModuleUiHostContext }) { + return ( + <> + + Add slide} title="Slides"> +

Nothing scheduled yet.

+ Paused + + + ); +} +``` + +Render `` once, near the top of your tree. It puts the element stylesheet into +whichever root your artifact is mounted in, so you never have to know whether that is a document or +an isolated root. + +**Use semantic names, not colours.** `designToken("text.danger")` says what the text *means*; +`#9f1239` says what it looks like today. An installation that changes its theme changes the first +and not the second. `designToken` only accepts registered names, so a typo is a compile error. + +**Never define an `--ekklesia-*` custom property.** Those are the platform's global theme variables, +and inventing one would create a global a future theme editor could not enumerate and another module +could unknowingly depend on. You may derive as many *private* aliases as you like inside your own +artifact, under your own prefix: + +```tsx +
+``` + +The host installs the default token values at its own root, and CSS custom properties inherit +through an isolated artifact's boundary — so the tokens are simply there, with nothing to import at +run time and nothing for the host to hand you. + +Every other shared package stays rejected inside a module: `@ekklesia/api-client`, +`@ekklesia/auth-client`, `@ekklesia/surface-sdk`, and `@ekklesia/module-ui-host` are not yours to +import, and `pnpm boundaries` says so. + ### Styling: inline style objects only, for now Style with React's `style` prop: @@ -437,7 +495,7 @@ the build pipeline** — adding the pipeline required no boundary relaxation at | --- | --- | | `.tsx` source | `.jsx` (strict TypeScript only), `.css`, `.vue`, `.svelte`, `.astro`, `.mdx`, `.svg`, `.html` | | `react`, `react-dom` | Every other framework, plus `react-router-dom` (routing is the host's), `react-native`, `@vitejs/plugin-react` | -| `@ekklesia/module-ui-sdk`, `@ekklesia/module-ui-build` | `@ekklesia/ui` and other shared UI-role packages | +| `@ekklesia/module-ui-sdk`, `@ekklesia/module-ui-build`, `@ekklesia/design-tokens`, `@ekklesia/ui` | Every other shared role: `api-client`, `auth-client`, `surface-sdk`, `module-ui-host` | You do not need a bundler plugin — `@vitejs/plugin-react` and friends stay rejected because `@ekklesia/module-ui-build` owns the bundler entirely. diff --git a/packages/design-tokens/package.json b/packages/design-tokens/package.json new file mode 100644 index 0000000..76a5b2a --- /dev/null +++ b/packages/design-tokens/package.json @@ -0,0 +1,32 @@ +{ + "name": "@ekklesia/design-tokens", + "version": "0.1.0", + "type": "module", + "files": [ + "dist" + ], + "exports": { + ".": { + "types": "./dist/index.d.ts", + "import": "./dist/index.js" + } + }, + "scripts": { + "build": "tsc --project tsconfig.build.json", + "lint": "biome lint .", + "prepack": "pnpm --workspace-root exec turbo run build --filter=@ekklesia/design-tokens", + "test": "vitest run", + "typecheck": "tsc --noEmit --project tsconfig.json && tsc --noEmit --project tsconfig.test.json" + }, + "devDependencies": { + "@biomejs/biome": "2.5.3", + "@ekklesia/typescript-config": "workspace:*", + "@types/node": "24.13.3", + "happy-dom": "20.0.11", + "typescript": "7.0.2", + "vitest": "4.1.10" + }, + "ekklesia": { + "layer": "design-tokens" + } +} diff --git a/packages/design-tokens/src/index.ts b/packages/design-tokens/src/index.ts new file mode 100644 index 0000000..350ab32 --- /dev/null +++ b/packages/design-tokens/src/index.ts @@ -0,0 +1,3 @@ +export * from "./install.js"; +export * from "./registry.js"; +export * from "./token.js"; diff --git a/packages/design-tokens/src/install.ts b/packages/design-tokens/src/install.ts new file mode 100644 index 0000000..ddc0281 --- /dev/null +++ b/packages/design-tokens/src/install.ts @@ -0,0 +1,72 @@ +import { ekklesiaDesignTokenStylesheet } from "./registry.js"; + +/** + * The attribute that marks a token stylesheet this package installed. Used to make installation + * idempotent, and to let a host remove exactly what it added. + */ +export const DESIGN_TOKEN_STYLE_ATTRIBUTE = "data-ekklesia-design-tokens"; + +/** + * A root that can own a `