Visual Themes

Choose the visual style for your application with our theme system.

Developer Choice

Themes are set by developers at build time, not by end users. Choose the visual style that best fits your application's purpose.

Available Themes

The design system ships with two visual themes. Both themes fully support light and dark mode.

Base Theme

Active

Clean, flat design with minimal shadows. Ideal for data-heavy dashboards and technical interfaces.

- Flat surfaces with subtle borders
- Minimal shadow depth
- Maximum content density
- Professional, utilitarian feel

Elevated Theme

Premium feel with depth and dimension. Perfect for consumer products and marketing sites.

- Floating cards with soft shadows
- Raised buttons with highlights
- Recessed input fields
- Modern, premium aesthetic

Live Preview

Click a theme card above to see how components look with each theme. Currently viewing:

base

Example Card

Default

Secondary

Energy

Alert Examples

Success message

Warning message

Error message

Setup

Set your theme in the DesignSystemProvider:

// app/layout.tsx
import { ThemeProvider } from "next-themes"
import { DesignSystemProvider } from "@sourceful-energy/ui"

export default function RootLayout({ children }) {
  return (
    <html lang="en" suppressHydrationWarning>
      <body>
        <ThemeProvider attribute="class" defaultTheme="system">
          {/* Set your visual theme here */}
          <DesignSystemProvider defaultTheme="elevated">
            {children}
          </DesignSystemProvider>
        </ThemeProvider>
      </body>
    </html>
  )
}

CSS Variables

The elevated theme overrides these CSS variables to add depth:

[data-theme="elevated"] {
  /* Cards float above the surface */
  --card-shadow:
    0 1px 2px rgba(0, 0, 0, 0.04),
    0 4px 16px rgba(0, 0, 0, 0.04);

  /* Buttons feel tactile and raised */
  --button-shadow:
    0 1px 2px rgba(0, 0, 0, 0.06),
    0 2px 4px rgba(0, 0, 0, 0.04);
  --button-highlight: inset 0 1px 0 rgba(255, 255, 255, 0.25);

  /* Inputs appear carved into the surface */
  --input-bg: rgba(0, 0, 0, 0.02);
  --input-shadow: inset 0 1px 3px rgba(0, 0, 0, 0.06);
}

Accessing Theme Programmatically

Use the useDesignSystemTheme hook to read or change the theme:

import { useDesignSystemTheme } from "@sourceful-energy/ui"

function ThemeSwitcher() {
  const { theme, setTheme } = useDesignSystemTheme()

  return (
    <select value={theme} onChange={(e) => setTheme(e.target.value)}>
      <option value="base">Base</option>
      <option value="elevated">Elevated</option>
    </select>
  )
}

Theme vs Dark Mode

The theme system is separate from dark mode. Themes control visual style (flat vs elevated), while dark mode controls the color scheme.

Layer	Controlled By	Options	Purpose
Theme	Developer	base, elevated	Visual style & depth
Color Scheme	User / System	light, dark, system	Light or dark colors
Accessibility	User	See Accessibility page	Font, color, spacing adaptations