ekklesiaandClaude Opus 5
e03d38fcab
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]>
76 lines
4.4 KiB
Markdown
76 lines
4.4 KiB
Markdown
# Contributing
|
|
|
|
Ekklesia is being built in verified, reviewable phases. Changes should preserve the dependency
|
|
boundaries described in [repository-boundaries.md](docs/architecture/repository-boundaries.md).
|
|
|
|
Before opening a change, run:
|
|
|
|
```bash
|
|
pnpm verify
|
|
```
|
|
|
|
Migration-runner changes and changes to identity/authentication or the API's session transport also
|
|
require the disposable live PostgreSQL suite:
|
|
|
|
```bash
|
|
pnpm test:migrations:integration
|
|
```
|
|
|
|
See the [testing guide](docs/development/testing.md) for the distinction between unit and live
|
|
evidence and for credential-safe troubleshooting.
|
|
|
|
When adding or changing a module manifest, also run `pnpm modules:validate` directly for focused,
|
|
path-aware discovery errors. It is included in `pnpm verify`.
|
|
|
|
If Docker is available, also validate the development infrastructure:
|
|
|
|
```bash
|
|
pnpm infrastructure:config
|
|
```
|
|
|
|
## Package rules
|
|
|
|
- Use strict TypeScript for production packages.
|
|
- Expose supported entry points through package `exports`; do not import another package's
|
|
private source paths.
|
|
- Use `workspace:` ranges for internal package dependencies.
|
|
- Modules own their own UI and author it in React and TypeScript (ADR 0022). A module package may
|
|
contain `.tsx` and depend on `react`, `react-dom`, and `@ekklesia/module-ui-sdk`. Every other UI
|
|
framework, `.jsx`, stylesheets, and other presentation formats remain rejected by
|
|
`pnpm boundaries`. Primary and display sources live at the exact `src/ui/index.tsx` and
|
|
`src/display/index.tsx` conventions; one `pnpm build` invocation atomically compiles every role
|
|
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/<id>/...`, which is Ekklesia's
|
|
private deployment detail and would break standalone hosting.
|
|
- The containing application shell, navigation, global theme, and platform policy belong to Core and
|
|
the host application, never to a module. Ekklesia's own shell is `surfaces/shell`; it discovers
|
|
primary module UIs through `GET /api/v1/dashboard/navigation`, resolves a dedicated display
|
|
through `GET /api/v1/module-displays/<module-id>`, mounts both with
|
|
`@ekklesia/module-ui-host`, and statically imports no module (ADR 0026/0033).
|
|
- Dedicated displays are module-owned renderers mounted by a separate full-viewport surface at
|
|
`/display/<module-id>`, never Dashboard UI with hidden chrome. Its page and descriptor require the
|
|
module-owned, non-public permission declared by `entrypoints.display`; artifact bytes remain
|
|
anonymous trusted code. Public/device identity, display inventory, and variants are deferred.
|
|
- Dashboard groups are presentation configuration, never module structure. Do not add a parent
|
|
module, child module, owning module, or group-derived dependency: real module relationships are
|
|
the dependency contract's job alone, and grouping must never influence discovery, dependency
|
|
ordering, startup, or authorization (ADR 0027). A module declares its display name
|
|
(`manifest.name`); the Dashboard owns where it appears.
|
|
- A surface is browser code. It may depend on browser-safe shared roles only — never
|
|
`@ekklesia/contracts` or `@ekklesia/module-sdk`, whose type graphs pull Node's globals into the
|
|
browser — and it reaches the server over HTTP.
|
|
- Add or update tests when changing a contract or architectural rule.
|
|
- Record major architectural changes in an ADR rather than burying them in an implementation.
|
|
|
|
Runtime registries and aggregate schemas will be produced by later phases. Do not add a manually
|
|
maintained feature-module registry; discovery starts from validated `ekklesia.module.json` files.
|