Clerk

# Clerk Design System

## Overview
Clerk uses a modern, clean design system with both light and dark themes. The system emphasizes clarity, accessibility, and developer-focused aesthetics.

---

## Tokens — Colors

| Token | Light Mode | Dark Mode | Usage |
|-------|------------|-----------|-------|
| **Brand** |
| `primary` | `#6C47FF` | `#7C3AED` | Primary CTA buttons, accents, links |
| `primary-hover` | `#5B38E6` | `#6D28D9` | Hover state for primary actions |
| **Background** |
| `bg-base` | `#FFFFFF` | `#0A0A0A` | Main background |
| `bg-subtle` | `#FAFAFA` | `#0F0F0F` | Alternate background |
| `bg-muted` | `#F5F5F5` | `#18181B` | Disabled, muted areas |
| `bg-card` | `#FFFFFF` | `#1E293B` | Card backgrounds |
| `bg-announcement` | `#000000` | `#000000` | Top announcement bar |
| **Text** |
| `text-primary` | `#0A0A0A` | `#FFFFFF` | Primary text, headings |
| `text-secondary` | `#6B7280` | `#9CA3AF` | Secondary text, descriptions |
| `text-tertiary` | `#9CA3AF` | `#6B7280` | Tertiary text, captions |
| `text-inverse` | `#FFFFFF` | `#000000` | Text on dark/light backgrounds |
| **Border** |
| `border-subtle` | `#E5E7EB` | `#27272A` | Subtle borders, dividers |
| `border-default` | `#D1D5DB` | `#3F3F46` | Default borders |
| `border-strong` | `#9CA3AF` | `#52525B` | Strong borders, focus rings |
| **Interactive** |
| `button-primary-bg` | `#6C47FF` | `#7C3AED` | Primary button background |
| `button-secondary-bg` | `#F9FAFB` | `#374151` | Secondary button background |
| `button-secondary-border` | `#D1D5DB` | `#4B5563` | Secondary button border |
| `link` | `#3B82F6` | `#60A5FA` | Hyperlinks |
| `link-hover` | `#2563EB` | `#3B82F6` | Link hover state |

---

## Tokens — Typography

### Font Families
- **Sans**: `Inter, -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif`
- **Mono**: `"JetBrains Mono", "Fira Code", Consolas, monospace`

### Type Scale

| Token | Size | Line Height | Weight | Usage |
|-------|------|-------------|--------|-------|
| `display-xl` | 96px / 6rem | 1.1 | 900 | Hero headlines |
| `display-lg` | 72px / 4.5rem | 1.1 | 800 | Large hero text |
| `heading-1` | 56px / 3.5rem | 1.2 | 700 | Page titles |
| `heading-2` | 40px / 2.5rem | 1.3 | 700 | Section headings |
| `heading-3` | 28px / 1.75rem | 1.4 | 600 | Subsection headings |
| `heading-4` | 24px / 1.5rem | 1.4 | 600 | Card titles |
| `body-lg` | 18px / 1.125rem | 1.6 | 400 | Large body text |
| `body` | 16px / 1rem | 1.6 | 400 | Default body text |
| `body-sm` | 14px / 0.875rem | 1.5 | 400 | Small text, captions |
| `caption` | 12px / 0.75rem | 1.4 | 400 | Fine print |

---

## Tokens — Spacing

| Token | Value | Usage |
|-------|-------|-------|
| `space-1` | 4px / 0.25rem | Tight spacing |
| `space-2` | 8px / 0.5rem | Compact spacing |
| `space-3` | 12px / 0.75rem | Small spacing |
| `space-4` | 16px / 1rem | Default spacing |
| `space-5` | 20px / 1.25rem | Medium spacing |
| `space-6` | 24px / 1.5rem | Comfortable spacing |
| `space-8` | 32px / 2rem | Large spacing |
| `space-10` | 40px / 2.5rem | Extra large spacing |
| `space-12` | 48px / 3rem | Section spacing |
| `space-16` | 64px / 4rem | Major section spacing |
| `space-20` | 80px / 5rem | Hero spacing |

