# Apple Hig

> Apple Human Interface Guidelines as a working reference — the visual and structural design system for iOS/iPadOS 26+ (Liquid Glass). Verbatim HIG corpus (171 pages) plus recovered hard specs — Dynamic Type scale, SF Pro tracking, system color hex, device metrics, layout margins. Use when building, reviewing, or converting UI that must look and behave Apple-native, on SwiftUI/UIKit or on the web. Covers components (buttons, sheets, tab bars, toolbars, lists, pickers), foundations (typography, color, layout, materials, icons, accessibility), and patterns (navigation, modality, onboarding, feedback, data entry). Trigger on "make this look like iOS", "Apple design", "HIG", "native iOS UI", "Liquid Glass", "system colors", "Dynamic Type", or any iOS design audit or spec question.

- Skill: `danielimad/apple-hig` (Agent Skill, multi-file: 177 files)
- Install (CLI): `npx skillmds@latest add danielimad/apple-hig`
- Raw SKILL.md: https://api.skillmd.com/api/skills/danielimad/apple-hig/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Design & Media
- Author: danielimad (https://skillmd.com/u/danielimad)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/danielimad/apple-hig

---


# Apple HIG

The visual and structural half of Apple design: what things look like, what size they are, what
they're called, and how they're composed. For motion, gestures, and interaction physics, use the
**apple-design** skill instead — the two are complements, not overlaps.

**Target: iOS/iPadOS 26+ (Liquid Glass).** Corpus crawled from developer.apple.com, most pages
stamped `2025-12-16` or later. Every reference file carries its own source URL and update date.

## How to use this skill

`references/` holds 171 verbatim HIG pages (1.8 MB). **Never read them all.** Read the specific
pages the task needs, and prefer the four digests below for anything numeric.

### Digests — read these first for hard values

| File | Contains |
| --- | --- |
| `references/_specs-typography.md` | Full Dynamic Type scale (xSmall→xxxLarge, AX1–AX5), SF Pro tracking per point size, minimum/default sizes |
| `references/_specs-color.md` | Every system color + gray as hex, light/dark/increased-contrast |
| `references/_specs-layout.md` | Device dimensions pt+px, size classes, margins, safe areas |
| `references/_specs-geometry.md` | Button sizes/padding/radii, Liquid Glass layer stack, sheet radii, standard margins. **Figma-derived — second-tier provenance, see the file header** |
| `references/_index.json` | Machine-readable map of all 171 pages: slug, title, platforms, update date, table count, abstract |

### Full pages — read on demand

Slug maps directly to filename: `references/buttons.md`, `references/sheets.md`,
`references/tab-bars.md`. Grep `_index.json` when unsure which page owns a topic.

## Non-negotiable specs

These are the values most often gotten wrong. All verified against Apple source.

**Type — iOS default (Large) Dynamic Type.** Size / leading in points:

| Style | Weight | Size | Leading |
| --- | --- | --- | --- |
| Large Title | Regular | 34 | 41 |
| Title 1 | Regular | 28 | 34 |
| Title 2 | Regular | 22 | 28 |
| Title 3 | Regular | 20 | 25 |
| Headline | Semibold | 17 | 22 |
| Body | Regular | 17 | 22 |
| Callout | Regular | 16 | 21 |
| Subhead | Regular | 15 | 20 |
| Footnote | Regular | 13 | 18 |
| Caption 1 | Regular | 12 | 16 |
| Caption 2 | Regular | 11 | 13 |

Tracking is **size-specific** — never one value. 17pt → −0.43pt; positive below 12pt, negative
above. Full table in the typography digest.

**Colors changed in iOS 26.** The "unified" palette revised several system colors. `systemBlue` is
now `#0088FF` (light), not the pre-26 `#007AFF`. `systemRed` is `#FF383C`, not `#FF3B30`. Do not
carry over older constants. Grays are unchanged: `systemGray #8E8E93`, `systemGray6 #F2F2F7` light /
`#1C1C1E` dark.

**Minimum tap target is 44×44 pt.** Non-negotiable, including on web.

**Body text minimum 11pt, default 17pt** on iOS/iPadOS.

**Buttons are capsules, not squircles.** `corner-radius: 1000` — fully rounded. Heights 50 / 34 / 28
for Large / Medium / Small. Continuous corner curvature does not apply to them. Sheets do use large
radii: 34 top on iPhone, 38 on iPad. Standard content margin is 16 iPhone / 20 iPad. Full geometry
in `references/_specs-geometry.md`.

## The most important rule

**On native, these specs are for auditing — not for typing in.**

Every number in the digests is something the system already produces. SwiftUI and UIKit give you the
50pt button, the 34pt sheet radius, the 17pt body text, the correct system blue. Reproducing those
values by hand does not make the UI more Apple-native — it makes it *less* so, because you have
frozen a value that is supposed to move. Hardcoded sizes break under Dynamic Type, break across
device classes, break in split view, and break when Apple revises the system next OS.

The failure looks like this:

```swift
// Wrong — freezes what the system should decide
Text("Continue").font(.system(size: 17)).frame(height: 50)
Button("Save") { }.background(Color(hex: "#0088FF")).cornerRadius(1000)

// Right — the system supplies the same values, and keeps supplying correct ones
Text("Continue").font(.body)
Button("Save") { }.buttonStyle(.glassProminent)
```

Use the specs to **verify** what you're rendering, to **build on the web** where nothing is given,
and to **reason about proportion**. Do not use them to reimplement what the framework ships. If you
are hardcoding a value from these tables on native, the fix is almost always to delete the modifier.

The exception is web work, where you must supply every value yourself — see §Web caveat.

## Working rules

1. **Semantic over literal.** Use `Color.primary`, `.secondarySystemBackground`, `.tint` — not raw
   hex — in native code. The hex table exists for web work and for verifying what the system
   produces, not for hardcoding into SwiftUI.
2. **Support Dynamic Type properly.** Scale layout with the text: spacing in relative units, no
   fixed-height text containers. Test at AX5 — that's where layouts break.
3. **Light and dark are both first-class.** Every color decision needs both. Increased-contrast
   variants exist and are in the digest.
4. **Liquid Glass is a material, not a color.** Translucent layers over content, with the content
   scrolling underneath. Never stack one translucent surface on another. See `references/materials.md`.
5. **Use SF Symbols for iconography** before drawing anything custom; match symbol weight to
   adjacent text weight. See `references/sf-symbols.md`.
6. **Respect the accessibility settings**: reduced motion, reduced transparency, increased contrast,
   bold text. See `references/accessibility.md`.
7. **Name things the way Apple names them.** A sheet is not a modal; a tab bar is not a nav bar.
   Correct vocabulary makes the rest of the guidance findable.

## Two workflows

### A. New build — designing from scratch

1. Read `references/designing-for-ios.md` and `references/design-principles.md` for posture.
2. Establish the token layer first, from the digests: type scale, color roles (light+dark), spacing,
   and the 44pt target. Everything downstream depends on it.
3. Pick navigation structure before screens — `references/tab-bars.md`, `references/sidebars.md`,
   `references/split-views.md`. This is the hardest thing to change later.
4. Compose from documented components. For each one used, read its page: correct anatomy, states,
   and platform behavior are all specified.
5. Check patterns for the flows involved — `references/onboarding.md`,
   `references/modality.md`, `references/feedback.md`, `references/entering-data.md`.
6. Verify against §Non-negotiable specs, then accessibility.

### B. Retrofit — converting an existing app

Produce a gap report before changing any code.

1. **Inventory.** List every screen, component, and token currently in use. Identify what each
   maps to in HIG vocabulary — this reveals both non-standard components and misused standard ones.
2. **Audit against the digests**, in this order (highest visual payoff first):
   - Type: is there a real scale, does it match Dynamic Type, does it respond to user text size?
   - Color: semantic roles or hardcoded hex? Does dark mode exist and is it correct?
   - Targets and spacing: anything under 44pt, inconsistent spacing?
   - Components: custom reimplementations of things the system already provides.
   - Materials and depth: opaque bars where translucent layers belong.
   - Accessibility: the four settings above.
3. **Classify each finding** as: `token` (cheap, global, high impact), `component` (medium, local),
   `structure` (expensive — navigation model, information architecture).
4. **Phase the plan.** Tokens first — they change everything at once and are low-risk. Components
   second. Structure last, and only where it earns the cost. State explicitly what you're not
   changing and why.
5. **Report as a table**: finding, HIG reference, current state, target state, effort, phase.
   Cite the reference file for every claim.

**On native, the target state is almost always "delete code", not "change the number".** A screen
with a hardcoded 44pt row height and `#007AFF` is not fixed by rewriting them to 50pt and `#0088FF`
— that repeats the original mistake with fresher values. It is fixed by removing the literals so
the system supplies them, and the value stops being your problem at the next OS release. Prefer, in
order: use the system component → use the semantic token → use the system value → hardcode (last
resort, and note why).

A good retrofit usually *reduces* the amount of styling code. If your plan adds spec constants
everywhere, you have translated Apple's system into your own dialect instead of adopting it.

## Web caveat

When targeting the browser rather than native, these do not transfer cleanly — say so rather than
faking it:

- **SF Pro is not licensed for general web use.** Use `-apple-system, BlinkMacSystemFont, system-ui`
  so Apple platforms get the real font and others fall back gracefully.
- **Continuous corner curvature** (Apple's squircle) has no CSS equivalent. `border-radius` is an
  approximation; a slightly larger radius reads closer.
- **Liquid Glass** approximates as `backdrop-filter: blur() saturate()` over a semi-transparent
  background. It is not the same material and will not match on non-Apple hardware.
- **Points are not pixels.** 1pt = 1 CSS px at 1x, but Apple's specs assume 2x/3x rendering.
- Dynamic Type maps to `rem` plus `@media (prefers-*)` queries, not to the OS text-size setting.

## Provenance

Crawled from `developer.apple.com/tutorials/data/design/human-interface-guidelines/*.json` —
Apple's own backing API for the HIG site, so the prose is verbatim rather than reconstructed.
Color hex values are not published as text; they were recovered by sampling Apple's published
swatch images at 2x, and validated against known constants (`systemGray #8E8E93`,
`systemGray6 #F2F2F7`, `systemGreen` dark `#30D158` — all exact matches).

**Refreshing after a WWDC:** re-run the crawl and diff. Each page's `Change log` section and the
`updated` field in `_index.json` show what Apple revised and when.