DESIGN.md native UI contract (upstream 9daaa947)

[evilchinesefood]

Part of #417 (upstream main after v0.11.0). Upstream commit 9daaa947 docs(design): define the native UI contract (DESIGN.md, 660 lines, plus a line in AGENTS.md); later upstream commits (e31cf649, f587f7fc, 2bd69011, 6003ae11, 40489933, fbfefd25, db6c40d2) each amend it. Land after #438 is decided: the document's dock and Review metrics assume upstream's shape.

What upstream did

DESIGN.md is a normative MUST / SHOULD / MAY contract for the native GPUI app with a status vocabulary (Canonical / Contextual / Migration / Proposed) and an authority order (product intent > Canonical rule > shared primitives > local render code); any visual change must update the document in the same PR. Thesis: a "cockpit" where the pane grid is the content and the chrome recedes:

• Quiet: hue-free neutrals, accent only on links, focus and one primary action, translucent washes. Continuous: squircle corners, no separators between chips or tabs, interpolated hover. Native: client-side decorations with platform caption glyphs, AppKit sidebar material on macOS (Mica on Windows 11, KDE blur on Linux).
• Fixed tokens: semantic UiColors roles with a hex per variant, an alpha-tint table, radius / spacing / size tables, typography (Geist; 12 body / 11 label / 9–10 micro / 14 title / 26 heading, sentence case), icon sizes 10–20 painted with text_color, motion gated on reduce_motion.
• Component contracts for the title bar, sidebar, pane card, diff dock and Review, Settings, menus, Launch Pad and Composer, toasts. Bans: drop shadows on chrome, tab separators, identity pills, hue in neutrals, new radii or text sizes, per-component light/dark branching.
• Section 9 is a seven-point delivery gate (three themes in both variants, material on and off, reduce_motion, 800 × 500, truncation, control states, a PR screenshot). Outline: 1 Contract · 2 Thesis · 3 Anatomy · 4 Foundations · 5 Component Contracts · 6 Interaction · 7 Platform Materials · 8 What Not To Do · 9 Delivery Gate · 10 Known Gaps.

What the fork has

• No DESIGN.md; nothing under docs/, CLAUDE.md or AGENTS.md is a design contract. Partial, non-normative coverage only: CLAUDE.md "Styling conventions" (inline builder API, hardcoded chrome colours unless UiColors, the 36-slot TerminalTheme + APCA selection_foreground), plus the menu, keybinding and theme notes.
• Fork facts the document would contradict as written: it is macOS-only (cut §7's Mica and Wayland material sections and the cross-platform caption-glyph rules); its §3.1 / §5.4 dock metrics (880 default / 360 min / 1400 max, 300 px right rail) conflict with the fork's live-remainder dock clamp (7c15bdaa, 7799e2b4, feat: #184 Phase 4 - diff dock per tab, width clamped to the live remainder #193) and with the 250 px in-dock tree of File tree inside the editor dock instead of a rail (upstream 2bd69011) #437; the fork's accessibility work ([deep-review] [S2] shared icon_button has no Role or accessible name (src-app/src/ui_primitives.rs) #316, [deep-review] [S2] sidebar toggle has a tooltip but no button role (src-app/src/window_chrome/title_bar.rs) #321, Accessible icon buttons: tooltip + role + aria_label everywhere, enforced by the primitives #340, [deep-review] [S2] Settings ComboBox opens only on mouse-down (src-app/src/settings/components.rs) #361, [deep-review] [S2] Settings toggles are click-only with no switch role (src-app/src/settings/components.rs) #275: named icon buttons, switch roles, keyboard-operable lists, APCA floors) has no section in upstream's document and should get one.

Port

git show upstream/main:DESIGN.md
git log --oneline v0.11.0..upstream/main -- DESIGN.md

• Take upstream's structure and tokens; rewrite §7 to macOS only; replace the dock and Review metrics with the fork's rules (or Review reworked into Workspaces and Changes rails over a pane grid (upstream a8d55f74, fbfefd25) #438's outcome); add an accessibility section citing the fork's primitives; add the six-gate verification to the §9 delivery gate.
• Link it from CLAUDE.md "Styling conventions" and from AGENTS.md the way upstream does, so agents read it before touching chrome.

Done when

• DESIGN.md at the repo root, every metric in it true of the fork's tree on the day it lands (spot-check five: sidebar width, dock floor, tab height, icon sizes, body text size); CLAUDE.md points at it; no Windows or Linux material rules remain.