---
version: alpha
name: Clerk
description: Crisp white developer canvas where a Suisse-grotesque sans meets Söhne Mono labels, electric Clerk purple accents the chrome, and the primary CTA stays resolutely black — authentication tooling that looks as pixel-perfect as it promises.

colors:
  # Surface / canvas
  background: "#ffffff"
  surface: "#f8f8f8"           # muted section bands, code-ref chips
  surface-dark: "#131316"      # dark embedded widget surface, primary button

  # Ink / text
  ink: "#131316"               # near-black headings, body, primary button fill
  ink-soft: "#2f3037"          # primary-button hover, dark outline borders
  ink-secondary: "#5e5f6e"     # supporting copy, mono labels
  ink-muted: "#9394a1"         # captions, metadata
  ink-tertiary: "#747686"      # faint helper text
  on-dark: "#ffffff"           # text on dark surfaces and the black CTA

  # Brand accent — the singular Clerk purple
  primary: "#6c47ff"           # eyebrows, links, code refs, accent CTAs
  primary-hover: "#561ee3"     # accent-button hover
  primary-strong: "#6430f7"    # badge text, pressed accent
  primary-soft: "#9785ff"      # decorative purple tints
  primary-container: "#d7d4ff" # badge / pill fills
  on-primary: "#ffffff"

  # Borders
  border: "#eeeef0"            # hairline dividers, card edges
  border-strong: "#d9d9de"     # input + secondary-button outlines

  # Shadow tints (opaque approximations for the elevation table)
  shadow-ambient: "#191c21"    # was rgba(25,28,33,0.2) — Google format requires hex
  shadow-soft: "#000000"       # was rgba(0,0,0,0.08) — Google format requires hex

typography:
  display-hero:
    fontFamily: "Geist, Suisse Intl, -apple-system, BlinkMacSystemFont, system-ui, sans-serif"
    fontSize: 64px
    fontWeight: 700
    lineHeight: 1.13
    letterSpacing: -1.6px
  display:
    fontFamily: "Geist, Suisse Intl, -apple-system, system-ui, sans-serif"
    fontSize: 32px
    fontWeight: 600
    lineHeight: 1.25
    letterSpacing: -0.48px
  heading:
    fontFamily: "Geist, Suisse Intl, -apple-system, system-ui, sans-serif"
    fontSize: 24px
    fontWeight: 700
    lineHeight: 1.33
    letterSpacing: -0.24px
  heading-sub:
    fontFamily: "Geist, Suisse Intl, -apple-system, system-ui, sans-serif"
    fontSize: 22px
    fontWeight: 600
    lineHeight: 1.27
    letterSpacing: -0.2px
  body-large:
    fontFamily: "Geist, Suisse Intl, -apple-system, system-ui, sans-serif"
    fontSize: 18px
    fontWeight: 400
    lineHeight: 1.56
    letterSpacing: 0px
  body:
    fontFamily: "Geist, Suisse Intl, -apple-system, system-ui, sans-serif"
    fontSize: 16px
    fontWeight: 400
    lineHeight: 1.5
    letterSpacing: 0px
  body-small:
    fontFamily: "Geist, Suisse Intl, -apple-system, system-ui, sans-serif"
    fontSize: 15px
    fontWeight: 400
    lineHeight: 1.6
    letterSpacing: 0px
  label:
    fontFamily: "Geist, Suisse Intl, -apple-system, system-ui, sans-serif"
    fontSize: 13px
    fontWeight: 500
    lineHeight: 1.53
    letterSpacing: 0px
  caption:
    fontFamily: "Geist, Suisse Intl, -apple-system, system-ui, sans-serif"
    fontSize: 13px
    fontWeight: 400
    lineHeight: 1.54
    letterSpacing: 0px
  eyebrow-mono:
    fontFamily: "Söhne Mono, ui-monospace, SFMono-Regular, Menlo, monospace"
    fontSize: 12px
    fontWeight: 600
    lineHeight: 2.0
    letterSpacing: 1.2px
  code-mono:
    fontFamily: "Söhne Mono, ui-monospace, SFMono-Regular, Menlo, monospace"
    fontSize: 13px
    fontWeight: 500
    lineHeight: 1.53
    letterSpacing: 0px

spacing:
  xs: 4px
  sm: 8px
  md: 12px
  lg: 16px
  xl: 20px
  2xl: 24px
  3xl: 32px
  4xl: 48px
  5xl: 64px
  6xl: 128px

rounded:
  sm: 4px
  md: 6px
  lg: 8px
  xl: 12px
  2xl: 16px
  pill: 9999px

