Apple Human Interface Guidelines — Comprehensive Reference
Overview
The Human Interface Guidelines (HIG) define Apple's design philosophy and provide concrete guidance for creating intuitive, accessible, platform-appropriate experiences across all Apple devices.
Three Core Principles
Every design decision should support these principles:
1. Clarity
Content is paramount. Interface elements should defer to content, not compete with it. Every element has a purpose, unnecessary complexity is eliminated, and users should immediately know what they can do without extensive instructions.
2. Consistency
Apps use standard UI elements and familiar patterns. Navigation follows platform conventions, gestures work as expected, and components appear in expected locations. This familiarity reduces cognitive load.
3. Deference
The UI should not distract from essential content. Use subtle backgrounds, receding navigation when not needed, restrained branding, and let content be the hero.
From Apple HIG: "Deference makes an app beautiful by ensuring the content stands out while the surrounding visual elements do not compete with it."
Design System Philosophy
From WWDC25: "A systematic approach means designing with intention at every level, ensuring that all elements, from the tiniest control to the largest surface, are considered in relation to the whole."
Related Skills
- Use
axiom-hig for quick decisions and checklists
- Use
axiom-liquid-glass for iOS 26 material implementation
- Use
axiom-liquid-glass-ref for iOS 26 app-wide adoption
- Use
axiom-accessibility-diag for accessibility troubleshooting
Color System
Semantic Colors Explained
Instead of hardcoded color values, use semantic colors that describe the purpose of a color rather than its appearance. Semantic colors automatically adapt to light/dark mode and accessibility settings.
Key insight from WWDC19: "Think of Dark Mode as having the lights dimmed rather than everything being flipped inside out." Colors are NOT simply inverted—table row backgrounds are lighter in both modes.
Label Colors (Foreground Content)
Four semantic label levels for text and symbols, each progressively less prominent:
| Style |
Semantic Color |
Usage |
.primary |
label |
Titles, most prominent text |
.secondary |
secondaryLabel |
Subtitles, less prominent |
.tertiary |
tertiaryLabel |
Placeholder text |
.quaternary |
quaternaryLabel |
Disabled text |
Text("Title").foregroundStyle(.primary)
Text("Subtitle").foregroundStyle(.secondary)
Background Colors (Primary → Tertiary)
Background colors come in two sets — ungrouped (standard lists) and grouped (iOS Settings style):
| Level |
Ungrouped |
Grouped |
| Primary |
.systemBackground |
.systemGroupedBackground |
| Secondary |
.secondarySystemBackground |
.secondarySystemGroupedBackground |
| Tertiary |
.tertiarySystemBackground |
.tertiarySystemGroupedBackground |
Ungrouped: pure white/black in Light/Dark. Grouped: light gray/dark in Light/Dark.
List { Text("Item") }
.background(Color(.systemBackground))
List { Section("Section") { Text("Item") } }
.listStyle(.grouped)
Base vs Elevated Backgrounds
There are actually two sets of background colors for layering interfaces:
- Base set: Used for background apps/interfaces
- Elevated set: Used for foreground apps/interfaces
Why this matters:
In Light Mode, simple drop shadows create visual separation. In Dark Mode, drop shadows are less effective, so the system uses lighter colors for elevated content.
Example: iPad multitasking:
- Mail app alone → base color set
- Contacts in slide-over → elevated colors (lighter, stands out)
- Both side-by-side → both use elevated colors for contrast around splitter
- Email compose sheet → elevated colors with overlay dimming
Critical: Some darker colors may not contrast well when elevated. Always test designs in elevated state. Semi-opaque fill and separator colors adapt gracefully.
Tint Colors (Dynamic Adaptation)
Tint colors are dynamic - they have variants for Light and Dark modes:
Button("Primary Action") {
}
.tint(.blue)
Custom tint colors:
When creating custom tint colors, select colors that work well in both modes. Use a contrast calculator to aim for 4.5:1 or higher contrast ratio. Colors that work in Light Mode may have insufficient contrast in Dark Mode.
Fill Colors (Semi-Transparent)
Fill colors are semi-transparent to contrast well against variable backgrounds:
Color(.systemFill)
Color(.secondarySystemFill)
Color(.tertiarySystemFill)
Color(.quaternarySystemFill)
When to use: Controls, buttons, and interactive elements that need to appear above dynamic backgrounds.
Separator Colors
Color(.separator)
Color(.opaqueSeparator)
Opaque separators are used when transparency would create undesirable results (e.g., intersecting grid lines where overlapping semi-transparent colors create optical illusions).
When to Use Permanent Dark Backgrounds
Apple's explicit guidance:
"In rare cases, consider using only a dark appearance in the interface. For example, it can make sense for an app that enables immersive media viewing to use a permanently dark appearance that lets the UI recede and helps people focus on the media."
Examples from Apple's apps:
| App |
Background |
Rationale |
| Music |
Dark |
Album art should be visual focus |
| Photos |
Dark |
Images are hero content |
| Clock |
Dark |
Nighttime use, instrument feel |
| Stocks |
Dark |
Data visualization, charts |
| Camera |
Dark |
Reduces distraction during capture |
For all other apps: Support both Light and Dark modes via system backgrounds.
Creating Custom Colors
When you need custom colors:
- Open Assets.xcassets
- Add Color Set
- Configure variants:
- Light mode color
- Dark mode color
- High Contrast Light (optional but recommended)
- High Contrast Dark (optional but recommended)
Color("BrandAccent")
Typography
System Fonts
San Francisco (SF): The system sans-serif font family.
- SF Pro: General use
- SF Compact: watchOS and space-constrained layouts
- SF Mono: Code and monospaced text
- SF Rounded: Softer, friendlier feel
- Weights: Ultralight, Thin, Light, Regular, Medium, Semibold, Bold, Heavy, Black
New York (NY): System serif font family for editorial content.
Both available as variable fonts with seamless weight transitions.
Font Weight Recommendations
From Apple HIG: "Avoid light font weights. Prefer Regular, Medium, Semibold, or Bold weights instead of Ultralight, Thin, or Light."
Why: Light weights have legibility issues, especially at small sizes, in bright lighting, or for users with visual impairments.
Hierarchy:
Text("Header")
.font(.title.weight(.bold))
Text("Subheader")
.font(.title2.weight(.semibold))
Text("Body text")
.font(.body)
Text("Caption")
.font(.caption)
Text Styles for Hierarchy
Use built-in text styles for automatic hierarchy and Dynamic Type support:
.font(.largeTitle) .font(.title) .font(.title2)
.font(.title3) .font(.headline) .font(.body)
.font(.callout) .font(.subheadline) .font(.footnote)
.font(.caption) .font(.caption2)
All text styles scale automatically with Dynamic Type.
Dynamic Type Support
Requirement: Apps must support text scaling of at least 200% (iOS, iPadOS) or 140% (watchOS).
Implementation:
Text("Hello")
.font(.body)
Text("Hello")
.font(.system(size: 17))
Layout considerations:
- Reduce multicolumn layouts at larger sizes
- Minimize text truncation
- Use stacked layouts instead of inline at large sizes
- Maintain consistent information hierarchy regardless of size
Not all content scales equally: Prioritize what users actually care about. Secondary elements like tab titles shouldn't grow as much as primary content.
Custom Fonts
When using custom fonts:
- Ensure legibility at various distances and conditions
- Implement Dynamic Type support
- Respond to Bold Text accessibility setting
- Test at all text sizes
- Match system font behaviors for accessibility
If your custom font is thin: Increase size by ~2 points when pairing with uppercase Latin text.
Leading (Line Spacing)
Loose leading: Wide columns (easier to track to next line)
Tight leading: Constrained height (avoid for 3+ lines)
Text("Long content...")
.lineSpacing(8)
Shapes & Geometry
Three Shape Types (iOS 26)
From WWDC25: "There's a quiet geometry to how our shapes fit together, driven by concentricity. By aligning radii and margins around a shared center, shapes can comfortably nest within each other."
1. Fixed Shapes
Constant corner radiu
