Icons
The Mzizi design system uses Lucide React as its icon library. Lucide provides a consistent set of open-source icons with a clean, minimal style that complements the Five African Minerals design language.
Installation
Section titled “Installation”Lucide React is included as a dependency when you install Mukoko components. To add it manually:
pnpm add lucide-reactImport icons individually for optimal tree-shaking:
<Sun className="size-4" /><ArrowRight className="size-5 text-muted-foreground" />Always import specific icons — never import the entire library.
Sizing conventions
Section titled “Sizing conventions”| Context | Size class | Pixels | Usage |
|---|---|---|---|
| Inline text | size-3 |
12px | Inside badges, small labels |
| Button icon | size-4 |
16px | Icon buttons, button with text |
| Card icon | size-5 |
20px | Card headers, list items |
| Feature icon | size-6 |
24px | Feature cards, section icons |
| Hero icon | size-8 |
32px | Large display icons |
| Illustration | size-12 |
48px | Empty states, large callouts |
Use the size-* shorthand (which sets both width and height) instead of separate h-* and w-* classes.
Common icons in Mukoko apps
Section titled “Common icons in Mukoko apps”Navigation
Section titled “Navigation”| Icon | Component | Usage |
|---|---|---|
Menu |
hamburger | Mobile menu toggle |
X |
close | Close dialogs, dismiss |
ArrowLeft |
back | Back navigation |
ArrowRight |
forward | Next, link arrow |
ChevronDown |
expand | Dropdown trigger |
ExternalLink |
external | External links |
Actions
Section titled “Actions”| Icon | Component | Usage |
|---|---|---|
Search |
search | Search input |
Plus |
add | Create new item |
Trash2 |
delete | Delete action |
Pencil |
edit | Edit action |
Copy |
copy | Copy to clipboard |
Share2 |
share | Share content |
Download |
download | Download file |
Status
Section titled “Status”| Icon | Component | Usage |
|---|---|---|
Check |
success | Completion, validation pass |
AlertCircle |
warning | Warning message |
AlertTriangle |
error | Error state |
Info |
info | Informational message |
Loader2 |
loading | Loading spinner (animate with animate-spin) |
Ecosystem
Section titled “Ecosystem”| Icon | Component | Usage |
|---|---|---|
Sun / Moon |
theme | Theme toggle |
Github |
social | GitHub link |
Bell |
notification | Notification bell |
Settings |
settings | Settings/preferences |
User |
account | User menu |
Accessibility
Section titled “Accessibility”Icon-only buttons
Section titled “Icon-only buttons”When an icon is used without visible text, always provide an accessible label:
{/* Using aria-label */}<Button variant="ghost" size="icon" aria-label="Close dialog"> <X className="size-4" /></Button>
{/* Using sr-only text */}<Button variant="ghost" size="icon"> <Search className="size-4" /> <span className="sr-only">Search</span></Button>Decorative icons
Section titled “Decorative icons”Icons that accompany visible text are decorative and should be hidden from screen readers:
<Button> <Plus className="size-4" aria-hidden="true" /> Add item</Button>Lucide icons have aria-hidden="true" set by default, so this is handled automatically in most cases.
Icon color
Section titled “Icon color”Icons inherit color from their parent via currentColor. Use text color utilities:
<Search className="size-4 text-muted-foreground" /><Check className="size-4 text-[var(--color-malachite)]" />Icon with text alignment
Section titled “Icon with text alignment”When pairing icons with text, use flex with items-center and appropriate gap:
<span className="flex items-center gap-1.5 text-sm text-muted-foreground"> <Clock className="size-3.5" /> 3 minutes ago</span>For buttons and links, the gap-* within the flex container keeps spacing consistent:
<Button className="gap-2"> <Download className="size-4" /> Download report</Button>