components:
  button-primary:
    backgroundColor: "{colors.ink}"
    textColor: "{colors.on-dark}"
    typography: "{typography.label}"
    rounded: "{rounded.md}"
    padding: 10px 16px
  button-primary-hover:
    backgroundColor: "{colors.ink-soft}"
    textColor: "{colors.on-dark}"

  button-secondary:
    backgroundColor: "{colors.background}"
    textColor: "{colors.ink}"
    typography: "{typography.label}"
    rounded: "{rounded.md}"
    padding: 10px 16px
  button-secondary-hover:
    backgroundColor: "{colors.surface}"
    textColor: "{colors.ink}"

  button-accent:
    backgroundColor: "{colors.primary}"
    textColor: "{colors.on-primary}"
    typography: "{typography.label}"
    rounded: "{rounded.md}"
    padding: 10px 16px
  button-accent-hover:
    backgroundColor: "{colors.primary-hover}"
    textColor: "{colors.on-primary}"

  card:
    backgroundColor: "{colors.background}"
    textColor: "{colors.ink}"
    rounded: "{rounded.xl}"
    padding: 24px
  card-elevated:
    backgroundColor: "{colors.background}"
    textColor: "{colors.ink}"
    rounded: "{rounded.2xl}"
    padding: 24px

  input:
    backgroundColor: "{colors.background}"
    textColor: "{colors.ink}"
    typography: "{typography.body}"
    rounded: "{rounded.md}"
    padding: 10px 12px
  input-focus:
    backgroundColor: "{colors.background}"
    textColor: "{colors.ink}"

  nav-bar:
    backgroundColor: "{colors.background}"
    textColor: "{colors.ink}"
    typography: "{typography.label}"
    padding: 16px 24px

  link:
    textColor: "{colors.primary}"
    typography: "{typography.body}"
    padding: 0px

  eyebrow:
    textColor: "{colors.primary}"
    typography: "{typography.eyebrow-mono}"
    padding: 0px
  label-mono:
    textColor: "{colors.ink-secondary}"
    typography: "{typography.eyebrow-mono}"
    padding: 0px

  code-ref:
    backgroundColor: "{colors.surface}"
    textColor: "{colors.primary}"
    typography: "{typography.code-mono}"
    rounded: "{rounded.sm}"
    padding: 2px 6px

  badge:
    backgroundColor: "{colors.primary-container}"
    textColor: "{colors.primary-strong}"
    typography: "{typography.eyebrow-mono}"
    rounded: "{rounded.pill}"
    padding: 4px 10px
---

# Clerk Design System

## Overview

Clerk's website is what an authentication SDK looks like when the people building it actually care about pixels. The canvas is uncompromising white (`{colors.background}`), broken only by the faintest gray section bands (`{colors.surface}`) — no gradients washing the page, no hero photography, no decorative noise. The restraint is the point: Clerk sells drop-in UI components, so the marketing site has to read as visual proof that the components themselves are immaculate. The headline "Pixel-perfect UIs, embedded in minutes" is set in a tightly-tracked Suisse-grotesque sans at `{typography.display-hero}` weight 700, near-black (`{colors.ink}`), with letter-spacing pulled to -1.6px so the words sit dense and confident.

The signature move is the typographic pairing. Body and display run in a clean geometric-humanist sans, but every label, eyebrow, and inline code reference switches to **Söhne Mono** (`{typography.eyebrow-mono}`) — uppercased, letter-spaced to 1.2px, and frequently tinted Clerk purple (`{colors.primary}`). Component names appear as literal JSX chips (`<SignUp />`, `<UserButton />`) rendered in that mono, collapsing the gap between the marketing copy and the actual API. It tells a developer audience exactly what they're buying without a single screenshot caption.

Then there's the color discipline. Clerk purple (`{colors.primary}`) is electric and instantly recognizable, but it is used as an *accent*, never as the workhorse. Eyebrows, links, code refs, and the occasional secondary CTA carry it. The primary call-to-action — "Continue", "Start building" — stays resolutely **black** (`{colors.ink}`). That inversion (black does the heavy lifting, purple does the signaling) is what keeps the system feeling like premium developer tooling rather than a consumer SaaS splash page. The embedded sign-up card, the literal product, floats on a soft multi-layer shadow that is the most three-dimensional thing on the page.

