# Apple HIG Skill

Use the distilled HIG references in `references/hig/` through `routing-index.md`. The source snapshot and verified release measurements are in README.md.

## Loading Protocol

Release **2026-09-27**; Apple source snapshot **2026-09-12**.
For help, installation, version or capability questions, read only this entry
point and the relevant README section. Do not load the HIG corpus for setup help.
Installing or upgrading this skill includes its `/duo` slash command. After the
skill folder is in place, check whether the host already offers `/duo`. If it
does not, copy `commands/duo.md` into the host's custom slash-command or custom
prompt directory (user-level unless the user asks for one project), confirm
`/duo` is available, and tell the user if a restart is needed.
Work directly in the conversation and the user's project; do not create a browser
intake form, onboarding site, dashboard, or browser setup step.

Ordinary guidance is the default. Only an explicit request to apply enforce mode
activates its procedure. Read `references/enforce.md` first in that case and check
reviewer, Python and observation capabilities before loading the design guidance.
A leading `/duo`, `Use apple-hig in Duo mode`, or an explicit request to adapt
an existing app for iPhone Duo starts Duo mode: read `references/duo.md` and
follow its stages. Questions about the command and ordinary Duo design questions
stay ordinary guidance. Duo mode works only in the app's native code; it never
produces HTML, SVG, or web mockups.
Use the available Python 3.10+ interpreter (`python3` or `python`); do not assume
the executable name. Ordinary guidance also works without Python.

When Python is available, use the standard-library routing helper to resolve
steps 2–6: save only the exact user request to a UTF-8 text file in a temporary
directory outside the user's project, then run `<python> "<skill-root>/scripts/hig_route.py" --request-file "<request.txt>"`.
Read every file in its `files` list in bounded sections, completing any truncated
read before continuing. Do not concatenate the entire set into one tool output;
the helper output is metadata, not the guidance itself. Do not add
your own instructions to the request text or promote inferred topics to
initial matches. If the user explicitly excludes a platform/device/topic, pass
the excluded topic IDs with `--exclude-topic` (repeat for each topic, including
platform aliases matched inside an excluded phrase); record the user's reason.
Keep a platform that is also positively requested elsewhere. Do not exclude
topics merely to reduce context. Exclusions apply
to direct and related selections, never to the 16 foundations. Without Python,
apply the same steps and explicit exclusions manually.

### Step 1 — Parse Task Context

From the user's request, identify:
- **Platform(s):** ios / ipados / macos / tvos / visionos / watchos
- **Device/form factor:** iPhone Duo when named or matched by its tier-2 triggers
- **Components or patterns** mentioned (buttons, tab bars, sheets, etc.)
- **Frameworks or SDKs** referenced (HealthKit, SiriKit, ARKit, etc.)
- **Task type:** design / review / spec / audit / guidance
- **Mode:** ordinary guidance by default. Activate enforce mode only when the user explicitly asks to apply it; mentioning the mode or asking what it means does not activate it. Duo mode starts only as described above.

### Step 2 — Load Tier 1 (every design or review task)

Read all 16 files listed in `routing-index.md` under `## tier-1`:

`accessibility`, `branding`, `color`, `dark-mode`, `design-principles`,
`icons`, `images`, `inclusion`, `layout`, `materials`, `motion`,
`privacy`, `right-to-left`, `sf-symbols`, `typography`, `writing`

These apply universally. Load them before answering.

### Step 3 — Load Platform File (Tier 2)

Read `routing-index.md` → `## tier-2 platform-map`.
For each detected platform, load its `designing-for-[platform]` file.
Also match the tier-2 map's device/form-factor and API triggers using
standalone word/phrase/API-symbol matching. A Duo match loads both
`designing-for-iphone-duo` and `designing-for-ios`; Duo is an iOS form factor.
If "game" or "gaming" is mentioned, also load `designing-for-games`.

### Step 4 — Keyword Scan (Tier 3)

Read `routing-index.md` → `## tier-3 trigger-map`.
Normalize the user request to lowercase. Match trigger strings as
standalone words, phrases, or API symbols; plural, hyphenated and bare-symbol
forms count (`tab bars`, `full-screen`, `keyboardType`). Never match a trigger
merely because it appears inside an unrelated word. For example, `AR` doesn't
match "tab bar," and `AI` doesn't match "explain." Load every matching
file. Load each file at most once.

### Step 5 — Related Expansion

Freeze the initial selection set as the tier-2 and tier-3 files selected in steps 3–4. Read only that set's `related:` frontmatter.
Load the listed files once. Do not expand related lists from those newly added files.

Bind each in

…