Usage Guidelines

Do This

✓Use semantic tokens: text-foreground
✓Let tokens handle theme switching automatically
✓Follow color hierarchy (foreground → neutral-strong → neutral)
✓Use accent colors for interactive elements

Do not Do This

✗Avoid hard-coded colors: #000000
✗Never use inline CSS variables in components
✗Do not mix semantic tokens with arbitrary colors
✗Avoid using surface colors for text

Text Colors

Semantic text color tokens for content hierarchy

Foreground

Primary text color - highest contrast

CSS Variable: --text-primary-color

Common Uses:

HeadingsBody textImportant content

Neutral Strong

Secondary text with good contrast

CSS Variable: --text-secondary-color

Common Uses:

DescriptionsLabelsSupporting text

Neutral

Tertiary text with moderate contrast

CSS Variable: --text-tertiary-color

Common Uses:

CaptionsMetadataPlaceholders

Disabled

Disabled or inactive text

CSS Variable: --text-disabled-color

Common Uses:

Disabled inputsInactive states

Surface Colors

Background colors for elevation and layering

Background

Root background - deepest level

CSS Variable: --background-color

Common Uses:

Page backgroundApp canvas

Surface Sunken

Recessed surfaces below base level

CSS Variable: --surface-sunken-color

Common Uses:

Inset panelsDepressed areas

Surface 1

Base surface level - primary containers

CSS Variable: --surface-1-color

Common Uses:

CardsPanelsDialogs

Surface 2

Raised surface - second elevation

CSS Variable: --surface-2-color

Common Uses:

Nested cardsHover statesDropdowns

Surface 3

Highest surface elevation

CSS Variable: --surface-3-color

Common Uses:

TooltipsPopoversTop-level modals

Border Colors

Border and divider tokens

Border

Default border color

CSS Variable: --border-color

Common Uses:

DividersCard bordersInput borders

Border Muted

Subtle border with lower contrast

CSS Variable: --border-muted-color

Common Uses:

Subtle dividersSection separators

Accent Colors

Brand colors for interactive elements

Accent

Primary brand color

CSS Variable: --accent-color

Common Uses:

Primary buttonsLinksActive states

Accent Hover

Accent color hover state

CSS Variable: --accent-hover-color

Common Uses:

Button hoversInteractive element states

Status Colors

Semantic colors for state communication

Success

Success state indicator

CSS Variable: --success-color

Common Uses:

Success messagesCompleted states

Warning

Warning state indicator

CSS Variable: --warning-color

Common Uses:

WarningsCaution messages

Error

Error state indicator

CSS Variable: --error-color

Common Uses:

Error messagesValidation errors

Code Example

Here is how to properly use semantic tokens in your components:

// ✓ Correct - Using semantic tokens
<div className="bg-surface-1 border rounded-xl p-6">
  <h2 className="text-foreground font-semibold mb-2">
    Card Title
  </h2>
  <p className="text-neutral-strong">
    Card description with secondary text
  </p>
  <button className="bg-accent hover:bg-accent-hover text-white px-4 py-2 rounded-lg">
    Primary Action
  </button>
</div>

// ✗ Incorrect - Hard-coded colors
<div style={{ backgroundColor: '#1a1a1a' }}>
  <h2 style={{ color: '#ffffff' }}>Card Title</h2>
  <p style={{ color: '#999999' }}>Card description</p>
</div>

// ✗ Incorrect - Inline CSS variables
<div style={{ backgroundColor: 'var(--surface-1-color)' }}>
  <h2 style={{ color: 'var(--text-primary-color)' }}>Card Title</h2>
</div>

Need Help Migrating?

Check out our comprehensive token migration guide with complete before/after examples and common patterns.

View Migration Guide →