# Meridian - design system

An example design-system file, structured the way an AI design tool
(and any new teammate) can read and follow it. Replace the values with
your own; keep the sections. The brand here - "Meridian" - is
fictional.

This file follows one rule above all others: **write values, not
vibes.** Every decision is stated as something a stranger could apply
without asking.

---

## Typography

- **Display / headings:** "Fraunces Alternative", serif. Weight 400
  only. Used for h1-h3 and pull quotes. Italic carries the accent
  color (see Color palette).
- **Body:** "Inter Tight", sans-serif. Weights 400 (body), 500
  (emphasis), 600 (buttons, labels).
- **Mono:** "JetBrains Mono". Weight 400-500. Used for eyebrows,
  labels, code, and metadata rows only - never body copy.

### Scale (px)

| Step | Size | Line-height | Use |
| --- | --- | --- | --- |
| display | 96 | 0.96 | Page hero only |
| h1 | 56 | 1.05 | Section titles |
| h2 | 34 | 1.15 | Sub-sections |
| lead | 21 | 1.5 | Opening paragraphs |
| body | 16.5 | 1.6 | Default text |
| small | 13.5 | 1.55 | Captions, cards |
| micro | 11 | 1.4 | Mono labels; letter-spacing 0.14em, uppercase |

- Letter-spacing: -0.025em on display/h1, -0.012em on h2, 0 on body.
- Minimum body size anywhere: 16px. Never ship smaller body text.

## Color palette

Dark is the default theme. All values are tokens; components reference
the token name, never the hex.

### Dark theme (default)

| Token | Value | Role |
| --- | --- | --- |
| --bg | #141311 | Page background |
| --surface | #1d1b18 | Cards, panels |
| --fg | #ece7df | Primary text |
| --muted | #8f887c | Secondary text, labels |
| --accent | #d97757 | The one accent - links, highlights, markers |
| --accent-ink | #e08b6d | Accent used AS text on dark bg (contrast-safe) |
| --border | #2c2925 | Hairlines, card borders |
| --code-bg | #201e1a | Code blocks |

### Light theme

| Token | Value | Role |
| --- | --- | --- |
| --bg | #faf8f5 | Page background |
| --surface | #ffffff | Cards, panels |
| --fg | #26231f | Primary text |
| --muted | #6b655c | Secondary text, labels |
| --accent | #d97757 | Same accent, both themes |
| --accent-ink | #b0653f | Accent as text on light bg (contrast-safe) |
| --border | #e5dfd6 | Hairlines, card borders |
| --code-bg | #f1ede6 | Code blocks |

- Every text/background pair above meets WCAG AA (4.5:1 body, 3:1
  large text). New pairs must be checked before use.
- There is exactly ONE accent. Do not introduce a second accent hue.

## Spacing scale

8px base. Legal steps only: **4, 8, 12, 16, 24, 32, 48, 64, 96**.

- Card padding: 24-32.
- Section vertical padding: 96 desktop, 48 mobile.
- Gap between cards in a grid: 16.
- No off-scale values. If a layout seems to need 20px, use 16 or 24.

## Radius scale

| Token | Value | Use |
| --- | --- | --- |
| --radius-s | 6px | Chips, inputs, code spans |
| --radius-m | 12px | Buttons |
| --radius-l | 16px | Cards, panels |

Never fully-round rectangles (no pill cards). Avatars are circles.

## Component recipes

### Button

- Primary: bg --accent, text #fff, radius --radius-m, padding 12x24,
  weight 600, size 15px. Hover: darken accent 8%, translateY(-1px).
- Secondary: transparent bg, 1px --border, text --fg. Hover: border
  becomes --accent.
- One primary button per view, maximum.

### Card

- bg --surface, 1px --border, radius --radius-l, padding 24-32.
- Hover (when clickable): translateY(-3px), border-color --accent at
  40% mix, 250ms ease.
- Card title in display serif; meta row in mono micro style.

### Nav

- Top bar, height 72, bg --bg with 1px --border bottom.
- Links: body size 14, --muted, hover --fg. Active page: --fg with
  2px --accent underline offset 6px.

### Form input

- bg --surface, 1px --border, radius --radius-s, padding 10x14.
- Focus: border --accent plus 3px accent ring at 25% opacity.
- Labels above the field, mono micro style. Never placeholder-as-label.

## Motion

- Standard transition: 200-250ms, ease-out (cubic-bezier(0.2, 0.6,
  0.2, 1)).
- Hover moves are small: 1-3px translate, never scale above 1.02.
- No infinite looping animation on content.
- Respect prefers-reduced-motion: all movement collapses to opacity.

## Accessibility constraints

- Contrast: WCAG AA minimum everywhere; AAA (7:1) for long-form body.
- Focus: visible focus ring on every interactive element - 2px
  --accent outline, offset 2px. Never remove outlines without a
  replacement.
- Hit targets: 44x44px minimum on touch surfaces.
- Color is never the only signal - pair state colors with an icon or
  label.

## Hard rules

Things that must never change, and mistakes we never want to see:

1. Dark mode is the default theme.
2. One accent color. No gradients as backgrounds.
3. No em or en dashes in copy - use a plain hyphen with spaces.
4. No emoji in UI copy.
5. Serif is for display only - never set body copy in the serif.
6. Never use pure #000 or pure #fff as a background.
7. Photography is duotone-warm; no stock-photo blue.
8. Buttons are never all-caps.