Semantic Tokens

Semantic tokens are purpose-based design tokens that reference primitive colors. They describe where a color is used, not what it is.

Dark mode is supported as of v0.4.1: semantic tokens remap automatically when dark mode is active (see Dark mode below).

Why Semantic Tokens?

Layer	Example	Purpose
Primitive	`--color-primary-500`	The raw color value
Semantic	`--background-primary`	Where that color is used

This separation enables:

Theming — Change --background-page in dark mode without touching primitives
Consistency — Components use purpose-based tokens, not arbitrary colors
Maintainability — Update one semantic token, all usages update

Token Categories

Backgrounds

Token	Light value	Dark value	Purpose
--background-default	white	neutral-900	Primary content area
--background-page	neutral-50	#0f0e0d	Page background
--background-muted	neutral-100	neutral-700	Muted surfaces
--background-subtle	neutral-200	neutral-500	Subtle surfaces
--background-elevated	white	neutral-700	Modals, dropdowns
--background-overlay	rgba(28,25,23,0.5)	rgba(0,0,0,0.7)	Backdrop behind modals
--background-primary	primary-500	primary-500	Primary actions
--background-primary-subtle	primary-100	color-mix primary	Subtle primary tint
--background-success	green-50	color-mix green	Success states
--background-warning	amber-50	color-mix amber	Warning states
--background-error	red-50	color-mix red	Error states
--background-info	blue-50	color-mix blue	Info states
--background-nav	primary-100	neutral-700	Sidebar/nav background
--background-nav-hover	primary-200	neutral-500	Nav item hover
--background-nav-active	primary-500	primary-500	Nav item active

Foregrounds

Token	Light value	Dark value	Purpose
--foreground-default	neutral-900	neutral-100	Primary text
--foreground-muted	neutral-500	neutral-400	Secondary text
--foreground-subtle	neutral-400	neutral-500	Tertiary text
--foreground-primary	primary-700	primary-200	Primary accent text
--foreground-success	green-700	green-200	Success text
--foreground-warning	amber-700	amber-200	Warning text
--foreground-error	red-700	red-200	Error text
--foreground-info	blue-700	blue-200	Info text
--foreground-on-primary	white	white	Text on primary backgrounds
--foreground-nav	neutral-700	neutral-300	Nav item text
--foreground-nav-hover	neutral-900	neutral-100	Nav item hover text
--foreground-nav-active	white	white	Nav item active text

Borders

Token	Light value	Dark value	Purpose
--border-default	neutral-200	neutral-500	Default borders
--border-muted	neutral-100	neutral-600	Subtle borders
--border-strong	neutral-300	neutral-400	Emphasized borders
--border-primary	primary-500	primary-500	Primary accent borders
--border-error	error	error	Error state borders
--border-success	green-200	color-mix green	Success state borders
--border-warning	amber-200	color-mix amber	Warning state borders
--border-info	blue-200	color-mix blue	Info state borders
--border-error-subtle	red-200	color-mix red	Subtle error borders

Dark mode

In dark mode, semantic tokens resolve to different primitives (or color-mix tints) while primitive tokens stay the same. --background-default might map to white in light mode and neutral-900 in dark mode; components that use semantic variables pick up the correct surfaces and text without code changes.

Dark mode is activated when:

The prefers-color-scheme: dark media query matches and the root is not forced to light, or
The .dark class is on <html> (this overrides the system preference), or
.light on <html> forces light mode even when the system prefers dark.

For a manual toggle and localStorage pattern, see Q4.3 in the Integration Guide.

Use the semanticDark export from @akanaka-design/tokens when you need resolved dark hex values in TypeScript.

Swatches

Click any card to copy the CSS variable name—the same interactive previews as on the Tokens page.

Backgrounds

Foregrounds

Borders

Usage

CSS Variables

.sidebar {
  background: var(--background-nav);
  border-right: 1px solid var(--border-default);
}

.sidebar-link {
  color: var(--foreground-nav);
}

.sidebar-link:hover {
  background: var(--background-nav-hover);
  color: var(--foreground-nav-hover);
}

.sidebar-link.active {
  background: var(--background-nav-active);
  color: var(--foreground-nav-active);
}

Tailwind Utilities

Semantic tokens are available as Tailwind utilities:

<aside className="bg-background-nav border-r border-border">
  <a className="text-foreground-nav hover:bg-background-nav-hover hover:text-foreground-nav-hover">
    Dashboard
  </a>
</aside>

TypeScript

import { semantic, cssVars } from "@akanaka-design/tokens";

// Raw hex values
const navBg = semantic.background.nav; // "#FADDD5"

// CSS variable references
const navBgVar = cssVars.semantic.background.nav; // "var(--background-nav)"

For dark mode hex values, import semanticDark alongside semantic.