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.
Contrast requirements
Section titled “Contrast requirements”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.
Minimum contrast values
Section titled “Minimum contrast values”| 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 |
Testing contrast
Section titled “Testing contrast”Every pairing of foreground and background tokens has been validated. When adding new tokens:
- Test in both light and dark themes
- Use the APCA contrast calculator (not the WCAG 2.x ratio checker)
- Verify with
--muted-foregroundon--muted,--foregroundon--card, etc.
Touch targets
Section titled “Touch targets”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>Keyboard navigation
Section titled “Keyboard navigation”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
Focus indicators
Section titled “Focus indicators”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-ringNever remove focus indicators. They are essential for keyboard users.
Screen reader support
Section titled “Screen reader support”Semantic HTML
Section titled “Semantic HTML”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
ARIA attributes
Section titled “ARIA attributes”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>Testing screen readers
Section titled “Testing screen readers”Test with at least one screen reader:
- macOS: VoiceOver (built in, Cmd+F5)
- Windows: NVDA (free)
- Mobile: TalkBack (Android), VoiceOver (iOS)
Color independence
Section titled “Color independence”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.
Checklist
Section titled “Checklist”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)