apple-hig

name

apple-hig

description

Design, build, review, or AUDIT interfaces that follow Apple's Human Interface Guidelines (HIG) for iOS 26, iPadOS, macOS, watchOS, tvOS, visionOS — Liquid Glass era, Swift 6 / SwiftUI, UIKit, AppKit. Use for any request to make a UI feel native to Apple — even when "HIG" is not said — including web/Figma mockups and Flutter/React Native Cupertino UI. TRIGGER on: "iOS app", "macOS app", "visionOS", "SwiftUI", "HIG", "Apple design", "SF Symbols", "Dynamic Type", "Dark Mode", "Liquid Glass", "safe area", "accessibility review", "tap target", "audit my UI against the HIG", "should I use a modal here". Run Phase 0 (targeting + project-context check) before generating code or a spec.

apple-hig

Make Claude actually follow Apple's Human Interface Guidelines when building, reviewing, or auditing UI for iOS, iPadOS, macOS, watchOS, tvOS, or visionOS. Current to the 2025 Liquid Glass design language (iOS 26 / iPadOS 26 / macOS 26) and Swift 6 / SwiftUI. Works with SwiftUI, UIKit, AppKit, adaptive Flutter (Cupertino), and Apple-native-feeling web/Figma mockups.

Status: stable. Reference content cites the live HIG and is verified for the iOS 26 era. If HIG guidance evolves (WWDC, policy changes), update the matching reference file's Last verified: date and revise. Apple updates the HIG roughly yearly around WWDC.

You are an expert in Apple's Human Interface Guidelines. Be specific about component names, API constants, design tokens, and exact sizing. Distinguish requirements ("must") from recommendations ("should", "consider"). Cite the relevant HIG topic when giving guidance.

---

How to use this skill

1. Run Phase 0 (targeting + project-context check) before generating anything.
2. Identify the target platform(s) and the component / pattern in play (e.g., settings screen, modal sheet, list, toolbar, onboarding).
3. Load only the reference files you need via the Decision Tree — never the whole references/ tree. This progressive-disclosure model keeps context lean.
4. Never produce code or a design spec without consulting (a) references/foundations.md (accessibility floor + color/type/materials), (b) the relevant platform section in references/platforms.md, and (c) the relevant component or pattern guidance.
5. Apply the Core non-negotiables on every output.
6. Run the final review checklist (references/checklists.md) before calling work complete.

---

Phase 0 — Targeting and project context (do this first)

Check for .claude/apple-design-context.md before asking any questions. If it exists, read it and use it — only ask for what it does not already cover. This file is a durable, per-project design brief (platforms, frameworks, brand colors, accessibility bar). If the project is non-trivial and no context file exists, offer to create one from the template in references/apple-design-context-template.md so future turns skip the interview.

Then resolve targeting. Use AskUserQuestion to ask up to two of these in one turn. Skip any the user already answered.

1. Target platform(s)? (multi-select) — iOS / iPhone · iPadOS · macOS · watchOS · tvOS · visionOS
2. Framework? (multi-select) — SwiftUI · UIKit / AppKit · Flutter (adaptive Cupertino) · Web or Figma (Apple-native feel)
3. What are you building? (single-select) — New full screen/window · Single component · Design spec (no code) · Reviewing/auditing existing UI

If the brief is already clear ("I'm building an iPhone onboarding screen in SwiftUI"), skip the questions and go straight to loading references.

---

Decision tree — what to load

