Design Tokens are the smallest building blocks of a design system, encoding design decisions (colors, typography, spacing, etc.) as cross-platform variables.
Token Hierarchy
Core Tokens → Base color scales, font definitions
↓
Semantic Tokens → Brand colors, text colors, backgrounds, state colors
↓
Component Tokens → Button backgrounds, input borders, etc.
Naming Convention
All tokens use the --ds- prefix and follow kebab-case:
--ds-{category}-{group}-{variant}-{state}
| Level | Example | Description |
|---|---|---|
| Core color | --ds-color-core-accent1-50 | Accent1 color scale step 50 |
| Semantic color | --ds-color-brand-accent1-default | Brand primary color default state |
| Text color | --ds-color-text-primary | Primary text color |
| Background | --ds-color-background-primary | Primary background |
| State color | --ds-color-state-hover | Generic hover state |
| Spacing | --ds-spacing-comp-md | Component-level medium spacing |
| Radius | --ds-radius-md | Medium border radius |
| Typography | --ds-font-size-title-lg | Large title font size |
Multi-Brand Support
The system supports two brands: ELFBAR and LOSTMARY. The Accent 1/2/3 core color scales differ per brand, while all other tokens (Neutral, functional colors, spacing, etc.) remain consistent.
| Token | ELFBAR | LOSTMARY |
|---|---|---|
--ds-color-core-accent1-50 | Pink tones | Purple tones |
--ds-color-core-accent2-50 | Brand secondary | Brand secondary |
--ds-color-core-neutral-* | Same | Same |
Theme Support
Each brand provides both Light and Dark themes, plus a Desktop responsive override:
| File | Purpose |
|---|---|
light.css | Light mode semantic tokens |
dark.css | Dark mode semantic tokens |
desktop.css | Desktop override (≥1024px) |
Usage
In CSS
.button {
background: var(--ds-color-brand-accent1-default);
color: var(--ds-color-text-white-primary);
padding: var(--ds-spacing-comp-md);
border-radius: var(--ds-radius-full);
font-size: var(--ds-font-size-body-md);
}
Token Build Pipeline
Figma Variables → tokens.json → Style Dictionary → CSS Variables
↓
light.css / dark.css / desktop.css
↓
elfbar/ + lostmary/ dual output
Toolchain: Style Dictionary 4.3, configuration at packages/tokens/sd.config.js.