**Key Characteristics:**
- Pure white canvas (`{colors.background}`) with whisper-gray section bands (`{colors.surface}`) — light-first, zero dark mode on marketing
- Suisse-grotesque sans for display and body; tight negative tracking on large type (`{typography.display-hero}` at -1.6px)
- **Söhne Mono** for every eyebrow, label, and inline code chip (`{typography.eyebrow-mono}`) — uppercased, 1.2px tracking
- Electric Clerk purple (`{colors.primary}`) used strictly as accent: eyebrows, links, code refs
- Primary CTA is **black** (`{colors.ink}`), not purple — the brand inverts the expected hierarchy
- Component names rendered as live JSX chips (`<SignUp />`) in purple mono — marketing copy doubles as API reference
- Soft, layered card shadows (ring + ambient) reserved for the embedded product widget
- Compact 6px radius on buttons (`{rounded.md}`), 12-16px on cards — restrained, never pill-happy
- Hairline borders (`{colors.border}`) do most of the structural separation, not boxes or fills

## Colors

### Surface & Canvas
- **White** (`{colors.background}`): The dominant canvas. Nearly the entire site sits on pure white.
- **Whisper Gray** (`{colors.surface}`): Muted section bands and the fill behind inline code-ref chips. A barely-there shift from white.
- **Near-Black Surface** (`{colors.surface-dark}`): The dark embedded widget chrome and the fill of the primary button.

### Ink / Text
- **Near-Black** (`{colors.ink}`): Headings, body copy, and the primary CTA fill. Not pure black — a hair of blue.
- **Soft Black** (`{colors.ink-soft}`): Primary-button hover state and dark outline borders.
- **Slate** (`{colors.ink-secondary}`): Supporting paragraph copy and mono labels.
- **Muted Slate** (`{colors.ink-muted}`): Captions and metadata.
- **Faint Slate** (`{colors.ink-tertiary}`): The lowest-emphasis helper text.

### Brand Accent
- **Clerk Purple** (`{colors.primary}`): The singular brand color. Eyebrows, links, inline code refs, and accent CTAs. Used sparingly to preserve its charge.
- **Purple Hover** (`{colors.primary-hover}`) / **Purple Strong** (`{colors.primary-strong}`): Pressed and hover states for accent elements and badge text.
- **Purple Soft** (`{colors.primary-soft}`) / **Purple Container** (`{colors.primary-container}`): Light tints for badge fills and decorative purple moments.

### Borders & Shadow Tints
- **Hairline** (`{colors.border}`): Card edges and dividers — the primary structural device.
- **Strong Border** (`{colors.border-strong}`): Input and secondary-button outlines.
- **Ambient / Soft** (`{colors.shadow-ambient}`, `{colors.shadow-soft}`): Opaque stand-ins for the layered card shadow (the originals were rgba — flattened for the Google spec).

## Typography

### Font Family
- **Primary**: a Suisse-grotesque sans (`Geist, Suisse Intl, system-ui` stack) — geometric-humanist, clean, slightly warm. Carries all display and body text.
- **Monospace**: `Söhne Mono`, with fallbacks `ui-monospace, SFMono-Regular, Menlo, monospace`. Reserved for labels, eyebrows, and code references — a core part of the brand voice, not just for code.
- **OpenType / tracking**: large display sizes use aggressive negative tracking (-1.6px at 64px); mono labels use positive 1.2px tracking with uppercase transform.

### Hierarchy

The full type scale lives in the `typography:` token block. Reference tokens directly.

| Token | Use |
|---|---|
| `display-hero` | 64px / 700 / -1.6px — the marquee headline |
| `display` | 32px / 600 / -0.48px — section titles |
| `heading` | 24px / 700 — feature headings |
| `heading-sub` | 22px / 600 — sub-section headings |
| `body-large` | 18px / 400 — lead paragraphs |
| `body` | 16px / 400 — standard body and inputs |
| `body-small` | 15px / 400 — dense supporting copy |
| `label` | 13px / 500 — button text, UI labels |
| `caption` | 13px / 400 — metadata, helper text |
| `eyebrow-mono` | 12px / 600 / uppercase / 1.2px — **Söhne Mono** eyebrows and category labels |
| `code-mono` | 13px / 500 — **Söhne Mono** inline JSX code refs |

### Principles
- **Mono as voice, not just code**: Söhne Mono labels are a brand signature. Use them for eyebrows and section markers, uppercased and tracked.
- **Tighten the big, leave the small**: heavy negative tracking on display sizes; near-zero on body.
- **Weight does hierarchy**: 700 for headlines, 600 for section titles, 400/500 for everything else. The system rarely goes lighter than 400.

## Layout

### Spacing System
The full scale is in the `spacing:` token block. Base unit: 8px, with a 4px sub-step for tight component internals. Generous vertical rhythm (`{spacing.6xl}` = 128px) separates major marketing sections; component internals stay compact (`{spacing.md}`–`{spacing.2xl}`).

