# design.md — designtakes.com

> Machine-readable design decisions for designtakes.com. Written for humans and
> bots (LLMs, agents) to understand *what* the design is and *why*. The single
> source of truth for values is `src/styles/tokens.css`; this file explains them.
> Human version: https://designtakes.com/design

## Summary

- **Voice:** bold, editorial, type-led. Restraint over decoration.
- **Theme:** dark-only. One neutral dark-gray ground, one vermilion accent. No light theme, no theme toggle.
- **Type:** the whole system — display *and* body — is set in **Mg¹²** (atipo foundry).
- **Engineering:** Astro static output, Tailwind v4 + CSS custom-property tokens, zero client JS by default, WCAG AA.

## Principles

1. **Tokens, not magic values.** Every colour, type step, space, and radius is a CSS custom property in `tokens.css`. Components never hardcode values that belong in the token layer. Re-skinning the site means editing one file.
2. **Type-led.** Typography carries the design. Mg¹² is used everywhere; there is no secondary body face.
3. **Dark-only.** `color-scheme: dark`. The palette is neutral gray (deliberately not warm/brown), with a single accent.
4. **Zero client JS by default.** Islands/inline scripts only where interaction genuinely needs it (pull-down menu, carousel, hero-video reduced-motion gate).
5. **Accessibility is not optional.** AA contrast on all text pairs, visible focus states, one `<h1>` per page, `prefers-reduced-motion` respected, alt text required on hero media.

## Typography

- **Family:** Mg¹² by **atipo foundry**. Buy / licence: https://www.atipofoundry.com/fonts/mg12
- **Licence:** single-website webfont licence (woff2/woff/ttf), self-hosted from `/fonts/`. No desktop use.
- **Cuts:** Regular (400), Medium (500), Bold (700) — each with a matching Italic. Declared as real `@font-face` faces so weights/italics are never synthesised.
- **Roles:** headings & wordmark = Medium (500); body = Regular (400); `<strong>`/`<b>` = Bold (700); `<em>` = Italic.
- **Fluid scale** (`clamp()`, viewport-responsive), min → max:
  - `--step--2` 0.69 → 0.76rem — fine print, eyebrows
  - `--step--1` 0.83 → 0.94rem — meta, captions
  - `--step-0` 1.06 → 1.18rem — body
  - `--step-1` 1.27 → 1.48rem — lead
  - `--step-2` 1.52 → 1.85rem — H3 / pull quote
  - `--step-3` 1.83 → 2.31rem — H2
  - `--step-4` 2.20 → 2.89rem — section titles
  - `--step-5` 2.63 → 3.61rem — page titles
  - `--step-6` 3.16 → 4.50rem — large display
  - `--step-7` 3.79 → 5.60rem — hero display
  - `--step-hero` 2.85 → 8.50rem — signature oversized hero (breaks the scale on purpose)
- **Leading:** tight 0.98, snug 1.12, body 1.6. **Tracking:** tight −0.02em, display −0.025em, wide 0.08em.
- **Mono:** system UI monospace stack (`--font-mono`) for code, dates, and technical labels.

## Colour

Dark-only. Values are the source of truth in `tokens.css`.

| Token | Hex | Role |
|---|---|---|
| `--bg` | `#161617` | Page background (neutral dark gray) |
| `--surface` | `#1f1f21` | Raised cards, menu panel |
| `--surface-sunken` | `#101011` | Wells, code blocks |
| `--ink` | `#f2f2f3` | Primary text |
| `--muted` | `#a0a0a6` | Secondary / meta |
| `--line` | `#2b2b2e` | Hairlines |
| `--accent` | `#ff6a45` | Brand vermilion — large text, marks, focus |
| `--accent-ink` | `#ff8a6b` | AA-safe inline links / small text |
| `--accent-wash` | `#2a1815` | Faint accent fill |
| `--on-accent` | `#1a0e08` | Text on accent fill |

## Space, layout & shape

- **Spacing** (fluid clamps): `--space-3xs` … `--space-3xl` (0.25rem → up to 12rem).
- **Layout:** `--container` 78rem (max page), `--container-prose` 46rem (reading), `--measure` 68ch, `--gutter` fluid 1.15 → 3rem, `--nav-h` 4.75rem (reserved top space for the persistent wordmark).
- **Radii:** `--radius-xs` 3px, `--radius-sm` 6px, `--radius-md` 12px, `--radius-lg` 20px, `--radius-full` 999px.
- **Elevation:** `--shadow-sm/md/lg` (very soft; shadows are minimal on dark).

## Motion

- Durations: `--dur-fast` 140ms, `--dur-base` 260ms, `--dur-slow` 620ms.
- Easings: `--ease-out` cubic-bezier(0.2,0.7,0.2,1), `--ease-spring` cubic-bezier(0.34,1.4,0.5,1).
- All motion is disabled under `prefers-reduced-motion: reduce`.

## Signature components

- **Navigation:** the wordmark is the only persistent chrome — centered, always present, shrinks on scroll. Hover reveals a small "Menu" hint with a chevron each side. Click pulls a full-width panel down and pushes the page down to meet it: a big centered trio (Home · All articles · About) over a small row (RSS · GitHub · Design).
- **Homepage:** one full-screen horizontal carousel. First slide is the latest post (with its hero video); up to four posts, then a "See all" card. Each slide has a "Read ↓" and "See all articles ↑" cue.
- **Hero media:** full-bleed background image or looping muted video (poster required). Autoplay is gated on `prefers-reduced-motion`.

## Colophon / built with

- **Licence:** open source under the **MIT licence**. © Design Takes.
- **Framework:** Astro 5, `output: 'static'` (fully prerendered), TypeScript (strict). Zero client JS by default; small inline islands only where interaction needs it.
- **Styling:** Tailwind CSS v4 (CSS-first) layered over `src/styles/tokens.css` design tokens.
- **Type:** self-hosted Mg¹² by atipo foundry (woff2/woff/ttf) — https://www.atipofoundry.com/fonts/mg12
- **Hosting:** Cloudflare Workers static assets, served from the Cloudflare edge; DNS on Cloudflare.
- **Content:** Markdown posts in Astro content collections; reader feedback curated from GitHub Discussions at build time.
- **Package manager:** pnpm. **CI/CD:** GitHub Actions → `wrangler deploy`.
- **Source:** https://github.com/Design-takes/designtakes

## Non-goals

- No light theme. No theme toggle. No warm/brown tones.
- No second body typeface. No icon fonts as decoration.
- No client-side framework runtime; no tracking analytics.

_Last reviewed against `tokens.css` — keep in sync when tokens change._