|
| 1 | +# Terminal-native redesign — design spec |
| 2 | + |
| 3 | +**Date:** 2026-06-15 |
| 4 | +**Status:** Approved (vibe confirmed via `design-demo/` prototype) |
| 5 | +**Scope:** Whole-site visual redesign (home, explore, config cards, docs, header, footer, shared shell) |
| 6 | + |
| 7 | +## 1. Direction |
| 8 | + |
| 9 | +Refined, terminal-native identity executed with **restraint** — the register is "high-end, |
| 10 | +textured, not flashy, no AI-smell," in the spirit of Vercel / pi.dev. Fully monospace, dark-first |
| 11 | +with a deliberate light mode. The terminal is the brand's visual *language* (prompts, carets, mono, |
| 12 | +command-style labels), not literal cosplay — sections are clean web layouts with **one** real |
| 13 | +terminal window as the signature moment. |
| 14 | + |
| 15 | +**Anti-goals (the "AI-smell" to avoid):** purple/blue gradients, gradient blobs, heavy neon glows, |
| 16 | +over-rounded everything, evenly-distributed timid color, flat digital surfaces, emoji UI. |
| 17 | + |
| 18 | +**Reference prototype:** `design-demo/index.html` (throwaway). The production build reproduces this |
| 19 | +look using the project's CSS-variable system and Svelte components. The demo is the source of truth |
| 20 | +for the visual target. |
| 21 | + |
| 22 | +## 2. Design tokens |
| 23 | + |
| 24 | +Re-map values onto the **existing** token names in `src/lib/styles/variables.css` (so components |
| 25 | +don't all need editing), and add the new tokens listed. Pure white text is intentionally retired in |
| 26 | +favor of a soft off-white for a premium feel. |
| 27 | + |
| 28 | +### Dark (default) |
| 29 | +``` |
| 30 | +--bg-primary: #0a0a0b (was #0a0a0a) |
| 31 | +--bg-secondary: #100f12 surface (cards, terminal, command box) |
| 32 | +--bg-tertiary: #161519 surface-2 (code blocks, raised) |
| 33 | +--bg-hover: #1b1a1f |
| 34 | +--text-primary: #ededf0 soft white, not #ffffff |
| 35 | +--text-secondary:#9a99a2 |
| 36 | +--text-muted: #5b5a63 |
| 37 | +--accent: #4ec98a refined mint (was neon #22c55e) |
| 38 | +--accent-hover: #6ad9a0 |
| 39 | +--accent-glow: rgba(78,201,138,0.10) (lower than before) |
| 40 | +--border: #1f1e22 |
| 41 | +--border-hover: #2c2b30 |
| 42 | +--code-bg: #161519 |
| 43 | +--header-bg: rgba(10,10,11,0.78) |
| 44 | +--danger: #d4655c refined red |
| 45 | +--danger-hover: #c0473d |
| 46 | +/* new */ |
| 47 | +--accent-deep: #2f6b4d muted prompt / subtle ring |
| 48 | +--amber: #c9a14e secondary terminal color (warnings/steps) |
| 49 | +--shadow: rgba(0,0,0,0.5) |
| 50 | +--vignette: color-mix(in srgb, var(--bg-primary) 55%, #000) |
| 51 | +--grain-blend: soft-light |
| 52 | +--grain-opacity:0.05 |
| 53 | +``` |
| 54 | + |
| 55 | +### Light ("paper terminal") |
| 56 | +``` |
| 57 | +--bg-primary: #fafaf8 warm off-white (was stark #ffffff) |
| 58 | +--bg-secondary: #ffffff |
| 59 | +--bg-tertiary: #f3f3f0 |
| 60 | +--bg-hover: #ecece7 |
| 61 | +--text-primary: #18181b |
| 62 | +--text-secondary:#5b5b60 |
| 63 | +--text-muted: #909095 |
| 64 | +--accent: #1c7d52 deep green, AA on light |
| 65 | +--accent-hover: #176343 |
| 66 | +--accent-glow: rgba(28,125,82,0.08) |
| 67 | +--border: #e7e7e2 |
| 68 | +--border-hover: #d6d6cf |
| 69 | +--code-bg: #f3f3f0 |
| 70 | +--header-bg: rgba(250,250,248,0.78) |
| 71 | +--danger: #c0473d |
| 72 | +--danger-hover: #a83a31 |
| 73 | +/* new */ |
| 74 | +--accent-deep: #cde7d9 |
| 75 | +--amber: #946a1a |
| 76 | +--shadow: rgba(20,20,30,0.10) |
| 77 | +--vignette: transparent |
| 78 | +--grain-blend: multiply |
| 79 | +--grain-opacity:0.035 |
| 80 | +``` |
| 81 | + |
| 82 | +## 3. Typography — fully monospace |
| 83 | + |
| 84 | +- **Family:** Geist Mono (primary) → JetBrains Mono (fallback, already loaded) → system mono. |
| 85 | + Add a `--font-mono` token; set it as the global body font. |
| 86 | +- **Loading:** In `src/app.html`, replace the `Outfit` Google Fonts request with `Geist Mono` |
| 87 | + (weights 400/500/600). Keep `JetBrains Mono`. Outfit is removed entirely. |
| 88 | +- **Hierarchy comes from size / weight / color / case** (one family, no font-switching): |
| 89 | + |
| 90 | +| Role | Size | Weight | Tracking | Notes | |
| 91 | +|------|------|--------|----------|-------| |
| 92 | +| Display (h1) | clamp(2.3rem, 4.6vw, 3.7rem) | 500 | -0.04em | line-height 1.04 | |
| 93 | +| h2 | 1.7rem | 500 | -0.025em | | |
| 94 | +| h3 | ~1rem | 500 | -0.01em | | |
| 95 | +| Body | 0.94rem | 400 | — | line-height 1.7, max-width ≤ 54–62ch | |
| 96 | +| Label / eyebrow | 0.72–0.8rem | 400/500 | 0.02–0.1em | often lowercase or `#`/`>`-prefixed, uppercase for footer col heads | |
| 97 | + |
| 98 | +**Fully-mono readability guardrails (hard rules):** body line-height ≥ 1.7; text measure ≤ 62ch; |
| 99 | +body size ≥ 15px (0.94rem). These keep mono prose comfortable. |
| 100 | + |
| 101 | +## 4. Texture, depth & motion |
| 102 | + |
| 103 | +- **Film grain:** fixed full-viewport SVG fractal-noise overlay (`body::after`), `mix-blend-mode` |
| 104 | + and opacity per `--grain-blend` / `--grain-opacity`. This is the primary "texture." Add to the |
| 105 | + layout shell. |
| 106 | +- **Vignette:** subtle radial darkening at page edges in dark mode only (`--vignette`); transparent |
| 107 | + in light. |
| 108 | +- **Grid:** faint graph-paper grid behind the hero only, radial-masked, ~0.4 opacity. Not site-wide. |
| 109 | +- **Depth:** hairline 1px borders + soft low shadows (`--shadow`). No large lifts, no neon. |
| 110 | +- **Motion:** 150–250ms ease-out. Hover = border brightens + faint `--accent-glow` ring + ≤1px |
| 111 | + nudge. One on-scroll reveal (fade + 8px rise, once). Hero terminal auto-types. **All motion |
| 112 | + (typing, reveals, caret) disabled under `prefers-reduced-motion`** — terminal renders final state. |
| 113 | + |
| 114 | +## 5. Component / file changes |
| 115 | + |
| 116 | +Project uses **pure CSS + scoped `<style>` + CSS variables**, no Tailwind. Footer currently lives in |
| 117 | +`src/routes/+page.svelte`. |
| 118 | + |
| 119 | +| File | Change | |
| 120 | +|------|--------| |
| 121 | +| `src/lib/styles/variables.css` | New token values + added tokens (§2). | |
| 122 | +| `src/app.html` | Swap Outfit→Geist Mono in the fonts link. | |
| 123 | +| `src/routes/+layout.svelte` | Global body font → `--font-mono`; add grain + vignette overlays; base type rhythm; `prefers-reduced-motion` reset. | |
| 124 | +| `src/lib/components/SiteHeader.svelte` | Terminal status-bar style: `$ openboot` (green prompt), lowercase mono nav, `★ 256`, refined ☾/☀ toggle, hairline border + blur. | |
| 125 | +| `src/routes/+page.svelte` | Hero (mono display headline w/ green on key phrase, `#`-eyebrow, ✓ list, hairline click-to-copy command box w/ caret, signature auto-typing terminal, masked grid bg); How It Works (prompt header `> how it works`, hairline-divided 4-cell grid, quiet `01–04`, hover fill); Footer (`openboot $ _` prompt + caret, mono link columns, legal line). Tighten section rhythm. | |
| 126 | +| `src/routes/explore/+page.svelte` | `> explore` prompt header; mono sort control; raise muted-text contrast; spacing rhythm. | |
| 127 | +| `src/lib/components/ConfigCard.svelte` | Mono throughout; keep colored top accent but unify into the terminal language; green stats; badges as `[featured]`/`[official]`; bottom install line w/ copy; hover = border + faint glow. | |
| 128 | +| Docs styles (mdsvex/docs layout) | Mono prose w/ readability guardrails; code blocks on `--bg-tertiary` w/ left green border; sidebar active item w/ `>` marker. | |
| 129 | + |
| 130 | +## 6. Accessibility |
| 131 | + |
| 132 | +- All text/background pairs meet **WCAG AA** (the new `--text-muted` and light-mode `--accent` are |
| 133 | + chosen for this; verify with a contrast check during build). |
| 134 | +- Full `prefers-reduced-motion` support (§4). |
| 135 | +- Keep keyboard focus styles; command/terminal copy actions remain reachable. |
| 136 | + |
| 137 | +## 7. Quality (non-visual, in-scope) |
| 138 | + |
| 139 | +- Investigate & fix the **2–3 console errors** seen on the live site during this pass. |
| 140 | + |
| 141 | +## 8. Out of scope / non-goals |
| 142 | + |
| 143 | +- No new pages, features, or copy rewrites beyond micro-labels (prompts, eyebrows). Marketing |
| 144 | + copywriting is a separate effort. |
| 145 | +- No backend / API / DB changes. |
| 146 | +- No framework or build-system changes (still SvelteKit + scoped CSS, no Tailwind). |
| 147 | +- `design-demo/` is a throwaway and is removed (or git-ignored) before merge. |
| 148 | +- Self-hosting Geist Mono (vs Google Fonts) is a possible later perf optimization, not this pass. |
| 149 | + |
| 150 | +## 9. Success criteria |
| 151 | + |
| 152 | +- Home, explore, docs, header, footer, config cards all render in the new terminal-native system, |
| 153 | + dark + light, both deliberate. |
| 154 | +- `npm run validate` (check + lint + test) passes. |
| 155 | +- Visual parity with the approved `design-demo/` look on the home page. |
| 156 | +- No remaining console errors on the main pages. |
| 157 | +- Target subjective quality: ~9/10 per the original critique's gap list, all six gaps closed. |
0 commit comments