# Clerk · Design system migration spec

> Source: https://clerk.com  ·  Curated by OpenDesign  ·  en

> Exemplary developer tool design that balances professionalism with approachability through careful typography and purposeful visual hierarchy

## 1. Identity DNA

Clerk's design language treats authentication as the robust foundation of a secure building—visible when needed, but engineered to disappear behind the confidence of the structure it supports. Every visual decision reinforces the platform's core promise: complete user management that developers can build upon without hesitation.

**One-liner:** Complete user management platform for developers to build secure, scalable applications
**Keywords:** Authentication · User Management · Developer Experience · Scalable
**Analogy:** The robust foundation of a secure building

## 2. Color

The palette operates with architectural restraint, maintaining vast fields of clean white and light gray to let content breathe. A single vibrant purple accent (#6248F6) serves as the system's singular signal, directing attention to primary actions and interactive hierarchy without chromatic competition.

| Token | Value | Use |
|---|---|---|
| `--bg` | `#FFFFFF` | main background |
| `--bg-soft` | `#F7F7F8` | card background |
| `--ink` | `#131316` | body text |
| `--ink-soft` | `#5E5F6E` | secondary text |
| `--muted` | `#747686` | placeholder |
| `--muted-soft` | `#9394A1` | weak hint |
| `--accent` | `#6248F6` | single accent |
| `--line` | `rgba(217, 217, 222, 1)` | divider |

**Color principle:** Clean white space with sharp black text and a single vibrant purple accent

This discipline of one accent against neutrality ensures every call to action carries immediate, unambiguous weight.

## 3. Typography

Typography balances impact with readability, employing grotesque-sans for headlines where tight tracking and heavy weights create confident statements. Humanist-sans handles body text with generous line height, maintaining a comfortable reading rhythm for extended technical documentation and interface copy.

- **Display:** grotesque-sans
- **Body:** humanist-sans
- **Mono:** monospace

| Token | Size | Line-height | Weight | Letter-spacing | Use |
|---|---|---|---|---|---|
| display | 56px | 1.0 | 700 | -1.5px | Primary hero headline |
| body | 16px | 1.5 | 400 | 0px | Body text |

**Type rules:**
- Headlines use tight tracking and heavy weights for impact
- Body text maintains comfortable reading rhythm with generous line height
- Monospace elements used sparingly for technical emphasis

## 4. Spacing

Spacing follows a consistent 4px base grid, creating rhythmic predictability across all components.

- **Base unit:** 4px
- **Scale:** 4 / 8 / 12 / 16 / 24 / 32 / 48 / 64 / 96 px
- **Rhythm:** Consistent 4px base with generous whitespace in hero sections

## 5. Surfaces

Surfaces exist in a shallow depth hierarchy, using subtle, purposeful shadows only where elevation signals functionality. Borders appear as thin, light gray lines that provide structural separation without visual weight, maintaining the system's clean, construction-like clarity.

- **Radius:** sm 4px · md 8px · lg 12px · pill 999px
- **Shadows:**
  - rgba(0, 0, 0, 0.08) 0px 5px 15px 0px
  - rgba(25, 28, 33, 0.2) 0px 15px 35px -5px
  - rgba(0, 0, 0, 0.1) 0px 1px 3px 0px
- **Borders:** 1px solid rgba(217, 217, 222, 1)

## 6. Layout

The layout skeleton centers content within generous whitespace, beginning with a full-width hero that establishes visual authority. Subsequent sections unfold into multi-column feature grids that organize information with clear, scannable hierarchy.

- **Container max:** 1280px
- **Paragraph max:** 680px
- **Grid:** 12 columns, gutter 24px
- **Breakpoints:** 768 / 1024 px

**Skeleton:** Centered hero with generous whitespace, followed by multi-column feature grid

## 7. Motion & Interaction

Motion philosophy treats animation as functional feedback rather than decorative flourish. All transitions operate at a consistent 150ms pace, providing immediate visual confirmation of interaction without delay or distraction.

- **Durations:** micro 150ms · small 300ms · medium 450ms
- **Easing:** `cubic-bezier(0.4, 0, 0.2, 1)`
- **Patterns:**
  - Smooth color transitions on hover
  - Subtle opacity changes for interactive states
  - Gradual transform animations for expansion effects

- **Hover:** Subtle color darkening and background changes
- **Click:** Immediate visual feedback with no delay
- **Transition:** All interactive elements have smooth 150ms transitions
- **Keyboard:** Full keyboard navigation support with visible focus states

## 8. Voice & Don'ts

Voice maintains a professional, developer-focused tone with direct, benefit-driven headlines that use strong verbs and clear value propositions. Language avoids marketing jargon and casual exuberance, favoring technical specifics and actionable clarity.

- **Tone:** Professional, confident, and developer-focused
- **Headline style:** Direct and benefit-driven with strong verbs
- **CTA style:** Action-oriented with clear value proposition
- **Avoid:** Overly casual language / Excessive exclamation marks / Marketing jargon without substance / Vague promises without technical specifics

### Don'ts
- ❌ Don't use decorative fonts — screenshot shows clean, functional grotesque-sans typography
- ❌ Don't add unnecessary shadows — screenshot shows minimal, purposeful elevation only on key elements
- ❌ Don't use multiple accent colors — screenshot shows single purple accent (#6248F6) throughout
- ❌ Don't create cramped layouts — screenshot shows generous whitespace and breathing room
- ❌ Don't use complex gradients — screenshot shows subtle linear gradients and radial backgrounds
- ❌ Don't add unnecessary borders — screenshot shows borders only where functional separation is needed

The system deliberately forgoes decorative fonts, excessive shadows, multiple accent colors, cramped layouts, complex gradients, and unnecessary borders—each exclusion reinforcing the platform's engineering-first integrity.

## System Prompt (paste into AI tool)

```
Clerk is a premium developer tool platform focused on authentication and user management. The design uses a clean, professional aesthetic with white backgrounds (#FFFFFF) and light gray surfaces (#F7F7F8). Typography employs grotesque-sans for display and humanist-sans for body text, with tight tracking on headlines. A single vibrant purple accent (#6248F6) creates clear call-to-action hierarchy. The layout centers content with generous whitespace and uses subtle shadows for depth. Critical don'ts: avoid decorative fonts, excessive shadows, multiple accent colors, cramped layouts, complex gradients, and unnecessary borders. The system prioritizes developer experience with clear information hierarchy and purposeful visual elements that communicate reliability and technical sophistication.
```