Skip to content

Accessibility

Accessibility is not optional in the Mukoko ecosystem. Every component in this registry is built to meet strict accessibility standards, ensuring usability for all people across Africa’s diverse digital landscape.

Accessibility is especially critical for the African market, where assistive technology adoption varies widely and many users rely on older devices, lower bandwidth, and outdoor mobile usage. Components must be usable in bright sunlight on a cracked screen just as well as on a desktop in an office.

The Mzizi design system uses APCA 3.0 AAA (Advanced Perceptual Contrast Algorithm) rather than the older WCAG 2.x contrast ratio. APCA is more perceptually accurate, particularly for the warm cream and deep night backgrounds used in our palette.

Text type Minimum APCA Lc Example
Body text (16px) Lc 75 --foreground on --background
Large text (24px+) Lc 60 Headings on cards
UI controls Lc 60 Button labels, form inputs
Placeholder text Lc 45 Input placeholders

Every pairing of foreground and background tokens has been validated. When adding new tokens:

  1. Test in both light and dark themes
  2. Use the APCA contrast calculator (not the WCAG 2.x ratio checker)
  3. Verify with --muted-foreground on --muted, --foreground on --card, etc.

The hit area is set by the Bundu floor 1.1.0, the minimums nothing in the system may go under. It is 45px on touch and 24px with a fine pointer. Dense controls keep the full hit area. The floor replaces the earlier 56px default and 48px minimum. Drawn control heights are 33px and 41px; they are not hit areas, so a control drawn smaller than its hit area must extend the clickable area with padding. The Mzizi registry 4.45.0 ships these values, and the standard publishes its data as floor.json.

The touch requirement exists because the African mobile market uses these products outdoors, in bright sunlight, on varied screen sizes, and with assistive technology.

// A drawn checkbox is smaller than the touch hit area; the label carries the 45px minimum
<label className="flex min-h-[45px] items-center gap-3 px-3">
<Checkbox />
<span>Accept terms</span>
</label>

All Mukoko components use Radix UI primitives for accessible keyboard interaction. Radix handles:

  • Focus management — focus trapping in modals, focus restoration on close
  • Arrow key navigation — within menus, tabs, radio groups, comboboxes
  • Escape to close — dialogs, dropdowns, popovers, sheets
  • Enter/Space to activate — buttons, checkboxes, toggles
  • Home/End — jump to first/last item in lists

All focusable elements display a visible focus ring using the Tailwind focus-visible variant:

focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-ring

Never remove focus indicators. They are essential for keyboard users.

Use the correct HTML element for its purpose:

  • <button> for actions, not <div onClick>
  • <a> for navigation
  • <nav> for navigation landmarks
  • <main> for primary content
  • <h1> through <h6> in order, no skipped levels

Radix UI components include ARIA attributes automatically. For custom components:

// Describe the purpose of icon-only buttons
<Button aria-label="Close dialog" size="icon">
<X className="size-4" />
</Button>
// Link related elements
<Label htmlFor="email-input">Email</Label>
<Input id="email-input" type="email" />
// Announce dynamic content
<div aria-live="polite" aria-atomic="true">
{statusMessage}
</div>

Test with at least one screen reader:

  • macOS: VoiceOver (built in, Cmd+F5)
  • Windows: NVDA (free)
  • Mobile: TalkBack (Android), VoiceOver (iOS)

Never use color as the sole indicator of meaning. Always pair color with:

  • Text labels — “Error: Invalid email” not just a red border
  • Icons — checkmark for success, X for error
  • Patterns — striped or dotted backgrounds for emphasis

The Five African Minerals palette is designed to be distinguishable to people with common color vision deficiencies. The mineral accents were chosen with this constraint in mind.

When building or reviewing components, verify:

  • Contrast meets APCA 3.0 AAA in both light and dark themes
  • Hit areas meet the Bundu floor: 45px on touch, 24px with a fine pointer (dense controls keep the full hit area)
  • Keyboard navigation works for all interactions
  • Focus indicators are visible
  • Screen reader announces the component’s purpose and state
  • Color is not the sole indicator of meaning
  • Heading levels are sequential (no skipping)