|
| 1 | +# Design — btravstack · "Beetroot Nocturne" |
| 2 | + |
| 3 | +A locked design system for the btravstack org (landing + `@btravstack/theme` + |
| 4 | +the four docs sites). Every page redesign reads this file before emitting code. |
| 5 | +Do not regenerate per page — extend or amend this file when the system needs to |
| 6 | +grow. |
| 7 | + |
| 8 | +**The idea.** The original identity, elevated. A deep plum canvas built for the |
| 9 | +dark, two warm beetroot blooms, a weighty geometric sans, elevation through |
| 10 | +lightness instead of borders, warm glow on interaction, and the gradient |
| 11 | +mascot floating as the one character moment per page. (This is the dark |
| 12 | +atmospheric candidate — the sibling of "Beetroot Atlas" on |
| 13 | +`design/beetroot-atlas`; one of the two ships.) |
| 14 | + |
| 15 | +## Genre |
| 16 | + |
| 17 | +atmospheric. Vibe: *"late-night plum, warm bloom, velvet, exact"*. |
| 18 | + |
| 19 | +## Macrostructure family |
| 20 | + |
| 21 | +- Marketing pages (landing): **Marquee Hero** — the fold is the canvas |
| 22 | + (mascot + one statement + scroll cue, nothing else), a thick accent-wash |
| 23 | + rule, then intro + CTAs, elevated package panels, quiet numbered columns, |
| 24 | + a bloom-lit "why now" cluster, inspiration cards, closing CTA. |
| 25 | +- Docs sites (VitePress content): default VitePress layout wearing the theme |
| 26 | + tokens — floating hero mark, one ambient bloom top-right, elevated feature |
| 27 | + cards with glow hover. |
| 28 | +- Nav: **N5 floating pill** — content-sized, detached, blur backdrop over the |
| 29 | + bloom. |
| 30 | +- Footer: **Ft5 statement** — one large display sentence + a quiet meta row. |
| 31 | + |
| 32 | +## Theme |
| 33 | + |
| 34 | +**Dark "nocturne" is canonical** — the page is built for the dark. Light is |
| 35 | +the daylight fallback on `:root:not(.dark)`. |
| 36 | + |
| 37 | +| Token | Dark (canonical) | Light | |
| 38 | +| --- | --- | --- | |
| 39 | +| `--bg` (canvas) | `oklch(17% 0.024 305)` deep plum | `#FBF7F9` warm near-white | |
| 40 | +| `--card` | `oklch(20.5% 0.026 305)` — elevation step 1 | `#FFFFFF` | |
| 41 | +| `--card-soft` | `oklch(24% 0.027 305)` — elevation step 2 | `#F0E6EC` | |
| 42 | +| `--text` | `oklch(94% 0.008 340)` | `#1F0E18` | |
| 43 | +| `--accent` | **#E0589A** = `oklch(65.5% 0.182 353)` — THE knob | same (fills stay vibrant) | |
| 44 | +| `--text-accent` | `var(--accent)` (reads on plum) | accent darkened 26% (AA) | |
| 45 | +| `--bloom` / `--bloom-2` | accent at 15% / deep at 13% — radial only | 11% / 8% | |
| 46 | + |
| 47 | +**One-knob rebrand is contractual.** Docs sites override only `--accent` |
| 48 | +(`:root:root { --accent: … }`); every derived shade — including the blooms — |
| 49 | +flows via `color-mix`. amqp `#FF6600` · temporal `#6B76F2` · unthrown |
| 50 | +`#46B86C` · demesne `#B45CE0`. |
| 51 | + |
| 52 | +Bloom discipline: at most two per page, radial, fixed, never animated, |
| 53 | +~20–30% footprint each. Accent fills only on pill CTAs and small tags. |
| 54 | + |
| 55 | +## Typography |
| 56 | + |
| 57 | +- Display + body: **Geist** — one weighty family (display 600/700, tracking |
| 58 | + −0.03em; body 400/500). The single-family voice is the atmospheric register. |
| 59 | +- Mono (outlier): **JetBrains Mono** — code, identifiers, numerals, star counts. |
| 60 | +- Statement scale: `--fs-hero: clamp(42px, 5.5vw + 12px, 84px)`. |
| 61 | +- Never italic headers, never gradient text. |
| 62 | + |
| 63 | +## Spacing / shape |
| 64 | + |
| 65 | +Named px scale in `packages/theme/src/tokens.css` (`--space-1…6`). Corners: |
| 66 | +rounded (12–16px cards, 999px pills). **No hairline card borders** — elevation |
| 67 | +comes from surface lightness (`--card`, `--card-soft`); hairlines only as |
| 68 | +page-level dividers. Shadows: darkness for depth at rest, warm accent glow |
| 69 | +(`--shadow-accent`) on hover. |
| 70 | + |
| 71 | +## Motion |
| 72 | + |
| 73 | +- Easings: `--ease: cubic-bezier(0.16, 1, 0.3, 1)`; durations ≤ 0.2s. |
| 74 | +- Three primitives: the mascot bob (character moment), hover lift + glow on |
| 75 | + interactive cards, the copy toast. Fade only otherwise — no slide, no bounce. |
| 76 | +- Blooms never move. Reduced-motion: bob stops, transitions collapse. |
| 77 | + |
| 78 | +## Microinteractions stance |
| 79 | + |
| 80 | +- Silent success (copy button → small mono toast, 1.6s). |
| 81 | +- Hover tooltips 800ms · focus 0ms. Focus rings instant, 2px accent. |
| 82 | + |
| 83 | +## CTA voice |
| 84 | + |
| 85 | +- Primary: confident accent-filled pill, ink text, Geist 600. One per view. |
| 86 | +- Secondary: outlined pill, transparent fill. |
| 87 | + |
| 88 | +## Logos |
| 89 | + |
| 90 | +The original soft gradient marks are the canon here — they were drawn for |
| 91 | +this dark canvas (mascot, rabbit, hourglass, no-throw, shield). Keep the |
| 92 | +gradients; keep the rounded warmth. |
| 93 | + |
| 94 | +## What pages MUST share |
| 95 | + |
| 96 | +- The wordmark voice (Geist 700, "btrav" in accent + "stack" in ink). |
| 97 | +- The one-knob accent architecture and bloom discipline. |
| 98 | +- Geist + JetBrains Mono, pill CTAs, elevation-not-borders. |
| 99 | +- Exactly one character moment (the floating mascot) per page. |
| 100 | + |
| 101 | +## What pages MAY differ on |
| 102 | + |
| 103 | +- Macrostructure within the family (a future page may be Feature Stack or |
| 104 | + Split Studio — still wearing this theme). |
| 105 | +- Per-site accent hue (docs sites) — blooms recolor automatically. |
| 106 | +- Docs sites keep VitePress's functional layout; only the dress is shared. |
| 107 | + |
| 108 | +## Exports |
| 109 | + |
| 110 | +### tokens.css |
| 111 | +The canonical export lives at `packages/theme/src/tokens.css` (published as |
| 112 | +`@btravstack/theme`). It is the single source of truth; do not duplicate here. |
| 113 | + |
| 114 | +### Quick-reference (other projects) |
| 115 | +```css |
| 116 | +:root { |
| 117 | + --color-paper: oklch(17% 0.024 305); |
| 118 | + --color-ink: oklch(94% 0.008 340); |
| 119 | + --color-accent: #E0589A; |
| 120 | + --font-display: "Geist", sans-serif; |
| 121 | + --font-body: "Geist", sans-serif; |
| 122 | + --font-mono: "JetBrains Mono", monospace; |
| 123 | + --ease: cubic-bezier(0.16, 1, 0.3, 1); |
| 124 | + --radius-card: 16px; |
| 125 | +} |
| 126 | +``` |
0 commit comments