---
version: alpha
name: Making Software
description: Editorial reference-book aesthetic — warm paper-cream canvas with near-black ink, a single vermilion accent, grotesque-meets-serif typography, hairline rules, and a technical-diagram visual language that treats the page like a printed textbook on how software is built.
colors:
  # Canvas + ink
  background: "#f7f4ee"
  surface: "#ffffff"
  surface-soft: "#f1ede4"
  ink: "#16130f"
  ink-pure: "#000000"

  # Signature accent
  primary: "#e8401a"
  accent-hover: "#c8330f"
  accent-soft: "#fbe6df"

  # Secondary technical hues (diagram language)
  blue: "#2f6df0"
  green: "#1f9d57"
  yellow: "#f0b429"

  # Neutral scale (warm-tinted)
  gray-700: "#403a32"
  gray-600: "#5c554b"
  gray-500: "#7a7265"
  gray-400: "#a39a8b"
  gray-200: "#d8d1c4"
  gray-100: "#e7e1d6"

  # Lines + on-color
  hairline: "#ddd6c8"
  on-primary: "#ffffff"
  on-ink: "#f7f4ee"

  # Selection + focus
  selection-bg: "#fbe6df"
  focus-ring: "#e8401a"

typography:
  display-hero:
    fontFamily: "Spectral, Georgia, serif"
    fontSize: 56px
    fontWeight: 600
    lineHeight: 1.05
    letterSpacing: -1.12px
  section-heading:
    fontFamily: "Spectral, Georgia, serif"
    fontSize: 36px
    fontWeight: 600
    lineHeight: 1.15
    letterSpacing: -0.72px
  sub-heading:
    fontFamily: "Spectral, Georgia, serif"
    fontSize: 24px
    fontWeight: 500
    lineHeight: 1.30
    letterSpacing: -0.24px
  card-title:
    fontFamily: "Inter, Helvetica, Arial, sans-serif"
    fontSize: 18px
    fontWeight: 600
    lineHeight: 1.35
    letterSpacing: -0.18px
  eyebrow:
    fontFamily: "Inter, Helvetica, Arial, sans-serif"
    fontSize: 12px
    fontWeight: 600
    lineHeight: 1.20
    letterSpacing: 1.2px
  body-large:
    fontFamily: "Spectral, Georgia, serif"
    fontSize: 20px
    fontWeight: 400
    lineHeight: 1.65
    letterSpacing: 0px
  body:
    fontFamily: "Inter, Helvetica, Arial, sans-serif"
    fontSize: 17px
    fontWeight: 400
    lineHeight: 1.60
    letterSpacing: 0px
  body-small:
    fontFamily: "Inter, Helvetica, Arial, sans-serif"
    fontSize: 15px
    fontWeight: 400
    lineHeight: 1.50
    letterSpacing: 0px
  button-ui:
    fontFamily: "Inter, Helvetica, Arial, sans-serif"
    fontSize: 15px
    fontWeight: 500
    lineHeight: 1.20
    letterSpacing: 0px
  caption:
    fontFamily: "Inter, Helvetica, Arial, sans-serif"
    fontSize: 13px
    fontWeight: 500
    lineHeight: 1.40
    letterSpacing: 0px
  mono-label:
    fontFamily: "JetBrains Mono, ui-monospace, SFMono-Regular, Menlo, monospace"
    fontSize: 13px
    fontWeight: 500
    lineHeight: 1.40
    letterSpacing: 0px
  mono-caption:
    fontFamily: "JetBrains Mono, ui-monospace, SFMono-Regular, Menlo, monospace"
    fontSize: 11px
    fontWeight: 500
    lineHeight: 1.30
    letterSpacing: 0.5px

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

rounded:
  none: 0px
  xs: 3px
  sm: 5px
  md: 8px
  lg: 12px
  pill: 9999px

