--- name: mzizi-roots description: "Use this skill for anything involving Mzizi's components: using them, starting an app on them, or contributing one. Mzizi Roots is Mzizi's own components in Rust (UI and server components) from mzizi-dev/mzizi-registry. Covers `cargo add mzizi-roots` / `mzizi-roots-server`, what mzizi_get_component returns (Rust first), the node-to-crate map, `pub const CONTRACT`, the contracts in the registry's contracts/ for the Dashboard Standard (app/, 35 components) and the Discover Standard (discover/, 16 components; no script, server-filled shells): read one before building or changing a @bundu/ui component. Also no-JS fallback, density and floors (49px hit region, 17px body, 14px inset, 7px gaps) and brand-overlay rules, the frontend paths (pure .astro via `mzizi add --type astro`, Astro with Roots, pure Rust; Next.js adopts the .tsx), reuse before build, and adding a component (node, .rs, .tsx, registry.json, the gates). Files are the data layer: no database." --- # Mzizi Roots — the Rust build of Mzizi's components **Mzizi Roots** is Mzizi's own components in Rust: UI components, and server components as host-agnostic Rust. Write no new code against a third-party UI framework (owner, 2026-11-04, mzizi-registry#635). What renders a Roots UI component is the registry's decision, so this skill names no rendering target. They are built to support the Mzizi language (the `mzizi-language` skill) as its component model, the way React is JavaScript's; they are not the language. They live in [`mzizi-dev/mzizi-registry`](https://github.com/mzizi-dev/mzizi-registry) and are compiled by the crates in its `mzizi-rs/` workspace. The plan is `docs/roots/RFC-roots.md` there. **Rust first.** Where a Rust implementation exists, present it and use it first. The React/TSX components are **the React build**: they keep working for existing React apps, and they are deprioritised, so no new work goes into them. This skill describes registry `main` at v4.18.0 (`0d17818`, 2026-11-01) and its `contracts/` (77 component contracts in four families, and the `lib/` family), the crates at **0.7.0** (registry v4.18.0, on crates.io since 2026-11-01; 0.7.0 adds two crates, `mzizi-resilience`, the N5 core, and `mzizi-chaos-engine`, the N8 seeded chaos engine, from registry PRs #584 and #586; 0.6.0 before it carried the `--assurance-*` and `--attestation-*` roles in the generated `mzizi-tokens` pack, from mzizi-registry #578, and 0.5.0 the `mzizi-mongodb` security fixes from mzizi-registry #567; the UI crates otherwise match 0.4.0, on crates.io since 2026-10-20 with `markdown-renderer` 1.2.0 and 1.2.1 from mzizi-registry #483 and #517), and `mzizi-mcp` 0.13.0. It replaces three 0.7.0 skills: `scaffold-component` (now "Contributing a component"), `simplify` (now "Reuse before build") and the frontend half of `ecosystem-app-setup` (now "Starting an app"). Tokens, brand and the Ubuntu constraints are in the `mzizi-design` skill. ## Install Two umbrella crates with no code of their own re-export the node crates behind features: ```sh cargo add mzizi-roots # UI: tokens + ui + brand + shell (all default features) cargo add mzizi-roots-server # server: assurance + fundi + docs + discovery ``` Take only what you use: ```toml [dependencies] mzizi-roots = { version = "0.7", default-features = false, features = ["brand"] } ``` To follow `main`, or pin a commit, install from git. Cargo finds a crate by name anywhere in the repository's workspace: ```sh cargo add mzizi-roots --git https://github.com/mzizi-dev/mzizi-registry ``` ```toml mzizi-brand = { git = "https://github.com/mzizi-dev/mzizi-registry", rev = "" } ``` A single node crate works too (`cargo add mzizi-ui`). Read a crate's own `Cargo.toml` at the commit you pin for what it depends on; this skill does not restate it. `mzizi add --type mzizi` (`@nyuchi/mzizi-cli` 0.9.0 or later; `--target rust` on 0.8.0) records the crate and prints the `cargo add` rather than copying a `.rs` file into your project: a copied component is a fork of a crate module. ## What the MCP returns `mzizi_get_component` on `https://mcp.mzizi.dev/mcp` (free, no account; `mzizi-mcp` 0.11.0) is Rust first. It returns `{name, renamedFrom?, lead, note, rust, react, docs?, versions?}`: - `lead` is `"rust"` when the component has a Roots implementation, else `"react"`; `note` says which build to use. - `rust` is the registry's `/v1/rs/` answer with the install first: `crate` (`{name, registry, git}`), `install.cargo` (`cargo add `), `install.pinned` (`cargo add --git https://github.com/mzizi-dev/mzizi-registry --rev `, which builds exactly the source shown), `module` (e.g. `mzizi_brand`), `contract` (the `contract … end` text, or `null`), and `files[]` with the `.rs` source inline. With no Rust it is `null`. - `react` is the React build: `build: "react"`, `status: "deprioritised"`, `install` (the `npx shadcn@latest add https://api.mzizi.dev/v1/ui/` line), then the `/v1/ui/` body. It is no longer under a `component` key (that was 0.10.x). `mzizi_list_components` rows carry `rustCrate` when a component has Rust, the response carries `withRust`, and `rust: true` lists only those. `mzizi_search` hits carry `rustCrate` too. For `mzizi-hero-stat` the answer is `lead: "rust"`, crate `mzizi-brand`, and the four-clause contract shown under "Contracts" below. ## The crates One crate per registry node that has Rust. The map is `mzizi-rs/crate-for-node.json`, and `pnpm rust:generate` refuses a node with Rust in it that no crate claims. | Node directory | Crate | Umbrella | What it holds | | ------------------- | ----------------- | ---------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `n1-tokens` | `mzizi-tokens` | `mzizi-roots` (always on) | the 21-family palette and scales as Rust consts, generated from `lib/tokens/palette.source.ts` | | `n2-primitives` | `mzizi-ui` | `mzizi-roots` (`ui`) | alert, avatar, badge, button, card, chart, input, label, markdown renderer, progress, safe-area frame, separator, skeleton, status badge | | `n3-brand` | `mzizi-brand` | `mzizi-roots` (`brand`) | alert banner, avatar stack, cover header, empty state, escalation card, gauge card, hero stat, meta tile, stats row, success screen, suitability card, user card (all `mzizi-*`) | | `n7-shell` | `mzizi-shell` | `mzizi-roots` (`shell`) | bottom nav, command palette, connectivity bar, deep-link handler, footer, mini-app runtime, notification center, persistent player, route guard, theme provider, toast provider, update prompt | | `n8-assurance` | `mzizi-assurance` | `mzizi-roots-server` (`assurance`) | probes, telemetry, the OTLP exporter, a11y and RTL conformity checks, alert and incident engines | | `n9-fundi` | `mzizi-fundi` | `mzizi-roots-server` (`fundi`) | the Fundi reporter and learning loop (client side) | | `n10-documentation` | `mzizi-docs` | `mzizi-roots-server` (`docs`) | the docs API and routing, AI context, the changelog and docs renderers | | `n11-discovery` | `mzizi-discovery` | `mzizi-roots-server` (`discovery`) | page metadata and Schema.org JSON-LD | N5 resilience has a crate since 0.7.0: `mzizi-resilience` (circuit breaker, retry backoff, bulkhead, rate limiter, fallback chain and deadline, each a sans-IO state machine with a `contracts/lib/` contract). Depend on it directly; no umbrella re-exports it yet, and `crate-for-node.json` still maps `n5-resilience` to `mzizi-data`. `mzizi-chaos-engine` (N8, a seeded deterministic fault schedule for chaos tests that refuses to run in production) is the same. N4 safety and N6 pages have no crate (N6 never will: a page implements nothing). A Workers adapter (`mzizi-worker`) is planned for `mzizi-roots-server` and has not landed. The registry has 577 items and 55 `.rs` files. Cite `GET https://api.mzizi.dev/v1/ui` or `/v1/stats` for a current count rather than repeating these. To find a component's crate, read `rust.crate` from `mzizi_get_component`, or take its node directory and read the table above. `https://api.mzizi.dev/v1/rs/` also serves a `crate` field, derived from the same map on registry `main`; the API serves the registry at a pinned commit, and until the gateway's pin moves past the map it names `mzizi-ui` for every component. Trust the map, or the MCP. ## The renderer Mzizi components are built in-house, not borrowed from another framework. The owner removed the framework the Roots UI crates were first built on (2026-11-04, across every Mzizi repository, [mzizi-registry#635](https://github.com/mzizi-dev/mzizi-registry/issues/635)). - **Built so far.** Seven components render with Mzizi's own `render(props) -> String`: the skeleton and six static primitives, merged in `mzizi-dev/mzizi-registry` ([#506](https://github.com/mzizi-dev/mzizi-registry/pull/506) and [#510](https://github.com/mzizi-dev/mzizi-registry/pull/510)). - **Not yet.** Some published crate versions still depend on a framework that is being removed; the registry tracks that migration in #635. The rendering target that replaces it is not decided, and this skill does not name one. - **Direction.** No third-party UI framework in new work. Astro renders HTML on the server, static components ship zero WASM, there is at most one WASM module per page, and Tokio runs server-side only. - **The order components are served in** (owner, 2026-11-04): Mzizi first, TypeScript second, native (Swift, Kotlin) where the registry has them. `mzizi add` serves every type. ## Using a UI component Ask the registry for the component and read what it returns: `mzizi_get_component` gives the crate, the `cargo add` line, the contract and the `.rs` source, and `mzizi add --type mzizi` records the crate. How a host mounts or renders the component depends on the rendering target the registry has not yet decided, so there is no host example here: do not copy one from an older version of this skill. The same component also exists as pure `.astro` (`mzizi add --type astro`) and as the `.tsx`. Its Rust build and those carry the same `data-slot`, `data-portal` and classes, so one stylesheet styles all of them. What a Roots UI component looks like: - **Same contract as the React build:** the same registry name, `data-slot`, `data-portal`, variant names and Tailwind classes over the same `var(--…)` tokens. No colour literals. - **Variants are enums**, and a `match` replaces `class-variance-authority` (`n2-primitives/badge.rs`, `button.rs`). - **Browser facilities are props.** Where the `.tsx` reads `useMziziHarness`, the Rust takes the one bit it branches on, usually `prefers_reduced_motion: bool`. Logging is the host's. - **Icons are slots:** an `Element` the host renders, where the `.tsx` takes a Lucide component. - **Each file is self-contained.** No helpers shared between components. ## The two frontend paths The frontend is either **Astro** (pure `.astro` components, or Roots rendered underneath) or **pure Rust end to end**. - **Pure Rust.** An app depends on the crates and mounts the components itself. The rendering target is not decided (mzizi-registry#635), so this skill gives no mounting example. - **Astro, static.** Render the Roots component to HTML at build time or in a Worker, and let Astro place the fragment. It ships no JavaScript and suits display components. The renderer that produces the fragment is the registry's decision; use the pure `.astro` component where you need a working path today. - **Astro, interactive islands.** Compile the behaviour to one wasm module per page and wrap it as a custom element. **Not packaged yet**: the wrapper crate (`mzizi-islands`) is proposed for batch 2 of the RFC. - **Astro, pure `.astro` components** (mzizi-registry #397, owner decision 2026-10-04). The registry is the single source of every component in every format: `.tsx`, `.rs`, `.astro` (and `.mz`, the Mzizi language, as it lands). A component's `.astro` sits beside its `.tsx` and `.rs` (`components/registry/n-*/.astro`), pure Astro with no React or Vue under it and no client JavaScript unless its contract allows one enhancement script. Install with `mzizi add --type astro` (inferred in an Astro project, even one with React islands): it reads `api.mzizi.dev/v1/astro/` and writes the component, its flat-imported siblings (`./button.astro`, `./ui-utils`, `./server-table`) and any brand asset into `src/components/mzizi/`. A component with no `.astro` is refused by name, never replaced by its `.tsx`. `mzizi_get_component` returns the Astro block too. The Mzizi Dashboard Standard's app components (`app-*`, plus the primitives `button`, `badge`, `card`, `alert`, `input`, `label`, `skeleton`), the Mzizi Discover Standard's components (`discover-*`, including the detail pattern) and the marketing-site components (`site-*`) all have an `.astro` AND a `.tsx` in the registry (the `ui/` family's Astro ports keep the registry's own `.tsx`, which share only what their contract's `identity` says), each held to its contract ("The Dashboard and Discover Standards' contracts" below). `@bundu/ui` (`@bundu/ui/app/*`, `@bundu/ui/discover/*`) is BUILT from these files at a pinned registry commit, and its CI fails on drift; a Next.js app adopts the same design through the registry's `.tsx` (`mzizi add app-data-table --type tsx` or `npx shadcn add` of `api.mzizi.dev/v1/ui/`). Use them as they are: do not fork, restyle or wrap the shell or a component; fix it upstream in the registry (contract, `.astro` and `.tsx` together), in the same change. ## Starting an app **Install the shell first.** Before the first page, mount the app's one shell: `AppShell` for a signed-in app or console, `DiscoverShell` for a public discover site, both from `@bundu/ui`. Then check that every page renders inside it. The `mzizi-architecture` skill has the choice, the install and the check. Apps built page by page without a shell are the failure it exists to stop. Neither shell has a Rust build yet (`rs: null`), so a Rust or Astro-with-Roots app still takes the shell from `@bundu/ui`. For a new Mzizi-ecosystem app, or any app that consumes the design system. Pick the path first (above); these steps are the Astro one, with the pure-Rust differences noted. ### 1. Create the project (Astro) ```bash pnpm create astro@latest my-app -- --template minimal --typescript strict cd my-app pnpm astro add tailwind cloudflare ``` Astro renders HTML by default, which is what makes a new app indexable by N11 and paintable on a low-end device without opting in to either. For a pure-Rust app, start from `cargo new my-app` and skip to step 3. ### 2. Wire the tokens Copy the generated stylesheet rather than retyping hexes: `skills/mzizi-design/tokens/palette.css` in `@nyuchi/mzizi-skills` (all 21 families, light and dark, generated from `palette.canonical.json` at the package root). Import it from your global stylesheet (in Astro, `src/styles/global.css`) and register the properties in the Tailwind 4 `@theme` block so utilities generate. In Rust the same palette is the `mzizi-tokens` crate, always on in `mzizi-roots`. How the 21 families are meant to be used, the radius scale and the Bundu floor (17px body, 14px captions, a 49px hit region on every control, a 14px inset and 7px gaps) are in the `mzizi-design` skill. Pick the app's accent through `--brand-accent` rather than hardcoding a mineral hex: nyuchi = gold, mukoko = tanzanite, and a Mzizi surface = hematite (a Heritage tone, not a mineral; see the constellation in `mzizi-design`). ### 3. Add the Roots components ```bash cargo add mzizi-roots # tokens, primitives, brand components, shell parts (no AppShell yet) ``` For Astro, a small Rust crate (a build step, or a `workers-rs` Worker for request-time rendering) renders each component to HTML, and Astro places the fragment. The fragment carries the same Tailwind classes as the React build, so the stylesheet from step 2 styles it, and it ships no JavaScript. Which renderer that crate calls is undecided (mzizi-registry#635), so use the pure `.astro` components for a working path. Interactive islands (Roots compiled to wasm and wrapped as custom elements) are proposed and not packaged yet. Never copy component source between apps. Depend on the crate, so every app inherits fixes. ### 4. Give the app's AI assistants the doctrine Install the published skills bundle so any assistant working in the repo has the design system, the language and the components on hand: ```bash npm install -D @nyuchi/mzizi-skills npx skills experimental_sync # links the bundled skills into .agents/skills/ ``` `npx skills add @nyuchi/mzizi-skills` does **not** work: the `skills` CLI reads that argument as a GitHub repository and fails to clone it. `experimental_sync` is the CLI's route for skills that ship in `node_modules`, and it is marked experimental. The same skills are served with no install at all by the MCP's `mzizi_get_skills`. The public Claude Code plugin installs these skills and the MCP in one step: ``` /plugin marketplace add mzizi-dev/mzizi-registry /plugin install mzizi@mzizi ``` To wire the MCP directly instead, add it to `.mcp.json` or your client config. It is free with no account; only the Fundi tools need sign-in: ```json { "mcpServers": { "mzizi": { "type": "http", "url": "https://mcp.mzizi.dev/mcp" } } } ``` ### 5. Let fundi read the project `@nyuchi/mzizi-cli` ships the **fundi** agent, which reads the project off disk and plans the wiring against the registry: ```bash pnpm add -D @nyuchi/mzizi-cli pnpm exec fundi explore # offline — snapshot the project pnpm exec fundi plan "wire up Mzizi tokens" ``` Run the bins from the installed package (`pnpm exec`, or `npx` inside the project). A bare `npx fundi` outside it fetches an unrelated npm package called `fundi`. `explore` runs without credentials; `plan` and `chat` need `ANTHROPIC_API_KEY`. A plan is inert until you apply it, so read it before letting it write. ### 6. Verify ```bash pnpm dev ``` Confirm the tokens resolve in light and dark, a rendered Roots fragment picks up the styles, and the page is readable with JavaScript off. ### 7. An existing React app If the app is already React, the React build installs with the CLI or shadcn, by absolute URL: ```bash pnpm add -D @nyuchi/mzizi-cli && pnpm exec mzizi add button # infers the type (tsx here) npx shadcn@latest add https://api.mzizi.dev/v1/ui/mzizi-theme-provider ``` Point `components.json` `registries.mzizi.url` at `https://api.mzizi.dev/v1/ui`. A bare name resolves against shadcn's own registry and installs a different component. Do not start a new app this way. ## Server components A Roots server component is a **sans-IO core**: typed request in, typed response out, every external facility (a store, a clock, an outbound fetch, a secret) behind a trait. The host owns I/O and credentials. `n10-documentation/mzizi-docs-api.rs` is the model: it parses a path into a typed `Route`, asks a `DocsStore` trait for data and returns an `ApiResponse`. `mzizi-assurance`, `mzizi-fundi` and `mzizi-discovery` have no dependencies at all. The RFC records a passing `wasm32-unknown-unknown` `cargo check` for those three and `mzizi-docs`; CI does not run a wasm32 job yet. A host adapter mounts the core: a `workers-rs` adapter for Cloudflare Workers, an axum adapter for containers. Neither adapter crate exists yet. Until then the host writes the few lines that turn its request into the core's request (see the `mzizi-backend` skill). ## Contracts Every Roots component carries a contract, in two parts: 1. **The registry contract:** one registry name, description, dependencies and variants shared by both builds, and the same `data-slot`, `data-portal` and tokens. Each crate's `tests/contract.rs` reads the `.tsx` sibling and asserts that the slot, the portal and every variant value the Rust emits appear there too. A deliberate divergence, such as a touch target raised to the 49px hit region, is asserted from both sides, so the test fails when the React build is fixed. 2. **Checkable clauses** in the Mzizi language's `contract … end` grammar (RFC-0006; the `mzizi-language` skill), exported as `pub const CONTRACT: &str`. From `n3-brand/mzizi-hero-stat.rs`: ```rust pub const CONTRACT: &str = r#"contract slot is "mzizi-hero-stat" role is "region" label not_empty button "Share" min_height 48 end"#; ``` `min_height 48` is that component's own clause, quoted as the registry has it: a minimum **drawn** height. It is not the floor. The floor is the **49px hit region** (`BUNDU_FLOOR.hitAreaPx`, `lib/tokens/roles.source.ts` in mzizi-registry), which a control keeps however tall it is drawn. `mzizi-brand`'s contract suite renders each component in named states and evaluates every clause against the markup it emits. **A clause it cannot evaluate fails.** `mzizi_roots::brand::CONTRACTS` lists every brand component with its contract. Today the twelve `mzizi-brand` components export `CONTRACT`. The other crates check the registry contract against the `.tsx`, and their `CONTRACT` clauses arrive batch by batch. Server-component clauses (status per route, CORS and cache headers, no credential in the core) wait on the language's contracts-everywhere RFC (RFC-0010). Until then their tests assert those properties against an in-memory implementation of the traits. The language's own `service` contracts (`example` and `ensure`, RFC-0011) apply to a Mzizi `service`, not to these Rust crates. No component lowers to Rust yet (only a Mzizi `service` does, to a local axum package), so `mz contract` does not read a Roots `CONTRACT`. ### The Dashboard and Discover Standards' contracts The registry's [`contracts/`](https://github.com/mzizi-dev/mzizi-registry/tree/main/contracts) holds a machine-readable, versioned contract for every component of `@bundu/ui` (built in `mzizi-dev/packages-npm`), in two families of one format: - **`app/`, the Mzizi Dashboard Standard** (since registry `a298a4e`, 2026-10-04, mzizi-registry #404): the one dashboard design for every product in the Bundu ecosystem, with each brand's mineral as an overlay (docs.mzizi.dev/patterns/dashboard-standard). Its 35 contracts are the server-rendered app components (`@bundu/ui/app/*.astro`): the shell, the page and data patterns, and seven primitives. - **`discover/`, the Mzizi Discover Standard** (since registry `0bea10c`, 2026-10-04, mzizi-registry #415, tracking issue #413): one design for every public discover and browse page in the Mukoko family (docs.mzizi.dev/patterns/discover-standard). Its 16 contracts are the Discover components (`@bundu/ui/discover/*.astro`). "The Discover Standard" below says what is different. | File | What it is | | ------------------------------------------------- | ---------------------------------------------------------------------------------- | | `contracts/schema/component-contract.schema.json` | the format, one for both families | | `contracts/app/.contract.json` | one Dashboard Standard component's contract | | `contracts/discover/.contract.json` | one Discover Standard component's contract | | `contracts/site/.contract.json` | one marketing-site component's contract | | `contracts/ui/.contract.json` | one Astro port of a registry primitive (native select, segmented control, …) | | `contracts/index.json` | all 77 component contracts with their version and `.astro`, `.tsx`, `.rs` items | | `contracts/README.md` | the coverage tables, the recorded gaps, the shared rules, how to change a contract | **Read the contract before you build or change a `@bundu/ui` component, in any language.** It is the specification: `props` and `slots` (types, required, defaults, closed `values`; the `.astro` file's props and slots must be exactly these), `behaviour`, `states` (named fixtures, `default` required; every runner renders every state), `accessibility` (roles, keyboard, focus, ARIA, WCAG 2.2 criteria), `density`, `theming`, `noJs`, `responsive`, the `contract` block and `checks` (selector assertions on the rendered markup). `implementations` names the Astro export and the `.tsx` and `.rs` siblings, with what they share (`identity`: `slot`, `slot+role` or `slot+variants`) and their `divergences`; items under `related` look similar and have a different contract, so they are not implementations. `implementations.astro` gives the package, the export and `since`: the `@bundu/ui` release that first shipped it, 0.3.0 for the original two families (mzizi-registry #419) and 0.6.0 for the components added since (money, plan summary, tier status, confirm action, the markdown renderer, and the trust and address primitives). `@bundu/ui` is 0.7.0 on npm. `gaps` records where the current build falls short. **Every new build starts from its contract, library or component** (owner, 2026-10-31). Write or change the contract first, then the builds. A fifth family, `lib/`, holds contracts for non-visual libraries: the N5 resilience primitives (circuit breaker, retry, bulkhead, rate limiter, fallback chain, deadline) and the N8 chaos engine, in their own format (`schema/lib-contract.schema.json`), each invariant held by a test in the implementing crate (mzizi-registry #585, released in v4.18.0). Four fields are requirements. packages-npm's contract test evaluates the first three on the rendered Astro build; the responsive rules are prose. The values below are the Dashboard Standard's; the Discover Standard's differ (below): - **No-JS fallback.** `noJs.script` is `none` (no script) or `enhancement` (one script, and everything in `noJs.without` works when it does not run). Only AppShell and CommandPalette are `enhancement`; every other app component ships no script. - **Density.** Each row gives a part's height in px for a fine pointer and a coarse one (touch), read from the rendered classes (`h-N`, `min-h-N`, `size-N` = N×4; `pointer-coarse:` for touch). Dashboards are drawn dense on a mouse and at the floor on touch: the app Button's `md` row reads 36px fine and 48px coarse as the **drawn** height (its `button.contract.json` density rows), with the small radius; a button is a `hit-area` element, so its **hit region is 49px**, the floor, on both pointers, and its `sm` link row is a pinned gap, and nav rows are drawn 32 on a mouse. The registry primitives read the same density from the size roles (`h-control`: 49px coarse, 36px drawn at desktop density, hit region 49px either way), which the runner and `mzizi-rs/contract-eval` understand (`ROLE_HEIGHTS`). Since the Bundu floor (registry 4.23.0) both fail a density row whose interactive control has a hit region under 49px on either pointer, or a button-like control drawn under 28px; they count the 49px hit region only where the token layer's `hit-area` rule provably applies (`contracts/hit-region-cases.json`). Rows that predate the floor are pinned in `HIT_AREA_GAPS` and listed in `gaps`, not hidden. - **Theming.** A brand overlay changes colour only: `--primary`, `--ring`, AppShell's `--app-accent` and the brand mark. Layout never varies by brand. A mineral may be named only as one of the component's declared `statusColours`; any other mineral class, or any colour value, fails (the `mzizi-design` skill). - **Responsive.** Each contract's rules from 320px up. In both families the tests also fail **any inline `style` attribute** on a rendered element, so a page's Content-Security-Policy can keep `style-src 'self'` with no `style-src-attr 'unsafe-inline'`: custom properties go through classes or data attributes (AppShell's `data-accent`), sizes through classes or SVG geometry (BarChart). JSON-LD (`type="application/ld+json"`) is data and does not count as a script. **How they relate to `CONTRACT` and the language.** The `contract` field is a `contract … end` block in the same clause grammar as a Roots `pub const CONTRACT` (RFC-0006 and RFC-0010), restricted to what applies to rendered markup: subjects `slot`, `role`, `label`, `class`, `portal`, ` ""`, `uses ` and `when …`; predicates `is`, `contains`, `not_empty`, `in`, `uses "--token"`, `min_height` and `shows`. As in the language, **a clause, check or density row a runner cannot evaluate fails** (FM-12). The registry's own suites evaluate them: `__tests__/astro/contracts.test.ts` renders every `.astro` in every state (Astro's container, no renderer), `__tests__/contracts/ tsx-contracts.test.tsx` renders every `contract`-identity `.tsx` with the same runner (`contracts/runner.ts`), and `__tests__/contracts/contracts.test.tsx` validates every contract against the schema and the grammar and checks each identity-only sibling. packages-npm's `src/app/contracts.test.ts` runs the same contracts again on the built package. A crate's own `CONTRACT` and `tests/contract.rs` still run as before. Every contract has an `.astro` (`implementations.astro.registry`). The seven app primitives' `.tsx` are the registry's own `button`, `badge`, `card`, `alert`, `input`, `label` and `skeleton`, which share only their identity (the contract lists the divergences), as do the `ui/` family's; every other `.tsx` (`app-*`, `discover-*`, `site-*`) has `identity: "contract"`, held to the whole contract exactly as the Astro build is. A `.rs` exists in `mzizi-ui` for `button`, `badge`, `card`, `input`, `label` and `safe-area-frame`; mzizi-registry #401 tracks Rust ports of the rest, done when each passes the contract. ### The Discover Standard The 11 Discover Standard list-page contracts in `discover/` and the node each declares (the detail pattern below adds five more). DiscoverShell's `kind` is `shell`; the other ten are `pattern`s. | Contract | Component | Node | What it is | | --------------------------- | --------------- | ---- | --------------------------------------------------------------------------------------------- | | `discover/discover-shell` | DiscoverShell | N7 | the frame: skip link, mineral strip, header (brand, "Main" nav, one action), `
`, footer | | `discover/discover-meta` | DiscoverMeta | N6 | the `` tags: title, description, robots, canonical, Open Graph, the X card, JSON-LD | | `discover/discover-hero` | DiscoverHero | N6 | breadcrumbs, eyebrow, the page's one `

