Skip to main content

Source: ocean/docs/design-tokens.md | ✏️ Edit on GitHub

Design Tokens Reference

This document describes the design tokens available in the Ocean application and how to use them.

Overview​

Design tokens are the visual design atoms of the design system — specifically, they are named entities that store visual design attributes. We use them in place of hard-coded values (such as hex values for color or pixel values for spacing) in order to maintain a scalable and consistent visual system.

Token Categories​

Color Tokens​

Color tokens are managed dynamically by the theme system. The following semantic color tokens are available:

  • --background: Page background color
  • --foreground: Default text color
  • --card: Card background color
  • --card-foreground: Card text color
  • --popover: Popover background color
  • --popover-foreground: Popover text color
  • --primary: Primary brand color
  • --primary-foreground: Text color on primary backgrounds
  • --secondary: Secondary brand color
  • --secondary-foreground: Text color on secondary backgrounds
  • --muted: Muted background color
  • --muted-foreground: Muted text color
  • --accent: Accent color for highlights
  • --accent-foreground: Text color on accent backgrounds
  • --destructive: Error/destructive action color
  • --destructive-foreground: Text color on destructive backgrounds
  • --border: Default border color
  • --input: Form input border color
  • --ring: Focus ring color
  • --chart-1 through --chart-5: Chart color palette

Typography Tokens​

Font Sizes​

  • --font-size-xs: 0.75rem (12px)
  • --font-size-sm: 0.875rem (14px)
  • --font-size-base: 1rem (16px)
  • --font-size-lg: 1.125rem (18px)
  • --font-size-xl: 1.25rem (20px)
  • --font-size-2xl: 1.5rem (24px)
  • --font-size-3xl: 1.875rem (30px)
  • --font-size-4xl: 2.25rem (36px)
  • --font-size-5xl: 3rem (48px)
  • --font-size-6xl: 3.75rem (60px)
  • --font-size-7xl: 4.5rem (72px)
  • --font-size-8xl: 6rem (96px)
  • --font-size-9xl: 8rem (128px)

Line Heights​

  • --line-height-none: 1
  • --line-height-tight: 1.25
  • --line-height-snug: 1.375
  • --line-height-normal: 1.5
  • --line-height-relaxed: 1.625
  • --line-height-loose: 2

Font Weights​

  • --font-weight-thin: 100
  • --font-weight-extralight: 200
  • --font-weight-light: 300
  • --font-weight-normal: 400
  • --font-weight-medium: 500
  • --font-weight-semibold: 600
  • --font-weight-bold: 700
  • --font-weight-extrabold: 800
  • --font-weight-black: 900

Letter Spacing​

  • --letter-spacing-tighter: -0.05em
  • --letter-spacing-tight: -0.025em
  • --letter-spacing-normal: 0
  • --letter-spacing-wide: 0.025em
  • --letter-spacing-wider: 0.05em
  • --letter-spacing-widest: 0.1em

Spacing Tokens​

Spacing tokens follow a consistent scale:

  • --spacing-0: 0
  • --spacing-1: 0.25rem (4px)
  • --spacing-2: 0.5rem (8px)
  • --spacing-3: 0.75rem (12px)
  • --spacing-4: 1rem (16px)
  • --spacing-5: 1.25rem (20px)
  • --spacing-6: 1.5rem (24px)
  • --spacing-8: 2rem (32px)
  • --spacing-10: 2.5rem (40px)
  • --spacing-12: 3rem (48px)
  • --spacing-16: 4rem (64px)
  • --spacing-20: 5rem (80px)
  • --spacing-24: 6rem (96px)
  • And continues up to --spacing-96: 24rem (384px)

Border Radius Tokens​

  • --radius-sm: 0.375rem (6px)
  • --radius-md: 0.625rem (10px)
  • --radius-lg: 0.75rem (12px)
  • --radius-xl: 1rem (16px)
  • --radius-2xl: 1.5rem (24px)
  • --radius-full: 9999px (fully rounded)

Shadow Tokens​

Shadows adjust automatically for dark mode:

  • --shadow-sm: Small shadow
  • --shadow: Default shadow
  • --shadow-md: Medium shadow
  • --shadow-lg: Large shadow
  • --shadow-xl: Extra large shadow
  • --shadow-2xl: 2X large shadow
  • --shadow-inner: Inner shadow
  • --shadow-none: No shadow

Animation Tokens​

Durations​

  • --duration-75: 75ms
  • --duration-100: 100ms
  • --duration-150: 150ms
  • --duration-200: 200ms
  • --duration-300: 300ms
  • --duration-500: 500ms
  • --duration-700: 700ms
  • --duration-1000: 1000ms

Timing Functions​

  • --ease-linear: linear
  • --ease-in: cubic-bezier(0.4, 0, 1, 1)
  • --ease-out: cubic-bezier(0, 0, 0.2, 1)
  • --ease-in-out: cubic-bezier(0.4, 0, 0.2, 1)

Z-Index Scale​

  • --z-index-0: 0
  • --z-index-10: 10
  • --z-index-20: 20
  • --z-index-30: 30
  • --z-index-40: 40
  • --z-index-50: 50
  • --z-index-auto: auto

Usage Examples​

Using with Tailwind CSS​

Since we're using Tailwind CSS v4, you can use these tokens directly in your classes:

// Using spacing tokens
<div className="p-[var(--spacing-4)] m-[var(--spacing-2)]">
  Content
</div>

// Using color tokens (already integrated)
<div className="bg-primary text-primary-foreground">
  Primary button
</div>

// Using shadow tokens
<div style={{ boxShadow: 'var(--shadow-lg)' }}>
  Card with large shadow
</div>

Using in CSS​

.custom-component {
  padding: var(--spacing-4);
  border-radius: var(--radius-md);
  font-size: var(--font-size-lg);
  font-weight: var(--font-weight-semibold);
  line-height: var(--line-height-relaxed);
  transition-duration: var(--duration-200);
  transition-timing-function: var(--ease-out);
}

Using in JavaScript/TypeScript​

const styles = {
  padding: 'var(--spacing-4)',
  fontSize: 'var(--font-size-lg)',
  boxShadow: 'var(--shadow-md)',
  animationDuration: 'var(--duration-300)',
}

Best Practices​

  1. Always use tokens instead of hardcoded values - This ensures consistency and makes updates easier
  2. Use semantic color tokens - Use --primary instead of specific color values
  3. Follow the spacing scale - Use the predefined spacing tokens for consistent layouts
  4. Leverage CSS variables - They update automatically with theme changes
  5. Check dark mode - Shadows automatically adjust for dark mode

Theme Integration​

The color tokens are managed by the theme system and update automatically when users:

  • Switch between light and dark modes
  • Select different color themes (Neutral, Stone, Zinc, Gray, Slate)

All components should use these tokens to ensure they respond correctly to theme changes.