|
| 1 | +# Design — Arraylist |
| 2 | + |
| 3 | +A locked design system for this app. Every page redesign reads this file before |
| 4 | +emitting code. Do not regenerate per page — extend or amend this file when the |
| 5 | +system needs to grow. |
| 6 | + |
| 7 | +## Genre |
| 8 | + |
| 9 | +editorial |
| 10 | + |
| 11 | +## Macrostructure family |
| 12 | + |
| 13 | +- Home / index pages: **Index-First** — categorized link rows, hairline dividers, no hero cards |
| 14 | +- Content / docs pages: **Long Document** — single prose column (~65ch), inline section heads, side doc rail on lg+ |
| 15 | + |
| 16 | +## Theme |
| 17 | + |
| 18 | +- `--color-paper` oklch(14% 0.02 260) |
| 19 | +- `--color-paper-2` oklch(17% 0.025 260) |
| 20 | +- `--color-ink` oklch(88% 0.02 145) |
| 21 | +- `--color-ink-2` oklch(62% 0.04 145) |
| 22 | +- `--color-rule` oklch(26% 0.02 260) |
| 23 | +- `--color-accent` oklch(78% 0.19 145) |
| 24 | +- `--color-focus` oklch(78% 0.19 145) |
| 25 | + |
| 26 | +## Typography |
| 27 | + |
| 28 | +- Display: JetBrains Mono, weight 500, style normal |
| 29 | +- Body: JetBrains Mono, weight 400 |
| 30 | +- Mono: JetBrains Mono, weight 400 |
| 31 | +- Display tracking: -0.02em |
| 32 | +- Type scale anchor: `--text-display` = clamp(1.75rem, 3vw + 1rem, 2.75rem) |
| 33 | + |
| 34 | +## Spacing |
| 35 | + |
| 36 | +4-point named scale. Values live in `site/src/tokens.css`. Pages must use named |
| 37 | +tokens (`var(--space-md)`), never raw values. |
| 38 | + |
| 39 | +## Motion |
| 40 | + |
| 41 | +- Easings: cubic-bezier(0.16, 1, 0.3, 1) named `--ease-out` |
| 42 | +- Reveal pattern: none on pages; micro-interactions on buttons and copy only |
| 43 | +- Reduced-motion fallback: opacity-only, ≤ 150 ms |
| 44 | + |
| 45 | +## Microinteractions stance |
| 46 | + |
| 47 | +- Silent success on copy; no toasts |
| 48 | +- Hover delay 0 ms on nav links; focus ring instant |
| 49 | +- Copy button fades in on hover (desktop) or stays visible (touch) |
| 50 | + |
| 51 | +## CTA voice |
| 52 | + |
| 53 | +- Primary CTA: typographic link with arrow (`Quickstart →`), accent colour, 1px underline on hover |
| 54 | +- Secondary CTA: muted ink-2 link, same arrow pattern |
| 55 | + |
| 56 | +## Navigation & footer |
| 57 | + |
| 58 | +- Nav: **N8 Terminal command** — `> arraylist --home --docs --github` |
| 59 | +- Footer: **Ft4 Dense typographic** — colophon block in small mono |
| 60 | + |
| 61 | +## Per-page allowances |
| 62 | + |
| 63 | +- Home: Index-First link index only; no enrichment |
| 64 | +- Docs: Long Document prose; typography-only; no hero enrichment |
| 65 | +- 404: minimal prose + typographic links |
| 66 | + |
| 67 | +## What pages MUST share |
| 68 | + |
| 69 | +- Terminal dark palette and phosphor accent |
| 70 | +- JetBrains Mono across display, body, mono |
| 71 | +- N8 nav and Ft4 footer |
| 72 | +- Typographic link CTAs (no filled button blocks) |
| 73 | +- Hairline `--color-rule` dividers |
| 74 | + |
| 75 | +## What pages MAY differ on |
| 76 | + |
| 77 | +- Home uses full-width index rows; docs use 65ch prose + side rail |
| 78 | +- Docs page adds TOC and prev/next navigation |
| 79 | + |
| 80 | +## Exports |
| 81 | + |
| 82 | +### tokens.css |
| 83 | + |
| 84 | +See `site/src/tokens.css`. |
| 85 | + |
| 86 | +### Tailwind v4 `@theme` |
| 87 | + |
| 88 | +```css |
| 89 | +@theme { |
| 90 | + --color-paper: oklch(14% 0.02 260); |
| 91 | + --color-ink: oklch(88% 0.02 145); |
| 92 | + --color-accent: oklch(78% 0.19 145); |
| 93 | + --font-display: "JetBrains Mono", monospace; |
| 94 | + --font-body: "JetBrains Mono", monospace; |
| 95 | + --spacing-md: 1.5rem; |
| 96 | + --text-md: 1rem; |
| 97 | + --ease-out: cubic-bezier(0.16, 1, 0.3, 1); |
| 98 | +} |
| 99 | +``` |
| 100 | + |
| 101 | +### DTCG tokens.json |
| 102 | + |
| 103 | +```json |
| 104 | +{ |
| 105 | + "color": { |
| 106 | + "paper": { "$value": "oklch(14% 0.02 260)", "$type": "color" }, |
| 107 | + "ink": { "$value": "oklch(88% 0.02 145)", "$type": "color" }, |
| 108 | + "accent": { "$value": "oklch(78% 0.19 145)", "$type": "color" } |
| 109 | + }, |
| 110 | + "font": { |
| 111 | + "display": { "$value": "JetBrains Mono", "$type": "fontFamily" }, |
| 112 | + "body": { "$value": "JetBrains Mono", "$type": "fontFamily" } |
| 113 | + }, |
| 114 | + "space": { |
| 115 | + "md": { "$value": "1.5rem", "$type": "dimension" } |
| 116 | + } |
| 117 | +} |
| 118 | +``` |
| 119 | + |
| 120 | +### shadcn/ui CSS variables |
| 121 | + |
| 122 | +```css |
| 123 | +:root { |
| 124 | + --background: 14% 0.02 260; |
| 125 | + --foreground: 88% 0.02 145; |
| 126 | + --primary: 78% 0.19 145; |
| 127 | + --primary-foreground: 12% 0.03 145; |
| 128 | + --muted: 26% 0.02 260; |
| 129 | + --muted-foreground: 62% 0.04 145; |
| 130 | + --border: 26% 0.02 260; |
| 131 | + --input: 26% 0.02 260; |
| 132 | + --ring: 78% 0.19 145; |
| 133 | + --radius: 0.375rem; |
| 134 | +} |
| 135 | +``` |
0 commit comments