#Theming

Configure components with ConfigProvider. Start with a primary color, base radius and control height; related sizes and interaction colors are derived for you.

#Start with a few settings

Wrap the application and import the stylesheet once:

import { Button, ConfigProvider, Input } from '@sudden3/leaf-ui';
import '@sudden3/leaf-ui/styles.css';

export function App() {
  return (
    <ConfigProvider theme={{
      primaryColor: '#7654c6',
      borderRadius: 8,
      controlHeight: 34,
    }}>
      <Input aria-label="Project name" placeholder="Project name" />
      <Button>Save</Button>
    </ConfigProvider>
  );
}

Omitted settings use defaults. Hover, pressed, soft backgrounds and focus colors follow the primary color automatically.

#Try your theme

Adjust color, radius, height and appearance. Copy the generated ConfigProvider code into your application.

import { Button, ConfigProvider } from '@sudden3/leaf-ui';

<ConfigProvider theme={{
  primaryColor: '#20834a',
  borderRadius: 10,
  controlHeight: 34,
  appearance: 'light',
}}>
  <Button>Save</Button>
</ConfigProvider>

#Derived sizes

The defaults are a 10px base radius, 34px control height and 14px font size:

Numbers are pixels; CSS lengths with units are also accepted. Buttons, inputs and pickers share the same sizes.

#Regional themes

Nested providers override only supplied settings, including individual token overrides:

<ConfigProvider theme={{ primaryColor: '#20834a', controlHeight: 36 }}>
  <Button>Default region</Button>
  <ConfigProvider theme={{ primaryColor: '#7654c6', borderRadius: 16 }}>
    <Button>Campaign region</Button>
  </ConfigProvider>
</ConfigProvider>

Floating panels, Modal and message / confirm context holders placed in a region inherit its theme. Set locale separately for built-in text.

#Appearance and switching

import { useState } from 'react';
import { Button, ConfigProvider } from '@sudden3/leaf-ui';

export function ThemeSwitch() {
  const [dark, setDark] = useState(false);
  return (
    <ConfigProvider theme={{ appearance: dark ? 'dark' : 'light' }}>
      <Button onClick={() => setDark(!dark)}>Switch appearance</Button>
    </ConfigProvider>
  );
}

Dark appearance supplies suitable text, surface, border and status colors. Explicit primary colors keep their value. Pair very light brand colors with a suitable onPrimaryColor override.

#Advanced overrides

Use theme.tokens when you need specific derived sizes, semantic colors, surfaces, typography, motion or overlay stacking:

import type { LeafTheme } from '@sudden3/leaf-ui';

const theme: LeafTheme = {
  controlHeight: 36,
  borderRadius: 8,
  tokens: {
    controlHeightSm: 28,
    borderRadiusLg: 18,
    infoColor: '#1677ff',
    motionDuration: 200,
  },
};

Explicit small and large sizes take precedence over derived values. See LeafThemeTokens for all options.

motion: false disables transitions and pauses loading icons. System reduced-motion preferences remain respected.

#Reuse styles in your own components

Read the current region's CSS variables in your application styles. Use ConfigProvider to configure Leaf UI, and var() to make custom components follow that configuration:

<ConfigProvider theme={{ primaryColor: '#7654c6', borderRadius: 8 }}>
  <button className="product-button" type="button">Custom button</button>
  <Button>Leaf UI button</Button>
</ConfigProvider>

.product-button {
  min-height: var(--leaf-control-height);
  padding: 0 14px;
  border: 0;
  border-radius: var(--leaf-radius);
  background: var(--leaf-color-primary);
  color: var(--leaf-color-on-primary);
  font-family: var(--leaf-font-family);
  font-size: var(--leaf-font-size);
  font-weight: var(--leaf-font-weight);
  cursor: pointer;
}

Place custom components inside the intended provider. Import the compiled styles.css; consumers do not need Sass.

#Server rendering

Static CSS and dynamic themes work together without generating CSS at runtime. See SSR usage for Next.js and other frameworks.