### Grid & Container
- Max content width: ~1200px, centered
- Common pattern: a left text column paired with a live component demo on the right (the embedded sign-up card)
- Feature lists use a single column of mono-labeled, expandable rows

### Whitespace Philosophy
- **White is the design**: the canvas does the work; whitespace is the primary separator, not borders or fills
- **Dense components, airy page**: individual cards and forms are tightly composed but float in generous surrounding space
- **The product is the hero**: the embedded widget gets the most visual weight (shadow, contrast) on any given screen

## Elevation & Depth

| Level | Treatment | Use |
|---|---|---|
| Flat (Level 0) | No shadow, hairline `{colors.border}` only | Section bands, most page content |
| Hairline ring (Level 1) | `inset 0 0 0 1px` at ~5% ink | Subtle input and chip containment |
| Subtle (Level 2) | `0 1px 3px` + `0 1px 2px -1px` at ~10% black | Resting buttons, small cards |
| Elevated (Level 3) | `0 0 0 1px` ring + `0 5px 15px` (`{colors.shadow-soft}`) + `0 15px 35px -5px` (`{colors.shadow-ambient}`) | The embedded sign-up widget — the signature elevation |

**Shadow Philosophy**: Clerk's shadows are soft, layered, and reserved. The page itself is almost entirely flat — separation comes from hairline borders. Elevation is spent deliberately on the product widget, where a multi-layer stack (a tight contact ring, a soft mid shadow, and a wide ambient cast) makes the card read as a real, liftable object. It is the most physical element on an otherwise paper-flat site.

## Shapes

The full radius scale is in the `rounded:` token block.

| Token | Value | Use |
|---|---|---|
| `sm` | 4px | Code-ref chips, small tags |
| `md` | 6px | Buttons — the default interactive radius |
| `lg` | 8px | Inputs, mid containers |
| `xl` | 12px | Cards |
| `2xl` | 16px | Large elevated cards, the sign-up widget |
| `pill` | 9999px | Avatars, badges, circular toggles |

The system is restrained and graduated: a compact 6px on buttons, scaling to 12-16px on cards. No oversized pill buttons — radius signals tidiness, not playfulness.

## Components

The complete component spec lives in the `components:` token block.

### Buttons
- **`button-primary`** — Black (`{colors.ink}`) fill, white text, 6px radius. The main CTA. Hover lifts to `{colors.ink-soft}`.
- **`button-secondary`** — White fill, near-black text, `{colors.border-strong}` outline. The "Continue with Google / GitHub" pattern. Hover fills `{colors.surface}`.
- **`button-accent`** — Clerk purple (`{colors.primary}`) fill, white text. Used sparingly for accent CTAs. Hover deepens to `{colors.primary-hover}`.

### Cards
- **`card`** / **`card-elevated`** — White surface, hairline border, 12-16px radius. The elevated variant carries the signature layered shadow and holds the embedded auth widget.

### Inputs
- **`input`** — White fill, `{colors.border-strong}` outline, 6px radius, label set above. **`input-focus`** swaps to a dark `{colors.ink}` border (not a purple ring) for a crisp, high-contrast focus.

### Navigation
- **`nav-bar`** — White, hairline bottom border, mono-feel UI labels. Sits flush at the top; no heavy shadow.

### Accent & Code
- **`link`** — Clerk purple text, no underline until hover.
- **`eyebrow`** — Purple Söhne Mono, uppercased — the section-marker signature.
- **`label-mono`** — Slate Söhne Mono for muted category labels.
- **`code-ref`** — Inline JSX chip: whisper-gray fill, purple mono text, 4px radius. Marketing copy that doubles as API.
- **`badge`** — Purple-container fill, purple-strong mono text, pill radius.

## Do's and Don'ts

### Do
- Keep the canvas pure white (`{colors.background}`) — let whitespace and hairline borders (`{colors.border}`) do the structural work
- Use **Söhne Mono** (`{typography.eyebrow-mono}`) for eyebrows, category labels, and inline code — uppercased with 1.2px tracking
- Reserve Clerk purple (`{colors.primary}`) for accents: eyebrows, links, code refs, and the occasional accent CTA
- Keep the primary CTA **black** (`{colors.ink}`) — this inversion is core to the brand
- Render component/API names as literal code chips (`<SignUp />`) in purple mono
- Spend elevation on the product widget only — soft, layered shadows (`{colors.shadow-ambient}`)
- Use tight negative tracking on display type (-1.6px at 64px) for that dense, confident headline feel
- Keep button radius compact at `{rounded.md}` (6px)

