# Web UI (foundation web surfaces)

> **Status: DRAFT — PENDING FOUNDER GATES F4 + F5. NOT ENACTED.**
> This document is written full so the founder enacts a finished text, but it
> carries **no force** today: it is deliberately **not wired into the rules
> index** — no rule below carries an `<a id>` anchor, none appears in the
> README *Index of MUSTs* or in `rules.json`, and the corpus MUST count is
> unchanged. **Enactment path:** it enacts as an **EXTEND** on the founder's
> **F5** word, after **F4** (the mgf-website homepage/site-pattern approval)
> settles the site patterns it cites. At enactment: add the `WUI-*` anchors,
> walk DOC-18 propagation (Index of MUSTs, `mgf-fed standards`/`agents`,
> conformance matrices), and bump the headline counts — same commit.
>
> **Conformance (once enacted):** L1 for every Magogi-foundation **web
> surface** — public sites (mgf-website and template-generated siblings) and
> operator web apps (the fed-web / test-web / cloud-web class).
> **Audience:** maintainers and AI agents building or reviewing any
> foundation web surface, in any stack (Python-served, Astro/npm, static).
> **Reference consumers:** [`mgf-website`](https://codeberg.org/magogi-admin/mgf-website)
> (public-site shape; PageHeader + vendored tokens + evidence ledger) and
> `cloud-web` / `fed-web` / `test-web` (operator shape on the
> `mgf-brand-web` kit). Template delivery:
> [`mgf-website-template`](https://codeberg.org/magogi-admin/mgf-website-template)
> (generates on-brand-by-default sites; its CI palette lint is the reference
> enforcement implementation).
> **Relationship to the corpus:** `PRESENTATION_LAYER.md` (PR-*) owns
> *where presentation logic lives*; `GUI_CONSUMERS.md` (GUI-*) is the Qt
> specialisation and declares visual design out of its scope. **WUI-*** is
> the web-surface specialisation that owns what those leave open for the
> web: visual identity, delivery of the brand system, the accessibility
> floor, and their mechanical enforcement. The visual system itself is
> owned by `mgf-brand` (Brand Book + generated tokens); this standard binds
> consumers to it — it defines no colours of its own.
> **Propagation (DOC-18):** when a `WUI-*` rule changes, also update → the
> README *Index of MUSTs* + `CHANGELOG.md` + the `mgf-fed standards` / `agents`
> CLI surfaces + the conformance-tracker template + the implementing kit
> `mgf-brand-web` (console shell / generated tokens / icon sprite) + the
> exemplar surfaces `mgf-website` + `mgf-website-template` + the CI enforcement
> (palette-breach lint, token `--check`, screenshot regression). See
> DOCUMENTATION.md §10.4. *(The `WUI-*` anchors and Index-of-MUSTs rows land at
> F5 enactment; the ripple targets are named now so they are visible at the
> point of edit — DOC-18's intent even for a draft.)*

---

## Intent

The foundation's answer to "will future web apps look and behave like
Magogi?" is governance, not hope. Two facts make that cheap:

1. **The brand system is generated.** `mgf-brand/brand/assets/system/design-tokens.json`
   is the single source; `gen_tokens.py` emits the CSS/JSON/ESM token
   layers (`--mgf-*` is the only spelling of every token), and the
   `mgf-brand-web` pip kit ships the same generated files plus components.
2. **Both delivery shapes are proven.** Python-served apps consume the kit
   (three apps, byte-identical assets); the Astro/static world vendors the
   generated layer verbatim with provenance (mgf-website, and every site
   the template generates).

This standard makes those the only two ways a foundation web surface may
obtain its look — and pins the floor every surface owes its users.

## Rules box (read this first) — DRAFT, carries no force until enacted

> Rule IDs are reserved as `WUI-01..WUI-07`; anchors are added at
> enactment (see the Status block).

| ID | Rule (DRAFT wording) |
|---|---|
| **WUI-01** | **Every foundation web surface MUST consume the brand system through a sanctioned delivery** — either (a) the **`mgf-brand-web` pip kit** (Python-served apps: mount its static dir, link its sheets) or (b) the **generated token layer** from `mgf-brand` (`global-tokens.css`, or the npm-shaped `tokens.mjs`/`tokens.json`), **vendored verbatim with provenance**: a `SYNC.md` recording upstream commit + sha256 + the re-vendor procedure, and the copy never hand-edited. Brand fonts ship **self-hosted** from the same sources (no CDN / third-party font requests). Hand-copied or hand-maintained token forks are a defect (the namespace-fork class that produced live undefined-token bugs). |
| **WUI-02** | **No raw hex colours outside the token layer.** All colour in app CSS, components, and templates MUST be spelled as `--mgf-*` tokens or project-scope values (`--site-*`/`--app-*`) composed from them via `var()`/`color-mix()`. Raw hexes are permitted only (a) inside the vendored/kit token files themselves and (b) in head-chrome that provably cannot read CSS custom properties (`theme-color` meta, `manifest.webmanifest`), where the value MUST mirror a named token and say so in an adjacent comment. Themes flip inside the token layer (`prefers-color-scheme` + `[data-theme]`, both paths at parity); a raw hex breaks both themes and the palette lint. |
| **WUI-03** | **Operator apps compose their shell from the kit's `.mgf-console` family** (topbar + mark/status pill, project rail + legend, printable readout + print reset) instead of re-deriving a local shell. App CSS carries only app-specific instruments on top. (This is the lift of the fed-web ↔ test-web duplication; the kit is the single owner of the console shape.) |
| **WUI-04** | **Public sites open every page with the PageHeader instrument pattern** — indigo field, mono eyebrow, masked lattice motif, optional mini-ledger — so the first viewport of every page reads as the same calibrated instrument. The exemplar implementation is `mgf-website`'s `src/components/PageHeader.astro` (**F4-staged**: the pattern this rule pins is the one F4 approves). Keystone Gold remains the one affirmative accent — at most one gold flame per view. |
| **WUI-05** | **The accessibility floor.** Every page: exactly **one `h1`**; a **skip-link** as the first focusable element; a **visible `:focus-visible` indicator** per the enacted focus law (F2: darkened teal on light grounds, gold on dark — never `outline: none` without an equivalent); **`prefers-reduced-motion` honoured** globally (strip movement, keep the state change); a **`color-scheme` meta** (with both theme paths served at parity); and **honest empty states** — absence is stated explicitly ("no runs yet", "0 members"), never faked, padded, or silently blank. |
| **WUI-06** | **Icon law.** Icons come from the canon set (`mgf-brand/brand/assets/icons/`, F3-approved; shipped as an SVG **sprite** + per-file in the kit). They inherit colour via **`currentColor`** (tinted by the surrounding token-driven text colour — never a hard-coded fill), and carry **`aria-hidden="true"`** when decorative or a text alternative when meaningful. No third-party icon fonts or sets. |
| **WUI-07** | **Enforcement lives in CI, not in review memory.** Every web surface's pipeline MUST carry: (a) a **palette-breach lint** — no raw hex outside the token set, the allowed set **derived from the vendored/kit token layer itself** (reference implementation: `mgf-website-template/scripts/palette_lint.py`); (b) for vendorers, a **token-freshness gate** — upstream `gen_tokens.py --check` discipline plus a byte-compare of the vendored copy at render/build time; (c) for public sites, **screenshot regression** (the pages × widths × themes harness) with diffs reviewed at every PR. |

---

## 1. The two deliveries (WUI-01)

- **Python-served** (FastAPI/Flask/Django operator apps): depend on
  `mgf-brand-web`, mount its `static_dir()`, link its sheets. Never vendor
  what the kit already ships; never pin a stale local wheel.
- **npm / static / Astro**: vendor the generated `global-tokens.css`
  (and/or import the npm-shaped `tokens.mjs`) **verbatim**, with a
  `SYNC.md` provenance record (upstream commit, sha256, re-vendor steps).
  mgf-website additionally *serves* the vendored file at a stable URL so
  its build manifest can attest the exact stylesheet — recommended for any
  site that publishes an evidence ledger.

Either way there is exactly **one spelling** of every brand value in the
app: the `--mgf-*` custom property.

## 2. Shells and headers (WUI-03, WUI-04)

Operator apps and public sites converge from opposite ends onto the same
identity: consoles inherit the `.mgf-console` shell from the kit; sites
open with the PageHeader instrument. Neither re-derives brand structure
locally. App/site CSS is for the surface's *own* instruments only.

## 3. The floor is the floor (WUI-05)

The floor items are deliberately few, mechanical, and testable — they are
the recurring defect classes from the 2026-07 Court review (eight missing
`h1`s, two missing skip-links, a dropped `:focus-visible`, unratified
focus colours, decorative motion without a reduced-motion path, fake-
looking empty tables). A surface that cannot pass the floor does not ship.

## 4. What enforcement looks like (WUI-07)

The pattern, proven in `mgf-website-template` CI: **render/build the real
artifact, then lint the output** — the palette lint greps every shipped
text surface (CSS/HTML/SVG/manifest) for hex literals and fails on any
value not present in the token layer, so re-vendoring tokens updates the
law and the lint in one file. Token `--check` gates keep the generated
layer fresh upstream; screenshot regression keeps the *composition*
honest, not just the colours.

## 5. Enactment checklist (F5, after F4)

One commit, on the founder's word:

1. Add `<a id="WUI-NN">` anchors to the Rules box rows.
2. Add the `WUI-*` rows to the README **Index of MUSTs** (or
   `SHOULD_ALLOWLIST` for any row the founder stages as SHOULD).
3. `python scripts/gen_rules_index.py` — regenerate `rules.json`; headline
   counts update via the coherence gate.
4. Walk DOC-18 propagation (CLIs, conformance matrices, FEDERATION.md §4
   family table gains `WUI — Web UI`).
5. Remove this Status block; record the enactment (founder gate F5) in the
   maintenance history.
