---
name: Josh Comeau
description: "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."
version: alpha

colors:
  background: "#FFFFFF"
  primary: "#0A0C10"
  secondary: "#294E60"
  tertiary: "#E60067"
  neutral: "#5A6072"
  bg-soft: "#B1DFF6"
  bg-quiet: "#F0F4F6"
  muted-soft: "#C1D1DB"
  line: "rgba(10, 12, 16, 0.1)"

typography:
  display:
    fontFamily: geometric-sans
    fontSize: 36px
    lineHeight: 1.1
    fontWeight: 700
    letterSpacing: "-1px"
  heading:
    fontFamily: geometric-sans
    fontSize: 24px
    lineHeight: 1.3
    fontWeight: 600
    letterSpacing: "normal"
  subtitle:
    fontFamily: geometric-sans
    fontSize: 19px
    lineHeight: 1.5
    fontWeight: 400
    letterSpacing: "normal"
  body:
    fontFamily: geometric-sans
    fontSize: 16px
    lineHeight: 1.5
    fontWeight: 400
    letterSpacing: "normal"
  caption:
    fontFamily: geometric-sans
    fontSize: 14px
    lineHeight: 1.5
    fontWeight: 400
    letterSpacing: "normal"

rounded:
  sm: 4px
  md: 8px
  lg: 12px
  pill: 999px

spacing:
  xs: 4px
  sm: 8px
  md: 12px
  lg: 16px
  xl: 24px
  2xl: 32px
  3xl: 48px

---

## Overview

An educational web developer blog that uses bright, playful illustrations and clear typography to make complex coding concepts accessible.

*A friendly, illustrated textbook that explains complex web technologies with colorful, interactive metaphors.*

## Colors

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.

- **Background (`#FFFFFF`)** — uses `bg` token
- **Primary text (`#0A0C10`)** — uses `ink` token
- **Secondary text (`#294E60`)** — uses `ink-soft` token
- **Accent (`#E60067`)** — uses `accent` token
- **Muted (`#5A6072`)** — uses `muted` token
- **Borders (`rgba(10, 12, 16, 0.1)`)** — uses `line` token

## Typography

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

- 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.

## Layout

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

*Rhythm:* A 4px base grid ensures consistent rhythm, with generous 24px gaps between structural elements and 48-96px spacing for major section breaks.

## Elevation & Depth

- 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.

## Shapes

- `sm`: 4px
- `md`: 8px
- `lg`: 12px
- `pill`: 999px

## Components

- **button:** Simple text-based buttons or subtle pill-shaped tags with light background fills and rounded corners.
- **card:** Clean, edge-to-edge content cards with clear typographic hierarchy and subtle background colors for emphasis.
- **chip:** Small, pill-shaped tags with uppercase text, used for categorization (e.g., CSS, React).
- **input:** Clean, rounded input fields with subtle borders and clear focus states.
- **hero:** A full-width illustrated hero section featuring 3D-style graphics and a light blue gradient background.

## Do's and Don'ts

**Don't:**
- 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).

---

## System Prompt (paste into AI agent)

```
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.
```