Theming

Customize the design system with brand themes, dark mode, and CSS variable overrides.

How Theming Works

The Mordecai Design System uses a two-layer theming approach:

Light/Dark mode — Controlled by the class attribute on <html>. Add the dark class for dark mode.

Brand theme — Controlled by the data-brand attribute on <html>. Set to a brand name like kilalo to apply brand overrides.

Dark Mode

Dark mode is applied by adding the dark class to the HTML element. Use next-themes to manage this automatically.

// app/layout.tsx
import { ThemeProvider } from 'next-themes'

export default function RootLayout({ children }) {
  return (
    <html lang="en" suppressHydrationWarning>
      <body>
        <ThemeProvider attribute="class" defaultTheme="system">
          {children}
        </ThemeProvider>
      </body>
    </html>
  )
}

Brand Themes

Brand themes override specific design tokens to match your brand's visual identity. The design system ships with a built-in Kilalo brand theme.

/* Import the kilalo brand theme */
@import '@corew500/tokens/css/kilalo';

Then set the data-brand attribute on your HTML element:

<html lang="en" data-brand="kilalo">
  ...
</html>

Custom Brand Theme

Create your own brand theme by overriding CSS variables. Only include the tokens that differ from the base light/dark themes.

/* brand/my-brand.css */
[data-brand="my-brand"] {
  --primary: 220 90% 45%;
  --primary-foreground: 0 0% 100%;
  --secondary: 160 60% 35%;
  --secondary-foreground: 0 0% 100%;
  --font-sans: 'My Brand Font', sans-serif;
}

[data-brand="my-brand"].dark {
  --primary: 220 90% 65%;
  --primary-foreground: 0 0% 10%;
}

CSS Variable Reference

Semantic color tokens

--primary / --primary-foreground

--secondary / --secondary-foreground

--destructive / --destructive-foreground

--muted / --muted-foreground

--accent / --accent-foreground

--background / --foreground

--border / --ring

--font-sans / --font-mono