What the user is doing	Load these references
Building a list / feed screen	components.md (lists) + platforms.md (target) + foundations.md (layout, a11y)
Settings screen	patterns.md (settings) + platforms.md + components.md (lists)
Modal / sheet	patterns.md (modality) + components.md (sheets) + platforms.md
Onboarding flow	patterns.md (onboarding) + platforms.md
Navigation structure	patterns.md (navigation) + components.md (bars) + platforms.md
Search experience	patterns.md (searching) + components.md (bars)
Forms / data entry	patterns.md (entering-data) + components.md (text inputs, pickers)
Picking colors	foundations.md (color, dark-mode)
Icons / glyphs	foundations.md (SF Symbols)
Typography decisions	foundations.md (typography, a11y)
Motion / animation	foundations.md (motion, a11y)
Materials / Liquid Glass	foundations.md (materials)
Feedback / haptics / alerts	patterns.md (feedback) + foundations.md (a11y)
macOS window / toolbar	platforms.md (macOS) + components.md (bars, split views)
iPad sidebar / split view	platforms.md (iPadOS) + components.md (split views, bars)
watchOS glance / complication	platforms.md (watchOS)
tvOS focus-driven screen	platforms.md (tvOS)
visionOS window / ornament	platforms.md (visionOS) + foundations.md (materials)
Live Activity / Dynamic Island / Widget	platforms.md (iOS — system features)
Web / Figma mockup, Apple-native feel	foundations.md (typography, color, layout, SF Symbols) + design-heuristics.md
Adaptive Flutter (iOS Cupertino)	platforms.md (iOS) + design-heuristics.md (adaptive branching)
Reviewing / auditing existing UI (code)	checklists.md + audit-workflow.md + the foundations/platform files for the violations found
Reviewing a screen image / Figma frame (no code)	audit-workflow.md (Nielsen 0–4 scale + screen-eval report template) + design-heuristics.md (Nielsen 10, visibility minimums, 2–3 lever rule)
Picking a starting palette / per-vertical accent + symbols	design-heuristics.md §2 (palette seeds — design phase only, never ship hex)

---

Core non-negotiables

Apply on every output. Each has a reason — these are the items that fail accessibility review or feel non-native.

• Touch / focus targets. iOS/iPadOS ≥ 44×44pt (28pt absolute floor). watchOS ≥ 44pt on 44mm+ / 40pt smaller. macOS pointer ≥ 28×28pt. tvOS: every actionable view focusable (≥ 66pt). visionOS ≥ 60pt. Put ~12pt padding around bezeled controls, ~24pt around bezel-less — two 44pt targets flush together still mis-fire.
• Dynamic Type. Use text styles (.body, .headline, .title) or UIFontMetrics. Never hardcode point sizes for body copy. Test through AX5. (macOS uses dynamic font variants — no Dynamic Type.)
• Dark Mode. Semantic colors (Color(.label), Color(.systemBackground), Color.accentColor) or asset-catalog colors with light/dark/increased-contrast variants. No hex literals in production UI — they break dark mode, increased contrast, and tinted icons.
• VoiceOver. Every non-decorative view has an accessibility label. .accessibilityLabel / .accessibilityHint / correct traits. Decorative images get .accessibilityHidden(true).
• SF Symbols first. If a system glyph exists (checkmark, magnifyingglass, xmark.circle.fill), use it. Custom icons only when no equivalent exists — and never in app icons / logos (license forbids it).
• Reduce Motion. Respect @Environment(\.accessibilityReduceMotion) / UIAccessibility.isReduceMotionEnabled. Swap parallax / springs / z-axis for cross-fades. Never animate into or out of blurs.
• Platform-correct navigation. iOS → tab bar or navigation stack. iPadOS → sidebar / split view at regular width (.sidebarAdaptable). macOS → menu bar + toolbar + sidebar (no tab bar). watchOS → page or hierarchical. tvOS → focus-driven. visionOS → ornaments
  • glass windows. Don't nest two top-level paradigms.
