Apple Hig

apple-hig

Make Claude actually follow Apple's Human Interface Guidelines when building for iOS, iPadOS, macOS, watchOS, tvOS, or visionOS. Works with SwiftUI, UIKit, AppKit, and Apple-native-feeling web/Figma mockups.

> Status: stable · v1.0.0. Feature-complete. 68 reference files across > foundations, patterns, components, inputs, platforms, and technologies, > each cited to the live HIG. If HIG guidance evolves (WWDC releases, policy > changes), update the matching file's Last verified: date and revise.

---

How to use this skill

1. Identify the target platform(s) (iOS, iPadOS, macOS, watchOS, tvOS,

visionOS) and the component or pattern in play (e.g., settings screen, modal sheet, list, toolbar).

1. Load only the reference files you need. Do not load the whole references/

tree.

1. Never generate code or a design spec without consulting: (a)

references/foundations/accessibility.md, (b) the relevant references/platforms/.md, and (c) the relevant component or pattern file.

1. Apply the non-negotiables below on every output.
2. Run the final review checklist before calling work complete.

---

Phase 0 — Ask before generating

Before writing any code or design spec, resolve targeting. Use AskUserQuestion to ask the user up to two of the following in a single turn. Skip any question the user has already answered in their message.

1. Target platform(s)? (multi-select)

• iOS / iPhone
• iPadOS
• macOS
• watchOS
• tvOS
• visionOS

1. Framework? (multi-select)

• SwiftUI
• UIKit / AppKit
• Web or Figma-native

1. What are you building? (single-select)

• A new full screen / window
• A single component
• A design spec (no code)
• Reviewing existing UI

If the user gives a clear enough brief ("I'm building an iPhone onboarding screen in SwiftUI"), skip Phase 0 and go straight to loading references.

---

Decision tree — what to load

| What the user is doing | Load these references | |---|---| | Building a list or feed screen | components/lists-and-tables.md + platforms/.md + foundations/layout.md + foundations/accessibility.md | | Designing a settings screen | patterns/settings.md + platforms/.md + components/lists-and-tables.md | | Adding a modal / sheet | patterns/modality.md + components/sheets-and-popovers.md + platforms/.md | | Onboarding flow | patterns/onboarding.md + platforms/.md + foundations/writing.md | | Navigation structure | patterns/navigation.md + components/bars.md + platforms/.md | | Search experience | patterns/search.md + components/bars.md | | Forms / data entry | patterns/entering-data.md + components/text-inputs.md + components/pickers-and-menus.md | | Picking colors | foundations/color.md + foundations/dark-mode.md | | Icons / glyphs | foundations/sf-symbols.md (+ foundations/app-icons.md if launcher icon) | | Typography decisions | foundations/typography.md + foundations/accessibility.md | | Motion / animation | foundations/motion.md + foundations/accessibility.md | | macOS window / toolbar | platforms/macos.md + components/bars.md + components/split-views.md | | iPad sidebar / split view | platforms/ipados.md + components/split-views.md + components/bars.md | | watchOS complication or glance | platforms/watchos.md + technologies/widgets-and-live-activities.md | | tvOS focus-driven screen | platforms/tvos.md + inputs/focus-and-remote.md | | visionOS window / ornament | platforms/visionos.md + foundations/materials.md + foundations/spatial-layout.md | | Live Activity / Dynamic Island | technologies/widgets-and-live-activities.md + technologies/dynamic-island.md | | Widget | technologies/widgets-and-live-activities.md + platforms/.md | | Web / Figma mockup, Apple-native feel | foundations/typography.md + foundations/color.md + foundations/layout.md + foundations/sf-symbols.md |

If a referenced file doesn't exist yet (see Status note above), fetch the matching HIG URL, apply the same rules, and tell the user the file is pending.

---

Core non-negotiables

Apply on every output:

• Touch / focus targets. iOS ≥ 44×44pt. watchOS ≥ 44×44pt on 44mm+ / ≥ 40pt

on smaller. tvOS: every actionable view must be focusable. macOS pointer targets ≥ 28×28pt. Reason: HIG ergonomic floors; missing them fails accessibility review.

• Dynamic Type. Use text styles (.body, .headline, .title) or

UIFontMetrics. Never hardcode point sizes for body copy. Reason: users who size up text must not get clipped UI.

• Dark Mode. Use semantic colors (Color(.label),

Color(.systemBackground), Color.accentColor) or asset catalog colors with any/dark variants. No hex literals in production UI. Reason: hardcoded hex breaks in dark mode, increased contrast, and tinted app icons.

• VoiceOver. Every non-decorative view has an accessibility label.

