Design Tokens Reference

Design Tokens Reference

This reference documents all design tokens defined in src/styles/_design-tokens.scss. These tokens provide a consistent design language across the application using CSS custom properties.

Tip

All tokens are defined as CSS custom properties (CSS variables) and can be used in both SCSS and CSS files using var(--token-name).

Color Tokens

Primary Palette

The primary color palette is used for brand colors, primary actions, and interactive elements.

—color-primary-50

#f0f9ff

Lightest shade

—color-primary-100

#e0f2fe

Very light backgrounds

—color-primary-200

#bae6fd

Light backgrounds

—color-primary-300

#7dd3fc

Subtle elements

—color-primary-400

#38bdf8

Hover states

—color-primary-500

#0ea5e9

Base brand color

—color-primary-600

#0284c7

Active states

—color-primary-700

#0369a1

Dark accents

—color-primary-800

#075985

Darker accents

—color-primary-900

#0c4a6e

Darkest shade

Navy Palette

The navy palette provides deeper, more professional tones for headers, navigation, and important content.

—color-navy-50

#eff6ff

Lightest navy

—color-navy-100

#dce6ff

Very light navy

—color-navy-200

#b9ccff

Light navy

—color-navy-300

#7aa3ff

Medium light

—color-navy-400

#4d7acc

Medium navy

—color-navy-500

#2d5aa8

Base navy

—color-navy-600

#003366

Dark navy

—color-navy-700

#002952

Darker navy

—color-navy-800

#001f3d

Very dark navy

—color-navy-900

#00142b

Darkest navy

Neutral Palette

The neutral palette provides grays for text, borders, backgrounds, and subtle UI elements.

—color-neutral-50

#fafafa

Lightest gray

—color-neutral-100

#f4f4f5

Subtle backgrounds

—color-neutral-200

#e4e4e7

Light borders

—color-neutral-300

#d4d4d8

Default borders

—color-neutral-400

#a1a1aa

Disabled text

—color-neutral-500

#71717a

Muted text

—color-neutral-600

#52525b

Secondary text

—color-neutral-700

#3f3f46

Body text

—color-neutral-800

#27272a

Headings

—color-neutral-900

#18181b

Darkest text

Semantic Colors

Semantic colors convey meaning for success, warning, error, and informational states.

—color-success

#22c55e

Success messages

—color-success-light

#dcfce7

Success backgrounds

—color-success-dark

#166534

Dark success

—color-warning

#f59e0b

Warning messages

—color-warning-light

#fef3c7

Warning backgrounds

—color-warning-dark

#92400e

Dark warning

—color-error

#ef4444

Error messages

—color-error-light

#fee2e2

Error backgrounds

—color-error-dark

#991b1b

Dark error

—color-info

#3b82f6

Info messages

—color-info-light

#dbeafe

Info backgrounds

—color-info-dark

#1d4ed8

Dark info

Typography Tokens

Font Families

Sans Serif

--font-family-sans: ui-sans-serif, system-ui, -apple-system,
  BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial,
  "Noto Sans", sans-serif, "Apple Color Emoji", "Segoe UI Emoji",
  "Segoe UI Symbol", "Noto Color Emoji";

Usage: Default for body text and UI elements

Serif

--font-family-serif: ui-serif, Georgia, Cambria, "Times New Roman",
  Times, serif;

Usage: Headings, formal content

Monospace

--font-family-mono: ui-monospace, SFMono-Regular, "SF Mono", Menlo,
  Monaco, Consolas, "Liberation Mono", "Courier New", monospace;

Usage: Code blocks, technical content

Font Sizes

Based on a modular scale for consistent typography hierarchy.

Token	Value	Pixels	Usage
--font-size-xs	0.75rem	12px	Fine print, captions
--font-size-sm	0.875rem	14px	Small text, labels
--font-size-base	1rem	16px	Body text (default)
--font-size-lg	1.125rem	18px	Lead paragraphs
--font-size-xl	1.25rem	20px	Subheadings
--font-size-2xl	1.5rem	24px	H3 headings
--font-size-3xl	1.875rem	30px	H2 headings
--font-size-4xl	2.25rem	36px	H1 headings
--font-size-5xl	3rem	48px	Hero headings
--font-size-6xl	3.75rem	60px	Display headings

