docs(14): UI design contract

.planning/phases/14-pax8-ui-surface/14-UI-SPEC.md

@@ -1,7 +1,8 @@
 ---
 phase: 14
 slug: pax8-ui-surface
-status: draft
+status: approved
+reviewed_at: 2026-07-11
 shadcn_initialized: true
 preset: "style=new-york, baseColor=neutral, cssVariables=true, iconLibrary=lucide, rsc=true"
 created: 2026-07-11
@@ -16,7 +17,7 @@ already-tokenized design system (see `DESIGN.md`, `components.json`). No new
 visual language is being introduced — this contract pins down which existing
 tokens/components apply and resolves the phase-specific gaps CONTEXT.md left
 to discretion (tab labels, column set, copy). Nearly every field below is
-pre-populated from `DESIGN.md`, `14-CONTEXT.md` (D-01…D-09), and
+pre-populated from `DESIGN.md`, `14-CONTEXT.md` (D-01…D-10), and
 `14-RESEARCH.md` — no user questions were required for this phase.
 
 ---
@@ -62,9 +63,19 @@ bar, table/card sections) — same shell `device-link-conflicts` uses.
 
 Matches the sitewide scale documented in `DESIGN.md` §2 (Type) and used
 throughout `DetailModal.tsx` / `device-link-conflicts/page.tsx`. This is a
-pre-existing, sitewide scale — not introduced for this phase — so it
-carries 3 weights (400/600/700) rather than the generic 2-weight target;
-noted as an accepted exception since it matches every other page in the app.
+pre-existing, sitewide scale — not introduced for this phase.
+
+**3-weight exception (D-10 — user-approved, not Claude's discretion):** the
+UI checker's Dimension 4 gate initially blocked this spec for declaring 3
+font weights (400/600/700) against its generic 2-weight default cap. The
+tradeoff was presented to the user directly — match `DESIGN.md`'s existing
+sitewide type scale (IBM Plex Sans, weights 300–700, already used on every
+other Pulse page) vs. trim `/pax8` alone to 2 weights and look visually
+inconsistent with the rest of the app. The user explicitly chose to keep the
+3-weight sitewide pattern for this phase. See `14-CONTEXT.md` D-10 for the
+full record. This exception applies only because it is a recorded,
+user-approved decision — it is not a general license to exceed the 2-weight
+cap on future phases without the same explicit approval.
 
 | Role | Size | Weight | Line Height |
 |------|------|--------|-------------|
@@ -105,6 +116,27 @@ not the 10% accent.
 
 ---
 
+## Visual Hierarchy (Focal Points)
+
+Each tab has exactly one primary visual anchor — everything else on the tab
+is secondary weight (muted borders, smaller type, no accent color):
+
+- **Companies tab:** the `DataTable` is the focal point. It occupies the
+  full content width immediately below the tab bar with no competing cards
+  or panels; row hover and the matched/unmatched `Badge` are the only
+  in-table emphasis.
+- **Needs Review tab:** the amber-bordered candidate cards
+  (`border-amber-200`, one per unresolved `pax8_company_match_review` row)
+  are the focal point. The `AlertTriangle` icon + amber border draws the eye
+  first, then the per-candidate confidence `Badge` and "Link company"
+  button (10% accent color) as the secondary action target within each card.
+- **DetailModal drill-down (either tab):** the new subscriptions/cost-
+  breakdown table is the focal point of the formatted tab — it renders
+  above the fold, before the Identity/System field groups, since it answers
+  the manager's primary question ("what am I paying for") ahead of metadata.
+
+---
+
 ## Copywriting Contract
 
 | Element | Copy |
@@ -179,11 +211,11 @@ governs whether D-02's "used as-is" framing produces a usable UI:
 
 ## Checker Sign-Off
 
-- [ ] Dimension 1 Copywriting: PASS
-- [ ] Dimension 2 Visuals: PASS
-- [ ] Dimension 3 Color: PASS
-- [ ] Dimension 4 Typography: PASS
-- [ ] Dimension 5 Spacing: PASS
-- [ ] Dimension 6 Registry Safety: PASS
+- [x] Dimension 1 Copywriting: PASS
+- [x] Dimension 2 Visuals: PASS
+- [x] Dimension 3 Color: PASS
+- [x] Dimension 4 Typography: PASS
+- [x] Dimension 5 Spacing: PASS
+- [x] Dimension 6 Registry Safety: PASS
 
-**Approval:** pending
+**Approval:** approved 2026-07-11