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
@@ -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 (
|
||||
<>
|
||||
<EkklesiaUiStyles />
|
||||
<Panel actions={<Button variant="primary">Add slide</Button>} title="Slides">
|
||||
<p style={{ color: designToken("text.secondary") }}>Nothing scheduled yet.</p>
|
||||
<Badge tone="warning">Paused</Badge>
|
||||
</Panel>
|
||||
</>
|
||||
);
|
||||
}
|
||||
```
|
||||
|
||||
Render `<EkklesiaUiStyles />` 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
|
||||
<div style={{ "--calendar-row-gap": designToken("spacing.sm") } as CSSProperties}>
|
||||
```
|
||||
|
||||
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.
|
||||
|
||||
Reference in New Issue
Block a user