.accessibilityLabel(...), .accessibilityHint(...), correct .accessibilityAddTraits(...). Decorative images get .accessibilityHidden(true).

• SF Symbols first. If a system glyph exists

(checkmark, xmark.circle.fill, magnifyingglass, etc.), use it — don't ship a custom icon. Custom icons only when no equivalent exists.

• Reduce Motion. Respect @Environment(\.accessibilityReduceMotion) /

UIAccessibility.isReduceMotionEnabled. Swap parallax / spring animations for cross-fades.

• Platform-correct navigation. iOS → tab bar or navigation stack. macOS →

menu bar + toolbar + sidebar; don't ship a tab bar. iPadOS → sidebar / split view for regular size class. watchOS → page navigation or hierarchical. tvOS → focus-driven. visionOS → ornaments + glass windows.

• Safe areas. Respect .safeAreaInset(...) / safe area layout guides.

Full-bleed backgrounds only below content, never under interactive elements.

• RTL-safe layout. Leading / trailing, not left / right. Mirror arrows and

directional icons when appropriate.

• Writing. "Tap" on touch platforms, "Click" on macOS, "Select" or "Choose"

when platform-agnostic. Sentence case in buttons and labels (not Title Case, unless it's a title).

---

Common mistakes without this skill

• Using a custom font when SF Pro / SF Compact / New York would be correct.
• Hardcoded hex colors that break dark mode and tinted icons.
• Too-small tap targets (<44pt) on iOS.
• Modal-happy flows — sheets for things that should be a push, alerts for

things that should be a toast or inline validation.

• iOS tab bars on macOS; macOS window chrome on iOS.
• Centering a nav bar title on iOS when the convention is leading-aligned (or

vice versa on macOS toolbars).

• Ignoring safe areas; content slides under the home indicator or notch.
• Forgetting Reduce Motion; sending motion-sensitive users through a parallax

onboarding.

• Light-mode-only screens.
• Missing VoiceOver labels on icon-only buttons.
• Using "Click" on iOS or "Tap" on macOS.
• Inventing non-standard navigation paradigms instead of NavigationStack /

NavigationSplitView / menu bar.

• Writing an AppKit window that behaves like an iOS screen (full-bleed, no

window chrome affordances).

---

Final review checklist (run before calling work complete)

Load assets/checklists/pre-submission-hig-review.md and assets/checklists/accessibility-review.md and confirm every item passes. Minimum bar (subset):

• [ ] Touch / focus target minimums met for target platform
• [ ] Dynamic Type scales without clipping
• [ ] Dark Mode verified — no hex literals
• [ ] VoiceOver labels on every interactive view
• [ ] SF Symbols used where a system glyph exists
• [ ] Reduce Motion path exists for any non-trivial animation
• [ ] Navigation paradigm matches target platform
• [ ] Safe-area respected
• [ ] Writing tone matches platform (Tap vs Click, sentence case)
• [ ] References cited at top of any generated design doc

---

Reference tree

references/
├── foundations/   typography, color, dark-mode, layout, sf-symbols, materials,
│                   motion, accessibility, inclusion, privacy, writing,
│                   app-icons, branding
├── patterns/      navigation, modality, onboarding, search, settings, loading,
│                   feedback, entering-data, drag-and-drop, file-management,
│                   offering-help, managing-accounts, in-app-purchase,
│                   multitasking, printing, ratings-and-reviews,
│                   undo-and-redo, managing-notifications, charting-data,
│                   going-full-screen, live-viewing-apps, workouts
├── components/    bars, buttons, lists-and-tables, collections-and-scrolling,
│                   sheets-and-popovers, alerts, text-inputs,
│                   pickers-and-menus, segmented-controls,
│                   sliders-steppers-toggles, progress-and-activity,
│                   labels-and-badges, split-views, system-experiences
├── inputs/        touch-and-gestures, pointer-and-keyboard, apple-pencil,
│                   digital-crown, focus-and-remote, spatial-input,
│                   game-controllers
├── platforms/     ios (deep), macos (deep), ipados, watchos, tvos, visionos
└── technologies/  widgets-and-live-activities, dynamic-island, control-center,
                    lock-screen, shortcuts-and-siri, app-clips,
                    share-extension, carplay, homekit, imessage-apps,
                    game-center, generative-ai

Load files lazily, only as the task requires.

---

Maintenance

HIG updates yearly around WWDC. After each release, re-verify the Last verified date at the top of each reference file and update any sizing numbers or API deprecations. The 2025 Liquid Glass refresh (iOS 26 / macOS 26) is covered in foundations/materials.md, foundations/app-icons.md, and the per-platform files.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: ebuntario
• Source: ebuntario/apple-hig
• License: MIT

Install and usage instructions live in the source repository linked above.