Skip to content

Design · Architecture

A system with depth, not just a stack.

The Nyuchi Design System is organised as a three-dimensional space — ten nodes across three axes, plus two outside actors. It is the structure that makes a fix in one place safe everywhere.

Open the design portal

Three axes

Composition, infrastructure, observation.

A flat layer stack cannot express a system where some concerns run sideways and others run through. So the architecture is a space, not a list.

  • X — horizontal composition

    What users see. Primitives compose into brand components, brand components into pages, pages into the shell.

  • Y — vertical infrastructure

    What flows through. Tokens, safety, and resilience run vertically through every visible layer.

  • Z — depth observation

    What watches. The assurance layer audits accessibility, RTL conformity, and live behaviour continuously.

The nodes

Ten nodes, two outside actors.

Each node has exactly one role. The dot colour marks which axis a node belongs to — composition, infrastructure, observation, or an outside actor.

  • L1

    Tokens

    Every CSS value — the Five African Minerals, semantic colours, spacing, radius, type. The single layer where raw values are allowed to live.

  • L2

    Primitives

    Unbranded building blocks — buttons, inputs, cards. Pill-shaped by default, 48-pixel touch targets, no harness dependency.

  • L3

    Brand

    Branded components that compose primitives, carry the nyuchi- prefix, and wire into the runtime harness for logging, motion, and live regions.

  • L4

    Safety

    Error boundaries, fallbacks, and guards that flow vertically through every visible component.

  • L5

    Resilience

    Offline-first behaviour, memory-pressure monitoring, and sequential mount queues — the connectivity-gradient layer.

  • L6

    Pages

    Pure composition. No inline buttons, cards, SVGs, or brand fonts — pages only assemble brand components.

  • L7

    Shell

    The application frame — navigation, layout regions, and the surfaces a whole product lives inside.

  • L8

    Assurance

    The depth axis that watches everything: accessibility audits, RTL conformity, probes, and alerts running continuously.

  • L9

    Fundi

    The self-healing actor. When Assurance files a regression, Fundi proposes the fix. (Nyuchi Fundi the product is separate — this is the architecture's repair node.)

  • L10

    Documentation

    The design portal itself — the living record that renders every component, token, and demo straight from the registry.

Live per-layer component counts and current version are published on the design portal — they shift as the system grows, so they are not printed here.

The framework underneath

Mzizi is the architecture. The Design System is what you build with.

Everything above — the axes, the nodes, the rules about what may compose what — is Mzizi, the architecture framework. The Nyuchi Design System is the colour, type, components, and patterns layered on top of it.

Keeping them separate is deliberate. A team can adopt the Mzizi architecture without the Nyuchi look, or take the Nyuchi Design System knowing the structure beneath it is sound. They version independently. Mzizi has its own home and documentation at mzizi.dev.

Visit mzizi.dev Back to Design