Theming

The design system uses CSS custom properties for theming, managed via ThemeProvider. Themes can be swapped at runtime with zero flash.

ThemeProvider

Wrap your app in ThemeProvider to activate theming:

import { ThemeProvider } from '@shellapps/react-ui';
 
function App() {
  return (
    <ThemeProvider theme="ocean" mode="dark">
      <YourApp />
    </ThemeProvider>
  );
}

Built-in Themes

There are 11 built-in themes:

Theme	Description
`default`	Neutral grey palette
`ocean`	Blue tones
`forest`	Green tones
`sunset`	Warm orange/red
`lavender`	Purple tones
`rose`	Pink tones
`slate`	Cool grey-blue
`midnight`	Deep dark blue
`ember`	Dark red/orange
`arctic`	Light icy blue
`sand`	Warm beige/tan

Colour Modes

Three modes are supported:

light — Light background, dark text
dark — Dark background, light text
system — Follows the user's OS preference via prefers-color-scheme

<ThemeProvider theme="ocean" mode="system">

CSS Custom Properties

All theme values are exposed as CSS custom properties:

/* Colours */
var(--color-bg)
var(--color-bg-secondary)
var(--color-text)
var(--color-text-secondary)
var(--color-primary)
var(--color-primary-hover)
var(--color-border)
var(--color-error)
var(--color-success)
var(--color-warning)
 
/* Spacing */
var(--space-xs)   /* 4px */
var(--space-sm)   /* 8px */
var(--space-md)   /* 16px */
var(--space-lg)   /* 24px */
var(--space-xl)   /* 32px */
 
/* Typography */
var(--font-sans)
var(--font-mono)
var(--font-size-sm)
var(--font-size-md)
var(--font-size-lg)
 
/* Radii */
var(--radius-sm)
var(--radius-md)
var(--radius-lg)
var(--radius-full)

Creating Custom Themes

Define a theme object and pass it to ThemeProvider:

import { ThemeProvider, createTheme } from '@shellapps/react-ui';
 
const myTheme = createTheme({
  name: 'custom',
  colors: {
    light: {
      bg: '#ffffff',
      bgSecondary: '#f5f5f5',
      text: '#1a1a1a',
      textSecondary: '#666666',
      primary: '#e63946',
      primaryHover: '#d62839',
      border: '#e0e0e0',
    },
    dark: {
      bg: '#1a1a1a',
      bgSecondary: '#2a2a2a',
      text: '#f0f0f0',
      textSecondary: '#999999',
      primary: '#e63946',
      primaryHover: '#ff4d5a',
      border: '#333333',
    },
  },
});
 
<ThemeProvider theme={myTheme} mode="system">
  <App />
</ThemeProvider>

Using Theme Values in Code

import { useTheme } from '@shellapps/react-ui';
 
function MyComponent() {
  const { theme, mode, setMode } = useTheme();
 
  return (
    <button onClick={() => setMode(mode === 'dark' ? 'light' : 'dark')}>
      Toggle {mode === 'dark' ? '☀️' : '🌙'}
    </button>
  );
}

Components — Components that use the theme
Installation — Setting up ThemeProvider
Experience — Theming in the Experience platform

Components Installation