> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mzizi.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Mzizi Roots

> Mzizi Roots: Mzizi's own UI and server components for the agentic web, being rebuilt in Rust. Ten crates on crates.io at 0.1.0, and a first batch of twelve brand components. The React components keep working as the React build.

<Warning>
  **In progress.** Mzizi Roots is a conversion with its first batch done, not a finished
  library. The first batch is twelve brand components; most of the registry's 434 branded
  items are still React only. The design is
  [`docs/roots/RFC-roots.md`](https://github.com/mzizi-dev/mzizi-registry/blob/main/docs/roots/RFC-roots.md)
  in the registry, merged with the status *"proposed, 2026-09-29"*. Where this page and that
  RFC disagree, the RFC is right.
</Warning>

**Mzizi Roots** is the name for Mzizi's own branded components rebuilt in Rust: **UI and
server components, built for the agentic web.** It is where new component work goes.

## Rust first

* **Rust is the lead.** Where a Rust implementation of a component exists, it is the one to
  use, and these docs present it first.
* **The React build keeps working.** The React and TypeScript (`.tsx`) components stay in
  the registry and stay installable. They are **deprioritised**: not the lead, and not where
  new work goes. These docs call them **the React build**.
* **UI and server.** Roots covers the handlers that serve a component as well as the
  component, which is the charter's full-stack shape for Phase 1.

This follows from the owner's direction for Mzizi as a whole: the frontend is either Astro
with Mzizi UI (Roots) underneath, or pure Rust end to end, and everything built carries a
contract. See [the roadmap](/roadmap).

## How Roots relates to the language

Roots components are written in Rust today, not in Mzizi. The language cannot produce them
yet: no component lowers to Rust (only a `service` does, to a local axum package), and Phase 1
waits on the benchmark ([Status](/status)).

Roots is built to support the language: it is meant to be the language's component model,
the way React is JavaScript's, with Rust as the platform underneath. When the language
lowers components to Rust, Roots is its target: the RFC writes every Roots contract in the language's
`contract … end` grammar. That is a design intention, gated on the benchmark like the rest
of Phase 1.

Until then, the components also do a second job. The registry's components, React and Rust
together, are the ground truth for the benchmark's UI tasks. The nine
[primitives](/primitives) are hand ports of registry components, and the benchmark scores a
candidate against a component's Rust reference. That is one of the components' jobs, not
what they are, and not the benchmark's goal, which is Mzizi against the best existing
language for each kind of task ([the benchmark](/benchmark)).

## What exists today

The Rust half of the registry lives in `mzizi-rs/` in
[`mzizi-dev/mzizi-registry`](https://github.com/mzizi-dev/mzizi-registry), a Cargo workspace.
All ten of its crates are on crates.io at `0.1.0` (checked 30 September 2026): eight node
crates, one per node that has Rust, and two umbrella crates that re-export them.

| Crate | What it holds (from each crate's own description) |
| - | - |
| `mzizi-roots` | **Umbrella, UI side.** Re-exports the tokens, `mzizi-ui`, `mzizi-brand` and `mzizi-shell` |
| `mzizi-roots-server` | **Umbrella, server side.** Re-exports `mzizi-assurance`, `mzizi-fundi`, `mzizi-docs` and `mzizi-discovery` |
| `mzizi-tokens` | N1 design tokens: the 21-family palette as Rust consts, generated from one source |
| `mzizi-ui` | N2 primitives for Dioxus: avatar, badge, button, card, chart, input, label, progress, separator |
| `mzizi-brand` | N3 brand components for Dioxus: the first Roots batch, each with a checkable contract |
| `mzizi-shell` | N7 app chrome for Dioxus: bottom nav, footer, command palette, connectivity, theme, toasts |
| `mzizi-assurance` | N8 assurance: probes, telemetry and the OTLP exporter |
| `mzizi-fundi` | The N9 fundi rung, client side: what is worth filing, shaping the issue, which fixes worked |
| `mzizi-docs` | The N10 documentation rung: AI context, docs API and routing, changelog, portal rendering |
| `mzizi-discovery` | The N11 discovery rung: page metadata and Schema.org JSON-LD |

## Install

```bash theme={null}
cargo add mzizi-roots            # the UI side: tokens, primitives, brand and shell
cargo add mzizi-roots-server     # the server side: assurance, fundi, docs and discovery
```

Each umbrella turns every feature on by default. `mzizi-roots` has the features `ui`, `brand`
and `shell`, and always includes `mzizi-tokens`. `mzizi-roots-server` has `assurance`,
`fundi`, `docs` and `discovery`; `docs` brings in Dioxus, because `mzizi-docs` also carries
two documentation renderers. To take less, turn the defaults off and name what you need, or
depend on a single node crate:

```bash theme={null}
cargo add mzizi-roots --no-default-features --features brand
cargo add mzizi-brand
```

The node crates are the ones that compile each component, and they keep their names.

## The first batch: twelve brand components

The first Roots batch converts twelve N3 brand components, where there was no Rust at all
before: `mzizi-alert-banner`, `mzizi-avatar-stack`, `mzizi-cover-header`, `mzizi-empty-state`,
`mzizi-escalation-card`, `mzizi-gauge-card`, `mzizi-hero-stat`, `mzizi-meta-tile`,
`mzizi-stats-row`, `mzizi-success-screen`, `mzizi-suitability-card` and `mzizi-user-card`.
They ship in `mzizi-brand`.

**Each one carries a contract, checked against its rendered output.** The contract has two
parts. The registry contract is the one every component has: one name, one set of variants,
the same `data-slot`, `data-portal` and tokens as the React build, asserted against the
`.tsx` sibling. On top of that, each module exports clauses in the language's
`contract … end` grammar, three to eight per component and 65 in all. The crate's contract
suite renders each component with `dioxus-ssr` and evaluates every clause against the markup
it emits. A clause it cannot evaluate fails. For example, from `mzizi-alert-banner`:

```text theme={null}
contract
  slot is "mzizi-alert-banner"
  portal is "https://mzizi.dev/components/mzizi-alert-banner"
  role is "alert"
  every alert_severity label not_empty
  watch.mineral uses "--severity-cold"
  button "Dismiss" min_height 48
  button "View Details" min_height 48
end
```

These clauses are evaluated by Rust tests in the registry, not by `mz contract`. The
language's own evaluator checks a `.mz` component against itself and cannot read Rust.

The ports also fix six defects the React build still has, such as a 40px button under the
48px touch floor and an unclamped `aria-valuenow`. Each fix has a test.

## Reading the Rust source

You can read a component's Rust source over the API:

```bash theme={null}
curl https://api.mzizi.dev/v1/rs/button
```

That route is a read surface, not an install path: depend on the crate instead. Each
document's `crate` field names the crate its component ships in, so it answers which one to
depend on:

```bash theme={null}
curl -s https://api.mzizi.dev/v1/rs/mzizi-alert-banner | jq .crate
# { "name": "mzizi-brand", "registry": "crates.io", "git": "https://github.com/mzizi-dev/mzizi-registry" }
```

From registry commit `9b86e03` on, `/v1/rs/{name}` serves all twelve brand components, each
naming `mzizi-brand`, alongside the primitives in `mzizi-ui`, the app chrome in `mzizi-shell`
and the server rungs in their own crates. On 30 September 2026 the API was built from that
commit, and so was the [MCP server](/toolchain/mcp). Both pins move, so read the live one from
the source: the API's `x-mzizi-source` header, or the MCP server's `catalogue.json`.

The MCP server is Rust first too: `mzizi_get_component` leads with the component's crate,
its `cargo add` line, its contract and its `.rs` source, and gives the React build second.

## Where to go next

<CardGroup cols={2}>
  <Card title="The registry" icon="library" href="/registry/overview">
    How the registry works, and how to install from it today.
  </Card>

  <Card title="The helix" icon="dna" href="/architecture/overview">
    The DNA-helix architecture every component, Rust or React, is placed on.
  </Card>

  <Card title="Browse the components" icon="search" href="https://mzizi.dev/components">
    Every component, grouped by node, at `mzizi.dev/components`.
  </Card>

  <Card title="The MCP server" icon="plug" href="/toolchain/mcp">
    Read any component, its tokens and its doctrine from an agent.
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.