Skip to content

Foundations

Foundations are the bedrock decisions that shape every component and pattern in the Mzizi design system. They define how we handle design tokens, typography, layout, motion, icons, accessibility, and internationalization across all ecosystem apps.

The Mzizi design system is built for the reality of African infrastructure. A user on a 2G connection in a village is not an edge case — that is the primary use case. Every foundation decision is shaped by four architectural pillars:

  1. Local-First — data and UI must work offline, syncing when connectivity returns
  2. Mobile-First — most users access Mukoko apps on mobile devices with constrained bandwidth and lower-end hardware
  3. Open Source & Sovereign — technology sovereignty for Africa; no dependency on infrastructure we do not control
  4. Open Data — transparent data pipelines that serve the continent’s interests

These pillars translate into concrete constraints:

  • Language-inclusive — the font stack supports African languages with full diacritics and extended character sets; African languages are first-class citizens, not localisations
  • Accessible by default — every component meets the contrast values of the Bundu floor 1.1.0 and keeps a hit area of at least 45px on touch (24px with a fine pointer)
  • Performant on constrained devices — lazy loading, memory pressure monitoring, and sequential mount queues keep the experience smooth on 2G connections and low-RAM devices
  • Offline-capable — components and patterns are designed for offline-first operation with graceful degradation

These are not aspirational goals. They are enforced constraints that shape every component in the registry.

Design Tokens

CSS custom properties — Five African Minerals, semantic colors, spacing, radius, typography.

Read more →

Typography

Font stack, type scale, and heading hierarchy.

Read more →

Layout

Responsive breakpoints, spacing scale, and container patterns.

Read more →

Motion

Animation principles, transitions, and reduced motion.

Read more →

Icons

Lucide React icon conventions, sizing, and accessibility.

Read more →

Accessibility

APCA contrast, 45px touch hit areas (24px with a fine pointer), keyboard navigation.

Read more →

Internationalization

Noto Sans for African languages, RTL support, locale formatting.

Read more →