---

## Tokens — Border Radius

| Token | Value | Usage |
|-------|-------|-------|
| `radius-sm` | 6px | Buttons, inputs, tags |
| `radius-md` | 8px | Small cards, dropdowns |
| `radius-lg` | 12px | Cards, modals |
| `radius-xl` | 16px | Large cards, containers |
| `radius-full` | 9999px | Pills, avatars |

---

## Tokens — Shadows

| Token | Value | Usage |
|-------|-------|-------|
| `shadow-xs` | `0 1px 2px rgba(0,0,0,0.05)` | Subtle elevation |
| `shadow-sm` | `0 1px 3px rgba(0,0,0,0.1)` | Small cards |
| `shadow-md` | `0 4px 6px rgba(0,0,0,0.1)` | Cards, dropdowns |
| `shadow-lg` | `0 10px 15px rgba(0,0,0,0.1)` | Modals, popovers |
| `shadow-xl` | `0 20px 25px rgba(0,0,0,0.15)` | Large modals |

---

## Tokens — Borders

| Token | Value | Usage |
|-------|-------|-------|
| `border-width-1` | 1px | Default borders |
| `border-width-2` | 2px | Emphasized borders, focus rings |
| `border-width-4` | 4px | Strong emphasis |

---

## Components

### Button
- **Primary**: Purple background (`#6C47FF`), white text, 6px radius, 12px 24px padding
- **Secondary**: Light gray background or outlined with border, dark text
- **Sizes**: Small (10px 20px), Medium (12px 24px), Large (14px 28px)
- **States**: Hover (darker shade), Active (pressed), Disabled (opacity 50%)

### Card
- **Background**: White (light mode), `#1E293B` (dark mode)
- **Border**: 1px `#E5E7EB` (light), `#27272A` (dark)
- **Radius**: 12px
- **Padding**: 24-32px
- **Shadow**: `shadow-sm` on hover

### Navigation
- **Height**: ~64px
- **Background**: White (light), `#0A0A0A` (dark)
- **Sticky**: Yes
- **Items**: Horizontal flex, 16px gap
- **Dropdowns**: With chevron icons

### Pricing Card
- **Layout**: Grid (4 columns on desktop)
- **Background**: Dark card (`#1E293B`)
- **Border**: Subtle
- **Padding**: 32px
- **Features**: Checkmark list, 8px gap between items

### Input
- **Height**: 40px
- **Padding**: 12px 16px
- **Border**: 1px `#D1D5DB`
- **Radius**: 6px
- **Focus**: 2px ring, primary color

### Icon Card
- **Size**: Variable (docs page ~200px width)
- **Icon**: Outlined style, 48px size
- **Padding**: 24px
- **Hover**: Subtle shadow lift

---

## Layout Patterns

### Hero Section
- **Container**: Max-width 1280px, centered
- **Padding**: 80-120px vertical
- **Heading**: `display-lg`, centered
- **Subheading**: `body-lg`, centered, max-width 600px
- **CTA Group**: Flex row, 16px gap, centered

### Pricing Grid
- **Grid**: 4 columns (desktop), 1 column (mobile)
- **Gap**: 24px
- **Container**: Max-width 1280px

### Documentation Layout
- **Sidebar**: 280px fixed width, light background
- **Main**: Flex-grow, max-width 900px
- **Spacing**: 32px between sections

### Card Grid
- **Grid**: 2-4 columns responsive
- **Gap**: 24px
- **Card Padding**: 24-32px

---

## Accessibility

- **Focus States**: 2px ring with primary color
- **Color Contrast**: WCAG AA compliant
- **Interactive Targets**: Minimum 44px touch targets
- **Keyboard Navigation**: Full support