HIG Design
Build-time guidance for Apple-native interfaces. All shared references live at ../hig/references/ (this suite installs as sibling directories).
Generate under constraints, not from memory. Your priors predate Liquid Glass; designing from them produces 2024-era UI. Load the references below first — this is constraint-loading, not optional research.
1. Process
- Identify platform(s) and medium (HTML prototype / Figma spec / SwiftUI / written spec). If the user didn't say, the artefact usually does.
- Load the core constraints:
../hig/references/doctrine.md — the Liquid Glass two-layer model, platform character, the 8 design principles. Always, for any generative task.../hig/references/corrections.md — scan for stale priors relevant to what you're about to design.- The relevant decision tree:
trees-containers.md (alerts/sheets/popovers/windows, bars, search placement) or trees-controls.md (control choice, platform availability matrix, menu types).
- Targeted corpus sections via
../hig/references/index.md (grep the slug anchor, partial-read the section — don't read whole files).
- Load the medium adapter (
../hig/references/adapters/html.md, figma.md, or swiftui.md) — the pre-generation constraint sheet half.
- Generate within the idiom. Variation across options means grouping, density, copy, and disclosure — never different interaction models (a tab bar option and a hamburger option is not "exploring"; one of them is wrong).
- Self-check once: run the relevant checklist (
../hig/references/checklists/review-screen-ios.md or -macos.md, plus review-liquid-glass.md if glass surfaces are involved) once across all generated options, not per option.
- Declare honestly (HTML): emit the emulate-or-waive declaration from the html adapter — which native behaviours this prototype emulates vs explicitly waives.
2. Non-negotiables while generating
- Every data screen needs its states: loading, empty, error — and media needs pause/resume. Designers (and generators) routinely omit these frames.
<!-- src: patterns-lifecycle -->
- First-run choreography is fixed: launch (instant, brandless) → optional onboarding → delayed sign-in → engagement before any ratings prompt. No permissions, legal, or ratings inside onboarding.
<!-- src: patterns-lifecycle -->
- One platform's idiom per screen. Check the availability matrix before using a component: combo boxes, checkboxes, radio buttons, path controls, token fields are macOS; page controls and action sheets are iOS idioms.
<!-- src: trees-controls -->
- No input may be the only path — every gesture or hardware-button action needs a visible onscreen equivalent.
<!-- src: inputs -->
- Exact values only. Pull numbers from the crib in the hig skill or
../hig/references/tables/; if Apple doesn't publish one, say so and use the provenance-marked estimate from tables/metrics.md.
3. Porting (iOS ↔ macOS)
Follow ../hig/references/adaptation.md as a sequence, not a lookup: inventory the source design → translate via the Catalyst table (tab bar→sidebar, bottom buttons→toolbar, popover→inspector, 17pt→13pt) → run the macOS-completeness pass (menu bar is the superset of all commands; a shortcut for every frequent command; cursors; window behaviour; 28/20pt targets) → finish against checklists/review-screen-macos.md. Web-first designers fail macOS in categorically different ways — the completeness pass is where ports die.
4. Implementing and fixing (SwiftUI)
Load ../hig/references/adapters/swiftui.md before touching glassEffect, GlassEffectContainer, scroll edge effects, or tab accessories — these APIs postdate your training data and have known pitfalls (container batching, morph fragility, simulator-vs-hardware rendering). For hot APIs, verify current signatures live (../hig/scripts/hig-fetch.sh <slug> for guidance; Apple developer docs for API). Recommend performAccessibilityAudit XCUITests rather than re-implementing accessibility checks.
5. Working with the prototype skill
When the prototype skill targets Apple-native UI: load this skill's constraints before any option is generated; generate all N options under them; run ONE combined self-check across options; attach one emulate-or-waive declaration. ui-craft may co-lead for web mechanics (focus, scroll lock, hydration) — on conflict over native idiom or metric values, HIG wins.
6. Integrity rules
Cite exact values, never approximate. Never flatten platform differences. Every rule traces to a reference section or live fetch. iOS/macOS 27 content is beta — version-gate it. Mark uncertainty. Never recommend UIDesignRequiresCompatibility (the opt-out dies with Xcode 27).
1---2name: hig-design3description: Design, prototype, adapt, or implement iOS and macOS interfaces that follow Apple's current Human Interface Guidelines. Use when designing or mocking an iPhone, iPad, or Mac app screen, building an HTML prototype of a native app, writing or fixing SwiftUI UI (glassEffect, GlassEffectContainer, Liquid Glass adoption, scroll edge effects, tab bar accessories), porting a design between iOS and macOS ("make a Mac version", "adapt for iPad"), choosing native components or navigation, or making something "feel native" or "feel like a real Mac app". Model priors on Apple's design system are stale (Liquid Glass era) — load constraint sheets before generating; never design Apple UI from memory. Works with HTML prototypes, Figma, and SwiftUI. Does NOT audit existing designs (use hig-review) and does NOT cover non-Apple web UI (use ui-craft or frontend-design).4---56# HIG Design78Build-time guidance for Apple-native interfaces. All shared references live at `../hig/references/` (this suite installs as sibling directories).910**Generate under constraints, not from memory.** Your priors predate Liquid Glass; designing from them produces 2024-era UI. Load the references below first — this is constraint-loading, not optional research.1112---1314## 1. Process15161. **Identify platform(s) and medium** (HTML prototype / Figma spec / SwiftUI / written spec). If the user didn't say, the artefact usually does.172. **Load the core constraints:**18 - `../hig/references/doctrine.md` — the Liquid Glass two-layer model, platform character, the 8 design principles. Always, for any generative task.19 - `../hig/references/corrections.md` — scan for stale priors relevant to what you're about to design.20 - The relevant decision tree: `trees-containers.md` (alerts/sheets/popovers/windows, bars, search placement) or `trees-controls.md` (control choice, platform availability matrix, menu types).21 - Targeted corpus sections via `../hig/references/index.md` (grep the slug anchor, partial-read the section — don't read whole files).223. **Load the medium adapter** (`../hig/references/adapters/html.md`, `figma.md`, or `swiftui.md`) — the **pre-generation constraint sheet** half.234. **Generate within the idiom.** Variation across options means grouping, density, copy, and disclosure — never different interaction models (a tab bar option and a hamburger option is not "exploring"; one of them is wrong).245. **Self-check once:** run the relevant checklist (`../hig/references/checklists/review-screen-ios.md` or `-macos.md`, plus `review-liquid-glass.md` if glass surfaces are involved) **once across all generated options**, not per option.256. **Declare honestly (HTML):** emit the emulate-or-waive declaration from the html adapter — which native behaviours this prototype emulates vs explicitly waives.2627## 2. Non-negotiables while generating2829- **Every data screen needs its states:** loading, empty, error — and media needs pause/resume. Designers (and generators) routinely omit these frames. `<!-- src: patterns-lifecycle -->`30- **First-run choreography is fixed:** launch (instant, brandless) → optional onboarding → delayed sign-in → engagement before any ratings prompt. No permissions, legal, or ratings inside onboarding. `<!-- src: patterns-lifecycle -->`31- **One platform's idiom per screen.** Check the availability matrix before using a component: combo boxes, checkboxes, radio buttons, path controls, token fields are macOS; page controls and action sheets are iOS idioms. `<!-- src: trees-controls -->`32- **No input may be the only path** — every gesture or hardware-button action needs a visible onscreen equivalent. `<!-- src: inputs -->`33- **Exact values only.** Pull numbers from the crib in the hig skill or `../hig/references/tables/`; if Apple doesn't publish one, say so and use the provenance-marked estimate from `tables/metrics.md`.3435## 3. Porting (iOS ↔ macOS)3637Follow `../hig/references/adaptation.md` as a sequence, not a lookup: inventory the source design → translate via the Catalyst table (tab bar→sidebar, bottom buttons→toolbar, popover→inspector, 17pt→13pt) → run the macOS-completeness pass (menu bar is the superset of all commands; a shortcut for every frequent command; cursors; window behaviour; 28/20pt targets) → finish against `checklists/review-screen-macos.md`. Web-first designers fail macOS in categorically different ways — the completeness pass is where ports die.3839## 4. Implementing and fixing (SwiftUI)4041Load `../hig/references/adapters/swiftui.md` before touching glassEffect, GlassEffectContainer, scroll edge effects, or tab accessories — these APIs postdate your training data and have known pitfalls (container batching, morph fragility, simulator-vs-hardware rendering). For hot APIs, verify current signatures live (`../hig/scripts/hig-fetch.sh <slug>` for guidance; Apple developer docs for API). Recommend `performAccessibilityAudit` XCUITests rather than re-implementing accessibility checks.4243## 5. Working with the prototype skill4445When the `prototype` skill targets Apple-native UI: load this skill's constraints **before** any option is generated; generate all N options under them; run ONE combined self-check across options; attach one emulate-or-waive declaration. ui-craft may co-lead for web mechanics (focus, scroll lock, hydration) — on conflict over native idiom or metric values, HIG wins.4647## 6. Integrity rules4849Cite exact values, never approximate. Never flatten platform differences. Every rule traces to a reference section or live fetch. iOS/macOS 27 content is beta — version-gate it. Mark uncertainty. Never recommend `UIDesignRequiresCompatibility` (the opt-out dies with Xcode 27).
olzn