Font Weights

Token	Value	Usage
--font-weight-thin	100	Very light text
--font-weight-light	300	Light text
--font-weight-normal	400	Body text (default)
--font-weight-medium	500	Emphasized text
--font-weight-semibold	600	Subheadings
--font-weight-bold	700	Headings, buttons
--font-weight-extrabold	800	Strong emphasis
--font-weight-black	900	Maximum emphasis

Line Heights

Token	Value	Usage
--line-height-none	1	Single line elements
--line-height-tight	1.25	Compact text
--line-height-snug	1.375	Headings
--line-height-normal	1.5	Body text (default)
--line-height-relaxed	1.625	Comfortable reading
--line-height-loose	2	Spaced paragraphs

Spacing Tokens

8pt Grid System

All spacing follows an 8-point grid for consistent rhythm and alignment.

—space-1 (0.25rem)

4px

—space-2 (0.5rem)

8px

—space-3 (0.75rem)

12px

—space-4 (1rem)

16px

—space-6 (1.5rem)

24px

—space-8 (2rem)

32px

—space-12 (3rem)

48px

—space-16 (4rem)

64px

Note

The spacing scale includes fractional values (0.5, 1.5, 2.5, 3.5) and extends up to --space-96 (24rem / 384px) for maximum flexibility.

Complete Spacing Scale

Token	Value	Pixels	Common Usage
--space-0	0	0px	Reset spacing
--space-px	1px	1px	Hairline borders
--space-0-5	0.125rem	2px	Micro spacing
--space-1	0.25rem	4px	Tight spacing
--space-2	0.5rem	8px	Component padding
--space-3	0.75rem	12px	Small gaps
--space-4	1rem	16px	Default spacing
--space-6	1.5rem	24px	Section padding
--space-8	2rem	32px	Card padding
--space-12	3rem	48px	Section margins
--space-16	4rem	64px	Large sections
--space-24	6rem	96px	Page sections

Border Tokens

Border Radius

Token	Value	Pixels	Usage
--radius-none	0	0px	Sharp corners
--radius-sm	0.125rem	2px	Subtle rounding
--radius-base	0.25rem	4px	Default rounding
--radius-md	0.375rem	6px	Medium rounding
--radius-lg	0.5rem	8px	Cards, buttons
--radius-xl	0.75rem	12px	Large cards
--radius-2xl	1rem	16px	Hero elements
--radius-3xl	1.5rem	24px	Decorative
--radius-full	9999px	Full	Pills, circles

Border Widths

Token	Value	Usage
--border-width-0	0	No border
--border-width-1	1px	Default borders
--border-width-2	2px	Emphasized borders
--border-width-4	4px	Strong emphasis
--border-width-8	8px	Decorative

Shadow Tokens

Shadows create depth and hierarchy in the interface.

—shadow-sm

Subtle elevation

—shadow-base

Default cards

—shadow-md

Elevated cards

—shadow-lg

Dropdowns

—shadow-xl

Modals

—shadow-2xl

Hero elements

Z-Index Tokens

Consistent z-index values for proper layering.

Token	Value	Usage
--z-index-hide	-1	Hidden behind
--z-index-auto	auto	Normal flow
--z-index-base	0	Base level
--z-index-docked	10	Docked elements
--z-index-dropdown	1000	Dropdowns
--z-index-sticky	1100	Sticky headers
--z-index-banner	1200	Banners
--z-index-overlay	1300	Overlays
--z-index-modal	1400	Modals
--z-index-popover	1500	Popovers
--z-index-skipLink	1600	Skip links
--z-index-toast	1700	Toast notifications
--z-index-tooltip	1800	Tooltips (highest)

Transition Tokens

Duration

Token	Value	Usage
--transition-duration-75	75ms	Instant feedback
--transition-duration-100	100ms	Quick transitions
--transition-duration-150	150ms	Smooth interactions
--transition-duration-200	200ms	Default duration
--transition-duration-300	300ms	Moderate animations
--transition-duration-500	500ms	Slow animations
--transition-duration-700	700ms	Deliberate motion
--transition-duration-1000	1000ms	Attention-grabbing

