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

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:

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:

// 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.