Natcore LogoNatCore

Theming

A theme is a named set of role colors you select with data-theme. Components keep using the same token classes while the active theme changes the values underneath; light and dark are a separate scheme axis.

How themes work

A theme sets the color for each semantic role. Natcore expands those roles into full palettes — see Palette for the shade mechanics — and components consume the resulting adaptive tokens.
01Assign role colors

A theme gives each semantic role — primary, secondary, accent, surface, danger, success — a color or anchors.

02Select with data-theme

Switching data-theme swaps the whole role set. Component and utility classes never change.

03Pick a scheme

Light and dark are a separate axis controlled by scheme-* classes, so one theme serves both.

Semantic roles

A theme assigns a color to each of these roles. Markup references the role by intent — not a specific hex — so the same components work across every theme. These roles are the stable API; a theme changes the values underneath them.
primary

Primary actions, selected states, and the main brand direction.

--theme-primary
secondary

Supporting actions and secondary moments that still need color.

--theme-secondary
accent

Highlights, emphasis, and moments that should stand apart.

--theme-accent
surface

Page backgrounds, containers, borders, and neutral text.

--theme-surface
success

Positive outcomes, confirmations, and valid states.

--theme-success
danger

Destructive actions, errors, and blocking states.

--theme-danger
disabled

Unavailable controls, subdued text, and inactive surfaces.

--theme-disabled

Theme identity

Use data-theme to select a named palette. The selector defines role values Natcore uses to build the rest of the token system.
Codecss
:root[data-theme="citrine-reef"] {
  --theme-primary: #087f8c;
  --theme-secondary: #f59e0b;
  --theme-accent: #ef476f;

  --theme-surface-50: #f4fbf7;
  --theme-surface-500: #678f82;
  --theme-surface-950: #071c18;

  --theme-danger: #c2415d;
  --theme-success: #26966f;
}
Stable markup

Classes like btn-solid/primary and card-soft/surface stay the same when the selected theme changes.

Anchoring role colors

Within a theme, each role is a palette. Give a role a single color or pin specific shades with --theme-{role}-{shade} — Natcore fills in the rest of the ramp. This is the same anchor model documented on the Palette page, applied to a theme's roles.
Codecss
:root[data-theme="custom"] {
  /* A single color per role is enough… */
  --theme-primary: #087f8c;

  /* …or pin any shade 50-950 for a role, using the
     same anchor model palettes use. */
  --theme-primary-300: #4aa3c7;

  --theme-surface-50: #f4fbf7;
  --theme-surface-500: #678f82;
  --theme-surface-950: #071c18;
}

Light and dark

Natcore treats theme choice and light/dark choice as separate concerns. data-theme selects the palette; the scheme class controls which side of each adaptive token is used.
Codehtml
<html class="scheme-light-dark" data-theme="citrine-reef">
  <body>
    <button class="btn-solid/primary">
      Create project
    </button>
  </body>
</html>
scheme-light

Always resolves adaptive tokens to the light color ramp.

scheme-dark

Always resolves adaptive tokens to the dark color ramp.

scheme-light-dark

Lets the browser resolve light-dark tokens from the user's color scheme.

Next steps

Palette

See how each role becomes a full shade ramp — and define your own palettes.

Components

See adaptive theme tokens applied through component modifiers.

On this page