Colour

01Overview

Colour in Nuton has two tiers. Semantic tokens name a job (secondary text, a soft border, an error fill); the palette holds the raw steps they point to. Components and product code use semantic tokens only (D3), so a change of value, or a future dark theme, happens in one place.

Swatches render the live CSS variables. The State row shows each family's Base step; every family also has Dark, Light and Lighter.

Roles on a real surface

<ul className="lesson-list"> {/* bg-white, stroke-soft-200 border */}
  <li>
    <div>
      <span style={{ color: 'var(--nu-text-strong-950)' }}>Photosynthesis basics</span>
      <span style={{ color: 'var(--nu-text-sub-600)' }}>Biology 101 · 12 min</span>
    </div>
    <span style={{ background: 'var(--nu-state-success-lighter)', color: 'var(--nu-state-success-dark)' }}>
      Completed
    </span>
  </li>
  <li>
    …
    <Button size="sm">Continue</Button> {/* action-primary-bg / -fg */}
  </li>
</ul>

Dark mode

Nuton has three themes: Light, Dark and System (follows the device). Pick one by setting data-theme on <html>, or on any element to theme just that part. With no attribute you get Light. The Theme toggle sets it for the whole page and remembers the choice.

<html data-theme="system">   <!-- follows the device -->
<html data-theme="dark">
<section data-theme="dark">  <!-- one always-dark area -->

The dark values are code-only (D8, C69): Figma has one colour mode, so each palette ramp is reversed (Gray-50 swaps with Gray-950, and so on for every hue) and the semantic tokens keep pointing at the same palette names. Components need no dark rules. Shadows get stronger, and translucent black and white tints swap. Every required text and non-text pair is re-checked in dark by npm run tokens:check. Dark needs design approval, and a Dark mode on the Mapped collection (FC-38), before Stable.

Raw colours (hex, or palette steps used for fixed looks) do not change with the theme. For something that must stay dark, put data-theme="dark" on it and use ordinary semantic tokens inside.

02Tokens

Every table is generated from @nuton/tokens. Value shows the alias the token points to and the resolved colour; Source shows where it's authored. Figma names are kept verbatim, numeric suffix included: Text/Sub-600 becomes --nu-text-sub-600 (D3).

Background

Text

Stroke

Icon

Action

State

10 families (faded, primary, purple, success, error, warning, pending, feature, teal, verified), each with four steps. In @nuton/ui today, Lighter is a tinted background, Light is its hover, and Base is the solid colour for fills, icons, dots and labels. No component uses Dark yet; it reads as text on Lighter (Success Dark on Success Lighter is 6.53:1).

Overlay

Illustration

Global palette

03Usage

Load tokens.css once, then reference CSS variables directly or through the Tailwind theme. Tailwind exposes semantic colours only, named after the Figma path, so the role appears twice: bg-bg-white, text-text-sub-600.

@import '@nuton/tokens/tokens.css';

.lesson-row {
  background: var(--nu-bg-white);
  border: 1px solid var(--nu-stroke-soft-200);
  color: var(--nu-text-strong-950);
}
.lesson-row:hover { background: var(--nu-bg-weak-50); }
.lesson-row__meta { color: var(--nu-text-sub-600); }
.lesson-row__status {
  background: var(--nu-state-success-lighter);
  color: var(--nu-state-success-dark);
}

/* app.css */
@import 'tailwindcss';
@import '@nuton/tokens/tokens.css';
@import '@nuton/tokens/tailwind-v4.css';

// LessonRow.tsx
<li className="bg-bg-white hover:bg-bg-weak-50 border border-stroke-soft-200">
  <span className="text-text-strong-950">Photosynthesis basics</span>
  <span className="text-text-sub-600">Biology 101 · 12 min</span>
  <span className="bg-state-success-lighter text-state-success-dark">Completed</span>
</li>

// tailwind.config.js (load @nuton/tokens/tokens.css on the page too)
module.exports = {
  presets: [require('@nuton/tokens/tailwind-v3-preset')],
}

// Same class names as v4. Opacity modifiers work through color-mix:
<div className="bg-state-primary-base/10 text-state-primary-dark">…</div>
<button className="bg-action-primary-bg hover:bg-action-primary-bg-hover text-action-primary-fg">…</button>

Choosing a token

• Pick the role first, then the emphasis. Fills use bg-, text uses text-, borders use stroke-, icons use icon-. Don't borrow across roles because two values match today; dark mode may split them (D8).
• Main action: action-primary-*. Use state-primary-* only where the interactive blue is meant, such as links and selected controls (D13).
• Status: a Lighter background with Dark text, or Base for icons and dots. White text passes on state-primary-base (5.59:1); Success, Pending, Warning, Error, Feature, Verified and Teal Base fail with white text (A2).
• Secondary text: text-sub-600, including placeholders and hints. text-soft-400 is decorative only (D7, C1).
• No raw values. Lint blocks hex colours and arbitrary Tailwind colours in @nuton/ui; the palette is CSS-only.

04In use

Real @nuton/ui components, showing which semantic tokens they read.

Action and state colours on buttons

<Button appearance="stroke">Save draft</Button>   {/* stroke-sub-300, text-strong-950 */}
<Button>Publish lesson</Button>                   {/* action-primary-bg / -fg */}
<Button intent="primary">Join space</Button>      {/* state-primary-base, text-white */}

The neutral filled button is the main action; blue is the state colour (D13). Error buttons and error text use red-700, because Figma's state-error-base is 4.15:1 (C6, resolved 2026-10-14); see the Button page.

Text roles in a form

<Field label="Space name" hint="For example, Biology 101.">  {/* label: text-strong-950, hint: text-sub-600 */}
  <Input placeholder="Biology 101" />                         {/* placeholder: text-sub-600 (D7, C1) */}
</Field>

Figma draws placeholders in Soft-400; code uses Sub-600 so they pass 4.5:1 (D7, C1). The default border is Stroke/Sub-300 (C7). Error and disabled states are on the Inputs and fields page.

State colours as data series

<ul className="legend">
  <li><ChartLegend color="blue">Lessons completed</ChartLegend></li>   {/* state-primary-base */}
  <li><ChartLegend color="orange">Quizzes taken</ChartLegend></li>    {/* state-warning-base */}
  <li><ChartLegend color="teal">Flashcards reviewed</ChartLegend></li> {/* state-teal-base */}
</ul>

Chart colours map to State Base tokens, and every series keeps a text label so colour is never the only cue (WCAG 1.4.1).

05Accessibility

Ratios below are computed at build time from the resolved token values, with the same WCAG formula as npm run tokens:check. Text needs 4.5:1; borders, focus rings and other UI parts need 3:1.

Browser axe on the component pages reports the same failures; it measures the rendered disabled hint at 1.52:1 (docs/quality-strategy.md). Every failing pair is a Figma value implemented as specified, waiting on a design decision.

06Guidelines and related

Do and don't

Related

• TypographyType styles that pair with the text colour roles.
• ElevationShadows that separate surfaces alongside stroke colours.
• Layout and responsiveFocus rings and layering.
• ButtonAction and state colours on every intent.
• Inputs and fieldsText roles, error and disabled colours.
• Chart legendState Base colours as data series.