envsitter/site/DESIGN.md

# EnvSitter site design system

Source of truth for `site/`. Every color, size, radius, shadow, and motion value in `assets/styles.css` maps to a token here. Add the token here first, then use it. This file is excluded from the published Pages artifact.

## 0. Research Log

- Embedded references: shortlisted `vercel`, `linear.app`, `supabase` (developer tooling, monochrome, precise). Picked `vercel` as Layer B for its achromatic palette, shadow-as-border elevation stack, compressed display tracking, and mono technical labels, which suit a CLI security library. Layer A: `minimalist-skill` for macro whitespace, plain copy, and no gradient or emoji slop.
- Lazyweb real-product screens: skipped. The site is a two-page static docs landing whose content is fixed by the READMEs; no product-screen grammar was needed.
- StyleGallery spatial patterns: skipped. Both pages are scroll-the-document pages with no app shell; the document owns the scroll.
- Imagen concept drafts: skipped. The focal object is a typographic artifact (redacted env file plus terminal), rendered in HTML/CSS so it stays exact, accessible, and theme-aware.

## 1. Direction

A redacted dossier for developer infrastructure. The canvas is engineering white (deep graphite in dark mode), and the only "imagery" is the act of redaction: secret values appear as solid redaction bars while keys stay legible in mono. The memorable moment is the hero, where values are redacted in front of the visitor and a terminal beside them answers with keys and booleans only. Color is functional: green for a match or an allowed action, red for a blocked one, blue for fingerprints and focus.

## 2. Color tokens

All theme tokens use `light-dark()` with `color-scheme: light dark`, so one declaration serves both themes and the OS preference decides.

| Token | Light | Dark | Role |
|---|---|---|---|
| `--bg` | `#ffffff` | `#0a0a0a` | Page canvas |
| `--bg-subtle` | `#fafafa` | `#0f0f0f` | Alternate section band |
| `--surface` | `#ffffff` | `#141414` | Cards, panels |
| `--surface-2` | `#f5f5f5` | `#1c1c1c` | Inline code, chips, table header |
| `--text` | `#171717` | `#ededed` | Headings, primary text |
| `--text-2` | `#4d4d4d` | `#a3a3a3` | Body copy |
| `--text-3` | `#666666` | `#8f8f8f` | Captions, metadata (AA on both canvases) |
| `--ring` | `rgb(0 0 0 / 0.08)` | `rgb(255 255 255 / 0.10)` | Shadow-as-border |
| `--ring-strong` | `rgb(0 0 0 / 0.14)` | `rgb(255 255 255 / 0.18)` | Hover border, dividers |
| `--inner` | `#fafafa` | `rgb(255 255 255 / 0.03)` | Inner highlight ring in the card stack |
| `--redact` | `#171717` | `#e5e5e5` | Redaction bar ink |
| `--ok` | `#0f7b3d` | `#3fcf7f` | Match true, allowed |
| `--block` | `#c4291c` | `#ff7a6e` | Blocked, refused |
| `--hash` | `#0068d6` | `#5aa9ff` | Fingerprints, links |
| `--focus` | `hsl(212 100% 48%)` | same | Focus ring |

Terminal palette (dark in both themes, so the terminal reads as a real console): `--term-bg #0b0b0c`, `--term-bar #151517`, `--term-text #e6e6e6`, `--term-muted #8f8f94`, `--term-ok #3fcf7f`, `--term-block #ff7a6e`, `--term-hash #5aa9ff`, `--term-key #f2c46d` (keys in JSON output).

Atmosphere: hero dot grid `--dot` (`rgb(0 0 0 / 0.07)` / `rgb(255 255 255 / 0.06)`) masked to fade out, plus one radial glow `--glow` (`rgb(0 104 214 / 0.07)` / `rgb(90 169 255 / 0.08)`) behind the hero visual.

## 3. Typography

- `--font-sans`: `"Geist", ui-sans-serif, system-ui, -apple-system, "Segoe UI", sans-serif` (self-hosted variable woff2, OFL)
- `--font-mono`: `"Geist Mono", ui-monospace, "SF Mono", Menlo, Consolas, monospace` (self-hosted variable woff2, OFL)
- Ligatures on (`font-feature-settings: "liga"`); weights 400 read, 500 interact, 600 announce. No 700.

| Role | Size | Weight | Line height | Tracking |
|---|---|---|---|---|
| Display (h1) | `clamp(2.5rem, 4.2vw + 1rem, 4rem)` | 600 | 1.02 | `-0.045em` |
| Section (h2) | `clamp(1.75rem, 2vw + 1rem, 2.5rem)` | 600 | 1.1 | `-0.04em` |
| Card title (h3) | `1.25rem` | 600 | 1.3 | `-0.02em` |
| Lede | `clamp(1.0625rem, 0.4vw + 1rem, 1.25rem)` | 400 | 1.7 | normal |
| Body | `1rem` | 400 | 1.65 | normal |
| Small | `0.875rem` | 400/500 | 1.55 | normal |
| Eyebrow / label | `0.75rem` mono, uppercase | 500 | 1.3 | `0.08em` |
| Code | `0.8125rem` to `0.875rem` mono | 400 | 1.7 | normal |

