Core Tokens

Tokens are the CSS custom properties Natcore provides. Components and utilities read them, themes set their values, and palettes expand them into full shade ramps.

Anatomy of a token

Every color token is addressed by three facets. Together they name an exact, theme-aware color.

01Role

The semantic slot a token belongs to: primary, surface, danger, success, and the rest of the theme's roles.

02Shade

A step on the 50-950 scale. Lower numbers are softer, higher numbers carry stronger contrast.

03Tone

Each base token (--color-{role}-{shade}) is paired with a readable foreground token (--color-on-{role}-{shade}).

Color token families

These are the CSS variables Natcore exposes. Reference them directly, or reach them through utilities and component classes (see Palette).

--color-{role}-{shade}

The adaptive base color for a role and shade. Resolves to the light or dark value for the active scheme via light-dark().

--color-on-{role}-{shade}

A readable foreground paired with the matching base token, generated for contrast against it.

--color-{shade}

A current-tone alias that resolves to whatever palette is active on the element, so the same markup re-tones with the palette.

--color-on-{shade}

The current-tone foreground alias, pairing with --color-{shade} against the active palette.

--color-light-{role}-{shade}

The explicit light-scheme side of a base token, useful when you need to pin the light value regardless of scheme.

--color-dark-{role}-{shade}

The explicit dark-scheme side of a base token, the counterpart to the light family.

Codecss

/* Adaptive base + readable foreground, per role and shade */
--color-primary-500;        /* light-dark() base color */
--color-on-primary-500;     /* contrast foreground for that base */

/* The current-tone aliases resolve to the active palette */
--color-500;                /* = --color-{active}-500 */
--color-on-500;             /* = --color-on-{active}-500 */

/* Explicit scheme sides, when you need to pin light or dark */
--color-light-primary-500;
--color-dark-primary-500;

Theme override tokens

A theme sets a role's color by writing --theme-{role} (or --theme-{role}-{shade} to pin a specific anchor). Natcore reads these seeds to derive every other token above. This is the only part of the token system you usually write by hand — the rest is generated.

Codecss

:root[data-theme="citrine-reef"] {
  /* Seed a role with one color… */
  --theme-primary: #087f8c;

  /* …or pin any shade 50-950 */
  --theme-surface-50: #f4fbf7;
  --theme-surface-500: #678f82;
  --theme-surface-950: #071c18;
}

Next steps

Theming

Choose the role colors and schemes that give these tokens their values.

Palette

See how a single color becomes a full ramp, and the classes you type to use these tokens.

Components

See how component classes consume these tokens.