components:
  button-primary:
    backgroundColor: "{colors.primary}"
    textColor: "{colors.on-primary}"
    typography: "{typography.button-ui}"
    rounded: "{rounded.sm}"
    padding: 10px 20px
  button-primary-hover:
    backgroundColor: "{colors.accent-hover}"
    textColor: "{colors.on-primary}"
    typography: "{typography.button-ui}"
    rounded: "{rounded.sm}"
    padding: 10px 20px
  button-secondary:
    backgroundColor: "{colors.surface}"
    textColor: "{colors.ink}"
    typography: "{typography.button-ui}"
    rounded: "{rounded.sm}"
    padding: 10px 20px
    borderColor: "{colors.hairline}"
  button-ghost:
    backgroundColor: "{colors.background}"
    textColor: "{colors.ink}"
    typography: "{typography.button-ui}"
    rounded: "{rounded.sm}"
    padding: 10px 20px
  badge:
    backgroundColor: "{colors.accent-soft}"
    textColor: "{colors.primary}"
    typography: "{typography.mono-caption}"
    rounded: "{rounded.xs}"
    padding: 3px 8px
  card:
    backgroundColor: "{colors.surface}"
    textColor: "{colors.ink}"
    rounded: "{rounded.md}"
    padding: 24px
    borderColor: "{colors.hairline}"
  card-paper:
    backgroundColor: "{colors.surface-soft}"
    textColor: "{colors.ink}"
    rounded: "{rounded.md}"
    padding: 24px
    borderColor: "{colors.gray-100}"
  input:
    backgroundColor: "{colors.surface}"
    textColor: "{colors.ink}"
    typography: "{typography.body-small}"
    rounded: "{rounded.sm}"
    padding: 9px 12px
    borderColor: "{colors.hairline}"
  input-focus:
    backgroundColor: "{colors.surface}"
    borderColor: "{colors.focus-ring}"
  nav-bar:
    backgroundColor: "{colors.background}"
    textColor: "{colors.ink}"
    typography: "{typography.button-ui}"
    padding: 16px 24px
    borderColor: "{colors.hairline}"
  code-block:
    backgroundColor: "{colors.ink}"
    textColor: "{colors.on-ink}"
    typography: "{typography.mono-label}"
    rounded: "{rounded.md}"
    padding: 16px
  chapter-tag:
    backgroundColor: "{colors.background}"
    textColor: "{colors.gray-600}"
    typography: "{typography.eyebrow}"
    rounded: "{rounded.none}"
    padding: 0px 0px
---

# Making Software Design System

## Overview

Making Software is built to feel like a printed reference book that happens to live on the web — an editorial textbook about how software is actually made, from color and geometry to rendering and typography. The canvas is a warm paper-cream (`{colors.background}`) rather than clinical white, and the type is set in near-black warm ink (`{colors.ink}`). The effect is bookish and tactile: you are reading pages, not scrolling a marketing site. Every layout decision pushes toward legibility, generous measure, and the quiet authority of a well-set manual.

The typographic system is the heart of the identity: a refined serif (Spectral) carries headings and long-form reading passages, while a neutral grotesque (Inter) handles UI, labels, and captions. This serif-for-reading, sans-for-interface pairing mirrors how good textbooks separate the voice of the author from the apparatus of the page. A monospace (JetBrains Mono) appears for code, technical labels, and figure captions, reinforcing the subject matter without ever shouting.

Color is disciplined. The palette is overwhelmingly paper-and-ink, punctuated by a single signature vermilion (`{colors.primary}`) used for links, primary actions, and emphasis. A small set of secondary technical hues — blue, green, yellow — exists strictly as a diagram language for explanatory figures, never as decorative chrome. Structure comes from hairline rules (`{colors.hairline}`) rather than heavy boxes: thin lines divide sections, frame figures, and set tables, echoing the rules of a printed page.

**Key Characteristics:**
- Warm paper-cream canvas (`{colors.background}`) with near-black warm ink — bookish, not clinical
- Spectral serif for headings and reading; Inter grotesque for UI and labels
- A single vermilion accent (`{colors.primary}`) for links, CTAs, and emphasis
- Secondary technical hues reserved for explanatory diagrams only
- Hairline rules (`{colors.hairline}`) as the primary structural device
- Small, restrained radii (3–8px) — paper-flat, never glossy
- Monospace for code and figure captions, tying back to the subject matter

## Colors

### Primary
- **Paper** (`{colors.background}`): The warm cream canvas. The dominant surface.
- **Ink** (`{colors.ink}`): Near-black warm text for headings and body.
- **Vermilion** (`{colors.primary}`): The signature accent — links, primary buttons, emphasis.

### Accent
- **Vermilion Hover** (`{colors.accent-hover}`): Darker accent on hover/active.
- **Accent Soft** (`{colors.accent-soft}`): Tinted accent wash for badges and highlights.

