Skip to main content

Theming

Kikumi3n Design System supports light mode, dark mode, and system preference out of the box via ThemeProvider.

ThemeProvider​

Wrap your application root with ThemeProvider:

import { ThemeProvider } from '@kikumi3n/ui';
import '@kikumi3n/tokens/css';
import '@kikumi3n/ui/styles.css';

function App() {
  return (
    <ThemeProvider defaultTheme="system">
      <YourApp />
    </ThemeProvider>
  );
}

Props​

PropTypeDefaultDescription
defaultTheme'light' | 'dark' | 'system''system'Initial theme
storageKeystring'kikumi3n-theme'localStorage key for persistence
childrenReactNode—App content

useTheme Hook​

Access and control the current theme programmatically:

import { useTheme } from '@kikumi3n/ui';

function ThemeToggle() {
  const { theme, setTheme, resolvedTheme } = useTheme();

  return (
    <button onClick={() => setTheme(resolvedTheme === 'dark' ? 'light' : 'dark')}>
      Current: {resolvedTheme}
    </button>
  );
}

Return Value​

PropertyTypeDescription
theme'light' | 'dark' | 'system'Current theme setting
resolvedTheme'light' | 'dark'Actual applied theme (resolves 'system')
setTheme(theme) => voidChange theme

How It Works​

ThemeProvider
  ↓ sets data-theme attribute on <html>
<html data-theme="dark">
  ↓ CSS Variables update
:root[data-theme="dark"] {
  --color-bg-primary: #0f0f19;
  --color-text-primary: #f0f0f5;
}
  ↓ Components auto-update
All components use var(--color-*) → instant theme switch

Performance​

Theme switching is < 16ms — no JavaScript re-rendering of components. Only CSS Variables are updated, which triggers a single browser repaint.

CSS Variables​

All components use CSS Variables from @kikumi3n/tokens. This means:

  • ✅ Theme changes are instant (no React re-render)
  • ✅ Custom themes possible by overriding CSS Variables
  • ✅ Works with any CSS — not locked to React

Override Example​

/* Override primary color for your app */
:root {
  --color-primary: #059669; /* Change from indigo to emerald */
}

System Preference​

When defaultTheme="system", the theme automatically follows the user's OS preference via prefers-color-scheme:

@media (prefers-color-scheme: dark) {
  /* Applied automatically */
}

Changes to OS dark mode settings are detected in real-time.