design-tokens

name: design-tokens description: Apply Astra's design tokens system for consistent visual design. Use when building components, pages, or any UI that needs consistent colors, spacing, typography, or shadows. Based on src/theme/tokens/ implementation with tokens from design.md — includes colors, spacing, typography, and shadows following Precision, Clarity, Restraint principles. license: Complete terms in LICENSE.txt

Design Tokens

Apply Astra's design tokens system for consistent visual design. Based on src/theme/tokens/ implementation.

Design Philosophy

Color Tokens

Brand Colors (from src/theme/tokens/colors.ts)

primary: '#5A60F5'       // Soft indigo — main accent
primaryHover: '#5255DF'  // Interactive state
secondary: '#8a8f98'   // Neutral, icons

Background — Light Mode

background.light: '#F5F5F7'  // Page — NOT pure white
paperLight: '#FFFFFF'          // Cards, elevated

Background — Dark Mode

background.dark: '#0e1015'  // Page — NOT pure black
paperDark: '#16181D'        // Cards
panelDark: '#1E2028'        // Highest elevation

Text — Light Mode

text.primary: '#111318'    // Headings, body
text.secondary: '#687076'  // Captions, metadata

Text — Dark Mode

text.primary: '#EDEDEF'    // Headings, body
text.secondary: '#8A8F98' // Captions, metadata

Status Colors

error: '#ED5F74'
warning: '#F5A623'
success: '#34C759'
info: '#5A60F5'
crisis: '#F85149'  // Critical alerts

Borders

border.light: 'rgba(0, 0, 0, 0.08)'
border.dark: 'rgba(255, 255, 255, 0.08)'

Spacing Tokens

Base unit: 4px (from src/theme/tokens/spacing.ts)

Typography Tokens

Font Stack

sans: '"Inter", "Segoe UI", "Helvetica Neue", sans-serif'
mono: '"IBM Plex Mono", "Menlo", "Courier New", monospace'

Type Scale (from src/theme/tokens/typography.ts)

Custom Variants

monoBody:     // Monospace body
monoCaption: // Monospace small
body2Medium: // Medium weight body
body2Bold:   // Bold body
captionBold: // Bold caption
splashTitle: // Wide tracking uppercase
splashSubtitle: // Extended caption

Shadow Tokens

shadow-xs:   0 1px 2px rgba(0,0,0,0.05)
shadow-sm:   0 1px 3px rgba(0,0,0,0.10), 0 1px 2px rgba(0,0,0,0.06)
shadow-md:   0 4px 6px rgba(0,0,0,0.07), 0 2px 4px rgba(0,0,0,0.06)
shadow-lg:   0 10px 15px rgba(0,0,0,0.10), 0 4px 6px rgba(0,0,0,0.05)
shadow-xl:   0 20px 25px rgba(0,0,0,0.10), 0 8px 10px rgba(0,0,0,0.04)

Border Radius

radius-sm:   4px
radius-md:   8px
radius-lg:   12px
radius-xl:   16px
radius-2xl: 24px
radius-full: 9999px

Z-Index Scale

z-base:    0
z-raised:  10
z-dropdown: 200
z-sticky:  300
z-overlay: 400
z-modal:   500
z-toast:   600
z-tooltip: 700

Interaction States

Hover

/* Light mode */
:hover {
  filter: brightness(0.95);
}

/* Dark mode */
[data-theme="dark"] :hover {
  filter: brightness(1.1);
}

Active

:active {
  transform: scale(0.98);
  transition: transform 100ms ease-out;
}

Disabled

:disabled,
[disabled] {
  opacity: 0.5;
  cursor: not-allowed;
  pointer-events: none;
}

Surface & Elevation

Critical: Dark mode uses backgroundImage: 'none' on Paper to avoid MUI elevation overlay.

Using Tokens in Code

CSS Variables

:root {
  /* Colors */
  --color-primary: #5A60F5;
  --color-primary-hover: #5255DF;
  --color-secondary: #8a8f98;
  
  /* Background — Light */
  --color-bg: #F5F5F7;
  --color-paper: #FFFFFF;
  
  /* Background — Dark */
  --color-bg-dark: #0e1015;
  --color-paper-dark: #16181D;
  
  /* Text */
  --color-text: #111318;
  --color-text-muted: #687076;
  
  /* Spacing */
  --space-xs: 8px;
  --space-sm: 12px;
  --space-md: 16px;
  --space-lg: 24px;
  --space-xl: 32px;
  
  /* Typography */
  --font-sans: "Inter", "Segoe UI", sans-serif;
  --font-mono: "IBM Plex Mono", monospace;
  
  /* Shadows */
  --shadow-sm: 0 1px 3px rgba(0,0,0,0.10);
  --shadow-md: 0 4px 6px rgba(0,0,0,0.07);
  --shadow-lg: 0 10px 15px rgba(0,0,0,0.10);
  
  /* Radius */
  --radius-sm: 4px;
  --radius-md: 8px;
  --radius-lg: 12px;
}

/* Dark mode */
[data-theme="dark"] {
  --color-bg: #0e1015;
  --color-paper: #16181D;
  --color-text: #EDEDEF;
  --color-text-muted: #8A8F98;
}

React/MUI Usage

import { colors } from './theme/tokens/colors';
import { spacing } from './theme/tokens/spacing';
import { typography } from './theme/tokens/typography';

function Component() {
  return (
    <Box
      sx={{
        color: 'text.primary',
        px: spacing.md,      // 16px
        py: spacing.lg,    // 24px
        borderRadius: '8px', // radius.md
        boxShadow: 'sm',
      }}
    >
      <Typography variant="body1">
        Content
      </Typography>
    </Box>
  );
}

Golden Rules

Light Mode

• Avoid pure white (#FFFFFF) as dominant surface
• Use 3-5 neutral steps
• Prefer space over borders
• Text: near-black (#111318), not absolute black

Dark Mode

• Avoid pure black (#000000)
• Use layered dark grays (4-5 tiers)
• Keep accent saturation controlled
• Ensure text contrast tiers

Token Usage Checklist

• Colors from token system (not hardcoded)
• Spacing from 4px base unit scale
• Typography from defined variants
• Shadows subtle, not heavy
• Radius consistent with scale
• Z-index from scale
• Surfaces match light/dark tokens

For complete reference, see: design.md, src/theme/tokens/colors.ts, src/theme/tokens/spacing.ts, src/theme/tokens/typography.ts