---
version: alpha
name: ReadMe
description: Friendly developer-docs energy — a bright sky-blue brand color (#4FACFF) on a clean white canvas, rounded geometric sans headlines, playful "owlbert" warmth, generously rounded cards and pill buttons, and code-block accents that bridge marketing to product.
colors:
  # Canvas + ink
  background: "#ffffff"
  surface: "#ffffff"
  surface-soft: "#f6f9fc"
  surface-navy: "#018ef5"     # was deep brand navy panel, flattened to brand blue family
  ink: "#1a1e23"
  ink-soft: "#2b2f36"

  # Brand
  primary: "#4facff"          # signature ReadMe sky blue
  primary-deep: "#018ef5"     # deeper blue for hover / gradient base
  primary-soft: "#eaf4ff"     # was rgba(79,172,255,.12) — flattened over white

  # Accents
  accent-purple: "#7b61ff"
  accent-pink: "#ff5c8d"
  accent-green: "#22c993"
  accent-yellow: "#ffc930"

  # Neutral scale
  gray-800: "#363c44"
  gray-600: "#5a626d"
  gray-500: "#7a828e"
  gray-300: "#c7ccd4"
  gray-200: "#e3e7ec"
  gray-100: "#f0f3f7"

  # On-color
  on-primary: "#ffffff"
  on-ink: "#ffffff"

  # Code block
  code-bg: "#1a1e23"
  code-text: "#e3e7ec"

  # Borders + tints
  border-soft: "#e3e7ec"
  ring-blue: "#bfe0ff"        # was rgba(79,172,255,.4) — flattened over white

typography:
  display-hero:
    fontFamily: "Poppins, -apple-system, Segoe UI, sans-serif"
    fontSize: 56px
    fontWeight: 700
    lineHeight: 1.05
    letterSpacing: -1.5px
  section-heading:
    fontFamily: "Poppins, -apple-system, sans-serif"
    fontSize: 40px
    fontWeight: 700
    lineHeight: 1.15
    letterSpacing: -1px
  sub-heading:
    fontFamily: "Poppins, -apple-system, sans-serif"
    fontSize: 28px
    fontWeight: 600
    lineHeight: 1.25
    letterSpacing: -0.5px
  card-title:
    fontFamily: "Poppins, -apple-system, sans-serif"
    fontSize: 22px
    fontWeight: 600
    lineHeight: 1.3
    letterSpacing: -0.3px
  body-large:
    fontFamily: "Inter, -apple-system, sans-serif"
    fontSize: 20px
    fontWeight: 400
    lineHeight: 1.6
    letterSpacing: 0px
  body:
    fontFamily: "Inter, -apple-system, sans-serif"
    fontSize: 17px
    fontWeight: 400
    lineHeight: 1.6
    letterSpacing: 0px
  body-small:
    fontFamily: "Inter, -apple-system, sans-serif"
    fontSize: 15px
    fontWeight: 400
    lineHeight: 1.5
    letterSpacing: 0px
  body-medium:
    fontFamily: "Inter, -apple-system, sans-serif"
    fontSize: 15px
    fontWeight: 500
    lineHeight: 1.5
    letterSpacing: 0px
  button-ui:
    fontFamily: "Poppins, -apple-system, sans-serif"
    fontSize: 15px
    fontWeight: 600
    lineHeight: 1.2
    letterSpacing: 0px
  caption:
    fontFamily: "Inter, -apple-system, sans-serif"
    fontSize: 13px
    fontWeight: 500
    lineHeight: 1.3
    letterSpacing: 0.2px
  mono-body:
    fontFamily: "JetBrains Mono, ui-monospace, SFMono-Regular, Menlo, monospace"
    fontSize: 14px
    fontWeight: 400
    lineHeight: 1.6
    letterSpacing: 0px
  mono-caption:
    fontFamily: "JetBrains Mono, ui-monospace, Menlo, monospace"
    fontSize: 12px
    fontWeight: 500
    lineHeight: 1.4
    letterSpacing: 0px

spacing:
  xs: 4px
  sm: 8px
  md: 12px
  lg: 16px
  xl: 24px
  2xl: 40px
  3xl: 64px
  4xl: 96px

rounded:
  none: 0px
  sm: 6px
  md: 10px
  lg: 16px
  xl: 24px
  2xl: 32px
  pill: 9999px

components:
  # Primary blue CTA
  button-primary:
    backgroundColor: "{colors.primary}"
    textColor: "{colors.on-primary}"
    typography: "{typography.button-ui}"
    rounded: "{rounded.pill}"
    padding: 12px 24px
  button-primary-hover:
    backgroundColor: "{colors.primary-deep}"
    textColor: "{colors.on-primary}"
    typography: "{typography.button-ui}"
    rounded: "{rounded.pill}"
    padding: 12px 24px

  # Secondary outline
  button-secondary:
    backgroundColor: "{colors.background}"
    textColor: "{colors.primary-deep}"
    typography: "{typography.button-ui}"
    rounded: "{rounded.pill}"
    padding: 12px 24px
    borderColor: "{colors.primary}"

  # Pill badge
  badge:
    backgroundColor: "{colors.primary-soft}"
    textColor: "{colors.primary-deep}"
    typography: "{typography.caption}"
    rounded: "{rounded.pill}"
    padding: 4px 12px

  # Standard card
  card:
    backgroundColor: "{colors.background}"
    textColor: "{colors.ink}"
    rounded: "{rounded.xl}"
    padding: 24px
    borderColor: "{colors.border-soft}"

  # Soft surface card
  card-soft:
    backgroundColor: "{colors.surface-soft}"
    textColor: "{colors.ink}"
    rounded: "{rounded.xl}"
    padding: 24px
    borderColor: "{colors.gray-100}"

  # Input
  input:
    backgroundColor: "{colors.background}"
    textColor: "{colors.ink}"
    typography: "{typography.body-small}"
    rounded: "{rounded.md}"
    padding: 10px 14px
    borderColor: "{colors.gray-300}"
  input-focus:
    backgroundColor: "{colors.background}"
    borderColor: "{colors.primary}"

  # Top nav bar
  nav-bar:
    backgroundColor: "{colors.background}"
    textColor: "{colors.ink}"
    typography: "{typography.button-ui}"
    padding: 16px 24px
    borderColor: "{colors.border-soft}"

  # Code block
  code-block:
    backgroundColor: "{colors.code-bg}"
    textColor: "{colors.code-text}"
    typography: "{typography.mono-body}"
    rounded: "{rounded.lg}"
    padding: 20px

  # Accent tag pill
  tag-purple:
    backgroundColor: "{colors.accent-purple}"
    textColor: "{colors.on-primary}"
    typography: "{typography.caption}"
    rounded: "{rounded.pill}"
    padding: 4px 10px
---

# ReadMe Design System

## Overview

ReadMe's website is the friendly face of developer documentation — a design that feels approachable rather than intimidating, built to convince teams that great docs can be delightful. The page rides on a clean white canvas (`{colors.background}`) punctuated by a single, unmistakable signature: a bright sky-blue (`{colors.primary}`) that appears in CTAs, links, gradient washes, and product illustrations. Where many dev-tool brands lean cold and monochrome, ReadMe leans warm and playful, anchored by its mascot "Owlbert" and a rounded, geometric typographic voice.

The typography pairs a rounded geometric sans for headlines (Poppins-class) with a highly legible neutral sans for body (Inter-class). Headlines carry tight negative tracking and heavy weights (700) to feel confident and friendly at once, while body copy stays relaxed at 1.6 line-height for comfortable reading. A monospace face (JetBrains Mono-class) handles code samples, terminal output, and API snippets — the connective tissue between a marketing page and a developer product.

What distinguishes ReadMe is its generosity with rounding and color accents. Cards, buttons, and containers use large radii (`{rounded.xl}`–`{rounded.2xl}`), giving the whole interface a soft, pill-and-bubble character. Beyond the core blue, a small accent family — purple (`{colors.accent-purple}`), pink (`{colors.accent-pink}`), green (`{colors.accent-green}`), yellow (`{colors.accent-yellow}`) — adds personality to tags, illustrations, and category markers without overwhelming the blue-led identity.

**Key Characteristics:**
- Signature sky-blue brand color (`{colors.primary}`) leading every CTA and link
- Rounded geometric sans headlines (Poppins-class) with tight negative tracking and 700 weight
- Inter-class body at relaxed 1.6 line-height for documentation legibility
- Generous corner rounding throughout — pill buttons, `{rounded.xl}`+ cards
- Playful accent palette (purple, pink, green, yellow) for tags and illustration
- Dark code blocks (`{colors.code-bg}`) bridging marketing and product
- Clean white canvas — color is the signal, white is the stage

## Colors

### Primary
- **ReadMe Blue** (`{colors.primary}`): Signature brand color — CTAs, links, illustration highlights.
- **Deep Blue** (`{colors.primary-deep}`): Hover states, gradient base, stronger emphasis on light backgrounds.
- **Blue Soft** (`{colors.primary-soft}`): Tinted badge/highlight backgrounds.

### Canvas & Ink
- **White** (`{colors.background}`): Page background, card surfaces.
- **Soft Surface** (`{colors.surface-soft}`): Section tint, soft card fills.
- **Ink** (`{colors.ink}`): Primary headings and body text.

### Accents
- **Purple** (`{colors.accent-purple}`): Category tags, illustration accents.
- **Pink** (`{colors.accent-pink}`): Playful highlights.
- **Green** (`{colors.accent-green}`): Success, positive markers.
- **Yellow** (`{colors.accent-yellow}`): Attention, warm illustration accents.

### Neutral Scale
- **Gray 800** (`{colors.gray-800}`): Strong secondary text.
- **Gray 600** (`{colors.gray-600}`): Body description copy.
- **Gray 500** (`{colors.gray-500}`): Muted/tertiary text.
- **Gray 300** (`{colors.gray-300}`): Input borders.
- **Gray 200** (`{colors.gray-200}`): Dividers, soft borders.
- **Gray 100** (`{colors.gray-100}`): Subtle surface tint.

### Code & Borders
- **Code Background** (`{colors.code-bg}`): Dark code-block fill.
- **Code Text** (`{colors.code-text}`): Light code text.
- **Border Soft** (`{colors.border-soft}`): Card outlines, nav border.

## Typography

### Font Family
- **Display / Headings**: `Poppins`, with fallbacks `-apple-system, Segoe UI, sans-serif` — rounded geometric sans.
- **Body**: `Inter`, with fallbacks `-apple-system, sans-serif` — neutral, highly legible.
- **Monospace**: `JetBrains Mono`, with fallbacks `ui-monospace, SFMono-Regular, Menlo, monospace`.

### Hierarchy

The complete type scale lives in the `typography:` token block above. Reference tokens directly (`{typography.display-hero}`, `{typography.body}`, etc.).

| Token | Use |
|---|---|
| `display-hero` | 56px hero headline — confident, friendly |
| `section-heading` | Feature section titles |
| `sub-heading` | Sub-sections, large card headings |
| `card-title` | Feature cards |
| `body-large` | Intros, feature descriptions |
| `body` | Standard reading text |
| `body-small` | UI text, captions |
| `body-medium` | Emphasized UI text |
| `button-ui` | Buttons, nav links |
| `caption` | Tags, metadata |
| `mono-body` | Code blocks |
| `mono-caption` | Code labels |

### Principles
- **Two-family contrast**: Rounded geometric Poppins for headlines vs neutral Inter for body — friendly impact, comfortable reading.
- **Heavy, tight headlines**: 700 weight with negative tracking gives confidence without coldness.
- **Relaxed body rhythm**: 1.6 line-height respects the documentation-reading audience.
- **Mono as product voice**: JetBrains Mono in dark code blocks connects marketing to the actual docs product.

## Layout

### Spacing System
The complete scale lives in the `spacing:` token block above. Base unit is 8px, with generous jumps (`{spacing.3xl}` 64px, `{spacing.4xl}` 96px) for airy section separation.

### Grid & Container
- Max content width: approximately 1200px
- Hero: centered single-column with large illustration support
- Feature sections: 2–3 column card grids
- Generous vertical padding between sections (`{spacing.3xl}`–`{spacing.4xl}`)

### Whitespace Philosophy
- **Friendly air**: Lots of white space, but warmed by color accents and rounded shapes rather than gallery austerity.
- **Color as wayfinding**: The blue leads the eye through CTAs and links across an otherwise neutral page.

## Shapes

| Token | Value | Use |
|---|---|---|
| `none` | 0px | Reserved |
| `sm` | 6px | Small inline elements |
| `md` | 10px | Inputs, small containers |
| `lg` | 16px | Code blocks, medium cards |
| `xl` | 24px | Feature cards |
| `2xl` | 32px | Large hero panels |
| `pill` | 9999px | Buttons, badges, tags |

## Components

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

### Buttons
- **`button-primary`** — Sky-blue fill, white text, full pill. The default CTA.
- **`button-secondary`** — White with blue outline and blue text.

### Pills & Badges
- **`badge`** — Soft-blue tinted background, deep-blue text, full pill.
- **`tag-purple`** — Accent-purple fill for category tags.

### Cards
- **`card`** — White, soft border, large `{rounded.xl}` radius.
- **`card-soft`** — Soft-surface fill for grouped content.

### Inputs
- **`input`** — White surface, gray border, `{colors.primary}` focus border.

### Navigation
- **`nav-bar`** — White sticky header, soft bottom border, blue pill CTA right.

### Code
- **`code-block`** — Dark fill (`{colors.code-bg}`), light mono text, `{rounded.lg}` radius.

## Do's and Don'ts

### Do
- Lead with the sky-blue brand color (`{colors.primary}`) for CTAs and links
- Pair Poppins-class headlines with Inter-class body
- Use generous rounding — pill buttons, `{rounded.xl}`+ cards
- Use the accent palette for tags and illustration, sparingly
- Keep the canvas white so blue reads as the signal

### Don't
- Don't tint the whole page blue — blue is the accent, white is the stage
- Don't use sharp corners — the brand is soft and rounded
- Don't set body text in Poppins — Inter carries reading copy
- Don't overload the accent colors into UI chrome
- Don't use light code blocks — code stays dark for contrast

---

## Responsive Behavior

### Breakpoints
| Name | Width | Key Changes |
|------|-------|-------------|
| Mobile | <600px | Single column, stacked cards |
| Tablet | 600–1024px | 2-column grids |
| Desktop | 1024–1200px | Full multi-column layout |
| Large | >1200px | Centered, max content width |

### Collapsing Strategy
- Hero: 56px headline scales down, illustration stacks below
- Navigation: links collapse to hamburger menu, blue CTA persists
- Feature cards: 3-column → 2 → single column
- Section spacing: 96px → 48px on mobile

---

## Agent Prompt Guide

### Quick Color Reference
- Primary CTA: ReadMe Blue `{colors.primary}`
- Background: White `{colors.background}`
- Heading text: Ink `{colors.ink}`
- Body text: Gray 600 `{colors.gray-600}`
- Link: ReadMe Blue `{colors.primary}`
- Focus ring: `{colors.primary}`

### Example Component Prompts
- "Create a hero on white. Headline 56px Poppins weight 700, letter-spacing -1.5px, color `{colors.ink}`. Subtitle 20px Inter weight 400, color `{colors.gray-600}`. Blue pill CTA (`{colors.primary}`, 9999px radius, 12px 24px padding) and outline button (white, `{colors.primary}` border)."
- "Design a card: white background, `{colors.border-soft}` border, 24px radius, 24px padding. Title 22px Poppins weight 600. Body 17px Inter, `{colors.gray-600}`."
- "Build a pill badge: `{colors.primary-soft}` background, `{colors.primary-deep}` text, 9999px radius, 4px 12px padding, 13px Inter weight 500."
- "Create a code block: `{colors.code-bg}` background, `{colors.code-text}` JetBrains Mono 14px, 16px radius, 20px padding."

### Iteration Guide
1. Blue is the single signal color — everything else is neutral white/gray
2. Round everything generously — pills for actions, `{rounded.xl}`+ for cards
3. Poppins announces, Inter reads
4. Accent colors (purple/pink/green/yellow) belong in tags and illustration, never chrome
5. Code blocks stay dark to bridge marketing and product

---

## 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 ReadMe. Brand names and trademarks belong to their respective owners.