| name | apple-hig |
| description | Apple Human Interface Guidelines skill — spec (not code library) for iOS / iPadOS / macOS / visionOS / watchOS / tvOS native apps. Use as design token source for SwiftUI or as visual reference when replicating Apple aesthetics on the web. Includes SF Pro typography, spacing scale, corner radius tokens, dynamic system colors, Liquid Glass materials (WWDC 2025), and HIG principles. |
Apple Human Interface Guidelines — Design Spec Reference
Source: https://developer.apple.com/design/
Nature: Specification only — not a component library. Extract as design tokens.
Latest: Liquid Glass materials introduced at WWDC 2025
Health: 🟢 active (continuously updated)
1. When to use
- Building native iOS / macOS / visionOS apps (implement via SwiftUI — this is the design spec)
- Replicating Apple-style web pages or marketing sites
- AI agents generating UI for products that should feel "Apple-like"
- Extract as brand DNA in DesignDNA (see
design-md/apple/DESIGN.md)
2. Typography — SF Pro family
| Face | Use case |
|---|
| SF Pro Display | Headlines, large titles (≥ 20pt) |
| SF Pro Text | Body, labels, small UI copy (< 20pt) |
| SF Pro Rounded | Playful contexts (games, kids apps) |
| SF Mono | Code, technical data |
| SF Arabic / SF Hebrew | Non-Latin localization |
| SF Symbols | Icon font (6,000+ symbols) |
Dynamic Type sizes (iOS)
| Size | Default pt | Range |
|---|
| Large Title | 34 | 23–60 |
| Title 1 | 28 | 18–48 |
| Title 2 | 22 | 14–36 |
| Title 3 | 20 | 12–32 |
| Headline | 17 (semibold) | 11–30 |
| Body | 17 | 11–53 |
| Callout | 16 | 10–29 |
| Subheadline | 15 | 9–28 |
| Footnote | 13 | 7–25 |
| Caption 1 | 12 | 6–23 |
| Caption 2 | 11 | 5–22 |
Apps must respect the user's chosen Dynamic Type size.
3. Spacing — 4pt / 8pt grid
- Baseline grid: 4pt (also shown as 4px at 1x)
- Most spacing multiples of 8pt: 8 / 16 / 24 / 32 / 48 / 64
- Min touch target: 44 × 44 pt (iOS) · 40 × 40 pt (macOS)
- Safe area insets honored via
safe-area-inset-* CSS or SwiftUI safeAreaInset
4. Corner radius
| Context | Radius |
|---|
| Buttons, text fields | 10–12 pt |
| Cards, popovers | 16 pt |
| Sheets (half / form) | 10 pt top corners only |
| Widgets | 22 pt (iOS 17+) |
| App icon rounded rect | 22.37% of icon width |
| Continuous corners (squircle) | Preferred over strict circle — looks less harsh |
On iOS/macOS use .cornerRadius(16) OR .clipShape(RoundedRectangle(cornerRadius: 16, style: .continuous)) (squircle).
5. Dynamic system colors
Apple's colors auto-adapt light/dark. Do not hardcode grays.
| Token | Light | Dark |
|---|
| label | #000 | #fff |
| secondaryLabel | #3c3c4399 | #ebebf599 |
| tertiaryLabel | #3c3c434c | #ebebf54c |
| systemBackground | #fff | #000 |
| secondarySystemBackground | #f2f2f7 | #1c1c1e |
| tertiarySystemBackground | #fff | #2c2c2e |
| separator | #3c3c4349 | #54545899 |
| systemBlue | #007aff | #0a84ff |
| systemRed | #ff3b30 | #ff453a |
| systemGreen | #34c759 | #30d158 |
In web / Tailwind, replicate with CSS variables:
:root {
--label: rgba(0, 0, 0, 1);
--secondary-label: rgba(60, 60, 67, 0.6);
--system-background: #fff;
--system-blue: #007aff;
}
@media (prefers-color-scheme: dark) {
:root {
--label: rgba(255, 255, 255, 1);
--secondary-label: rgba(235, 235, 245, 0.6);
--system-background: #000;
--system-blue: #0a84ff;
}
}
6. Liquid Glass (WWDC 2025)
Introduced for iOS 18+ / macOS 15+. Translucent layered materials with depth.
Material layers
| Material | Opacity | Use |
|---|
| Ultra thin | ~40% | Floating nav, tab bar over content |
| Thin | ~60% | Sheets over background |
| Regular | ~80% | Standard modals |
| Thick | ~90% | Emphasized overlays |
| Ultra thick | ~95% | Fallback when blur isn't supported |
Web approximation
.glass {
background: rgba(255, 255, 255, 0.7);
backdrop-filter: blur(20px) saturate(180%);
border: 0.5px solid rgba(255, 255, 255, 0.4);
box-shadow: 0 10px 40px rgba(0, 0, 0, 0.08);
}
@media (prefers-color-scheme: dark) {
.glass {
background: rgba(20, 20, 22, 0.7);
border-color: rgba(255, 255, 255, 0.1);
}
}
Use sparingly — overuse defeats the depth contrast. Reserve for nav bars, floating modals, picker popovers.
7. Motion principles
| Principle | Guideline |
|---|
| Purposeful | Animation should communicate state or navigation |
| Responsive | < 400ms for interaction feedback |
| Natural | Use spring-like easing, not linear |
| Consistent | Same action = same animation |
| Respectful | Honor prefers-reduced-motion |
Default easing: cubic-bezier(0.25, 0.1, 0.25, 1) (ease-out-ish).
8. Layout principles
- Space over decoration: whitespace carries meaning
- Photography-first: product imagery dominates marketing pages
- Sentence case for titles: "Get started" not "Get Started"
- One primary action per screen: resist stacking CTAs
- Consistent alignment: left-align most content; centered only for hero
9. Web-side implementation (when to use)
| Scenario | Recommendation |
|---|
| Apple marketing page clone | Use HIG tokens as brand DNA |
| iOS-native app | Use SwiftUI — respects HIG automatically |
| Progressive web app mimicking iOS feel | Use HIG tokens + Liquid Glass CSS approximation |
| Enterprise app | Probably don't mimic — HIG is context-specific; use MUI / Fluent / Ant instead |
10. BANNED (when targeting Apple aesthetic)
- ❌ NEVER use pure
#000 text — use #1d1d1f warm near-black
- ❌ NEVER use pure
#fff surfaces — use #fafaf9 warm off-white
- ❌ NEVER use generic system fonts — SF Pro (or fallback to
-apple-system)
- ❌ NEVER use thick borders — Apple uses very subtle
rgba(0,0,0,0.08) or separators
- ❌ NEVER use saturated neon colors as accents — Apple's accents are restrained (system blue, muted)
- ❌ NEVER use all-caps headings (except tiny eyebrow labels ≤ 12pt)
- ❌ NEVER stack multiple primary CTAs — Apple uses ONE primary, optionally one secondary link
- ❌ NEVER use fake-looking "Loading..." placeholders — Apple uses shimmer skeletons or spinner
- ❌ NEVER use emoji in headings or buttons
- ❌ NEVER override dynamic system colors with hardcoded hex (on iOS native)
11. Pre-flight checklist (Apple-style UI)
- [ ] Typography uses SF Pro (native) or -apple-system fallback (web)
- [ ] Spacing on 4pt/8pt grid
- [ ] Touch targets ≥ 44pt
- [ ] Warm near-black text, not #000
- [ ] Off-white backgrounds, not pure #fff
- [ ] Dynamic system colors used (iOS) or CSS variables with light/dark (web)
- [ ] Border radius uses continuous corners (squircle) where possible
- [ ] Liquid Glass used sparingly (nav, modals only)
- [ ] One primary action per section
- [ ] Safe area insets honored
- [ ] prefers-reduced-motion respected
- [ ] Animation easing is natural (not linear)
12. Dial fit (Apple aesthetic)
formality: 9 · motion: 4 · density: 2 · warmth: 6 · contrast: 7
13. Related
- Apple brand DNA:
design-md/apple/DESIGN.md + design-md/apple/BANNED.md in this repo
- SwiftUI: Apple's native UI framework — automatically respects HIG
- For native iOS: do NOT use
material-components-ios (archived 2025-12). Use SwiftUI directly.
