# Josh Comeau · Design system migration spec

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

> This site is worth including as a prime example of how to make technical educational content feel warm, accessible, and engaging through thoughtful design and illustration.

## 1. Identity DNA

Josh Comeau's design system operates like a friendly, illustrated textbook, one that uses color and interactive metaphor to demystify complex web technologies. The identity is built on a foundation of approachability, using a bright, airy aesthetic to create a space where technical learning feels both welcoming and clear.

**One-liner:** An educational web developer blog that uses bright, playful illustrations and clear typography to make complex coding concepts accessible.
**Keywords:** educational · playful · accessible · technical · friendly
**Analogy:** A friendly, illustrated textbook that explains complex web technologies with colorful, interactive metaphors.

## 2. Color

The color system is built on a foundation of clarity and distinction. A signature sky-blue provides a constant, airy background, while a vibrant magenta accent is reserved for precise, energetic highlights that guide the eye without shouting.

| Token | Value | Use |
|---|---|---|
| `--bg` | `#FFFFFF` | main background |
| `--bg-soft` | `#B1DFF6` | card background |
| `--bg-quiet` | `#F0F4F6` | quiet area |
| `--ink` | `#0A0C10` | body text |
| `--ink-soft` | `#294E60` | secondary text |
| `--muted` | `#5A6072` | placeholder |
| `--muted-soft` | `#C1D1DB` | weak hint |
| `--accent` | `#E60067` | single accent |
| `--line` | `rgba(10, 12, 16, 0.1)` | divider |

**Color principle:** A bright, airy aesthetic dominated by a signature sky-blue (#B1DFF6) and a vibrant magenta accent (#E60067), grounded by deep navy text (#0A0C10) for maximum readability.

The underlying principle is one of purposeful contrast: a deep navy text color ensures maximum readability against the bright, light-filled canvas.

## 3. Typography

Typography here serves a dual voice: a clean, geometric sans-serif handles all prose with generous line-height for comfort, while a reserved monospace font appears only for code, creating a clear visual boundary between concept and execution.

- **Display:** geometric-sans
- **Body:** geometric-sans
- **Mono:** monospace

| Token | Size | Line-height | Weight | Letter-spacing | Use |
|---|---|---|---|---|---|
| display | 36px | 1.1 | 700 | -1px | Article headings and major titles. |
| heading | 24px | 1.3 | 600 | normal | Subheadings and section titles. |
| subtitle | 19px | 1.5 | 400 | normal | Article subtitles and introductory text. |
| body | 16px | 1.5 | 400 | normal | Main body text and paragraphs. |
| caption | 14px | 1.5 | 400 | normal | Secondary text, tags, and captions. |

**Type rules:**
- Use uppercase and wide letter-spacing for category labels.
- Reserve monospace font exclusively for code snippets and technical terms.
- Maintain generous line-height (1.5) for long-form readability.
- Use bold weights sparingly to highlight key terms without overwhelming the layout.

## 4. Spacing

A 4px base grid underpins the entire system, creating a predictable rhythm that scales from intimate 24px gaps to expansive 96px section breaks.

- **Base unit:** 4px
- **Scale:** 4 / 8 / 12 / 16 / 24 / 32 / 48 / 64 / 96 px
- **Rhythm:** A 4px base grid ensures consistent rhythm, with generous 24px gaps between structural elements and 48-96px spacing for major section breaks.

## 5. Surfaces

Depth is communicated through barely-there means. Shadows are applied in three soft, progressive layers, creating a gentle lift from the page, while borders are kept thin and transparent, serving as subtle delineators rather than heavy containers.

- **Radius:** sm 4px · md 8px · lg 12px · pill 999px
- **Shadows:**
  - 0px 2px 4px rgba(0, 0, 0, 0.02)
  - 0px 4px 12px rgba(0, 0, 0, 0.03)
  - 0px 8px 24px rgba(0, 0, 0, 0.05)
- **Borders:** Subtle, thin borders in neutral grays (e.g., rgba(10, 12, 16, 0.1)) are used for cards and inputs, while category tags use slightly more defined strokes.

## 6. Layout

The layout is a straightforward two-column skeleton: a generous main content column dominates, flanked by a narrower sidebar for persistent navigation and discovery. This structure prioritizes reading flow while keeping supplementary content within easy reach.

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

**Skeleton:** A two-column layout with a narrow sidebar (300px) for 'Popular Content' and 'Categories' alongside a wide main content column.

## 7. Motion & Interaction

Motion is treated as a subtle conductor, not a performer. All transitions adhere to a consistent 0.3-second duration, using smooth opacity and transform animations to provide feedback and guide attention without interrupting the learning process.

- **Durations:** micro 125ms · small 300ms · medium 500ms
- **Easing:** `cubic-bezier(0.06, 0.63, 0.43, 1)`
- **Patterns:**
  - Smooth opacity transitions for UI state changes.
  - Subtle transform animations for interactive elements.
  - Staggered entry animations for content sections.

- **Hover:** Subtle scaling or color shifts on interactive elements to provide immediate visual feedback.
- **Click:** Smooth transition to a new state or page with minimal delay.
- **Transition:** Consistent 0.3s duration for most interactive transitions.
- **Keyboard:** Full keyboard navigability with clear, visible focus outlines (often using custom outline colors).

## 8. Voice & Don'ts

The editorial voice is that of a helpful mentor—direct, encouraging, and free of impersonal jargon. Calls to action are woven into the content as subtle, text-based suggestions rather than loud demands.

- **Tone:** Friendly, approachable, and encouraging, like a helpful mentor.
- **Headline style:** Clear, direct, and benefit-oriented, often using 'An Interactive Guide to...' or 'A Friendly Introduction to...'
- **CTA style:** Subtle, text-based calls to action that blend naturally into the content flow.
- **Avoid:** Dense, impenetrable jargon. / Impersonal, corporate-speak. / Overly dramatic or sensationalist language. / Dull, textbook-like prose.

### Don'ts
- ❌ Don't use a dark background for the main content area — the screenshot shows a bright, light-background aesthetic.
- ❌ Don't use a purely monochrome or grayscale palette — the design relies on vibrant sky blue and magenta accents.
- ❌ Don't use traditional serif fonts for body text — the screenshot exclusively uses clean, geometric sans-serif and monospace.
- ❌ Don't use harsh, black borders for UI components — borders are subtle and light, often transparent or gray.
- ❌ Don't overcrowd the layout with tight margins — the design uses generous whitespace and clear section breaks.
- ❌ Don't use sharp, 90-degree corners for buttons or cards — the screenshot shows consistent use of rounded corners (4-12px).

What the system deliberately avoids is as defining as what it includes: it rejects dark backgrounds, serif body fonts, harsh borders, and cramped spacing in favor of its signature lightness and clarity.

## System Prompt (paste into AI tool)

```
This site is a friendly, educational web developer portfolio and blog. The aesthetic is bright and airy, using a signature sky-blue (#B1DFF6) for hero sections and a vibrant magenta accent (#E60067) for highlights. Typography is clean and geometric, with a focus on readability and clear hierarchy. The layout is spacious, using generous whitespace and subtle borders to define sections. Critical don'ts include avoiding dark mode as the primary theme, using serif fonts for body copy, or creating a cramped, low-contrast layout. The overall feel is welcoming and encouraging, making complex technical topics feel accessible.
```
