> ## 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.

# The Bundu floor

> The minimums every Mzizi surface keeps, in two tiers by pointer. Touch keeps a 45px hit region and 17px body text, a desktop keeps 24px and 15px. Captions are 14px, and contrast and line height hold on both.

The Bundu floor is a set of hard minimums in **two tiers, by pointer**. Touch (a coarse pointer,
or any window narrower than 64rem) keeps the high numbers: a 45px hit region and 17px body text.
A desktop (a fine pointer with hover, 64rem and up) keeps a 24px hit region and 15px body text.
Captions, the [spacing layers](https://docs.mzizi.dev/foundations/spacing-layers.md) and contrast hold on both.

The floor protects the people the touch numbers are for. A market trader in Mbare reads prices on
a cracked phone in full sun, and 7:1 contrast and 17px text make that possible. A family sharing
one phone, from a grandmother with less steady hands to a child, can hit every button, because of
the 45px target and the 9px gap between controls. A developer shipping to Bulawayo or Nairobi does
not need to know the WCAG numbers, because the build will not let a screen go under them.

> [!NOTE]
>
> **Registry 4.45 and later.** The values on this page are the owner's ruling of 19 November 2026,
> and they ship in the registry from version 4.45.

The owner's ruling moves the hit regions. Touch is **45px**, and the desktop is **24px**. 45 is the
nearest Mzizi number at or above WCAG's 44 and Apple's 44 pt (3 × 15), and 24 is WCAG 2.2's minimum
(3 × 8).

## What the floor is

| Floor | Touch | Desktop | Derives from |
| - | - | - | - |
| Hit region of every control | 45px | 24px | 3 × 15, above WCAG 2.5.5 and Apple's 44 pt; 3 × 8, WCAG 2.5.8 |
| Body text | 17px | 15px | Apple's iOS default body size (a prime); the owner's desktop size |
| Captions, metadata, secondary text | 14px | 14px | 2 × 7, the radius unit |
| Spacing | per layer | per layer | [The spacing layers](https://docs.mzizi.dev/foundations/spacing-layers.md) |
| Line height of body text | 1.5 | 1.5 | WCAG 1.4.12: content must survive a user setting of 1.5 |
| Contrast | 7 / 4.5 / 3 | 7 / 4.5 / 3 | WCAG 2: body text, non-body text, UI parts |

Nothing readable is smaller than 14px. Nothing interactive has a hit region smaller than its
tier's minimum: 45px on touch, 24px on a desktop. The drawn size of a control is set separately,
and a hit region is a floor under it, not a size for it.

The numbers live in one place in the registry, `BUNDU_FLOOR` in `lib/tokens/roles.source.ts`,
with the desktop tier under `pointerFine`. The token generators, the contract runner, the Rust
evaluator and the registry's tests all read it.

## How the floor has moved

| From | Touch hit region | Desktop hit region | Source |
| - | - | - | - |
| Before 1 November 2026 | 48px (56px large) | not set | The registry before the touch tier |
| 1 to 2 November 2026 | 44px | 24px | The first Bundu floor sizes |
| 3 November 2026 (registry 4.23.0) | 49px | not split, 49px | Owner rulings of 1 and 2 November ([mzizi-registry#597](https://github.com/mzizi-dev/mzizi-registry/issues/597)) |
| 12 November 2026 (registry 4.36.0) | 49px | 28px | The desktop tier, on the owner's ruling ([mzizi-registry#660](https://github.com/mzizi-dev/mzizi-registry/issues/660)) |
| 19 November 2026 (owner's ruling) | **45px** | **24px** | This page and [the spacing layers](https://docs.mzizi.dev/foundations/spacing-layers.md) |

Body text has been 17px on touch and 15px on a desktop since the desktop tier, and the owner's
19 November ruling does not change it.

## Tiers

The layers are defined once in the token layer and emitted as media queries on the size
variables. A component never branches on screen size.

| Layer | Applies when | Controls drawn at | Hit region | Body | Caption |
| - | - | - | - | - | - |
| Phone, touch | the defaults | 49px (large 56px) | 45px | 17px | 14px |
| Tablet | `min-width: 48rem` | 49px: an iPad is touched | 45px | 17px | 14px |
| Desktop | `min-width: 64rem` and `pointer: fine` and `hover: hover` and not `any-pointer: coarse` | 28 to 41px (28, 33, 36 or 41) | 24px | 15px | 14px |

The control sizes on the rule are 28, 33, 36, 41, 48, 49 and 56px. On a desktop a control is drawn at
one of the smaller sizes, from 28 to 41px. A field is 36px on a desktop, and 33px in its compact
form. A standard button on touch is drawn at 49px, and the large button at 56px. The 45px touch floor
is a hit region, not a drawn size.

On a desktop, large body text (`text-body-lg`) is 17px, and a caption stays 14px. Only display and
heading sizes step down as screens grow, and body text steps down once, at the desktop tier. A
touchscreen laptop reports a coarse pointer (`any-pointer: coarse`), so the desktop layer does not
apply to it, and neither does it apply to a tablet.

Density is about visual size only. Screen size is never used to guess network quality, and the
gaps between targets are spacing tokens that density does not change.

## How a control keeps its hit region

On touch, a control keeps a 45px hit region even where it is drawn smaller. The token layer's
`hit-area` rule gives every `button`, `summary`, `[role="button"]`, `[role="tab"]`,
`[role="switch"]` and any `.hit-area` element a transparent `::after` of
`max(100%, var(--target-floor))`. `--target-floor` is 2.8125rem (45px) on touch, and only the
desktop density layer lowers it, to 1.5rem (24px) and not below. On a desktop a control is drawn at no less than 28px, and its hit region is at least 24px. Its drawn
box is its hit region when it is drawn at least 24px, and it needs no pseudo-element.

The rule steps aside on purpose for an element that draws its own `after:` pseudo-element
(checkbox, switch, radio group, the tabs line variant), for menu and listbox rows (they take
`min-height: var(--target-floor)` instead), for a calendar day, and for an element with
`overflow: hidden`, which would clip it. Three consequences matter when you build:

* A native `input`, `select` or `textarea` cannot carry a pseudo-element, so the field roles
  (`h-field`, `h-field-sm`) are drawn at their component height, 49px on touch, which is above the 45px hit floor, and on a
  desktop 36px (33px in the compact form). Their drawn box is the hit region.
* A standalone link that is a target is drawn at 45px on touch and 24px on a desktop at least, or
  takes the `hit-area` class. An inline link in running text is exempt, as in WCAG 2.5.8.
* Where two covered controls sit closer than 45px apart on touch, their overlays overlap and the
  later sibling wins the overlap, so keep gaps from the spacing tokens.

## Contrast beside the floor

The floor's contrast numbers are WCAG 2 minimums: **7:1** for body text, **4.5:1** for non-body
text and **3:1** for UI parts. The registry's token build fails when a default role is under its
minimum, and the APCA bars still apply. Five button-label roles hold 4.5:1 rather than 7:1, an
owner-confirmed exception: `primary-foreground`, `brand-accent-foreground`,
`app-accent-foreground`, `sidebar-primary-foreground` and `destructive-foreground`. The thresholds,
the reason for the exception and how to test a pairing are on
[accessibility](https://docs.mzizi.dev/foundations/accessibility.md#contrast-wcag-minimums-and-apca).

## Migrating

The 19 November ruling changes the hit regions, the spacing and the control heights. Body text,
captions, line height and contrast do not change.

| Token or floor | Earlier (registry 4.36.0, 12 November 2026) | Now (19 November 2026 ruling) |
| - | - | - |
| `--target-floor`, touch | 49px | 45px |
| `--target-floor`, desktop | 28px | 24px |
| Inset floor | 14px | 17px controls, 12px chips, 9px pills, 21px cards, 28px containers, 17px page edge |
| Gap between adjacent controls | 7px | 9px |
| Gap between a label and its field | 7px | 7px default, 5px dense |
| Gap between sibling items in a list, grid or toolbar | 7px | 14px default, 7px dense (the card gap) |
| `spacing-control-sm`, `spacing-control-dense`, `spacing-field-sm` | 32px | 33px |
| `spacing-control-lg`, `--touch-target-sm` | 40px | 41px |
| Body text, captions, line height, contrast | 17px and 15px; 14px; 1.5; 7 / 4.5 / 3 | Unchanged |

The size roles set on 1 November 2026 moved again on 3 and 12 November. An app that still uses
the 1 November sizes can use this table to see what it has to change:

| Token | Earlier (1 November 2026) | Now: phone and tablet | Now: desktop |
| - | - | - | - |
| `--size-touch` | 44px; 36px on desktop | 45px | 36px (hit 36px) |
| `--size-control` | 44px; 36px on desktop | 49px | 36px (hit 36px) |
| `--size-control-sm` | 44px; 32px on desktop | 49px | 33px (hit 33px) |
| `--size-control-lg` | 48px; 40px on desktop | 56px | 41px (hit 41px) |
| `--size-field`, `--size-field-sm` | 44px; 36px, 32px | 49px | 36px, 33px |
| `--target-floor` | 44px; 24px on desktop | 45px | 24px |
| `--fs-body` | 17px; 16px; 15px | 17px | 15px |
| `--fs-small` (`text-body-sm`, `text-sm`) | 15px; 14px | 14px | 14px |
| `--fs-caption` (`text-xs`) | 12px | 14px | 14px |
| Badge text, chart axis labels | 10 to 12px | 14px | 14px |

In an app:

1. Take the registry version (or `@bundu/ui` built from it) and re-run `pnpm tokens:sync` or
   re-copy `mzizi-tokens-globals.css`.
2. Replace `h-12`, `h-14` and `min-h-[44px]` on a control with a size role (`h-control`,
   `h-field`, `min-h-touch-min`). On a desktop a control is drawn at 28 to 41px, and its drawn box
   is the hit region, which is at least 24px. On touch a control never goes under 45px.
3. Replace any `text-[Npx]` under 14 with `text-sm`, and write body copy as `text-body`.
4. If a layout breaks and cannot move yet, set the legacy alias (below) and plan the move.

Expect denser layouts to need room: a badge or a meta label that fitted at 10px is now 14px.

### The legacy alias

To take the version and keep the earlier sizes for a while, put the attribute on the root
element:

```html theme={null}
<html data-mzizi-sizes="legacy">
```

It restores the sizes from before 1 November 2026 (a 48px floor, 56px and 48px controls, 16px
body, 12px captions) and outranks the density layer; it does not restore the 1 November sizes in
the table above. It **steps out of the floor**: that is the point of it, and the reason to remove
it as soon as the app has moved. It is a compatibility alias, and the registry plans to remove it
in the next major version. `text-xs` and `text-body` follow the same variables, so they step out
with it.

### One class name to avoid

Write body copy as `text-body`, not `text-base`. The token layer registers `--text-base` (17px),
but a theme that also defines a colour named `base` (`--color-base`) can make `text-base`
ambiguous. The registry has not yet decided how to settle it; `text-body`, `text-sm` and `text-xs`
work meanwhile.

## What fails the build

The registry's `bundu-floor` test fails when a default type step is under its floor in any layer,
when a floored size role is under its tier's minimum (45px on touch), when the desktop layer
lowers `--target-floor` below 24px or the `hit-area` rule is gone, when a desktop control is drawn under its 28px drawn minimum or its hit region is under 24px, when a copy of the floor disagrees with `BUNDU_FLOOR`, or when a registry component
names an arbitrary text size under 14px. The contract runner and the Rust evaluator fail a density
row whose interactive control has a hit region under 45px on a coarse pointer or 24px on a fine
one. Rows that predate the floor are pinned, so a new one cannot join them unseen; see
[the Dashboard Standard's density table](https://docs.mzizi.dev/patterns/dashboard-standard.md#density).

## The Bundu Order

The Bundu Order draws on biblical mathematical patterns and prime numbers (owner, 2 November
2026\). This section states only what the registry's code holds, in its `brand-guidelines`
doctrine page.

* **The unit is 7px** (`--radius-unit`). The radii are 4, 7, 12, 14 and 17px and a pill, and they
  do not change.
* **P7 and P17** are prime steps of the surface-elevation ladder (`surface` is P7, `raised` is
  P17), and the seven experimental colour families are a heptagon of hues offset 17 degrees.
* **The floors derive from the same numbers.** Body text is 17px on touch, a prime and Apple's iOS
  default, and 15px on a desktop (the owner's number). Captions are 14px (2 × 7). Every control
  keeps a hit region of 45px on touch (3 × 15, the nearest Mzizi number above Apple's 44 pt) and
  24px on a desktop (3 × 8, WCAG 2.5.8), never smaller.

The number rule that sets the spacing and the hit regions is on
[the spacing layers](https://docs.mzizi.dev/foundations/spacing-layers.md#the-number-rule). The comparison with the other
systems is on [the standards comparison](https://docs.mzizi.dev/foundations/standards-comparison.md).

## Sources

* The owner's rulings of 2 November 2026 (touch 49px), 12 November 2026 (desktop 28px, #660) and
  19 November 2026 (touch 45px, desktop 24px, layered spacing).
* The registry's
  [`sizes-and-density.md`](https://github.com/mzizi-dev/mzizi-registry/blob/main/docs/sizes-and-density.md)
  (the migration guide) and its `content/doctrine/documentation/brand-guidelines.mdx`.
* Registry 4.45 and later, through the MCP operations `get_tokens` (`family=floors`) and `get_doctrine`
  (`topic=bundu-floor`), once the MCP server is repinned to that release.
* The other systems: [the standards comparison](https://docs.mzizi.dev/foundations/standards-comparison.md), which lists
  WCAG 2.2, Apple's Human Interface Guidelines, Material 3 and Anthropic's brand guidelines.


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