references/code-implementation.md
# Code Implementation — HTML/CSS/JS & React + Tailwind
Concrete tokens and recipes. Read alongside the HIG references (app UI) or marketing-pages (landing pages).
## Design tokens (drop-in CSS)
```css
:root {
--font-stack: -apple-system, BlinkMacSystemFont, "SF Pro Display", "SF Pro Text",
Inter, "Helvetica Neue", Arial, sans-serif;
/* HIG semantic tokens — light */
--label: #000;
--label-2: rgba(60,60,67,.60);
--label-3: rgba(60,60,67,.30);
--separator: rgba(60,60,67,.29);
--bg: #fff; --bg-2: #f2f2f7; --bg-3: #fff;
--bg-grouped: #f2f2f7; --bg-grouped-cell: #fff;
--tint: #0088ff; --green: #34c759; --red: #ff383c; --orange: #ff8d28;
/* Marketing palette */
--mk-text: #1d1d1f; --mk-muted: #86868b; --mk-surface: #f5f5f7;
--mk-link: #0066cc; --mk-cta: #0071e3; --mk-cta-hover: #0077ed;
--mk-dark-text: #f5f5f7; --mk-dark-muted: #a1a1a6; --mk-dark-link: #2997ff;
--radius-pill: 980px;
--ease-apple: cubic-bezier(0.28, 0.11, 0.32, 1);
}
.dark, [data-theme="dark"] {
--label: #fff; --label-2: rgba(235,235,245,.60); --label-3: rgba(235,235,245,.30);
--separator: rgba(84,84,88,.60);
--bg: #000; --bg-2: #1c1c1e; --bg-3: #2c2c2e;
--bg-grouped: #000; --bg-grouped-cell: #1c1c1e;
--tint: #0091ff; --green: #30d158; --red: #ff4245; --orange: #ff9230;
}
body { font-family: var(--font-stack); -webkit-font-smoothing: antialiased; }
/* If Inter actually renders (non-Apple device / client work): */
body { font-feature-settings: "cv05", "cv11"; }
```
## Type scale
App UI (HIG, px = pt at 1x): Large Title 34/41 · Title1 28/34 · Title2 22/28 · Title3 20/25 · Headline 17/22 semibold · Body 17/22 · Callout 16/21 · Subheadline 15/20 · Footnote 13/18 · Caption 12/16.
Marketing headlines:
```css
h1.hero { font-size: clamp(48px, 7vw, 96px); font-weight: 700; letter-spacing: -.022em; line-height: 1.05; }
h2.section { font-size: clamp(32px, 5vw, 56px); font-weight: 600; letter-spacing: -.015em; line-height: 1.08; }
p.subhead { font-size: 21px; line-height: 1.4; color: var(--mk-muted); letter-spacing: .011em; }
```
## Liquid Glass recipe (CSS approximation)
Floating bar / island — the signature current-Apple element:
```css
.glass {
background: rgba(255,255,255,.55); /* dark mode: rgba(30,30,32,.55) */
backdrop-filter: blur(24px) saturate(180%);
-webkit-backdrop-filter: blur(24px) saturate(180%);
border-radius: 28px; /* capsule for bars: 999px */
box-shadow:
0 8px 32px rgba(0,0,0,.08), /* soft lift */
inset 0 1px 0 rgba(255,255,255,.55), /* specular top edge */
inset 0 0 0 .5px rgba(255,255,255,.25); /* glass rim */
}
.glass--clear { background: rgba(255,255,255,.18); } /* over media; add a 35%-black
dimming layer if content is bright */
```
Floating iOS-style tab bar:
```css
.tabbar {
position: fixed; left: 50%; bottom: max(16px, env(safe-area-inset-bottom));
transform: translateX(-50%);
display: flex; gap: 8px; padding: 8px 12px; border-radius: 999px;
/* + .glass properties */
}
.tabbar a { width: 56px; height: 44px; display: grid; place-items: center;
border-radius: 999px; color: var(--label-2); }
.tabbar a[aria-current] { color: var(--tint); } /* icons monochrome; active = tint */
```
Scroll edge effect (content fading under a floating top bar):
```css
.scroll-edge {
position: fixed; inset: 0 0 auto 0; height: 96px; pointer-events: none;
backdrop-filter: blur(8px);
mask-image: linear-gradient(to bottom, black 30%, transparent 100%);
-webkit-mask-image: linear-gradient(to bottom, black 30%, transparent 100%);
}
```
Key behavior: content scrolls edge-to-edge *beneath* bars (no `padding-top` shoving content down; use safe-area padding inside the scroller instead).
## Buttons
```css
.btn-filled { /* prominent: ONE per view */
background: var(--tint); color: #fff; font-size: 17px; font-weight: 600;
padding: 13px 24px; border-radius: 999px; min-height: 44px;
transition: opacity .2s var(--ease-apple), transform .2s var(--ease-apple);
}
.btn-filled:active { opacity: .8; transform: scale(.97); } /* press = dim, never ripple */
.btn-gray { background: var(--bg-2); color: var(--tint); /* same metrics */ }
.btn-plain { background: none; color: var(--tint); }
.btn-destructive { color: var(--red); }
```
Marketing CTA: same pill, `--mk-cta` background, 12px/24px padding, hover lightens to `--mk-cta-hover` — no lift, no shadow.
## Grouped list (Settings style)
```css
.group { background: var(--bg-grouped-cell); border-radius: 10px; margin: 0 16px; overflow: hidden; }
.row { display: flex; align-items: center; gap: 12px; min-height: 44px; padding: 11px 16px; font-size: 17px; }
.row + .row { border-top: .5px solid var(--separator); margin-left: 16px; padding-left: 0; }
.row .icon { width: 29px; height: 29px; border-radius: 7px; display: grid; place-items: center; color: #fff; }
.row .value { margin-left: auto; color: var(--label-2); }
.row .chevron { color: var(--label-3); }
.row:active { background: rgba(0,0,0,.05); }
```
Page background: `var(--bg-grouped)`. Toggle: 51×31px pill, `--green` on-state, white knob with `0 3px 8px rgba(0,0,0,.15)` shadow.
## Motion
Ease/duration defaults: `--ease-apple`, 0.3–0.4s; springs for interactive elements (Framer Motion: `type:"spring", stiffness:340, damping:30`).
GSAP reveal (subtle rise, settles fast, no bounce):
```js
gsap.utils.toArray('[data-reveal]').forEach(el => {
gsap.from(el, { y: 28, opacity: 0, duration: .7, ease: 'power2.out',
scrollTrigger: { trigger: el, start: 'top 85%', once: true } });
});
```
Pinned scrub and canvas image-sequence patterns: pin the section, `scrub: 0.6`, map progress → transform or frame index (≤120 frames). Pair with Lenis on marketing pages. Direction rule: whatever slides in from an edge dismisses back to that edge.
Always gate:
```js
if (matchMedia('(prefers-reduced-motion: reduce)').matches) {
ScrollTrigger.getAll().forEach(t => t.kill());
document.querySelectorAll('[data-reveal]').forEach(el => el.removeAttribute('style'));
}
```
## React + Tailwind mapping
```js
// tailwind theme extension
extend: {
colors: {
label: 'var(--label)', label2: 'var(--label-2)',
bg: { DEFAULT: 'var(--bg)', 2: 'var(--bg-2)', grouped: 'var(--bg-grouped)', cell: 'var(--bg-grouped-cell)' },
tint: 'var(--tint)', sysgreen: 'var(--green)', sysred: 'var(--red)',
},
borderRadius: { cell: '10px', card: '22px', pill: '980px' },
transitionTimingFunction: { apple: 'cubic-bezier(0.28,0.11,0.32,1)' },
}
```
Conventions: `<Button variant="filled|gray|plain|destructive">`; `<GlassBar>` wrapper applying the glass recipe; icons via lucide-react at consistent strokeWidth (1.8–2), sized to the adjacent text. Section wrapper for marketing: `py-24 md:py-36 text-center` with `max-w-[980px] mx-auto px-6`.
## Sheet (web approximation)
Bottom sheet: full-width card, top radius 16–20px, grabber (36×5px pill, `--separator`), scrim `rgba(0,0,0,.4)`, slides up 0.35s `--ease-apple`, drag-to-dismiss mirrors downward. Cancel leading / Done trailing in its top bar.
## Self-check for code output
Bars float (fixed, inset, rounded, glass) with content scrolling beneath — not opaque strips. One tinted primary per view. Press states dim/scale. 44px targets. `env(safe-area-inset-*)` respected. Reduced motion handled. Dark mode via tokens, not per-element overrides.
references/figma-workflow.md
# Figma Workflow — Apple Design
Setting up Apple-style work in Figma, whether giving guidance or building via Figma MCP tools (if using MCP, load the figma-use skill first).
## Frames
- iOS app: **393×852** (iPhone 16/17 class) or 402×874 (17 Pro); design at @1x in points.
- iPadOS: 834×1210 (11″ Pro) or 1024×1366 (13″).
- macOS app: 1440×900 window, 10 corner radius.
- Marketing desktop: 1440×auto (verify at 1024); marketing mobile: 390×auto.
## Variables (one collection, Light + Dark modes)
**App (HIG) collection** — bind every fill/text to these, hardcode nothing:
| Variable | Light | Dark |
|---|---|---|
| label/primary | `000000` | `FFFFFF` |
| label/secondary | `3C3C43` 60% | `EBEBF5` 60% |
| label/tertiary | `3C3C43` 30% | `EBEBF5` 30% |
| separator | `3C3C43` 29% | `545458` 60% |
| bg/primary | `FFFFFF` | `000000` |
| bg/secondary | `F2F2F7` | `1C1C1E` |
| bg/tertiary | `FFFFFF` | `2C2C2E` |
| bg/grouped | `F2F2F7` | `000000` |
| bg/groupedCell | `FFFFFF` | `1C1C1E` |
| tint | `0088FF` | `0091FF` |
| green | `34C759` | `30D158` |
| red | `FF383C` | `FF4245` |
| orange | `FF8D28` | `FF9230` |
**Marketing collection**: `text/primary 1D1D1F`, `text/secondary 86868B`, `surface/default FFFFFF`, `surface/alt F5F5F7`, `surface/dark 000000`, `text/onDark F5F5F7`, `text/onDarkSecondary A1A1A6`, `accent/link 0066CC`, `accent/linkDark 2997FF`, `accent/cta 0071E3`.
## Text styles
Font: **SF Pro** (free from Apple for design use); fallback **Inter**.
App set (name / size / line height / weight — create both regular and emphasized where noted):
LargeTitle 34/41 Regular (emph Bold) · Title1 28/34 · Title2 22/28 · Title3 20/25 (emph Semibold) · Headline 17/22 Semibold · Body 17/22 · Callout 16/21 · Subheadline 15/20 · Footnote 13/18 · Caption1 12/16 · Caption2 11/13. macOS set is denser: Body 13/16, Title1 22/26, LargeTitle 26/32.
Marketing set: `Hero/80 Bold, -2.2%` · `H2/56 Semibold, -1.5%` · `H3/32 Semibold, -1%` · `Eyebrow/24 Semibold` · `Body/21 Regular, +1%, LH 140%` · `Body-S/17` · `Footnote/12`.
## Liquid Glass in Figma
Recipe for a floating bar/island:
1. Frame with corner radius 999 (capsule) or 28 (island); fill `FFFFFF` 55% (dark: `1E1E20` 55%).
2. **Background blur 24** (effect — background blur, not layer blur).
3. Inner shadow: Y 1, blur 0, `FFFFFF` 55% (specular top edge).
4. Inside stroke 0.5, `FFFFFF` 25% (rim).
5. Drop shadow: Y 8, blur 32, `000000` 8%.
Place bars **over** content in the layer stack; let a screenshot/artwork layer run beneath to prove the float. Add a "scroll edge" rectangle above content at bar edges: fill = bg color, gradient fade to 0%, plus background blur 8 if the plugin/version allows blur masking.
## Auto layout values
- 4/8 grid: spacing tokens 4, 8, 12, 16, 20, 24, 32. Screen margins 16 (iPhone) / 20 (iPad).
- iOS grouped list: container radius 10, rows min-height 44 with 16 horizontal padding, 0.5 separator inset 16; leading icon 29×29 radius 7.
- Buttons: prominent capsule = padding 13/24, radius 999, min height 44; form primary = height 50, radius 14; iOS switch 51×31.
- Floating tab bar: capsule, padding 8/12, item 56×44, gap 8, pinned 16 from bottom + home-indicator space.
- Marketing section: vertical auto layout, 120 gap between sections; inside: 24 gap eyebrow→headline→subhead, 40 copy→visual, 120/64 top-bottom padding desktop/mobile; bento gap 20, card radius 22.
## Component build order (Apple-style library)
Variables → text styles → Button (Filled/Gray/Plain/Destructive × sizes, with pressed variants) → Floating tab bar (icon items w/ active boolean) → Toolbar/nav bar (large + inline title variants) → List row (icon/value/chevron/toggle props) → Toggle → Segmented control → Search field → Sheet template (grabber + Cancel/Done bar) → Alert → Empty state → Marketing: nav, section template, link-arrow, bento card.
Use variants + component properties (booleans for icon/chevron, instance-swap for symbols, text props for labels). Icons: SF Symbols plugin or Lucide at uniform stroke; match icon optical size to adjacent text size.
## Review checklist in Figma
Every fill bound to a variable (test by switching mode) · bars float with glass recipe · one tint-filled action per screen · 44pt targets · type only from styles · dark mode actually checked, not assumed.
references/hig-components.md
# HIG Components — Bars, Buttons, Lists, Presentation, Controls
Synthesized from Apple's Human Interface Guidelines (mid-2026). The details below are what make a screen read as genuinely Apple.
## Tab bars (navigation between top-level sections)
- Navigation **only** — actions never live here; that's the toolbar's job.
- iOS: floats at the bottom as a capsule island on Liquid Glass; can **minimize on scroll-down** and restore on scroll-up/tap; may carry a distinct search item at the trailing end; can host an accessory (mini-player) that moves inline when minimized.
- iPadOS/macOS: tab bar sits near the top; can be convertible to a sidebar (`sidebarAdaptable`) — prefer tab bar first, sidebar for many/rarely-used sections. ≤5 default items.
- Filled SF Symbols + one-word labels. Never hide or disable a tab — show an empty state inside instead. Badges (red oval) only for genuinely critical info.
## Toolbars / navigation bars (actions on the current view)
- Three zones: **leading** (Back/Close, sidebar toggle, title), **center** (common actions; customizable on iPad/Mac; collapses to overflow first), **trailing** (critical persistent items: primary action, search, More).
- iOS **large title** transitions to inline title on scroll and back at top.
- Standard Back/Close symbols only — no "Back" text labels. Titles ≤15 characters; omit when redundant.
- Symbols preferred over text except unsymbolizable actions ("Edit"). No borders on bar buttons — the bar is the container. One `.prominent` (tint-background) action max, trailing side.
- ≤3 visual groups; separate navigation from destructive/commit actions; put fixed space between adjacent text buttons.
- macOS: every toolbar item must also exist as a menu-bar command.
## Sidebars
- Leading edge, top-level navigation with ≤2 levels of hierarchy (deeper → split view with a content column).
- Content scrolls beneath the floating sidebar; use a background extension effect under it.
- User-customizable contents; hideable but never hidden by default; SF Symbols, accent-colored selection (don't fix icon colors unless color means something).
## Buttons
Anatomy = **style** (prominence/shape) + **content** (symbol, label, both) + **role** (normal / primary / cancel / destructive).
- Hit region ≥ 44×44pt (60pt visionOS). Always design a pressed state (dim to ~80% opacity or slight scale — never ripples).
- **Prominent style** (tint-filled background, white label) for the single most likely action; 1–2 per view max. Distinguish importance by *style*, never by making one button bigger.
- Secondary styles: gray fill (`systemGray5`-family bg + tint label) and plain (tint text, no container).
- Roles: primary responds to Return and gets the accent; destructive renders red; never make a destructive action the default/primary; always pair destructive with Cancel.
- Labels start with a verb ("Add to Cart"), 1–2 words, title case. In-button spinner + label swap ("Checkout" → "Checking out…") for non-instant actions.
- Shapes: capsule for standalone/prominent CTAs, rounded-rect (~12–14pt radius, 50pt tall) for full-width primaries in forms, circle for icon-only.
## Lists & tables
- Lists for text; collections/grids for image-heavy or varied-size content.
- iOS grouped style: inset rounded groups (10pt radius) on the grouped background set; rows 44–52pt; separators inset to text alignment.
- Selection feedback: **navigation rows** highlight persistently to show the path; **option rows** flash then show a checkmark.
- Row anatomy: optional leading icon (29×29pt rounded-square, white glyph on flat color — Settings style), 17pt label, trailing secondary value, chevron `›` in tertiary gray. Info button (ⓘ) reveals detail *without* navigating; chevron navigates — don't confuse them.
- macOS: sortable, resizable columns; alternating row backgrounds for wide tables; outline views (disclosure triangles) for hierarchy.
## Sheets, alerts & modality
**Modality doctrine**: one modal at a time; simple scoped tasks only; obvious dismiss (top toolbar button or swipe-down on iOS; button in view on macOS); confirm before dismissing unsaved work; complex flows get full-screen or a window, not nested sheets.
**Sheets**: resizable with detents — `medium` (~half, for progressive disclosure like Share) and `large`; include the grabber (36×5pt pill) when resizable; compose-type tasks are full-height only. Buttons: Cancel/Close leading, Done (or a more specific verb) trailing; multi-step flows swap Cancel for Back after step 1. macOS sheets are rounded cards over a dimmed parent window. Nonmodal sheets (iOS) exist for panels that live alongside the parent (formatting palettes).
**Alerts**: critical + actionable only; never at launch, never purely informational, never for routine undoable deletes. Title = what happened and why, ≤2 lines, no "Error". Buttons: 1–3, verb titles ("Delete", "View All"); "OK" only for pure information; Cancel always cancels, sits leading/bottom, never the default; destructive style + Cancel always together.
**Action sheets / confirmation dialogs**: the follow-up to an intentional but risky tap ("Delete draft?") — not alerts.
**Popovers** (iPad/Mac): transient, anchored to their control, for lightweight tools/options; on iPhone they become sheets.
## Small controls
- **Toggles**: switch style only inside list rows (context = label); default green `#34c759` (accent acceptable); elsewhere use a toggle *button* with a filled active state. macOS: checkboxes for multi-select and hierarchies, radio buttons for 2–5 exclusive choices, switches for emphasized settings.
- **Segmented controls**: 2–5 segments (≤5 on iPhone), equal widths, nouns, text or icons but not mixed; for switching closely related subviews — separate app sections get a tab bar instead.
- **Text fields**: placeholder = purpose or format example, plus a persistent label for important fields; clear button trailing (iOS); secure entry for credentials; width hints at expected length; validate email-type fields on blur; number formatters, never regex-hardcoded formats.
- **Search fields**: icon + placeholder + clear; search-on-keystroke; suggestions early; scope control to filter; tokens for structured filters. iOS placement options: trailing search tab in the tab bar, bottom toolbar (search-first apps like Mail/Notes), or top trailing button expanding to a field; iPad/Mac: toolbar trailing (global) or top of sidebar (filtering nav).
- **Context menus**: touch-and-hold / right-click; only frequent, relevant items; ≤1 submenu level; every item must also exist somewhere visible; apply consistently across the whole app.
- **Progress**: determinate bar when duration is known, indeterminate spinner otherwise; prefer in-place skeletons/placeholder content over blocking spinners.
## Scroll behavior
- Elastic system scrolling only; make scrollability apparent by letting content peek at edges.
- Never nest same-orientation scroll views; orthogonal nesting is fine.
- Page-by-page: show a page control, hide the same-axis scroll indicator.
references/hig-foundations.md
# HIG Foundations — Color, Type, Layout, Materials, Icons, Motion, Accessibility
Synthesized from Apple's Human Interface Guidelines (mid-2026). Values are exact — use them, don't approximate.
## Materials & Liquid Glass
Two material families:
**Liquid Glass** — the functional layer (tab bars, toolbars, sidebars, floating buttons). Two variants:
- `regular` — blurs and adjusts luminosity of what's behind; the default for anything with significant text (sidebars, alerts, popovers, most bars).
- `clear` — highly translucent, shows background media through; only over visually rich content (photos, video). If the underlying content is bright, add a dark dimming layer at **35% opacity** behind clear glass.
Rules: glass takes color from behind it; small elements (tab bars, toolbars) flip light/dark based on underlying content with monochrome symbols; larger elements (sidebars) render more opaque for legibility. Never use glass in the content layer — exception: transient controls (a slider knob mid-drag) may briefly adopt it. If app content is colorful, keep bars monochrome.
**Standard materials** — content-layer separation, four thicknesses: `ultraThin`, `thin`, `regular` (default), `thick`. Thicker = better text contrast; thinner = more background context. Put *vibrant* system colors on top of materials so text adapts automatically.
**Scroll edge effect** — the transition where content meets a floating bar: `automatic` (default; progressive blur + fade), `soft`, or `hard` (opaque boundary — only when tested). Use only adjacent to floating elements, one per scroll view.
## Color
**Semantic first.** Colors are named by purpose, not appearance, and adapt to light/dark/increased-contrast automatically. Never hard-code where a token exists; never repurpose (no `separator` as text).
iOS/iPadOS backgrounds — two sets, each with 3 levels (primary = whole view, secondary = grouping, tertiary = grouping within grouping):
- **System set**: `#ffffff` / `#f2f2f7` / `#ffffff` (light); `#000000` / `#1c1c1e` / `#2c2c2e` (dark)
- **Grouped set** (Settings-style lists): inverse pairing — `#f2f2f7` page with `#ffffff` cells (light); `#000000` page with `#1c1c1e` cells (dark)
- Dark mode has **base** and **elevated** background variants (sheets/popovers brighten one step to convey depth).
Foreground: `label` #000/#fff; `secondaryLabel` rgba(60,60,67,.60) / rgba(235,235,245,.60); `tertiaryLabel` at .30 opacity; `quaternaryLabel` at .18/.16; `placeholderText` = tertiary; `separator` rgba(60,60,67,.29) / rgba(84,84,88,.60).
System tints (light / dark, current values):
| Color | Light | Dark |
|---|---|---|
| Blue (default tint) | `#0088ff` | `#0091ff` |
| Red | `#ff383c` | `#ff4245` |
| Green | `#34c759` | `#30d158` |
| Orange | `#ff8d28` | `#ff9230` |
| Yellow | `#ffcc00` | `#ffd600` |
| Mint | `#00c8b3` | `#00dac3` |
| Teal | `#00c3d0` | `#00d2e0` |
| Cyan | `#00c0e8` | `#3cd3fe` |
| Indigo | `#6155f5` | `#6d7cff` |
| Purple | `#cb30e0` | `#db34f2` |
| Pink | `#ff2d55` | `#ff375f` |
| Brown | `#ac7f5e` | `#b78a66` |
Grays: `systemGray` #8e8e93 (both modes), then gray2–gray6 light: #aeaeb2, #c7c7cc, #d1d1d6, #e5e5ea, #f2f2f7; dark: #636366, #48484a, #3a3a3c, #2c2c2e, #1c1c1e.
Never rely on color alone to convey state — pair with shape, icon, or label. Use Display P3 for rich imagery with sRGB fallbacks.
## Typography
System font SF Pro (serif: New York). Prefer Regular/Medium/Semibold/Bold; avoid Ultralight–Light, especially small.
**iOS/iPadOS text styles at the default (Large) Dynamic Type size** — size/leading in pt, with emphasized weight:
| Style | Weight | Size/Leading | Emphasized |
|---|---|---|---|
| Large Title | Regular | 34/41 | Bold |
| Title 1 | Regular | 28/34 | Bold |
| Title 2 | Regular | 22/28 | Bold |
| Title 3 | Regular | 20/25 | Semibold |
| Headline | Semibold | 17/22 | — |
| Body | Regular | 17/22 | Semibold |
| Callout | Regular | 16/21 | Semibold |
| Subheadline | Regular | 15/20 | Semibold |
| Footnote | Regular | 13/18 | Semibold |
| Caption 1 | Regular | 12/16 | Semibold |
| Caption 2 | Regular | 11/13 | Semibold |
**macOS text styles**: Large Title 26/32, Title 1 22/26, Title 2 17/22, Title 3 15/20, Headline 13/16 Bold, Body 13/16, Callout 12/15, Subheadline 11/14, Footnote 10/13, Caption 10/13. macOS has no Dynamic Type.
Minimums: iOS 11pt, macOS 10pt, tvOS 23pt (default 29), watchOS 12pt (default 16), visionOS 12pt (default 17). Support text enlargement to 200%; when text grows, keep hierarchy relative and let labels wrap rather than truncate; if you must truncate list items, prefer a centered ellipsis so start and end survive.
## Layout
- Screen margins: 16pt (iPhone), 20pt (large phones/iPad); spacing on a 4/8 grid (4, 8, 12, 16, 20, 24, 32).
- **Safe areas are law** — content respects Dynamic Island, home indicator, and floating bars; backgrounds and artwork extend edge-to-edge *behind* them. When content doesn't span the window (sidebar layouts), use a background extension effect so the sidebar floats over continued artwork.
- Reading order: top→bottom, leading→trailing (mirrors in RTL). Most important content top-leading.
- Group with space first; then background shapes, materials, or separators — in that order of preference.
- Avoid full-width edge-to-edge buttons on iOS; inset to margins and align to safe areas.
- Progressive disclosure: partially visible items at an edge invite scrolling; disclosure controls for depth.
- Current reference frames: iPhone 17 Pro 402×874pt, 17 Pro Max 440×956pt, iPhone 16 393×852pt (all @3x); iPad Pro 11″ 834×1210pt; design app UI at these, not 375×667.
- macOS: nothing critical at the window bottom (often offscreen); tvOS safe zone 60pt top/bottom, 80pt sides.
## SF Symbols & icons
- Use SF Symbols for all interface glyphs — 9 weights matching SF text weights, 3 scales (small/medium/large relative to cap height), so a symbol next to a Semibold 17pt label is Semibold and aligns automatically.
- Rendering modes: Monochrome (default), Hierarchical (one color, layered opacity = depth), Palette (color per layer), Multicolor (intrinsic colors). Gradient rendering exists for large sizes.
- Variant convention: **outline in toolbars and lists; fill in iOS tab bars and selections**. System pickers often choose automatically. Enclosed variants help tiny sizes; slash = unavailable.
- Symbol animations (bounce = action occurred, pulse = ongoing, replace = state change, wiggle = attention, draw-on = progress) — one meaning per animation, applied sparingly.
- In web/Figma work where SF Symbols aren't licensed: Lucide is the closest stroke match; keep one family and one stroke weight throughout, never mix.
- **App icons**: 1024×1024 layered (background + foreground layers), built for the system's Liquid Glass treatment (specular highlights, refraction) via Icon Composer. Six appearances: default, dark, clear light/dark, tinted light/dark. One concept, filled overlapping shapes, no photos, no text, no UI replicas; system applies the mask — never pre-round corners.
## Motion
- Purposeful only; never the sole carrier of information. System components animate themselves — don't re-animate standard interactions.
- Feedback motion mirrors the gesture: a sheet that slides up dismisses by sliding down. Keep it brief and cancellable.
- Springs over duration curves for interactive elements; scroll-linked (scrub) motion for content reveals.
- Reduce Motion on: replace zooms/z-depth/blur animations with fades, tighten springs, keep gesture-tracking motion.
## Accessibility numbers
Control sizes (default / minimum): iOS & watchOS 44×44 / 28×28pt; macOS 28×28 / 20×20pt; tvOS 66×66 / 56×56pt; visionOS 60×60 / 28×28pt. Pad ~12pt around bezeled controls, ~24pt around bare glyphs.
Contrast: 4.5:1 for text ≤17pt; 3:1 for ≥18pt or bold; meet it in light *and* dark, or at least when Increase Contrast is on. Every gesture needs an on-screen alternative; every element needs a VoiceOver label; no auto-dismissing timed UI.
references/hig-patterns.md
# HIG Patterns — Flows, States, and UX Writing
Synthesized from Apple's Human Interface Guidelines (mid-2026). These are the invisible details that make a flow feel Apple-designed.
## Launching & first run
- Launch fast; restore previous state (scroll position, last location) on every relaunch — never make people retrace steps.
- Launch screen (iOS/iPadOS/tvOS) mimics the app's first screen so startup *feels* instant — it is not a branding moment: no text, no logo, static only.
- Splash screens, if unavoidable: first step of onboarding, glance-length, never blocking on downloads.
## Onboarding
- Best onboarding is none. If needed: teach by doing, not by reading; prefer contextual tips at the moment of relevance over an upfront tour; always skippable, never repeated, findable later in help/settings.
- Sensible defaults over setup questionnaires; never ask what the system can detect (dark mode, device, controller).
- Permission prompts: at the moment the feature needs them, with a clear reason — inside onboarding only if the app can't function without them.
- Don't prompt for ratings or purchases before genuine engagement.
## Loading & progress
- Show something immediately — placeholder/skeleton content that gets replaced beats any spinner; a blank screen reads as broken.
- Keep the rest of the app interactive while loading in the background.
- Determinate progress when duration is known; something interesting (tips, previews) for unavoidably long loads.
## Feedback & errors
- Integrate status into the interface near the thing it describes (unread count in the toolbar), not in interruptions.
- Confirm success only when it genuinely matters (a payment, not a save).
- Warn before *unexpected, irreversible* loss only — intentional deletion doesn't need a speed bump; accidental-prone, non-undoable actions do.
- When a command fails, say what went wrong and how to fix it, next to where it went wrong.
## Empty states
Centered symbol (48–64pt, tertiary color) → short Title 3 heading → one Footnote/Subheadline line → one action button. Generous space. Empty states are temporary — never park crucial information there.
## Settings
- The best setting is one nobody needs to change: pick great defaults, detect what you can, keep the count small.
- Placement: task-specific options inline in the affected view; general rarely-changed options in an in-app settings area; system-level things link out to the Settings app.
- Never duplicate systemwide settings (appearance, accessibility) inside the app.
- Describe what a toggle does when **on**; people infer off. Label first, description only if the label can't carry it.
## Search
- Search as you type; suggestions before typing (recents, popular); most relevant results first, categorized when useful; scope bar to filter.
- Choose the entry point deliberately (see components file for iOS/iPad/macOS placements) — search-first apps put it in the bottom toolbar or a dedicated tab.
## UX writing (Apple voice)
- Every word earns its place; read it aloud; plain language, no jargon, no gendered terms.
- **Buttons/links**: active verbs — "Send", not "Let's do it!"; links say what they open ("Learn more about billing"), never "Click here". "Tap" on touch devices, "click" on Mac.
- **Capitalization**: pick per element type and never mix — Title Case for buttons, nav titles, and menu items; Sentence case for body, descriptions, and settings labels.
- **Flows**: "Get Started" opens, "Continue" *or* "Next" (pick one) advances, "Done" closes.
- **Pronouns**: "Favorites" over "Your Favorites"; never "we" in errors ("Unable to load content", not "We're having trouble"); if using my/your, don't switch perspective.
- **Errors**: specific and positive — "Choose a password with at least 8 characters" beats "Password too short"; no "Oops!"/"Uh-oh"; place the message at the field, not in an alert.
- **Alerts**: titles state what happened and why; fragments get Title Case without punctuation, sentences get sentence case with a period; don't explain the buttons in the body.
## Dark Mode behavior
- Never offer an in-app light/dark override of the system setting; support both, test with Increase Contrast and Reduce Transparency.
- Dark palettes dim backgrounds and *brighten* foregrounds — not an inversion. Elevated surfaces (sheets, popovers) step one background level brighter.
- Slightly darken white-heavy imagery for dark contexts; permanently-dark UI is only for immersive media apps.
## Platform feel deltas
- **iOS**: one-hand reach — key controls middle/bottom; swipe-back everywhere; list-row swipe actions; quick sessions, instant resume.
- **iPadOS**: design full-size first, degrade gracefully to any window size; convertible tab bar/sidebar; pointer + keyboard supported.
- **macOS**: denser (13pt body, 28pt controls); every command in the menu bar; keyboard shortcuts for everything; resizable, customizable, multi-window; hover states matter; Command-Comma opens Settings (toolbar-pane window, remembers last pane).
- **watchOS**: edge-to-edge content (bezel is the padding), vertical-first scrolling via Digital Crown, capsule buttons, full-width primaries, ≤2 text buttons side by side, no spinners — notify when done.
- **visionOS**: center the important content, 60pt center-to-center between controls, glass windows (don't fill them opaque), toolbar as bottom ornament, no head-anchored content.
references/marketing-pages.md
# Apple.com-Style Marketing Pages
How Apple product pages are actually constructed. Use these patterns for landing pages, product launches, and feature pages.
## Page anatomy
A typical Apple product page is a vertical stack of full-bleed sections, alternating light (`#fff` / `#f5f5f7`) and dark (`#000`). Each section = one feature, one hero visual, minimal copy. Order:
1. **Global nav** — 44–48px tall, frosted glass, ~12px links, centered, max-width ~1024px
2. **Hero** — product name huge, one-line tagline, two links, giant product image
3. **Feature sections** × N — alternating backgrounds
4. **Comparison / specs strip** (optional)
5. **Footer** — dense small links on `#f5f5f7`, 12px text, `#424245` borders
## The section formula
Every Apple feature section follows this exact copy structure. Use it verbatim as a template:
```
[Eyebrow] — 21–28px, semibold, often gray or gradient, names the feature area
[Headline] — 48–80px, weight 600–700, the single big claim. Short. Punchy.
[Subhead/body] — 19–21px, #86868b on light / #a1a1a6 on dark, 2–3 lines max
[Links] — "Learn more >" (#0066cc) and/or pill CTA "Buy"
[Hero visual] — enormous, centered, often bleeding off-section
```
Copywriting voice: short declarative fragments. "Lightning fast. Lightyears ahead." Sentence fragments are fine. Superlatives are earned by a spec, not stacked. Never bullet-point feature lists in hero sections — one claim at a time.
## Signature visual moves (pick 1–2 per page, not all)
- **Gradient headline text** — a key word or whole headline filled with a vivid gradient (`background-clip: text`) on a black section. Apple's classic "supercharged" move.
- **Scroll-scrubbed product sequence** — a pinned section where scrolling scrubs through an image sequence or transforms the product (rotate, explode, zoom). Implementation in `code-implementation.md`.
- **Sticky headline, scrolling visuals** — headline pins while feature cards/images scroll past.
- **Bento grid** — a specs/feature summary as a grid of rounded cards (18–28px radius) with mixed spans, each card one stat or claim. Dark cards on black, or white cards on `#f5f5f7`.
- **Device frame showcase** — UI screenshots always live inside an accurate device frame, never floating raw.
- **Horizontal card rail** — edge-bleeding horizontally scrollable cards with snap points (how Apple shows camera features, colors).
## Layout numbers
- Content max-width: 980–1024px for text blocks; visuals may bleed to viewport edge
- Section vertical padding: 100–150px desktop, 60–80px mobile
- Headline max-width: ~800px, centered
- Body/subhead max-width: ~600px, centered
- Grid gutters: 20–24px; bento gap: 16–20px
- Everything centered by default; left-alignment only inside cards or split layouts
## Dark sections
- Background pure `#000`, text `#f5f5f7` (never `#fff` — it vibrates)
- Secondary text `#a1a1a6`
- Links shift to lighter blue `#2997ff`
- Cards on dark: `#1d1d1f` background, optional `1px solid rgba(255,255,255,0.08)` hairline
- Dark sections are where gradient text and dramatic product photography live
## Nav bar spec
- Height 44–48px, `position: sticky/fixed`
- Background: `rgba(251,251,253,0.8)` light / `rgba(22,22,23,0.8)` dark, `backdrop-filter: saturate(180%) blur(20px)`
- Links: 12px, `#1d1d1f` at ~80% opacity, 400 weight, ~24–32px apart
- Hairline bottom border only after scroll begins
- Current-era alternative (matches Liquid Glass system aesthetic): a floating pill/island nav — rounded-999px glass capsule inset from the top edge rather than a full-width strip. Use the `.glass` recipe from `code-implementation.md`. Pick one style per page; full-width is classic apple.com, floating pill is the newer product-page look.
## What breaks the illusion (avoid)
- Drop shadows on buttons or nav
- More than one accent color
- Icon grids with tiny icons + paragraph blurbs (that's SaaS-template, not Apple)
- Headlines under 40px on desktop
- Busy hero with badge + headline + subhead + 2 buttons + trust logos + screenshot all at once
- `ease-in-out` default easing or bouncy springs on scroll reveals
SKILL.md
---
name: apple-design
description: Apply Apple's current design language (Human Interface Guidelines + Liquid Glass, mid-2026) to any UI work — app interfaces in the iOS/iPadOS/macOS style, and marketing/landing pages in the Apple.com style (huge headlines, alternating light/dark sections, scroll-driven product reveals). Use this skill whenever the user asks for "Apple style", "Apple-like", "HIG", "iOS style", "macOS style", "Liquid Glass", "iOS 26 style", "Cupertino", a "clean premium minimal" landing page, or a product page that feels like an iPhone/Mac launch page — even if they don't say "Apple" explicitly but describe frosted glass, floating tab bars, pill buttons, giant centered headlines, or scroll-scrubbed product animations. Also use when reviewing/critiquing a design for Apple-platform fit. Works for HTML/CSS/JS prototypes, React + Tailwind, and Figma design guidance.
---
# Apple Design (HIG + Liquid Glass edition)
This skill makes output actually *feel* Apple — not "generic minimal with more whitespace". The difference lives in specific numbers (type scales, radii, hit targets, easing) and in a philosophy of restraint. Specs here are synthesized from Apple's Human Interface Guidelines as of mid-2026, which means the current **Liquid Glass** design language, not the pre-2025 flat look.
## The one thing to know first: Liquid Glass
Since 2025, Apple platforms separate every screen into two layers:
1. **Content layer** — the app's actual content. Extends edge-to-edge, scrolls under everything, uses opaque backgrounds and standard materials.
2. **Functional layer (Liquid Glass)** — controls and navigation (tab bars, toolbars, sidebars, buttons) that *float above* content on a dynamic glass material. It has no color of its own; it refracts what's beneath, adapts light/dark from the underlying content, and keeps symbols monochrome by default.
Practical rules: bars are floating rounded/capsule islands, not full-width strips glued to edges. Content visibly scrolls beneath them. A *scroll edge effect* (progressive blur/fade) separates floating controls from content — never a hard hairline by default. Color on glass is reserved: tint the **background** of at most one prominent action (e.g. Done); everything else stays monochrome. Don't build content-layer cards out of glass — glass is for interactive chrome only.
## Route to the right reference
| Deliverable | Read |
|---|---|
| App UI — any screen, component, or flow | `references/hig-foundations.md` + `references/hig-components.md` |
| UX flows, copy, empty/error/loading states, onboarding, settings, search | `references/hig-patterns.md` |
| Marketing/landing/product page | `references/marketing-pages.md` |
| HTML/CSS/JS or React+Tailwind build (tokens, glass recipes, motion code) | `references/code-implementation.md` (in addition to the above) |
| Figma work (frames, variables, text styles, effects) | `references/figma-workflow.md` (in addition to the above) |
Mixed requests (landing page showing app screenshots): marketing rules govern the page; HIG rules govern anything depicted as an app.
## Core philosophy (applies to everything)
Apple's stated principles — purpose, agency, responsibility, familiarity, flexibility, simplicity, craft, delight — cash out in practice as:
- **One idea per screen/section.** Each view makes one point with one hero element. If it feels busy, cut elements; don't shrink them.
- **Content first, chrome recedes.** Controls float above and stay minimal; content owns the screen edge-to-edge.
- **Typography carries hierarchy** — dramatic size/weight jumps, not boxes and borders. Body 17pt (iOS) / 13pt (macOS); headlines are several steps up, never one.
- **Near-monochrome chrome.** Tint marks *interactivity* — anything tinted looks tappable, so never tint static decoration. One or two tinted elements per view, maximum.
- **Depth through material, not shadow stacks.** Glass, background-level steps (system → secondary → tertiary), and hairlines at 8–30% opacity. Shadows only for genuinely floating things, soft and low-opacity.
- **Motion is physics, tied to input.** Springs and scroll-linked transforms that settle fast; direction of dismissal mirrors direction of arrival; always honor Reduce Motion.
- **Forgiveness.** Easy undo, obvious dismiss, confirmation only for non-undoable destruction.
## Font strategy (read before choosing fonts)
Apple's SF Pro / SF Compact / New York fonts are licensed for Apple-platform design and development only:
- **Prototypes viewed on Apple devices**: use the system stack — `-apple-system, BlinkMacSystemFont, "SF Pro Display", "SF Pro Text", "Helvetica Neue", Arial, sans-serif` — which renders true SF on Mac/iPhone.
- **Client production work / non-Apple distribution**: recommend **Inter** (with `font-feature-settings: "cv05", "cv11"` for SF-like letterforms) and tell the client why. Never embed SF font files in deliverables.
- **In Figma**: SF Pro is fine (free for design), Inter as fallback.
- SF is a variable font with dynamic optical sizing; mimic it by tightening tracking as size grows: ~`-0.003em` at 17px → `-0.015em` at 48px → `-0.022em` at 80px+.
## Quality bar — self-check before delivering
1. Could one more element be removed? (Usually yes — do it.)
2. Do bars/controls float over content with a scroll edge effect, or are they opaque strips? (Strips = pre-2025.)
3. Is anything tinted that isn't interactive? Is more than one control's *background* tinted?
4. Are hit targets ≥ 44×44pt (28×28 macOS) with breathing room?
5. Do buttons read as Apple capsules/rounded-rects — not 1px-outlined rectangles (Material) and no ripple effects (Android)?
6. Dark surfaces: `#000` base with elevated `#1c1c1e`-family steps, text `#f5f5f7`-family — never pure white text?
7. Does every gesture have an on-screen alternative, and every destructive action a Cancel?
8. Would a casual observer accept a screenshot of this as an Apple app / apple.com?
If the user's brand conflicts with strict Apple rules (e.g., a gold hotel accent), keep the structure and restraint and swap only the tint color — and say you're doing this.