Icons

The Mukoko 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

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


pnpm add lucide-react

Usage

Import icons individually for optimal tree-shaking:


import { Sun, Moon, Menu, X, ArrowRight, Search } from "lucide-react"
 
<Sun className="size-4" />
<ArrowRight className="size-5 text-muted-foreground" />

Always import specific icons — never import the entire library.

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

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

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

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

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

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

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

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

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>