Skip to content
Back to search

apple-hig

SkillWorks with Claude CodeGitHub

Apple Human Interface Guidelines reference, updated for iPhone Duo and OS 27. Provides authoritative platform-specific design rules, component specifications, exact measurements, and interaction patterns for iOS, iPadOS, macOS, tvOS, visionOS, and watchOS. Use when designing, reviewing, auditing, or fixing any Apple platform UI, or when asked about specific HIG components, sizing, system behaviors, frameworks (HealthKit, SiriKit, ARKit, etc.), or platform conventions. Also use when the user is designing any digital interface and could benefit from established design principles, even without an explicit Apple platform context. Includes a guided /duo workflow that adapts an existing iOS app to iPhone Duo, plus opt-in enforce mode with independent review.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked yesterday
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/justinwetch--higagentskills/badge.svg)](/listings/justinwetch--higagentskills)

HTML

<a href="/listings/justinwetch--higagentskills"><img src="/api/listings/justinwetch--higagentskills/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Extract the ZIP's complete `apple-hig/` folder into your agent's skills directory, either for one project or for all local projects. Your agent's documentation names that location. Agents without skill discovery need explicit access to the extracted `SKILL.md` and its sibling files.

Keep `SKILL.md`, README, routing index, references, the `commands/` folder and the two helper scripts together. When upgrading, replace the old skill folder rather than merging files; check for another installed copy with the same name.