### Don't
- Don't make purple the primary button color — it's an accent, and the CTA is black
- Don't introduce gradients, hero photography, or decorative illustration — the restraint is the message
- Don't reach for pill-shaped buttons — the system tops out at 6px on buttons, 16px on cards
- Don't scatter shadows across the page — flatness plus hairlines is the default; elevation is reserved
- Don't use the sans for labels where mono belongs — the typographic pairing is the signature
- Don't add a dark marketing theme — Clerk's site is committedly light
- Don't loosen display tracking to 0 or positive — large type stays compressed

---

## Responsive Behavior

### Breakpoints
*(No explicit breakpoints surfaced in extraction; the values below are the standard Tailwind-style stops the site behaves to.)*

| Name | Width | Key Changes |
|---|---|---|
| Mobile | <640px | Single column; hero text scales 64px → ~36px; nav collapses to a menu; the embedded widget stacks below the copy and goes full-width |
| Tablet | 640–1023px | Two-column feature rows begin; widget sits beside copy at reduced width |
| Desktop | 1024–1279px | Full layout; copy-left / widget-right hero |
| Large | ≥1280px | Max ~1200px container, centered; generous section padding (`{spacing.6xl}`) |

### Touch Targets
- Buttons run ~40px tall with `10px 16px` padding — comfortable for thumbs
- Mono labels stay legible at 12px; tap rows in feature lists carry generous vertical padding

### Collapsing Strategy
- **Navigation**: full horizontal nav → menu toggle on mobile; the black "Start building" CTA persists
- **Hero**: copy and the embedded widget go from side-by-side to stacked, widget full-width
- **Type**: display drops from 64px toward ~36px while keeping proportional negative tracking
- **Spacing**: section padding compresses from 128px toward ~64px

### Image Behavior
- The site is near-imageless; the "images" are live product widgets that reflow as flex/grid children rather than fixed art

---

## Agent Prompt Guide

### Quick Color Reference
- Background: White (`{colors.background}`)
- Text: Near-Black (`{colors.ink}`)
- Brand accent: Clerk Purple (`{colors.primary}`)
- Secondary text: Slate (`{colors.ink-secondary}`)
- Border: Hairline (`{colors.border}`)
- Primary CTA: **Black** (`{colors.ink}`) — not purple

### Example Component Prompts

- "Create a hero on white (`{colors.background}`) with a 64px near-black (`{colors.ink}`) headline in a Suisse-grotesque sans, letter-spacing -1.6px, a purple (`{colors.primary}`) Söhne Mono uppercased eyebrow above it, and a black primary button (`{colors.ink}` fill, white text, `{rounded.md}` radius)"
- "Build a secondary button: white fill, near-black text, `{colors.border-strong}` 1px outline, `{rounded.md}` radius, hover fills `{colors.surface}` — the 'Continue with GitHub' pattern"
- "Render an inline code chip for a component name: whisper-gray (`{colors.surface}`) fill, Clerk purple (`{colors.primary}`) Söhne Mono text at 13px, `{rounded.sm}` radius, 2px 6px padding — e.g. `<SignUp />`"
- "Create the embedded auth card: white surface, hairline (`{colors.border}`) edge, `{rounded.2xl}` radius, layered shadow (1px contact ring + `0 5px 15px` soft + `0 15px 35px -5px` ambient via `{colors.shadow-ambient}`), with a stacked input + black continue button inside"
- "Design an input with label above: white fill, `{colors.border-strong}` outline, `{rounded.md}` radius; on focus swap the border to near-black (`{colors.ink}`), no purple ring"

### Iteration Guide

1. Start on pure white (`{colors.background}`). If you reached for a gradient or a tinted background, stop — Clerk is flat white.
2. Purple (`{colors.primary}`) is an accent only. If it's filling your primary button, recolor that button black (`{colors.ink}`).
3. Any eyebrow, category label, or code reference must be Söhne Mono (`{typography.eyebrow-mono}`), uppercased, 1.2px tracking.
4. Separate with hairline borders (`{colors.border}`) before reaching for shadows. Reserve real elevation for the one product widget.
5. Display type stays compressed — verify negative tracking (-1.6px at hero size) before moving on.
6. Keep radii tight: `{rounded.md}` (6px) on buttons, `{rounded.xl}`–`{rounded.2xl}` on cards. No pills.
7. Render component/API names as live code chips, not prose — it's the brand's proof-of-craft voice.

---

## Attribution

Independent design analysis from [Design Swatches](https://designmd.santiagoalonso.com) by [Santiago Alonso](https://santiagoalonso.com). Based on publicly observable interface patterns. Not affiliated with or endorsed by Clerk. Brand names and trademarks belong to their respective owners.