Apple Design Language

Apple Design Language

The editorial layer for Apple apps on iOS, iPadOS, and macOS: the parts of "feels Apple-quality" that aren't a spacing number — copy, interaction states, empty/error states, and the judgment of when to follow versus tastefully break the Human Interface Guidelines. Think in capabilities (touch vs. pointer, compact vs. regular vs. window), not device names.

This skill is the entry point to the design language. It owns four things and routes everything else.

Orientation index

| Concern | Where it lives | |---|---| | Spacing, optical alignment, padding, corner concentricity, hairlines, depth | swiftui-micro-craft | | Motion timing, named springs, gestures, haptics | swiftui-micro-craft | | Type scale mechanics, SF Symbol sizing/weight, Dynamic Type plumbing | swiftui-micro-craft | | Color, design tokens, Liquid Glass, system materials | apple-design | | VoiceOver, Dynamic Type coverage, tap-target sizing | ios-accessibility | | Adaptive layout, size classes, multi-platform navigation | cross-platform-adaptivity | | UX writing & copy | this skill → references/ux-writing.md | | Forms, validation, focus, loading, control states | this skill → references/interaction-states.md | | Empty & error states | this skill → references/empty-error-states.md | | When to follow vs. break HIG; quality-vs-slop judgment | this skill (below) | | Worked examples of tasteful HIG deviation | this skill → references/exemplars.md |

HIG is the floor, not the ceiling

The Human Interface Guidelines encode what is safe and approvable. Meet that floor everywhere. But Apple's own best apps — and most Apple Design Award winners — exceed or selectively break the defaults where it serves the user. "HIG-compliant" and "great" are not the same target. Your job: clear the floor without exception, then raise the ceiling deliberately.

Deviation decision gates

Deviate from a HIG default only when all four hold:

1. Named benefit — you can state the user benefit in one sentence that isn't "looks better," "feels modern," or "cleaner."
2. Survives the slop check — it is not one of the numbered tells below (and will pass swiftui-design-check once that exists).
3. Survives assistive tech — still correct under VoiceOver and Dynamic Type at AX5 (see ios-accessibility).
4. Systematic — applied as a rule across the app, not a one-off that creates an inconsistency.

If any gate fails, use the HIG default. Deviation is earned, not assumed.

Anti-slop tells (numbered — the contract with swiftui-design-check)

These are the Apple-native equivalents of web "AI slop." Each is numbered so the swiftui-design-check linter (sub-project #2) can map a scanner rule to it. Statically detectable ones are marked ⚙.

1. ⚙ System-gray everything — flat .gray/Color(.systemGray) fills where a system material or hierarchical foreground style belongs.
2. Sheet-for-everything — a modal .sheet where a push, popover, menu, or inline disclosure fits the navigation depth better.
3. ⚙ Unlabeled icon-only buttons — an icon Button/Label(systemImage:) with no accessibilityLabel and no visible text.
4. ⚙ Untouched .automatic styling — default button/list/navigation styling shipped with no deliberate choice behind it.
5. ⚙ Center-everything layout — no leading-edge alignment hierarchy; titles, body, and controls all centered.
6. ⚙ Hardcoded font sizes — .font(.system(size: 17)) instead of a semantic text style.
7. ⚙ Twin full-width CTAs — primary and secondary actions given equal visual weight, destroying hierarchy.
8. ⚙ Emoji as iconography — emoji where an SF Symbol is the native choice.
9. ⚙ Placeholder-as-label — relying on TextField placeholder text instead of a persistent field label.
10. Spinner-for-everything — indeterminate spinners where a skeleton or determinate progress fits, with no empty/error variant designed.
11. Overlay for the critical — a non-modal banner or overlay where an .alert is required (data loss, destructive confirmation).
12. ⚙ Gradient-and-glow slop — decorative purple-ish gradients, drop-glows, or faux depth not derived from system materials.
13. Generic empty state — "No items" with no cause and no next action (see references/empty-error-states.md).
14. ⚙ Title Case body copy — title-casing sentences, labels, or descriptions that should be sentence case (see references/ux-writing.md).

Quick reference

Capitalization

| Use | Case | |---|---| | Nav-bar titles, buttons, menu items, alert titles | Title Case | | Labels, body text, alert messages, hints, footnotes, placeholders | Sentence case |

Button verbs (pick the precise word)

| Word | Use for | |---|---| | Done | Dismiss, keeping changes already applied | | Save | Commit changes that aren't applied yet | | Cancel | Dismiss, discarding changes | | OK | Acknowledge an alert with no alternative — prefer a specific verb when one fits | | Delete / Remove | Destructive — pair with confirmation; never "OK" |

Empty/error: which surface

Data loss or destructive confirmation → .alert. Recoverable, non-blocking → inline state or banner. No data yet → designed empty state with cause + action. Full tree in references/empty-error-states.md.

Relationship to other skills

This skill is the design-language hub. It complements swiftui-micro-craft (quantified visual craft), apple-design (tokens, color, Liquid Glass), ios-accessibility (assistive tech), and cross-platform-adaptivity (layout). It is consumed by apple-review and apple-polish (design panels) and paywall-design (copy). The numbered anti-slop tells above are the rule source for swiftui-design-check.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: markdavidgan
• Source: markdavidgan/apple-dev-skills
• License: MIT

Install and usage instructions live in the source repository linked above.