`, lead, the search box and actions | | `discover/discover-search` | DiscoverSearch | N6 | the one search box: a `role="search"` GET form, so every search is a URL | | `discover/category-chips` | CategoryChips | N6 | the category links as a named navigation landmark; chips wrap | | `discover/category-chip` | CategoryChip | N6 | one category link, with an optional count; a link, never a button | | `discover/discover-section` | DiscoverSection | N6 | one band: eyebrow, heading, description and "See all" over its content | | `discover/result-grid` | ResultGrid | N6 | a polite status line, the cards, the empty state and "load more"; `grid`, `list` or `rail` | | `discover/discover-card` | DiscoverCard | N6 | one card for every page, variants `article`, `event`, `circle`, `place` | | `discover/load-more` | LoadMore | N6 | cursor pagination: one `rel="next"` link to `?cursor=…` | | `discover/open-in-app` | OpenInApp | N6 | "Open in Mukoko": an https link into the super-app, with one line saying what happens | Same format, schema, clause grammar and runners as the Dashboard Standard. What the Discover contracts state differently: - **What it is for.** Public discover and browse pages in the Mukoko family (circles, news, events, weather, and the super-app on the web), not admin or operator dashboards. It reuses the Dashboard Standard where they overlap: ResultGrid's `empty` slot takes `app/empty-state` or `app/state-message`, and `related` names `app/filter-bar` and `app/pagination` as similar components with a different contract. - **No script at all.** Every Discover contract's `noJs.script` is `none`; there is no `enhancement` like AppShell's or CommandPalette's. Views are URLs, not client state: search is a GET form (`?q=`, with no `cursor`, so a new search starts at the first page), a category is a link, and paging is LoadMore's `rel="next"` link to `?cursor=`. - **Sizes come from the size roles, with gaps still pinned.** Discover's search field is 49px on both pointers and its submit button 36px drawn on a mouse and 49px on touch (the size roles, mzizi-registry#597). "See all", LoadMore, OpenInApp, DiscoverCard's app link, the category chips, the navigation links and the home link are pinned in the registry's `HIT_AREA_GAPS` (links, or literal `h-11`/`h-12` classes) until they move onto a size role or take `hit-area`; do not copy their heights. Until 2026-11-01 Discover was the same size on every pointer; the Bundu floor replaced that. - **Theming.** The brand-overlay rule is the same (colour only, no colour values, a mineral only as a declared status colour), but there is no AppShell `--app-accent`. A brand shows in DiscoverShell's `brand` slot (its mark) and in whatever primary action its `action` slot holds; the frame, header, navigation and footer are identical in every brand. `--primary` reaches only DiscoverHero's wash (`gradient-showcase`), DiscoverCard's monogram and `brand` badge tone, and OpenInApp's `primary` variant. Chips, sections and LoadMore are neutral in every brand, and DiscoverSearch follows the brand only in its focus ring (`--ring`). Only DiscoverCard declares status colours (`cobalt`, `malachite`, `gold`, `terracotta`), for its badge tones. - **Server-filled shells.** Every Discover component also works in an Astro page built once with `{{placeholders}}` and filled by a server, as circles.mukoko.com's Rust Worker does: text props are plain strings, text that fills to `""` hides itself, and state switches are attributes styled by classes (ResultGrid, DiscoverSection and LoadMore `state`, DiscoverCard `badgeTone`, CategoryChip `current`). CategoryChip, DiscoverCard, DiscoverHero, LoadMore and ResultGrid have a `template` state with placeholders, rendered like every other state. DiscoverCard and CategoryChip render their own `
  • `, so they repeat as fragments. - **One card.** DiscoverCard's `variant` changes emphasis, never structure. Its title is the one primary link, stretched over the card; other actions stay separately focusable. - **OpenInApp's `href` is https** (a universal link or a server redirect), never a bare `mukoko://` link, which does nothing without the app. - **No siblings and no gaps yet.** No `.tsx` or `.rs` implements a Discover contract, and none records `gaps`. A React or Rust port is done when it passes the same contract. **Upstream first** (registry `CONTRIBUTING.md`, from #415, for both families): a component an app needs that Mzizi does not have, or a change to one it has, goes upstream immediately: its contract in the registry, its build in `@bundu/ui` and its page on docs.mzizi.dev. An app keeps a local copy only while that upstream pull request is open, marked at the top of the file with `TODO(mzizi): `. ### Changing a contract 1. Edit `contracts//.contract.json` in the registry and bump its `version`: major when a clause, prop, slot or state is removed or narrowed, minor when one is added, patch for prose. A new family also needs its directory in `FAMILIES` in `__tests__/contracts/contracts.test.tsx` and in packages-npm's `scripts/contract-paths.mjs`. 2. Update `contracts/index.json` and the README's coverage table for that family. The test fails if either disagrees. 3. Run `pnpm test` in the registry, then `pnpm contracts:fetch ` and `pnpm test` in packages-npm. The Astro build must pass the new contract before either side merges. Never edit the copy in packages-npm. **The detail pattern** (mzizi-registry #429; docs.mzizi.dev/patterns/discover-detail): the page for one item reached from a discover page uses five more `discover/` contracts, each an `.astro` and a `.tsx`: `detail-hero` (the page's only `

    `, when/where, lead, image or media slot), `breadcrumb` (named `