# Interface Guide — Components, Responsive UX & Accessibility

The component and interaction canon for executionspace.com. Pairs with
[`DESIGN-GUIDE.md`](DESIGN-GUIDE.md) (motion/materials) and
[`CONTENT-DESIGN.md`](CONTENT-DESIGN.md) (editorial). Specimens are live on
[`design/index.html`](index.html) §05; production implementations live in
`_components/` and the `/web/` pages.

---

## 1 · Foundations

**Type** — Figtree for everything; DM Mono for code, tokens, and terminal idioms.
Scale from `es-tokens.css`: `--h0` (clamp 3.25–6rem) → `--xs` (.75rem). Body copy line-height
1.6–1.65; headings 0.95–1.1 with tight tracking (−.03 to −.04em).

**Color** — `--bg` white / `--bg-dark #1A1A1A` / `--bg-alt #2B2B2B`; text `#0A0A0A` on light,
`#F3F3F3` on dark; muted `#7A7A7A`; accent `#FFCD05`. Yellow is an *accent and a surface* —
never body text on white (contrast fails; see §5).

**Spacing** — section rhythm `--sy` (clamp 4.5–7.5rem); container `--maxw 1280px`;
gutter `--gut` (clamp 1.25–3rem). Cards use 1.25rem gaps.

**Radii** — pills `999px` (buttons/badges); panels `10–14px`; chips `8px`.

## 2 · Core components

| Component | Spec |
|---|---|
| **Button, primary** | yellow pill, `#231f20` text, 700 weight; hover: brightness 1.08 + 2px lift (`--t-quick`) |
| **Button, outline** | 1px `rgba(255,255,255,.4)` on dark; same hover behavior |
| **Nav** | fixed 70px, blur backdrop, scroll shadow at 20px; links get yellow underline scale-in (`--ease`) |
| **Card** | 1px hairline border, hover: −4px lift + yellow top-rule scale-in (`--t-move --eout`) |
| **Section label** | `[ label ]` — yellow brackets, uppercase `--xs`, .14em tracking (`.slabel`) |
| **Form field** | dark: `rgba(255,255,255,.08)` fill, 1.5px border, focus → accent border. No floating labels — placeholder + visible label or `aria-label` |
| **Version stamp** | DM Mono `build vX.X.X` in footer (per `VERSIONING.md`) |

Reveal convention: `.r` / `.in` via IntersectionObserver (threshold .1), staggered `d1–d3`
(80–90ms steps). New pages should use the `.m-*` primitives from `es-motion.css`.

## 3 · Responsive & mobile UX

- **Breakpoints (as built):** ~520px (single-column grids), ~720–760px (nav collapse, panel
  stacks), ~860px (sidebar layouts stack). Design content-out; these are guides, not walls.
- **Mobile-first behaviors:** single-column stacks; hero type scales via `clamp()` (no
  orphan-word headlines below 400px — check manually); sticky sidebars (`--svc-col`) release
  to static below 860px.
- **Tap targets:** ≥44×44px for anything interactive (nav links get padding, not just text
  height). Pills already comply.
- **The thumb rule:** primary CTA reachable without stretch — on long pages, repeat the CTA
  at the bottom (the "Ready to close the gap?" band is the pattern).
- **No horizontal scroll, ever.** Wide tables/code get their own `overflow-x: auto` container.
- **Hover is enhancement only** — every hover state has a non-hover equivalent (lifts and
  rules are decorative; information never lives only in hover).

## 4 · Performance posture

Zero-dependency is the house style: system-hosted fonts (Google Fonts is the only external),
inline SVG over image assets, CSS animation over JS, no frameworks. Budget: any page
interactive < 1s on 4G; animatics are vector (bytes, not megabytes); star fields cap at ~200
nodes. `transform`/`opacity` only in animation — never animate layout properties.

## 5 · Accessibility (WCAG 2.2 AA)

- **Contrast:** `#F3F3F3` on `#1A1A1A` ≈ 15:1 ✓ · `#231f20` on `#FFCD05` ≈ 9:1 ✓ ·
  `#0A0A0A` on white ✓. **Never** yellow text on white (≈1.6:1 ✗) or muted-on-muted below
  4.5:1. Muted `#7A7A7A` on white is 4.5:1 — body-size only, don't shrink it.
- **Motion:** `prefers-reduced-motion` collapses all animation (built into `es-motion.css` /
  `es-animatics.js`); no autoplaying motion longer than 5s without a pause affordance;
  nothing flashes more than 3×/s.
- **Keyboard:** everything reachable in DOM order; `:focus-visible` ring (2px accent outline,
  2px offset — add to any new component); no keyboard traps; eggs never intercept typing in
  form fields.
- **Semantics:** one `<h1>` per page; landmarks (`header/nav/main/footer`); decorative
  SVG/animatics get `aria-hidden="true"`, meaningful ones get `role="img"` + `aria-label`
  (already in the registry).
- **Forms:** visible labels or `aria-label`; errors announced in text (not color alone);
  `autocomplete` attributes on name/email.
- **Images:** meaningful images need real `alt`; decorative gradients/covers use empty `alt`
  or CSS backgrounds.

## 6 · Do / Don't

| Do | Don't |
|---|---|
| Use tokens for every duration/color/space | Hand-type `#FFD600`, `300ms`, `13px` |
| One overshoot max (`--espring`) | Bouncy/elastic loops |
| Bracket motif `[ ]` for labels & corners | Introduce new decorative glyphs |
| Repeat CTA at page end | Sticky-chase the user with CTAs |
| Dark sections carry texture | Texture on yellow surfaces |