Theming

A step-by-step guide to customizing and extending Elemnts UI's design system to match your brand.

Customizing the Theme

Elemnts UI allows you to extend or override the default theme by adding your own design tokens, semantic tokens, and text styles in the theme.extend section of your configuration.

Modifying Design Tokens

Design tokens are the smallest building blocks of your design system, such as colors, font sizes, and spacing. You can define new tokens or override existing ones.

For example, to add a custom brand color palette:

export default defineConfig({
  theme: {
    extend: {
      tokens: {
        colors: {
          brand: {
            primary: { value: "oklch(60% 0.15 250)" },
            secondary: { value: "oklch(70% 0.1 250)" },
          },
        },
        fonts: {
          heading: { value: "Geist, sans-serif" },
        },
      },
    },
  },
});

Semantic Tokens

Semantic tokens map primitive tokens to specific contexts (e.g., danger, success, bg.primary). They are theme-aware, meaning they can adapt to light or dark modes automatically.

Here’s how to define semantic tokens for a danger color that changes between modes:

export default defineConfig({
  theme: {
    extend: {
      semanticTokens: {
        colors: {
          danger: {
            value: {
              base: "{colors.red.70}",
              _dark: "{colors.red.60}",
            },
          },
          brand: {
            value: "{colors.brand.primary}",
          },
        },
      },
    },
  },
});

Reusable Text Styles

Text styles let you group typography properties (e.g., font family, size, weight) into reusable styles like hero, body, or caption.

Define your text styles in a separate file:

import { defineTextStyles } from '@pandacss/dev'

export const textStyles = defineTextStyles({
  hero: {
    value: {
      fontFamily: "{fonts.heading}",
      fontWeight: "bold",
      fontSize: "4xl",
      lineHeight: "tight",
    },
  },
  body: {
    value: {
      fontFamily: "{fonts.body}",
      fontSize: "md",
      lineHeight: "relaxed",
    },
  },
})

Then, include them in your configuration:

export default defineConfig({
  theme: {
    extend: { textStyles },
  },
});

Customizing Components

Elemnts UI components are styled using Recipes and Slot Recipes. You can override these to change the default appearance of any component, such as a Button or Card.

Overriding Component Recipes

To customize a component’s styling, redefine its recipe in your configuration. For example, to style a Button with a bold font and rounded corners:

export default defineConfig({
  theme: {
    extend: {
      recipes: {
        button: {
          base: {
            fontWeight: "bold",
            borderRadius: "full",
          },
        },
      },
    },
  },
});

Best Practices for Theming

Follow these best practices to ensure a consistent and maintainable design system:

Best Practice	Description
Use extend	Always place your customizations inside `theme.extend` to avoid accidentally overwriting the base Elemnts UI theme.
Reference Tokens Properly	Use the `{category.name}` syntax to reference tokens (e.g., `{colors.red.50}` or `{surface.1}`).
Leverage Theme Awareness	Use semantic tokens for colors or styles that should adapt to light/dark modes.
Maintain Consistency	Stick to the provided duration and easing tokens to preserve the "Elemnts" feel across your design system.
Organize Your Tokens	Group related tokens (e.g., colors, fonts) logically to make your configuration easier to maintain.

Need help? Check out the Panda CSS documentation or reach out to the Elemnts UI community for support!