Natcore LogoNatCorev2 — In Progress
v2 — In Progress

Core Tokens

The shared color roles, shade scale, and naming rules behind Natcore components and utilities.

Token model

Natcore tokens start with semantic palette roles, then expand into adaptive shade scales that work across light and dark themes.
01Role

Choose a palette by intent: primary, surface, danger, success, and the rest of the core roles.

02Shade

Use the shade scale for hierarchy: lower numbers are softer, higher numbers carry stronger contrast.

03Tone

Pair background and foreground tokens so text follows the active palette and theme.

Palette roles

These roles are the stable API. Themes can change the color values while markup keeps the same intent.
primary

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

bg-primary-500text-on-primary-500palette-primary
secondary

Supporting actions and secondary moments that still need color.

bg-secondary-500text-on-secondary-500palette-secondary
accent

Highlights, emphasis, and moments that should stand apart.

bg-accent-500text-on-accent-500palette-accent
surface

Page backgrounds, containers, borders, and neutral text.

bg-surface-500text-on-surface-500palette-surface
success

Positive outcomes, confirmations, and valid states.

bg-success-500text-on-success-500palette-success
danger

Destructive actions, errors, and blocking states.

bg-danger-500text-on-danger-500palette-danger
disabled

Unavailable controls, subdued text, and inactive surfaces.

bg-disabled-500text-on-disabled-500palette-disabled

Shade scale

Each palette exposes the same shade steps, which keeps component variants predictable across roles.
primary
50
100
200
300
400
500
600
700
800
900
950
surface
50
100
200
300
400
500
600
700
800
900
950
danger
50
100
200
300
400
500
600
700
800
900
950

Using tokens

Use component modifiers when you can, and utility classes when you need to compose custom structure.
Codehtml
<button class="btn-solid/primary btn-size-md">
  Save changes
</button>

<div class="card card-soft/surface">
  <p class="text-surface-950/70">
    Tokens stay readable in markup.
  </p>
</div>
Read from intent

A class like btn-solid/primary says what the element is doing. Theme values can move underneath it without changing the markup.

Theme anchors

Any palette role can define 50, 500, and 950 anchors. If only a role color is provided, Natcore treats it as the 500 anchor and derives 50 and 950.
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;
}
50

Soft surface and low-emphasis fills.

500

The theme's central role color.

950

Strong contrast for text and deep surfaces.

Next steps

Theming

See how token anchors resolve across light and dark schemes.

Installation

Import the stylesheet and make the token classes available to your app.

Components

See how component classes consume palette and tone tokens.

On this page