## 4. Space, radius, elevation

- Spacing (4px base): `--s-1 4px`, `--s-2 8px`, `--s-3 12px`, `--s-4 16px`, `--s-5 24px`, `--s-6 32px`, `--s-7 48px`, `--s-8 64px`, `--s-9 96px`, `--s-10 128px`. Section padding `--section-y: clamp(64px, 9vw, 128px)`.
- Container: `--container: 1120px`, gutters `clamp(20px, 4vw, 32px)`.
- Radius: `--r-xs 4px` (inline code), `--r-sm 6px` (buttons), `--r-md 8px` (cards), `--r-lg 12px` (panels), `--r-pill 9999px` (badges only).
- Elevation (vercel shadow-as-border stack, never a CSS border on cards):
  - `--e-1`: `0 0 0 1px var(--ring)`
  - `--e-2`: `0 0 0 1px var(--ring), 0 2px 2px rgb(0 0 0 / 0.04)`
  - `--e-3`: `0 0 0 1px var(--ring), 0 2px 2px rgb(0 0 0 / 0.04), 0 12px 24px -12px rgb(0 0 0 / 0.12), inset 0 0 0 1px var(--inner)`
  - `--e-term`: `0 0 0 1px rgb(255 255 255 / 0.06), 0 24px 48px -24px rgb(0 0 0 / 0.45), 0 2px 6px rgb(0 0 0 / 0.10)`

## 5. Primitives and states

| Primitive | Anatomy | States |
|---|---|---|
| `.btn-primary` | `--text` fill, `--bg` text, `--r-sm`, 40px min height | hover: 85% fill; active: `scale(0.98)`; focus-visible: 2px `--focus` outline, 2px offset |
| `.btn-secondary` | `--surface` fill, `--e-1` ring | hover: `--ring-strong` ring; active, focus as above |
| `.copy-cmd` | mono command in a `--surface` box with `--e-2`, copy button on the right | button hidden until JS confirms clipboard support; copied: check glyph plus "Copied" announced through an `aria-live` region |
| `.card` | `--surface`, `--e-2`, `--r-md`, 24px to 32px padding | static (no hover lift: cards are not interactive) |
| `.card-link` | `.card` that is a link | hover: `--e-3`; focus-visible ring |
| `.badge` | pill, `--surface-2`, mono 12px uppercase | static |
| `.op` chip | mono op name plus one-line description | static |
| `.terminal` | window bar with three dots and a title, mono body lines `.ln-cmd`, `.ln-out`, `.ln-ok`, `.ln-block`, `.ln-muted` | static; horizontal scroll on narrow screens with a visible focusable region |
| `.envfile` | panel with key column and `.redact` bars | bars animate in once on load (see motion) |
| `.data-table` | hairline rows, `--surface-2` header | static |
| `.site-header` | sticky, translucent `--bg` with blur, hairline bottom | nav links: hover `--text`, current page `aria-current` |
| `.section-head` | eyebrow label plus h2 plus lede | static |

No coloured edge stripes anywhere: state is shown with tone (`--surface-2`), ink color, or glyphs.

## 6. Motion

- Redaction reveal (signature): `.redact` bars `transform: scaleX(0 -> 1)` from the left, 520ms `cubic-bezier(0.16, 1, 0.3, 1)`, staggered 90ms per row, after a 250ms delay. It demonstrates the product idea (values become bars) and runs once.
- Buttons: `transform` and `background-color` 150ms ease; `scale(0.98)` on active.
- Copy confirmation: glyph swap with `opacity` 150ms.
- `prefers-reduced-motion: reduce`: no transitions or animations; bars render in their final state.
- Only `transform` and `opacity` animate. No scroll-triggered reveals.

## 7. Responsive

- Breakpoints: `640px` (nav collapses to essentials, single column), `960px` (hero switches from stacked to two columns, grids to 2 or 3 columns).
- Hero visual stacks below the copy under 960px. Terminal and code blocks scroll horizontally inside their own focusable region instead of overflowing the page.
- Tap targets at least 40px; body text never below 16px.

## 8. Accessibility constraints and accepted debt

- WCAG AA contrast for all text tokens in both themes (verified pairs listed in section 2); terminal colors checked against `--term-bg`.
- Semantic landmarks (`header`, `nav`, `main`, `footer`), one `h1` per page, skip link, `aria-current="page"` on the active nav item.
- Redaction bars are decorative: each value cell has `aria-label="value hidden"` text for assistive tech.
- Every page works without JavaScript; JS only adds copy buttons.
- Accepted debt: no manual theme toggle (the OS preference decides); no search; content is duplicated from the READMEs and must be updated by hand when the tool surface changes.
- Accepted debt: Lighthouse mobile performance is 99 (simulated slow 4G with gzip: FCP 1.2s, LCP 1.8s, TBT 0, CLS 0); desktop is 100, and accessibility, best practices, and SEO are 100 on both. The last point needs the stylesheet inlined at deploy time, deferred to keep the site build-free. Dropping the Geist preload was measured and made FCP worse (1.7s), so the preload stays.