axiom-hig-ref

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)    // Black in Light, white in Dark
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.

// Standard list → ungrouped backgrounds
List { Text("Item") }
    .background(Color(.systemBackground))

// Settings-style list → grouped backgrounds
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:

// Tint color automatically adapts
Button("Primary Action") {
    // action
}
.tint(.blue)
// Gets lighter in Dark Mode, darker in Light Mode

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:

// System fill colors
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

// Standard separator (semi-transparent)
Color(.separator)

// Opaque 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:

1. Open Assets.xcassets
2. Add Color Set
3. Configure variants:
   • Light mode color
   • Dark mode color
   • High Contrast Light (optional but recommended)
   • High Contrast Dark (optional but recommended)

// Use custom color from asset catalog
Color("BrandAccent")
// Automatically uses correct variant

---

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:

// Headers - Bold weight for prominence
Text("Header")
    .font(.title.weight(.bold))

// Subheaders - Semibold
Text("Subheader")
    .font(.title2.weight(.semibold))

// Body - Regular or Medium
Text("Body text")
    .font(.body)

// Captions - Regular (never Light)
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:

// ✅ CORRECT - Scales automatically
Text("Hello")
    .font(.body)

// ❌ WRONG - Fixed size, doesn't scale
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)

// Adjust leading for specific layouts
Text("Long content...")
    .lineSpacing(8) // Add space between lines

---

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 radius regardless of size:

RoundedRectangle(cornerRadius: 12)

Use when: You need a specific, unchanging corner radius.

2. Capsules

Radius is half the container's height:

Capsule()

Use when: You want shapes that adapt to

---

Content truncated.