Theming

Lito uses a modern CSS Variable-based theming system with OKLCH color space for perceptually uniform colors.

Color System

Lito uses a comprehensive color palette system defined through CSS custom properties. Colors are configured in docs-config.json:

{
  "branding": {
    "colors": {
      "primary": "#f97316",
      "secondary": "#ea580c",
      "accent": "#fbbf24",
      "background": "#fffbeb",
      "text": "#7c2d12"
    }
  }
}

Color Palettes

Each color is expanded into a 10-shade palette for flexibility:

ShadeUsage
50Lightest - subtle backgrounds
100-200Light backgrounds, borders
300-400Hover states, secondary elements
500Base color - primary usage
600-700Darker variants, active states
800-900Dark backgrounds, emphasis
950Darkest - high contrast

Semantic Colors

In addition to the primary palette, Lito includes semantic colors for UI feedback:

VariablePurpose
--successSuccess states, confirmations
--warningWarnings, cautions
--dangerErrors, destructive actions
--infoInformational highlights
--noteNotes and callouts

These are used by MDX components like <Alert> to provide consistent visual feedback.

Dark Mode

Dark mode is fully supported out of the box. Lito:

  1. Respects system preference - Automatically detects prefers-color-scheme
  2. Persists user choice - Saves manual toggle to localStorage
  3. Smooth transitions - Theme changes animate smoothly

How It Works

The theme toggle adds a .dark class to the <html> element. All theme-aware styles use this class:

/* Light mode (default) */
:root {
  --background: oklch(99% 0.005 90);
  --foreground: oklch(20% 0.02 90);
}


/* Dark mode */
.dark {
  --background: oklch(15% 0.015 90);
  --foreground: oklch(95% 0.01 90);
}

Writing Theme-Aware Styles

Always use CSS variables for colors to ensure dark mode compatibility:

/* Good - uses theme variables */
.my-card {
  background: var(--card);
  color: var(--card-foreground);
  border: 1px solid var(--border);
}


/* Avoid - hardcoded colors break in dark mode */
.my-card {
  background: white;
  color: #1f2937;
}

Typography

Lito uses a clean, modern typography system:

VariableDefaultDescription
--font-sansInterPrimary font for UI and content
--font-monoFira CodeMonospace font for code blocks

Font Loading

Fonts are loaded as variable fonts for optimal performance and flexibility:

@font-face {
  font-family: 'Inter';
  src: url('/fonts/inter-variable.woff2') format('woff2');
  font-weight: 100 900;
  font-display: swap;
}

Design Tokens

Lito uses a comprehensive set of design tokens as CSS variables:

Surface Colors

TokenDescription
--backgroundPage background
--foregroundPrimary text color
--cardCard/panel backgrounds
--card-foregroundCard text color
--popoverPopover/dropdown backgrounds
--popover-foregroundPopover text color
--mutedMuted/subtle backgrounds
--muted-foregroundSecondary text color

Interactive Colors

TokenDescription
--primaryPrimary brand color
--primary-foregroundText on primary backgrounds
--accentAccent/highlight color
--accent-foregroundText on accent backgrounds

Utility Colors

TokenDescription
--borderBorder color
--inputForm input borders
--ringFocus ring color

Shadows

TokenDescription
--shadow-smSmall shadow (buttons, inputs)
--shadow-mdMedium shadow (cards, dropdowns)
--shadow-lgLarge shadow (modals, popovers)

Custom CSS

Lito supports custom CSS through the _css/ folder in your docs directory.

Quick Start

Create a _css/custom.css file:

my-docs/
├── docs-config.json
├── _css/
│   └── custom.css
└── ...

Your styles will be automatically imported.

Available Files

FilePurpose
custom.cssGeneral custom styles (auto-imported)
theme.cssTheme variable overrides (auto-imported)
*.cssAdditional CSS files (manually import)

Learn More

For detailed CSS customization instructions, see the Customizing Theme guide.

Component Theming

All MDX components use theme tokens for consistent styling:

Alert Component

<Alert variant="info">This uses --info color</Alert>
<Alert variant="warning">This uses --warning color</Alert>
<Alert variant="danger">This uses --danger color</Alert>

Cards and Panels

Cards automatically adapt to the current theme:

Themed Card

This card uses --card for background and --card-foreground for text, ensuring it looks great in both light and dark modes.

Best Practices

Use Design Tokens

Always reference CSS variables instead of hardcoding colors. This ensures consistency and dark mode support.

Test Both Modes

Preview your documentation in both light and dark mode during development.

Leverage Semantic Colors

Use semantic tokens (--success, --warning, etc.) for UI states rather than arbitrary colors.

Respect Contrast

Ensure sufficient contrast between foreground and background colors for accessibility.