### Technical Diagram Hues
- **Diagram Blue** (`{colors.blue}`): Figure annotations and code highlights.
- **Diagram Green** (`{colors.green}`): Positive/correct states in explanatory figures.
- **Diagram Yellow** (`{colors.yellow}`): Warnings and callouts in diagrams.

### Neutral Scale
- **Gray 700** (`{colors.gray-700}`): Strong secondary text.
- **Gray 600** (`{colors.gray-600}`): Body secondary, captions.
- **Gray 500** (`{colors.gray-500}`): Muted metadata.
- **Gray 400** (`{colors.gray-400}`): Placeholders, disabled.
- **Gray 200** (`{colors.gray-200}`): Soft dividers.
- **Gray 100** (`{colors.gray-100}`): Subtle surface tint borders.

### Lines & Surfaces
- **Hairline** (`{colors.hairline}`): The signature thin rule — section dividers, figure frames, table lines.
- **Surface** (`{colors.surface}`): White cards lifted off the paper.
- **Surface Soft** (`{colors.surface-soft}`): Tinted paper card.

## Typography

### Font Family
- **Serif (reading + headings)**: `Spectral`, with fallbacks `Georgia, serif`
- **Sans (UI + labels)**: `Inter`, with fallbacks `Helvetica, Arial, sans-serif`
- **Monospace (code + captions)**: `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 serif hero — book-cover impact |
| `section-heading` | Chapter / section titles |
| `sub-heading` | Sub-sections, figure titles |
| `card-title` | Card and list headings (sans) |
| `eyebrow` | Uppercase tracked labels above headings |
| `body-large` | Lead paragraphs, serif reading passages |
| `body` | Standard UI reading text (sans) |
| `body-small` | Compact UI text |
| `button-ui` | Buttons and links |
| `caption` | Metadata, tags |
| `mono-label` | Code, technical labels |
| `mono-caption` | Figure captions, fine print |

### Principles
- **Serif reads, sans operates**: long-form and headings use Spectral; interface and labels use Inter. Never mix the roles.
- **Generous measure and leading**: reading passages run at 1.6–1.65 line-height for textbook comfort.
- **Tracked uppercase eyebrows**: small Inter labels with positive letter-spacing mark section starts.
- **Mono for the subject**: code and figure captions stay monospace, reinforcing the technical voice.

## Layout

### Spacing System
The complete scale lives in the `spacing:` token block above. Base unit is 8px, with a generous editorial rhythm (`{spacing.3xl}`–`{spacing.4xl}`) between major sections.

### Grid & Container
- Max reading measure: approximately 720px for prose; ~1100px for full-width figures
- Single-column reading flow with figures breaking to wider widths
- Hairline rules separate sections instead of background color shifts

### Whitespace Philosophy
- **Page-like calm**: wide margins and generous leading make screens feel like book spreads.
- **Rules over boxes**: separation comes from `{colors.hairline}` thin lines, not heavy cards or shadows.
- **Figures earn width**: explanatory diagrams break the reading measure to command attention.

## Elevation & Depth

| Level | Treatment | Use |
|---|---|---|
| Flat (Level 0) | No shadow, paper canvas | Body text, sections |
| Hairline (Level 1) | `1px solid {colors.hairline}` | Dividers, figure frames, tables |
| Card (Level 2) | White surface + `1px solid {colors.hairline}` | Lifted content cards |
| Soft Shadow (Level 3) | `0 1px 3px rgba(22,19,15,0.06)` | Floating menus, sticky nav on scroll |

**Shadow Philosophy**: The system is paper-flat. Depth is communicated by hairline rules and subtle surface contrast (cream vs white), not glossy shadows. Where shadow appears it is whisper-soft and warm-tinted.

## Shapes

| Token | Value | Use |
|---|---|---|
| `none` | 0px | Rules, tags, full-bleed figures |
| `xs` | 3px | Badges, inline code |
| `sm` | 5px | Buttons, inputs |
| `md` | 8px | Cards, code blocks |
| `lg` | 12px | Featured figures |
| `pill` | 9999px | Status pills (rare) |

## Components

The full component spec lives in the `components:` token block above. Reference tokens directly (`{components.button-primary}`, `{components.card}`).

### Buttons
- **`button-primary`** — Vermilion fill, white text, 5px radius. The default CTA.
- **`button-secondary`** — White surface with hairline border.
- **`button-ghost`** — Transparent on paper, ink text.

### Badges
- **`badge`** — Soft accent wash, vermilion mono text, tight 3px radius.

### Cards
- **`card`** — White surface lifted off paper with a hairline border.
- **`card-paper`** — Tinted paper card for inset content.

### Inputs
- **`input`** — White surface, hairline border. Focus shifts the border to vermilion.

### Navigation
- **`nav-bar`** — Paper background, ink links, hairline bottom rule.

### Distinctive Components
- **Code Block**: Dark ink panel with paper-cream mono text — the one place the palette inverts.
- **Chapter Tag**: Uppercase tracked Inter eyebrow above section headings.
- **Figure Frame**: Diagrams framed by a single hairline rule with a mono caption beneath.

## Do's and Don'ts

### Do
- Use the warm paper canvas (`{colors.background}`), not pure white, for the page
- Pair Spectral serif for reading with Inter for UI
- Reserve vermilion (`{colors.primary}`) for links, CTAs, and emphasis only
- Separate sections with hairline rules (`{colors.hairline}`)
- Keep radii small (3–8px) — the system is paper-flat
- Use mono for code and figure captions

### Don't
- Don't use pure white as the page background — it breaks the bookish warmth
- Don't introduce the diagram hues (blue/green/yellow) into UI chrome — figures only
- Don't lean on heavy shadows or glossy depth
- Don't use the serif for buttons or dense UI labels
- Don't add a second accent color — vermilion is the only brand hue
- Don't use large pill radii on primary buttons

---

## Responsive Behavior

### Breakpoints
| Name | Width | Key Changes |
|------|-------|-------------|
| Mobile | <600px | Single column, reduced margins, figures full-bleed |
| Tablet | 600–1024px | Wider measure, side-by-side figure + caption |
| Desktop | 1024–1280px | Reading measure ~720px, figures break wider |
| Large | >1280px | Centered measure, generous outer margins |

### Touch Targets
- Buttons use comfortable 10px vertical padding
- Nav links spaced for tap comfort
- Inputs at 9px vertical padding

### Collapsing Strategy
- Hero: 56px serif scales down, retaining tight tracking
- Navigation: inline links → menu toggle on mobile
- Figures: break-to-wide on desktop → full-bleed on mobile
- Section spacing: `{spacing.4xl}` → `{spacing.2xl}` on mobile

### Image Behavior
- Figures keep hairline frames at all sizes
- Diagrams maintain aspect ratio and may horizontally scroll on mobile
- Captions stay in mono beneath figures

---

## Agent Prompt Guide

### Quick Color Reference
- Page background: Paper `{colors.background}`
- Heading + body text: Ink `{colors.ink}`
- Secondary text: Gray 600 `{colors.gray-600}`
- Primary CTA / link: Vermilion `{colors.primary}`
- Divider / border: Hairline `{colors.hairline}`
- Focus ring: Vermilion `{colors.focus-ring}`

### Example Component Prompts
- "Create a hero on paper-cream `{colors.background}`. Headline in Spectral serif 56px weight 600, line-height 1.05, letter-spacing -1.12px, color `{colors.ink}`. Lead paragraph in Spectral 20px weight 400, line-height 1.65, color `{colors.gray-700}`. Primary button: vermilion `{colors.primary}`, white text, 5px radius, 10px 20px padding."
- "Design a content card: white `{colors.surface}` background, 1px solid `{colors.hairline}` border, 8px radius, 24px padding. Title in Inter 18px weight 600, body in Inter 17px weight 400 color `{colors.gray-700}`."
- "Build a figure: framed by 1px solid `{colors.hairline}`, caption beneath in JetBrains Mono 11px weight 500, color `{colors.gray-600}`."
- "Create a code block: dark `{colors.ink}` panel, paper-cream `{colors.on-ink}` mono text, 8px radius, 16px padding, JetBrains Mono 13px."

### Iteration Guide
1. Start from paper, not white — the warm canvas is the foundation
2. Serif reads, sans operates, mono codes — keep the three roles strict
3. Vermilion is the only brand color; diagram hues stay inside figures
4. Hairline rules replace heavy boxes and shadows
5. Keep radii small and depth flat — this is a printed page, not a glossy app

---

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