Skip to content

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.

Lucide React is included as a dependency when you install Mukoko components. To add it manually:

Terminal window
pnpm add lucide-react

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

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.

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
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
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)
Icon Component Usage
Sun / Moon theme Theme toggle
Github social GitHub link
Bell notification Notification bell
Settings settings Settings/preferences
User account User menu

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>

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.

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)]" />

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>