Design System Overview

Velocity uses a three-tier token system built on OKLCH colors for perceptually uniform color transitions.

Token Architecture

Primitives

Raw values (grayscale, brand, status color scales) in src/styles/tokens/primitives.css.

Semantic Tokens

Intent-based tokens (background, foreground, border) defined per-theme in src/styles/themes/.

Themes

Swap themes by changing one import in colors.css. Ships with default and midnight.

Quick Reference

Background & Text

Class	Purpose
bg-background	Primary background
bg-background-secondary	Secondary background
text-foreground	Primary text
text-foreground-muted	Muted/subtle text

Buttons

Class	Purpose
bg-primary	Primary button background
text-primary-foreground	Primary button text
bg-secondary	Secondary button background

Borders

Class	Purpose
border-border	Standard border
border-border-strong	Emphasized border

Inverted Sections

Class	Purpose
bg-surface-invert	Dark section background
text-on-invert	Text on dark sections

OKLCH Color Format

Velocity uses OKLCH for perceptually uniform colors:

oklch(62.5% 0.22 38)
       ↑     ↑   ↑
       L     C   H

• L — Lightness (0-100%)
• C — Chroma (0-0.4, higher = more saturated)
• H — Hue (0-360, color wheel degrees)

Next Steps

• Colors — Color token reference
• Tailwind Utilities — Available utility classes
• Dark Mode — Dark mode implementation