• Liquid Glass is for chrome, not content. Tab bars, sidebars, toolbars, floating controls float on the Liquid Glass layer above full-bleed content. Don't apply a glass effect to a flat content card. Don't ship a custom opaque toolbar — the system toolbar is Liquid Glass for free.
• Safe areas. Respect .safeAreaInset(...) / safe-area layout guides. Backgrounds go full-bleed; interactive elements never slide under the home indicator, Dynamic Island, or camera housing.
• RTL-safe layout. Leading / trailing, never left / right. Mirror directional icons.
• Writing. "Tap" on touch platforms, "Click" on macOS, "Select"/"Choose" when platform-agnostic. Sentence case in buttons and labels (not Title Case, unless it's a title). No destructive verb without confirmation copy that says what will happen.
• Minimize modality + prefer undo. Sheets for focused sub-tasks that return to the parent; drill-in for hierarchy. Undo beats "Are you sure?" for reversible actions. Reserve alerts for blocking, user-actionable errors.

---

Output format

When giving HIG guidance, structure the response:

1. Recommendation with rationale, citing the relevant HIG topic / reference file.
2. Implementation — SwiftUI first; add UIKit/AppKit when the user uses them.
3. Platform variations for each targeted platform.
4. Common pitfalls that violate the HIG for this pattern.
5. Cite the HIG URL in any design doc deliverable for every non-obvious rule.

---

Common mistakes without this skill

• A custom font where SF Pro / SF Compact / New York is correct; or mixing 4+ typefaces.
• Hardcoded hex colors that break dark mode and tinted icons.
• 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.
• A custom opaque toolbar instead of the system Liquid Glass toolbar; tinting every toolbar button with the accent color.
• Ignoring safe areas; content under the home indicator or notch.
• Forgetting Reduce Motion; parallax onboarding for motion-sensitive users.
• Light-mode-only screens; missing VoiceOver labels on icon-only buttons.
• "Click" on iOS or "Tap" on macOS.
• Inventing non-standard navigation instead of NavigationStack / NavigationSplitView / menu bar; reinventing the system tab bar.
• 6+ tabs in a tab bar (max 5 — use a More tab).

---

Auditing existing UI

When the task is "review / audit my UI against the HIG", follow references/audit-workflow.md: detect the framework, scan for the high-signal violations (hex literals, fixed font sizes, sub-44pt targets, missing accessibility labels, custom-toolbar-instead-of-system, modal overuse), then produce a structured report grouped by HIG category (Foundations / Platform fit / Components / Accessibility / Writing) with severity and the exact fix per finding. Preserve the user's design — HIG fixes are structural and semantic, not a cosmetic redesign.

audit-workflow.md also covers the discipline that keeps a grep-based audit trustworthy: cut false positives (strip comments but keep strings; // is not a comment in CSS/HTML/.storyboard/.xib; context-aware and file-level suppression; the tempered-greedy-token "X without Y" regex), a severity judgment layer (don't let a heuristic check block a CI gate), and a separate screen-image / Figma path (Nielsen 0–4 scale, the screen-eval + batch-summary + CSV templates, and review-discipline rules). For the visual-quality rubrics it leans on — Nielsen's 10, visibility minimums, the 2–3 lever rule — see design-heuristics.md.

---

Final review checklist (run before calling work complete)

Load references/checklists.md and confirm every item passes. Minimum bar:

• Touch / focus target minimums met for the target platform
• Dynamic Type scales without clipping (tested at AX5)
• Dark Mode verified in light + dark + Increase Contrast — no hex literals
• VoiceOver label on every interactive view; decorative images hidden
• SF Symbols used where a system glyph exists
• Reduce Motion path exists for any non-trivial animation
• Navigation paradigm matches the target platform; no nested paradigms
• Liquid Glass used for chrome only; content stays in the content layer
• Safe areas respected; content not under home indicator / Dynamic Island
• Writing tone matches platform (Tap vs Click, sentence case, destructive confirms)
• HIG references cited in any generated design doc

---

Reference tree

references/
├── foundations.md                  Typography, color, dark mode, SF Symbols, materials
│                                   (Liquid Glass), motion, layout, and the accessibility
│                                   floor — the always-load foundation rules.
├── platforms.md                    Per-platform deep dives: iOS, iPadOS, macOS, watchOS,
│                                   tvOS, visionOS — traits, navigation, sizing tables,
│                                   system features, full SwiftUI + UIKit screen samples.
├── patterns.md                     Interaction/UX patterns: navigation, modality,
│                                   onboarding, search, settings, feedback/haptics,
│                                   entering data, loading, notifications, undo.
├── components.md                   Component guidance: bars (tab/nav/toolbar), buttons,
│                                   lists & tables, sheets & popovers, text inputs,
│                                   pickers & menus, split views, alerts.
├── checklists.md                   Pre-submission HIG review + accessibility review.
├── audit-workflow.md               How to audit an existing project against the HIG and
│                                   produce a structured report (framework detection,
│                                   violation patterns, severity, fixes).
├── design-heuristics.md            Cross-platform visual-design heuristics (8pt grid,
│                                   color ratio, thumb zone, hierarchy) + adaptive Flutter
│                                   + Apple-native web/hybrid gotchas.
└── apple-design-context-template.md  Template for .claude/apple-design-context.md so the
                                    skill skips re-interviewing on every turn.

Load files lazily, only as the task requires. The reference files are self-contained; each cites its HIG source URL and a Last verified: date.