Then install the `/duo` command. Some agents pick up `commands/duo.md` from the skill folder on their own; others need the file copied into their custom slash-command or custom prompt directory (your agent's documentation names it). If `/duo` doesn't appear after a restart, copy it there.

Confirm the installation in your agent:

Find the installed apple-hig skill. Read its SKILL.md and report its absolute
location, release version and supported modes, and whether /duo is available
as a slash command. Do not load the HIG references or start a review for this
setup check.

Expect release **2026-09-27**, ordinary HIG guidance, Duo mode with `/duo` available, and opt-in enforce mode. If the skill or `/duo` is missing, or the version differs, check the installation location and refresh/restart the host before using it. Automatic discovery has not been tested in every host.

There is no onboarding website, browser intake, dashboard or setup server. The agent works in your conversation and project. Ordinary guidance needs file access only. Python **3.10+** enables the optional routing helper and is required for enforce scoring; use the available `python3` or `python` executable.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

SKILL.md · Manifest · 170 lines
  1. ---
  2. name: apple-hig
  3. description: >
  4. Apple Human Interface Guidelines reference, updated for iPhone Duo and
  5. OS 27. Provides authoritative platform-specific design rules, component
  6. specifications, exact measurements, and interaction patterns for iOS,
  7. iPadOS, macOS, tvOS, visionOS, and watchOS. Use when designing, reviewing,
  8. auditing, or fixing any Apple platform UI, or when asked about specific HIG
  9. components, sizing, system behaviors, frameworks (HealthKit, SiriKit, ARKit,
  10. etc.), or platform conventions. Also use when the user is designing any
  11. digital interface and could benefit from established design principles, even
  12. without an explicit Apple platform context. Includes a guided /duo workflow
  13. that adapts an existing iOS app to iPhone Duo, plus opt-in enforce mode with
  14. independent review.
  15. ---
  16. # Apple HIG Skill
  17. Use the distilled HIG references in `references/hig/` through `routing-index.md`. The source snapshot and verified release measurements are in README.md.
  18. ## Loading Protocol
  19. Release **2026-09-27**; Apple source snapshot **2026-09-12**.
  20. For help, installation, version or capability questions, read only this entry
  21. point and the relevant README section. Do not load the HIG corpus for setup help.
  22. Installing or upgrading this skill includes its `/duo` slash command. After the
  23. skill folder is in place, check whether the host already offers `/duo`. If it
  24. does not, copy `commands/duo.md` into the host's custom slash-command or custom
  25. prompt directory (user-level unless the user asks for one project), confirm
  26. `/duo` is available, and tell the user if a restart is needed.
  27. Work directly in the conversation and the user's project; do not create a browser
  28. intake form, onboarding site, dashboard, or browser setup step.
  29. Ordinary guidance is the default. Only an explicit request to apply enforce mode
  30. activates its procedure. Read `references/enforce.md` first in that case and check
  31. reviewer, Python and observation capabilities before loading the design guidance.
  32. A leading `/duo`, `Use apple-hig in Duo mode`, or an explicit request to adapt
  33. an existing app for iPhone Duo starts Duo mode: read `references/duo.md` and
  34. follow its stages. Questions about the command and ordinary Duo design questions
  35. stay ordinary guidance. Duo mode works only in the app's native code; it never
  36. produces HTML, SVG, or web mockups.
  37. Use the available Python 3.10+ interpreter (`python3` or `python`); do not assume
  38. the executable name. Ordinary guidance also works without Python.
  39. When Python is available, use the standard-library routing helper to resolve
  40. steps 2–6: save only the exact user request to a UTF-8 text file in a temporary
  41. directory outside the user's project, then run `<python> "<skill-root>/scripts/hig_route.py" --request-file "<request.txt>"`.
  42. Read every file in its `files` list in bounded sections, completing any truncated
  43. read before continuing. Do not concatenate the entire set into one tool output;
  44. the helper output is metadata, not the guidance itself. Do not add
  45. your own instructions to the request text or promote inferred topics to
  46. initial matches. If the user explicitly excludes a platform/device/topic, pass
  47. the excluded topic IDs with `--exclude-topic` (repeat for each topic, including
  48. platform aliases matched inside an excluded phrase); record the user's reason.
  49. Keep a platform that is also positively requested elsewhere. Do not exclude
  50. topics merely to reduce context. Exclusions apply
  51. to direct and related selections, never to the 16 foundations. Without Python,
  52. apply the same steps and explicit exclusions manually.
  53. ### Step 1 — Parse Task Context
  54. From the user's request, identify:
  55. - **Platform(s):** ios / ipados / macos / tvos / visionos / watchos
  56. - **Device/form factor:** iPhone Duo when named or matched by its tier-2 triggers
  57. - **Components or patterns** mentioned (buttons, tab bars, sheets, etc.)
  58. - **Frameworks or SDKs** referenced (HealthKit, SiriKit, ARKit, etc.)
  59. - **Task type:** design / review / spec / audit / guidance
  60. - **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.
  61. ### Step 2 — Load Tier 1 (every design or review task)
  62. Read all 16 files listed in `routing-index.md` under `## tier-1`:
  63. `accessibility`, `branding`, `color`, `dark-mode`, `design-principles`,
  64. `icons`, `images`, `inclusion`, `layout`, `materials`, `motion`,
  65. `privacy`, `right-to-left`, `sf-symbols`, `typography`, `writing`
  66. These apply universally. Load them before answering.
  67. ### Step 3 — Load Platform File (Tier 2)
  68. Read `routing-index.md` → `## tier-2 platform-map`.
  69. For each detected platform, load its `designing-for-[platform]` file.
  70. Also match the tier-2 map's device/form-factor and API triggers using
  71. standalone word/phrase/API-symbol matching. A Duo match loads both
  72. `designing-for-iphone-duo` and `designing-for-ios`; Duo is an iOS form factor.
  73. If "game" or "gaming" is mentioned, also load `designing-for-games`.
  74. ### Step 4 — Keyword Scan (Tier 3)
  75. Read `routing-index.md` → `## tier-3 trigger-map`.
  76. Normalize the user request to lowercase. Match trigger strings as
  77. standalone words, phrases, or API symbols; plural, hyphenated and bare-symbol
  78. forms count (`tab bars`, `full-screen`, `keyboardType`). Never match a trigger
  79. merely because it appears inside an unrelated word. For example, `AR` doesn't
  80. match "tab bar," and `AI` doesn't match "explain." Load every matching
  81. file. Load each file at most once.
  82. ### Step 5 — Related Expansion
  83. 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.
  84. Load the listed files once. Do not expand related lists from those newly added files.
  85. Bind each initial topic to the exact platform/device/trigger text matched in
  86. the user's request. An inferred
  87. component concept is not a literal trigger match.
  88. A topic reached through `related:` stays related even when it is useful;
  89. never promote it to initial and expand it again. If semantic relevance calls
  90. for an additional reference, load that specific file without related expansion.
  91. ### Step 6 — Tier 4 On-Demand
  92. Read `routing-index.md` → `## tier-4 trigger-map (on-demand)`.
  93. Use the same standalone word/phrase/API-symbol matching rule. Load a
  94. tier-4 file only on direct keyword match, or if named in the initial selection
  95. set's `related:` list. Never expand from foundations, newly related files, or
  96. directly matched tier-4 files. These are niche — avoid loading broadly.
  97. ### Step 7 — Answer or enforce
  98. For explicitly requested enforcement, carry out `references/enforce.md` using
  99. the loaded source guidance. Ordinary guidance never starts that procedure.
  100. For an ordinary guidance answer, quote the short operative source clause verbatim
  101. with all qualifiers intact, then give only the needed application. A compact
  102. table works for multiple states. Keep the rule and application distinct;
  103. do not paraphrase the quotation into a stronger, broader, or narrower rule.
  104. Before sending, delete sentences that do not answer a requested part.
  105. Check the actor, starting state, action and resulting state; do not substitute
  106. a similar neighboring scenario. Mention an API as the implementation of a
  107. rule only when the loaded source supports that relationship.
  108. Do not add unrequested adjacent rules or measurements merely because they are
  109. loaded. Preserve the source's full scope: do not invent narrower device/state
  110. limits when applying a rule, and include every requested state it covers.
  111. Apply the guidance for the named platform, device, orientation, and state.
  112. An explicit scoped exception takes precedence over a broader rule within that scope;
  113. apply that exception only to its stated platform, device and state.
  114. Do not invent a reconciliation for unresolved source conflicts; identify the conflict.
  115. Apply all other compatible loaded content. If a topic isn't covered by loaded files,
  116. load the specific relevant reference before answering; keep unrelated expansion bounded.
  117. ---
  118. ## Non-Negotiables
  119. - **Cite exact values.** State pt sizes, pixel densities, margins, and
  120. timing values as they appear in the distilled files. Preserve source
  121. ranges and approximation qualifiers; do not invent or round values.
  122. - **Distinguish platforms.** When behavior differs across platforms,
  123. state each platform's rule explicitly. Never flatten to "generally."
  124. - **Preserve recommendation strength.** Keep must, prefer, consider, examples, conditions, and exceptions distinct when answering; do not turn an optional recommendation into a requirement.
  125. - **Preserve logical conditions.** Keep conjunctions and alternatives intact. A consequence stated for A and B does not establish the same consequence for either alone; an A-or-B option does not require both. Check the claim in the answer as well as its supporting clause.
  126. - **No invention.** Every Apple rule, measurement, and API recommendation must
  127. trace to a loaded reference. Distinguish Apple guidance from your own design
  128. choices. If unsure, say so and name the source.
  129. - **Terse and direct.** Keep ordinary guidance focused on the requested rule.
  130. ---
  131. ## File Locations
  132. - Distilled reference files: `references/hig/[topic].md`
  133. - Routing index: `routing-index.md`
  134. - Opt-in enforcement procedure: `references/enforce.md`
  135. - Guided iPhone Duo redesign: `references/duo.md`, `references/duo-checklist.md`;
  136. `/duo` slash command (install it with the skill): `commands/duo.md`
  137. - Frontmatter schema: each distilled file contains `topic`, `tier`,
  138. `platforms`, `category`, `triggers`, and `related` fields.
README.md · README · 107 lines
  1. # apple-hig
  2. ![Apple HIG reference library](https://raw.githubusercontent.com/justinwetch/HIGAgentSkills/main/docs/readme-graphics/2026-09-12/01-header-light.png)
  3. **157 source-reviewed Apple Human Interface Guidelines references, updated for iPhone Duo and OS 27**, with a guided `/duo` workflow that adapts an existing iOS app to the folding iPhone. Covers iOS, iPadOS, macOS, tvOS, visionOS and watchOS.
  4. Release **2026-09-27** · Apple source snapshot **2026-09-12**.
  5. [![Watch the demo](https://img.youtube.com/vi/jnD82EqZ2VQ/maxresdefault.jpg)](https://www.youtube.com/watch?v=jnD82EqZ2VQ)
  6. ## Copy-paste install prompt
  7. Copy and paste this message to your agent to have it install the skill and its `/duo` command for you.
  8. ```text
  9. Install the apple-hig skill for me from https://github.com/justinwetch/HIGAgentSkills.git
  10. It includes a required /duo slash command in commands/duo.md. If /duo isn't
  11. available after installing the skill, copy that file into your custom slash-command
  12. or custom prompt directory, then confirm /duo works.
  13. ```
  14. ## 2026-09-27 release: iPhone Duo and OS 27
  15. ![/duo redesigns your app for iPhone Duo: an open iPhone Duo on a table showing a record library in four columns](https://raw.githubusercontent.com/justinwetch/HIGAgentSkills/main/docs/readme-graphics/2026-09-27/02-duo-release.jpg)
  16. Apple's September guideline update added a whole new page for the folding iPhone Duo and brought the rest of the HIG up to OS 27. This release brings the skill up to that snapshot (captured September 12) and adds help for the job most iOS teams will actually have this fall: taking an app they already ship and making it work on a phone that opens.
  17. - **Duo mode.** `/duo` takes an existing iOS app through assessing its screens, matching them to Apple's Duo guidance, recommending changes for you to approve, and building them in SwiftUI or UIKit. It works in your app's own code and never draws web mockups (see "Redesign for iPhone Duo" below).
  18. - **Current guidance.** All 157 references follow Apple's September 12 pages, including the iPhone Duo page on displays, poses, reserved regions and side-mounted bars, and the OS 27 changes elsewhere.
  19. - **Lighter references.** The references were rewritten to about a third of Apple's wording overall (261,621 down to 90,027 words) while keeping exact values, conditions and how strongly Apple phrases each rule, so a request loads less context for the same answer.
  20. Ordinary questions work the way they did in June, just against newer and smaller files. There's also a new opt-in enforce mode for independent review and repair (see "Enforce mode" below). If you installed the June release, replace the whole skill folder rather than merging, since the references moved from `distilled/` to `references/hig/`. The release assessment and verification live in the repository under `docs/release-2026-09-27/`.
  21. ## Manual install
  22. Extract the ZIP's complete `apple-hig/` folder into your agent's skills directory, either for one project or for all local projects. Your agent's documentation names that location. Agents without skill discovery need explicit access to the extracted `SKILL.md` and its sibling files.
  23. Keep `SKILL.md`, README, routing index, references, the `commands/` folder and the two helper scripts together. When upgrading, replace the old skill folder rather than merging files; check for another installed copy with the same name.
  24. Then install the `/duo` command. Some agents pick up `commands/duo.md` from the skill folder on their own; others need the file copied into their custom slash-command or custom prompt directory (your agent's documentation names it). If `/duo` doesn't appear after a restart, copy it there.
  25. Confirm the installation in your agent:
  26. ```text
  27. Find the installed apple-hig skill. Read its SKILL.md and report its absolute
  28. location, release version and supported modes, and whether /duo is available
  29. as a slash command. Do not load the HIG references or start a review for this
  30. setup check.
  31. ```
  32. Expect release **2026-09-27**, ordinary HIG guidance, Duo mode with `/duo` available, and opt-in enforce mode. If the skill or `/duo` is missing, or the version differs, check the installation location and refresh/restart the host before using it. Automatic discovery has not been tested in every host.
  33. There is no onboarding website, browser intake, dashboard or setup server. The agent works in your conversation and project. Ordinary guidance needs file access only. Python **3.10+** enables the optional routing helper and is required for enforce scoring; use the available `python3` or `python` executable.
  34. ## Use
  35. ```text
  36. Use apple-hig to review the navigation and accessibility of this iOS app.
  37. ```
  38. The agent loads 16 foundations, relevant platform/device and component references, and one hop of related guidance. The [routing helper](scripts/hig_route.py) resolves literal matches; the agent passes any explicit topic exclusions separately. File-only hosts follow the same protocol manually. Setup/help questions do not load the corpus.
  39. Answers quote the operative source clause before applying it, preserving conditions, recommendation strength and exact specifications. Ordinary guidance never starts enforcement.
  40. ## Redesign for iPhone Duo
  41. ![An iPhone Duo half folded on a table, Now Playing split across the fold: the turntable on the raised half, the controls on the flat half](https://raw.githubusercontent.com/justinwetch/HIGAgentSkills/main/docs/readme-graphics/2026-09-27/03-duo-split.jpg)
  42. ```text
  43. /duo the library and reading flow
  44. ```
  45. Duo mode walks one journey of an existing iOS app through fixed stages:
  46. 1. **Assess** the current screens, bars and layouts in your code.
  47. 2. **Match** them against Apple's iPhone Duo guidance and tech talks, with sources.
  48. 3. **Decide:** it recommends options and stops for your choices, offering SwiftUI previews first.
  49. 4. **Build** the changes natively, in Apple's order.
  50. 5. **Verify** them in the Device Hub iPhone Duo simulator where available.
  51. It keeps a short `duo-notes.md` in your project so a later `/duo continue` picks up where it left off. It never makes HTML or web mockups, and it reports which checks it could not run.
  52. `/duo` comes from `commands/duo.md`, installed with the skill (see "Manual install"). If it's missing, `Use apple-hig in Duo mode for <journey>` starts the same workflow while you fix the install. The [workflow](references/duo.md) and [checklist](references/duo-checklist.md) load only in Duo mode.
  53. ## Enforce mode (optional)
  54. Ask for it by name ("Use apple-hig in enforce mode to review and fix this interface") and two independent reviewers score the interface against the HIG; the agent repairs what they find and re-reviews, for up to three cycles. A pass needs 90/100 or better, complete evidence and no unresolved material finding; otherwise the result is `needs changes` or `blocked`. It needs subagents, Python 3.10+ and a way to observe the actual artifact. The [procedure](references/enforce.md) and [data format](references/enforce-format.md) load only when enforcement is requested.
  55. ## Coverage and context
  56. The references cut Apple's source guidance from **261,621 to 90,027 words (65.6% shorter)**. That is short of the ~75% target: fidelity took priority, so exact values, conditions, recommendation strength, API names and scoped exceptions were kept, and short rule-dense topics stop around 57–68%. All 157 topics passed independent source review; each topic rewritten in the September 23–24 redistillation was re-reviewed against Apple's source.
  57. Complete reference files total **163,033 o200k_base / 162,491 cl100k_base tokens**. The 16 foundations total **27,096 / 26,936 tokens**, about 17% below June. Routing, entry-point instructions and selected topics add context; Duo mode adds its workflow and checklist only when it runs. These are static file counts, not measured per-request loads. Source review does not establish runtime behavior or native-device certification.
  58. ## Repository and packaging
  59. `SKILL.md` is the entry point; `routing-index.md` maps requests to `references/hig/*.md`. The repository's `distilled/` directory preserves the June baseline and is not loaded or packaged. Source captures, review logs, work files and maintenance documentation are also excluded from the runtime ZIP.
  60. The maintainer's `scripts/package_runtime_zip.py` builds a deterministic ZIP from an approved manifest. Package checks verify membership, hashes and local links; they do not certify app behavior. Compact corpus measurements and dispositions are retained under `docs/corpus-2026-09-12/` outside the package.
  61. ## Attribution
  62. Distilled from [Apple's Human Interface Guidelines](https://developer.apple.com/design/human-interface-guidelines). The Duo checklist also paraphrases Apple's iPhone Duo developer tech talks, linked in it. This independent project is not affiliated with or endorsed by Apple Inc. The enforce diagnostic workflow is informed by [shadcn/ui lint](https://github.com/shadcn-ui/lint); it uses HIG review and artifact evidence rather than adopting Tailwind-specific rules.
  63. ## License
  64. Code and original material are MIT licensed. The license does not claim to extend to material owned by Apple or others, including the guidelines the reference files are distilled from. See [LICENSE](https://github.com/justinwetch/HIGAgentSkills/blob/main/LICENSE) and [NOTICE](https://github.com/justinwetch/HIGAgentSkills/blob/main/NOTICE).

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.