Timing Functions

Token	Value	Usage
--transition-timing-linear	linear	Constant speed
--transition-timing-in	cubic-bezier(0.4, 0, 1, 1)	Ease in
--transition-timing-out	cubic-bezier(0, 0, 0.2, 1)	Ease out
--transition-timing-in-out	cubic-bezier(0.4, 0, 0.2, 1)	Ease in-out

Layout Tokens

Max Width Constraints

Token	Value	Pixels	Usage
--max-width-none	none	-	Full width
--max-width-xs	20rem	320px	Narrow forms
--max-width-sm	24rem	384px	Small cards
--max-width-md	28rem	448px	Medium content
--max-width-lg	32rem	512px	Large cards
--max-width-xl	36rem	576px	Form layouts
--max-width-2xl	42rem	672px	Article width
--max-width-3xl	48rem	768px	Blog posts
--max-width-4xl	56rem	896px	Wide content
--max-width-5xl	64rem	1024px	Page content
--max-width-6xl	72rem	1152px	Large layouts
--max-width-7xl	80rem	1280px	Main container

Breakpoints

Token	Value	Usage
--max-width-screen-sm	640px	Small screens
--max-width-screen-md	768px	Medium screens
--max-width-screen-lg	1024px	Large screens
--max-width-screen-xl	1280px	Extra large
--max-width-screen-2xl	1536px	2X large

Dark Mode Support

All color tokens automatically adjust for dark mode using a prefers-color-scheme: dark media query. The color scales are inverted to maintain proper contrast.

Tip

Dark mode tokens are automatically applied when the user’s system preference is set to dark mode. No additional code is required.

Component Token Aliases

Pre-configured token combinations for common components.

Card Tokens

Token	Value	Description
--card-background	var(--color-neutral-50)	Card background
--card-border	var(--color-neutral-200)	Card border
--card-radius	var(--radius-lg)	Card rounding
--card-shadow	var(--shadow-base)	Card elevation
--card-gap	var(--space-4)	Inner spacing
--card-padding	var(--space-6)	Card padding

Button Tokens

Token	Value	Description
--button-radius	var(--radius-base)	Button rounding
--button-padding-x	var(--space-4)	Horizontal padding
--button-padding-y	var(--space-2)	Vertical padding
--button-font-weight	var(--font-weight-medium)	Button text weight

Form Tokens

Token	Value	Description
--input-radius	var(--radius-base)	Input rounding
--input-border	var(--color-neutral-300)	Input border
--input-focus-border	var(--color-primary-500)	Focus state
--input-padding-x	var(--space-3)	Horizontal padding
--input-padding-y	var(--space-2)	Vertical padding

Usage Examples

SCSS

.button {
  background-color: var(--color-primary-500);
  color: white;
  padding: var(--button-padding-y) var(--button-padding-x);
  border-radius: var(--button-radius);
  font-weight: var(--button-font-weight);
  transition-duration: var(--transition-duration-200);
  transition-timing-function: var(--transition-timing-in-out);

  &:hover {
    background-color: var(--color-primary-600);
    box-shadow: var(--shadow-md);
  }
}

CSS

.card {
  background-color: var(--card-background);
  border: 1px solid var(--card-border);
  border-radius: var(--card-radius);
  padding: var(--card-padding);
  box-shadow: var(--card-shadow);
  max-width: var(--max-width-2xl);
}

Astro Component

---
// No imports needed - tokens available globally
---
<div class="hero" style="
  padding: var(--space-16) var(--space-4);
  background: var(--color-primary-50);
">
  <h1 style="
    font-size: var(--font-size-5xl);
    font-weight: var(--font-weight-bold);
    color: var(--color-primary-900);
  ">
    Hero Title
  </h1>
</div>

Related Documentation

• Utility Classes Reference - Pre-built utility classes using these tokens
• Design System Overview - Complete design system guide
• Figma Design Tokens - Figma-extracted design tokens

---

Source File: src/styles/_design-tokens.scss