MDK Logo

Theme

Design tokens and theme utilities for consistent styling

Theme

The @mdk/core package provides a theme system with design tokens and utilities for consistent styling across your application.

Import

// Import tokens
import { colors, spacing, borderRadius, fontSize } from '@mdk/core'

// Import utilities
import {
  getSystemTheme,
  applyTheme,
  getStoredTheme,
  setStoredTheme,
} from '@mdk/core'

// Import types
import type { Theme, ThemeConfig } from '@mdk/core'

Design tokens

Colors

Primary and gray color scales with 10 shades each (50-900).

import { colors } from '@mdk/core'

colors.primary[500]  // 'hsl(222, 47%, 50%)'
colors.gray[900]     // 'hsl(222, 47%, 11%)'

Primary scale

TokenValueUsage
primary.50hsl(222, 47%, 95%)Lightest background
primary.100hsl(222, 47%, 90%)Light background
primary.200hsl(222, 47%, 80%)Hover states
primary.300hsl(222, 47%, 70%)Borders
primary.400hsl(222, 47%, 60%)Secondary text
primary.500hsl(222, 47%, 50%)Primary color
primary.600hsl(222, 47%, 40%)Hover on primary
primary.700hsl(222, 47%, 30%)Active states
primary.800hsl(222, 47%, 20%)Dark backgrounds
primary.900hsl(222, 47%, 11.2%)Darkest

Gray scale

TokenValueUsage
gray.50hsl(210, 40%, 98%)Page background
gray.100hsl(210, 40%, 96.1%)Card background
gray.200hsl(214, 32%, 91.4%)Borders
gray.300hsl(213, 27%, 84.1%)Dividers
gray.400hsl(215, 20%, 65.1%)Placeholder text
gray.500hsl(215, 16%, 47%)Secondary text
gray.600hsl(215, 19%, 35%)Body text
gray.700hsl(215, 25%, 27%)Headings
gray.800hsl(217, 33%, 17%)Dark mode card
gray.900hsl(222, 47%, 11%)Dark mode bg

Spacing

Consistent spacing scale for margins, padding, and gaps.

import { spacing } from '@mdk/core'

spacing[4]   // '1rem' (16px)
spacing[8]   // '2rem' (32px)
TokenValuePixels
000px
10.25rem4px
20.5rem8px
30.75rem12px
41rem16px
51.25rem20px
61.5rem24px
82rem32px
102.5rem40px
123rem48px
164rem64px
205rem80px
246rem96px

Border radius

Border radius scale for rounded corners.

import { borderRadius } from '@mdk/core'

borderRadius.md    // '0.375rem'
borderRadius.full  // '9999px'
TokenValue
none0
sm0.125rem
DEFAULT0.25rem
md0.375rem
lg0.5rem
xl0.75rem
2xl1rem
full9999px

Font size

Font size scale for typography.

import { fontSize } from '@mdk/core'

fontSize.base  // '1rem'
fontSize.lg    // '1.125rem'
TokenValue
xs0.75rem
sm0.875rem
base1rem
lg1.125rem
xl1.25rem
2xl1.5rem
3xl1.875rem
4xl2.25rem
5xl3rem

Theme utilities

Theme type

type Theme = 'light' | 'dark' | 'system'

getSystemTheme

Get the user's system theme preference.

import { getSystemTheme } from '@mdk/core'

const systemTheme = getSystemTheme()  // 'light' or 'dark'

applyTheme

Apply a theme to the document root.

import { applyTheme } from '@mdk/core'

applyTheme('dark')   // Sets dark mode
applyTheme('light')  // Sets light mode
applyTheme('system') // Uses system preference

This function:

  • Removes existing light/dark classes from <html>
  • Adds the resolved theme class
  • Sets the color-scheme CSS property

getStoredTheme

Get the stored theme from localStorage.

import { getStoredTheme } from '@mdk/core'

const storedTheme = getStoredTheme()  // Theme | null
const customKey = getStoredTheme('my-theme-key')

setStoredTheme

Store the theme in localStorage.

import { setStoredTheme } from '@mdk/core'

setStoredTheme('dark')
setStoredTheme('light', 'my-theme-key')  // Custom storage key

Usage example

import { useEffect, useState } from 'react'
import {
  applyTheme,
  getStoredTheme,
  setStoredTheme,
  getSystemTheme,
} from '@mdk/core'
import type { Theme } from '@mdk/core'

function ThemeProvider({ children }) {
  const [theme, setTheme] = useState<Theme>(() => {
    return getStoredTheme() || 'system'
  })

  useEffect(() => {
    applyTheme(theme)
    setStoredTheme(theme)
  }, [theme])

  return (
    <ThemeContext.Provider value={{ theme, setTheme }}>
      {children}
    </ThemeContext.Provider>
  )
}

CSS custom properties

The theme system uses CSS custom properties that can be overridden:

:root {
  --mdk-color-primary: hsl(222, 47%, 50%);
  --mdk-color-background: hsl(210, 40%, 98%);
  --mdk-color-foreground: hsl(222, 47%, 11%);
  /* ... more properties */
}

.dark {
  --mdk-color-background: hsl(222, 47%, 11%);
  --mdk-color-foreground: hsl(210, 40%, 98%);
}

On this page