Theming

The Mukoko design system uses CSS custom properties (CSS variables) as the single source of truth for all visual tokens. Components never use hardcoded colors — every color, spacing value, and radius is a token defined in globals.css.

Five African Minerals overview

Five mineral accent colors form the core palette. These remain constant across light and dark themes:

Mineral	Hex	CSS Variable	Usage
Cobalt	`#0047AB`	`--color-cobalt`	Primary blue, links, CTAs
Tanzanite	`#B388FF`	`--color-tanzanite`	Purple accent, brand/logo
Malachite	`#64FFDA`	`--color-malachite`	Cyan accent, success states
Gold	`#FFD740`	`--color-gold`	Yellow accent, rewards/highlights
Terracotta	`#D4A574`	`--color-terracotta`	Warm accent, community

Each mineral is named after a resource found across the African continent, connecting the design system to its cultural roots.

How CSS custom properties work

All tokens are defined in globals.css under two scopes:

:root — light theme values
.dark — dark theme overrides


:root {
  --background: #FAF9F5;
  --foreground: #141413;
}
 
.dark {
  --background: #0A0A0A;
  --foreground: #F5F5F4;
}

Components reference these tokens through Tailwind utility classes:


<div className="bg-background text-foreground">
  Content that adapts to the active theme
</div>

When next-themes toggles the .dark class on the <html> element, all tokens update automatically.

The @theme inline block

Tailwind CSS 4 requires tokens to be registered in a @theme inline block so they generate utility classes:


@theme inline {
  --color-background: var(--background);
  --color-foreground: var(--foreground);
  --color-card: var(--card);
  --color-muted: var(--muted);
  --color-muted-foreground: var(--muted-foreground);
 
  /* Minerals */
  --color-cobalt: #0047AB;
  --color-tanzanite: #B388FF;
  --color-malachite: #64FFDA;
  --color-gold: #FFD740;
  --color-terracotta: #D4A574;
 
  /* Radius */
  --radius-sm: calc(var(--radius) - 4px);
  --radius-md: calc(var(--radius) - 2px);
  --radius-lg: var(--radius);
  --radius-xl: calc(var(--radius) + 4px);
}

This block connects CSS custom properties to Tailwind’s class generation engine, enabling classes like bg-background, text-muted-foreground, and rounded-lg.

Customizing the palette

To adjust the palette for a specific Mukoko app while maintaining brand consistency:

Keep the five mineral accents unchanged — they are the brand identity
Adjust semantic tokens — you can change --primary, --secondary, --destructive per app
Define both light and dark — every token must have values in both :root and .dark


:root {
  /* Weather app uses cobalt as primary */
  --primary: #0047AB;
  --primary-foreground: #FFFFFF;
}
 
.dark {
  --primary: #00B0FF;
  --primary-foreground: #141413;
}

Adding new tokens

When you need a new design token:

Add the CSS variable to both :root and .dark in globals.css
Register it in the @theme inline block
Use it via Tailwind classes, never directly


/* Step 1: Define in both themes */
:root {
  --surface-elevated: #FFFFFF;
}
.dark {
  --surface-elevated: #1A1A1A;
}
 
/* Step 2: Register in @theme */
@theme inline {
  --color-surface-elevated: var(--surface-elevated);
}


/* Step 3: Use via Tailwind */
<div className="bg-surface-elevated">Elevated card</div>

Rules

Never use hardcoded hex colors — always reference CSS custom properties via Tailwind classes
Never use inline style={{}} — except in next/og routes, Three.js, or SVG
Use cn() for class composition — never string concatenation
Define both light and dark values — incomplete tokens break theme switching