Status: Phase 1 stub. Matures in Phase 5 per §8.1 of Design/0000-hig-diagnostic.md. Decision: DEC-0022 (HIG doctrine: who wins on conflict).

Statement

Behavior, proportion, and interaction follow Apple Human Interface Guidelines (HIG). Visual identity follows Ledger (F-1, F-2, F-7). When the two conflict, HIG wins on hit target, focus visibility, modality hierarchy, motion grammar, density, form-input semantics, safe-area respect, reduced-motion / forced-colors / prefers-color-scheme honoring, RTL mirroring, sound, and haptics. Ledger wins on color, surface, ink, gradient, type face, type scale, and icon style.

This is the behavioral counterpart to F-1's visual contract. Together they constitute the system's full design surface.

Why

The Phase 0.5 close-out (Design/0000-hig-diagnostic.md §11) filed 30+ HIG-driven defects. The clustering was unambiguous: substantive bugs lived on behavior, not visuals. Toast collisions (#3446), tab chain omissions (#3449, #3450), missing hover affordance (#3461, #3462), suppressed focus ring (#3460), missing skip-to-main (#3457), unbounded loading state (#3447), unfocusable decorative pills (#3456), RTL physical-side leaks (#3458, #3459) — every one is a behavioral defect inside a correctly rendered Ledger visual frame. The principle catalog needed a behavioral contract to cite when filing or fixing these.

F-1 alone is not enough. F-1 says "every visual atom resolves through a named token." It does not say "every interactive element has ≥44pt hit target," "every focus state is visible at ≥3:1 contrast," "every destructive action confirms per DEC-0009," or "every form input declares enterkeyhint, inputMode, autocomplete, and autocapitalize per HIG's keyboard semantics." H-1 supplies that surface.

How

In Phase 1 (this stub), the behavioral contract is stipulated by reference. Every existing accessibility principle (A-1, A-2, A-3), every existing motion + density principle (F-6, DEC-0012), every existing modality decision (DEC-0016, DEC-0017, DEC-0019, DEC-0020), and every existing focus + keyboard decision (DEC-0018) is HIG-aligned by intent. H-1 makes that alignment explicit and gives the behavioral surface a single citable home.

Phase 2 adds the four mechanical surfaces missing from the contract:

**enterkeyhint + inputMode + autocomplete + autocapitalize

sweep.** Every <input> and <textarea> in src/**/*.{tsx} declares the correct keyboard semantics. ESLint rule (eslint-rules/require-input-semantics.cjs) enforces. Phase 2 PR.

Safe-area-inset on MainLayout and DesktopSidebar. Mobile

PWA install on iOS notched + Android cutout devices respects the safe area without manual padding tweaks per route. Phase 2 PR.

Icon barrel + import ban. @/components/icons re-exports the

curated lucide-react set; direct lucide-react imports outside the barrel are banned. Phase 2 PR.

Material primitive + tokens. <Material> consuming

--material-thin / --material-regular / --material-thick / --material-chrome tokens per HIG's UIVibrancyEffect + UIBlurEffect taxonomy. Replaces ad-hoc bg-white/60 backdrop-blur-md patterns. Phase 2 PR.

Each step ships under its own ref #N to a tracking issue. None are on this stub's critical path; this stub establishes the doctrine slot.

Counter-examples (Phase 5 maturity pass)

Filled in Phase 5 once Phase 2–4 PRs have established the canonical violation patterns. Placeholder list:

Visual: a route that adopts iOS chrome (SF Pro, UIKit icons,

system colors) instead of Ledger. Treat as a regression.

Behavior: a route that suppresses focus ring on inputs because

"the design comp didn't show one" (the #3460 anti-pattern).

Behavior: a route that hardcodes min-h-[44px] per call site

instead of consuming the --hit-target-min token (the A-3 anti-pattern).

Behavior: a destructive action that opens a <dialog> without

role="alertdialog" and the DEC-0009 tier-appropriate confirmation surface.

Citation

DEC-0022 — HIG doctrine: who wins on conflict
HIG: https://developer.apple.com/design/human-interface-guidelines
Phase 0 close-out: Design/0000-hig-diagnostic.md §11
Existing principles reinforced (not replaced): A-1, A-2, A-3, F-6, P-4
Existing DECs reinforced (not replaced): DEC-0009, DEC-0012,

DEC-0016, DEC-0017, DEC-0018, DEC-0019, DEC-0020

Decision history

2026-05-15 — H-1 stub created alongside DEC-0022. Phase 1 close-out

of Design/0000-hig-diagnostic.md §11.19. Behavioral contract registered as the third pillar (with F-1 visual contract and S-1 infrastructure contract) of the principle catalog.