Themes

Themes let you change how your UI looks by providing alternative values for your design tokens. For example, a dark mode theme might change your surface colors from light to dark, or a high contrast theme might increase the contrast of your text colors.

Creating themes

First, create theme files with the tokens you want to override:

tokens/brutalist.json
{
  "border": {
    "radius": { "$value": "0" }
  },
  "font": {
    "family": { "$value": "monospace" }
  }
}
tokens/purple.json
{
  "color": {
    "primary": { "$value": "{color.purple.600}" },
    "secondary": { "$value": "{color.purple.400}" }
  }
}

Then, add your themes to your config:

sugarcube.config.json
{
  "tokens": {
    "source": ["tokens/colors.json"],
    "themes": {
      "brutalist": ["tokens/brutalist.json"],
      "purple": ["tokens/purple.json"]
    }
  }
}

Getting started with themes

If you’re using a starter kit, you’ll already have a dark theme set up. If you’re initializing from existing tokens, the CLI will guide you through setting up collections and themes interactively.

Themes vs. Modes: Why “dark” and “light” are just themes

Some design systems use the term “mode” for things like dark and light, and “theme” for broader branding. In Sugarcube, we keep things simple: everything is a theme.

  • Want a dark mode? Add a "dark" theme.
  • Want a high-contrast mode? Add a "high-contrast" theme.
  • Want a brand or seasonal look? Add a "brand" or "holiday" theme.

This flat approach means you can easily add as many themes as you need, and switch between them by setting the data-theme attribute to a single theme name (e.g., <html data-theme="dark">).

Should I use more than one theme at a time?

No—by definition, a theme is meant to be a single, complete set of design decisions. If you need to support combinations (like “brand-dark” or “holiday-light”), create a theme for each combination. Using more than one theme at a time is not recommended and is not supported by default.

This approach matches how most modern design token systems work, making it easy to migrate or integrate with other tools.

Collections and themes

Each collection can have its own themes. This is useful when different parts of your application need different themes:

sugarcube.config.json
{
  "tokens": {
    "product": {
      "source": ["tokens/product/colors.json"],
      "themes": {
        "dark": ["tokens/product/dark.json"]
      }
    },
    "marketing": {
      "source": ["tokens/marketing/colors.json"],
      "themes": {
        "dark": ["tokens/marketing/dark.json"]
      }
    }
  }
}

See Configuration for more details.