Skip to content
Browse documentation
whisk/ui

Semantic tokens

Use names that describe interface meaning so the same component can adapt across themes and color modes.

Semantic tokens

Semantic tokens describe a role. The same token can resolve to a different primitive value in light and dark mode, so component code stays stable.

Prefer semantic tokens

We recommend using semantic tokens because they automatically adapt to color modes and provide consistent styling across your application.

Surfaces

background

light: var(--smth-colors-neutral-50)

dark: var(--smth-colors-neutral-900)

surface1

light: var(--smth-colors-neutral-100)

dark: var(--smth-colors-neutral-800)

surface2

light: var(--smth-colors-neutral-200)

dark: var(--smth-colors-neutral-700)

surface3

light: var(--smth-colors-neutral-300)

dark: var(--smth-colors-neutral-600)

Accent

accent

light: var(--smth-colors-neutral-800)

dark: var(--smth-colors-neutral-100)

accentSubtle

light: var(--smth-colors-neutral-700)

dark: var(--smth-colors-neutral-200)

accentEmphasized

light: var(--smth-colors-neutral-900)

dark: var(--smth-colors-neutral-50)

accentMuted

light: var(--smth-colors-neutral-300)

dark: var(--smth-colors-neutral-600)

Text

text

light: var(--smth-colors-neutral-900)

dark: var(--smth-colors-neutral-50)

textSubtle

light: var(--smth-colors-neutral-700)

dark: var(--smth-colors-neutral-300)

textDisabled

light: var(--smth-colors-neutral-500)

dark: var(--smth-colors-neutral-500)

textInverse

light: var(--smth-colors-neutral-50)

dark: var(--smth-colors-neutral-900)

Borders

borderSubtle

light: var(--smth-colors-neutral-300)

dark: var(--smth-colors-neutral-700)

border

light: var(--smth-colors-neutral-400)

dark: var(--smth-colors-neutral-600)

borderStrong

light: var(--smth-colors-neutral-500)

dark: var(--smth-colors-neutral-500)

borderFocus

light: var(--smth-colors-accent)

dark: var(--smth-colors-accent)

Success

success

light: var(--smth-colors-green-500)

dark: var(--smth-colors-green-400)

successSubtle

light: var(--smth-colors-green-400)

dark: var(--smth-colors-green-500)

successEmphasized

light: var(--smth-colors-green-600)

dark: var(--smth-colors-green-300)

successMuted

light: var(--smth-colors-green-100)

dark: var(--smth-colors-green-800)

Warning

warning

light: var(--smth-colors-yellow-500)

dark: var(--smth-colors-yellow-400)

warningSubtle

light: var(--smth-colors-yellow-400)

dark: var(--smth-colors-yellow-500)

warningEmphasized

light: var(--smth-colors-yellow-600)

dark: var(--smth-colors-yellow-300)

warningMuted

light: var(--smth-colors-yellow-100)

dark: var(--smth-colors-yellow-800)

Error

error

light: var(--smth-colors-red-600)

dark: var(--smth-colors-red-400)

errorSubtle

light: var(--smth-colors-red-500)

dark: var(--smth-colors-red-500)

errorEmphasized

light: var(--smth-colors-red-700)

dark: var(--smth-colors-red-300)

errorMuted

light: var(--smth-colors-red-100)

dark: var(--smth-colors-red-800)

Info

info

light: var(--smth-colors-blue-500)

dark: var(--smth-colors-blue-400)

infoSubtle

light: var(--smth-colors-blue-400)

dark: var(--smth-colors-blue-500)

infoEmphasized

light: var(--smth-colors-blue-600)

dark: var(--smth-colors-blue-300)

infoMuted

light: var(--smth-colors-blue-100)

dark: var(--smth-colors-blue-800)

Use role names in component code. This keeps the intent readable and lets a theme update the actual values later.

Primary content

Supporting content

<Box background="surface2" border="sm" borderColor="borderSubtle" padding={4}>
  <Text color="text">Primary content</Text>
  <Text color="subtle">Supporting content</Text>
</Box>
Saved

Workspace updated.

<Alert variant="success" title="Saved">
  <Text>Workspace updated.</Text>
</Alert>
PropTypeDefaultDescription
text / textSubtleColorTokenforeground rolesUse for primary and supporting content.
borderSubtle / borderStrongColorTokenboundary rolesUse for quiet and emphasized boundaries.
accent / accentSubtleColorTokenemphasis rolesUse for primary actions and their supporting surfaces.
success / warning / errorColorTokenstatus rolesPair the token with text or an icon so meaning is not color-only.

Light and dark values

The same semantic name can resolve differently in each color mode. The component remains unchanged while the theme keeps contrast and hierarchy appropriate.

Light mode

<Box background="surface2" padding={4}>
  <Text color="text">Light mode</Text>
</Box>

Dark mode

<Box background="surface2" padding={4}>
  <Text color="text">Dark mode</Text>
</Box>