saglitzdesign-mcp 0.3.1

package/knowledge/design-languages/apple-hig-liquid-glass.md

@@ -0,0 +1,94 @@
+---
+id: apple-hig-liquid-glass
+title: "Apple HIG & Liquid Glass (iOS 26)"
+category: design-language
+platform: mobile
+tags: [ios, apple, hig, liquid-glass, swiftui, materials, accessibility]
+sources: ["https://developer.apple.com/documentation/technologyoverviews/liquid-glass", "https://developer.apple.com/documentation/swiftui/view/glasseffect(_:in:)", "https://www.apple.com/newsroom/2025/06/apple-introduces-a-delightful-and-elegant-new-software-design/", "https://www.createwithswift.com/liquid-glass-redefining-design-through-hierarchy-harmony-and-consistency/", "https://www.conor.fyi/writing/liquid-glass-reference", "https://www.learnui.design/blog/ios-design-guidelines-templates.html", "https://blakecrosley.com/blog/liquid-glass-swiftui-patterns", "https://www.createwithswift.com/exploring-a-new-visual-language-liquid-glass/"]
+updated: 2026-07-08
+---
+
+# Apple Human Interface Guidelines & Liquid Glass (iOS 26)
+
+Introduced at WWDC 2025, **Liquid Glass** is Apple's biggest visual redesign since iOS 7 — a dynamic translucent material that reflects and refracts its surroundings ("lensing"), with specular highlights that respond to device motion. It ships across **iOS 26, iPadOS 26, macOS Tahoe 26, watchOS 26, and tvOS 26**, unifying the platforms for the first time. In 2026 it is the mandatory baseline: apps compiled with Xcode 26 get it automatically, and the compatibility opt-out (`UIDesignRequiresCompatibility`) expires with iOS 27.
+
+## Three governing principles (iOS 26 HIG)
+
+1. **Hierarchy** — Controls float on a distinct functional layer *above* content. Glass elevates and distinguishes navigation from the content beneath it; bars and controls shrink, hide, or simplify as the user scrolls to keep content primary.
+2. **Harmony** — Software geometry aligns with hardware: **concentric corner radii** (nested elements share a center so radii step down consistently toward the screen's rounded corners), capsule-shaped controls, and materials that echo the device.
+3. **Consistency** — Adopt platform conventions; the design adapts continuously across window sizes and displays rather than being redesigned per breakpoint.
+
+## The material
+
+- Liquid Glass performs real-time **lensing** (light bending), specular highlights, adaptive shadows, and adapts its tint to the content behind it and to light/dark mode. It is *not* a static blur.
+- **Two variants**:
+  - **`.regular`** (default) — adaptive, most legible; use for nearly everything: toolbars, tab bars, buttons, floating controls.
+  - **`.clear`** — more transparent and visually rich; only when **all** of: it sits over media-rich content, a dimming layer won't hurt the content, the foreground symbols/text are bold and bright, and the glass shape is simple. Typical use: playback controls over video/photos.
+  - `Glass.identity` disables the effect conditionally (not a third visual style).
+- Glass is **interactive**: `.interactive()` adds press scaling, bounce, shimmer, and touch-point illumination.
+
+## The one rule that matters most
+
+**Liquid Glass is exclusively for the navigation/control layer floating above content. Never apply it to content itself** — no glass lists, cards, table cells, or media containers. Content stays on opaque or standard-material surfaces; glass-on-glass stacking is explicitly discouraged (glass cannot sample other glass, and it muddles hierarchy).
+
+## System behavior to design around
+
+- **Tab bar**: now an inset floating capsule (inset ~21pt from left/right/bottom), 2–5 destinations, with Search often split into its own trailing "island." It can minimize on scroll.
+- **Navigation bar**: large title (34pt bold) collapses to compact (17pt semibold) on scroll; content scrolls *under* the glass bars with edge blur/fade.
+- **Toolbars**: related actions group into shared glass capsules; icons preferred over text labels; system spacing groups/separates actions.
+- **Sheets & menus**: partial-height sheets are glass and become opaque when expanded; menus/popovers morph out of the buttons that spawn them.
+- Home Screen icons/widgets are layered glass; ship a **layered app icon** (Icon Composer) so the system can render light/dark/clear/tinted variants.
+
+## Typography & layout (iOS 26 quick specs)
+
+| Element | Spec |
+|---|---|
+| Large page title | SF Pro 34pt Bold |
+| Compact title / primary button | 17pt Semibold / 17pt Regular |
+| Body & list items | 17pt Regular |
+| Secondary text | 15pt Regular (60–70% opacity secondary label color) |
+| Caption/tertiary | 13pt Regular |
+| Tab bar labels | 11pt Regular |
+| Minimum tap target | 44×44pt |
+| Home indicator reserve | 21pt |
+| Reference canvas | 390×844pt (check up to 440×956pt) |
+
+iOS styles text with **weight and color rather than size or case**. Use Dynamic Type text styles (LargeTitle…Caption2), never fixed sizes, and SF Pro / SF Symbols throughout.
+
+## Adoption guidance (SwiftUI)
+
+- Basic: `view.glassEffect()` → regular variant in a capsule shape. Parameters: glass type, shape, enabled.
+- **Group every set of glass elements in a `GlassEffectContainer(spacing:)`** — it provides a shared sampling region, correct rendering, and enables morphing between elements. Skipping it causes inconsistent sampling and worse performance.
+- **Morphing**: declare a `@Namespace`, tag views with `.glassEffectID(_:in:)`, wrap state changes in `withAnimation(.bouncy)`. Morphs are kinetic — gate them on Reduce Motion.
+- **Tint sparingly**: `.glassEffect(.regular.tint(.accent).interactive())` — tint only the primary call-to-action; tinting everything destroys hierarchy.
+- Standard bars/controls (TabView, NavigationStack, toolbars, buttons with `.buttonStyle(.glass)`) adopt Liquid Glass automatically on recompile — prefer system components over custom glass.
+- Pre-iOS-26 fallback: `.ultraThinMaterial` with a subtle gradient overlay.
+
+## Accessibility & performance
+
+- The system adapts glass automatically to **Reduce Transparency** (more frosting), **Increase Contrast**, **Reduce Motion**, and Low Power Mode. Do not bypass with custom opacity.
+- Read `accessibilityReduceTransparency` / `accessibilityReduceMotion` when using custom glass; swap to `Glass.identity` or solid fills where glass adds no value. Apple's own apps became more aggressive about this after 26.4.
+- Performance: glass rendering is GPU-heavy — use containers, let glass rest in steady states, avoid continuous animation, and test on iPhone 11–13-class devices. Early third-party measurements showed meaningful battery cost when overused.
+- Legibility: always test glass controls over the busiest content your app can show, in both light and dark mode; prefer bold SF Symbols over thin glyphs on glass.
+
+## Do / Don't summary
+
+**Do**
+- Reserve glass for the floating navigation/control layer; keep content opaque.
+- Use system components first; recompile with Xcode 26 before customizing.
+- Follow concentric corner geometry; capsules for controls.
+- Group glass in containers; use morphing to connect related states.
+- Respect all accessibility dials automatically.
+
+**Don't**
+- Don't put glass on lists, cards, or media content.
+- Don't stack glass on glass or scroll glass under glass.
+- Don't use `.clear` outside bold, media-rich contexts with dimming.
+- Don't tint decoratively or hardcode colors that ignore background adaptation.
+- Don't ship kinetic glass morphs without a Reduce Motion fallback.
+
+## When to use
+
+- **Native iOS/iPadOS/macOS apps**: adopt fully — it is the platform standard; fighting it reads as dated or non-native.
+- **Cross-platform apps**: mirror the *structure* (floating capsule nav, content-first hierarchy) on iOS builds; do not export literal glass to Android (use Material 3 there).
+- **Web**: glassmorphism-style headers/modals can echo the aesthetic, but treat it as inspiration, not a spec (see web-trends-2026.md for performance limits of `backdrop-filter`).

package/knowledge/design-languages/design-tokens-theming.md

@@ -0,0 +1,108 @@
+---
+id: design-tokens-theming
+title: "Cross-Platform Design Tokens & Theming"
+category: design-language
+platform: cross-platform
+tags: [tokens, theming, dtcg, style-dictionary, dark-mode, multi-brand, figma]
+sources: ["https://www.designtokens.org/tr/2025.10/format/", "https://www.w3.org/community/design-tokens/2025/10/28/design-tokens-specification-reaches-first-stable-version/", "https://styledictionary.com/info/dtcg/", "https://medium.com/eightshapes-llc/naming-tokens-in-design-systems-9e86c7444676", "https://www.alwaystwisted.com/articles/design-token-naming-conventions", "https://fluent2.microsoft.design/design-tokens", "https://docs.tokens.studio/manage-settings/token-format", "https://zeroheight.com/blog/whats-new-in-the-design-tokens-spec/"]
+updated: 2026-07-08
+---
+
+# Cross-Platform Design Tokens & Theming — Best Practices
+
+Design tokens are named, platform-agnostic design decisions (color, spacing, type, motion, elevation) stored as data and transformed into per-platform outputs (CSS variables, Swift, Kotlin, Compose, Flutter). They are how one brand ships coherently to web, iOS, Android, and desktop — and how dark mode, high contrast, and multi-brand theming become a value swap instead of a redesign.
+
+## The standard: W3C DTCG 2025.10
+
+The Design Tokens Community Group (Adobe, Google, Microsoft, Figma, Shopify, Salesforce, et al.) shipped the **first stable Design Tokens spec (2025.10) in October 2025**. Treat it as the interchange format.
+
+- **Format**: JSON; files use `.tokens` / `.tokens.json`; media type `application/design-tokens+json`.
+- **Token syntax**: `"$value"` (required), `"$type"` (required unless inherited from a group), optional `"$description"`, `"$extensions"`, `"$deprecated"`.
+- **Types**: color, dimension (px/rem), fontFamily, fontWeight (1–1000 or keywords), duration (ms/s), cubicBezier, number; **composites**: typography, shadow (single or array), border, transition, gradient, strokeStyle.
+- **Color**: modern color spaces supported via `colorSpace` + `components` notation (not just hex) — relevant for P3/OKLCH pipelines.
+- **Aliases**: `{group.token}` curly-brace references (chainable), plus JSON-Pointer `$ref` for sub-property access into composites.
+- **Groups**: hierarchical, can set `$type` for children; `$extends` allows group inheritance with deep-merge overrides.
+- Supported by Figma, Tokens Studio, Style Dictionary, Terrazzo, Penpot, Sketch, Supernova, zeroheight.
+
+Example:
+```json
+{
+  "color": {
+    "$type": "color",
+    "brand": { "500": { "$value": "#6750A4" } },
+    "action": { "primary": { "$value": "{color.brand.500}" } }
+  }
+}
+```
+
+## The three-tier architecture (non-negotiable)
+
+Every mature system (Fluent 2, Material, Carbon) uses layered tokens:
+
+1. **Primitive / global tokens** — raw values, named by what they *are*: `blue-500`, `space-4`, `radius-md`, `font-size-300`. No semantic meaning, never consumed directly by components.
+2. **Semantic / alias tokens** — named by *intent*: `color-text-primary`, `color-surface-raised`, `color-action-danger`, `space-inset-card`. They map to primitives. **This is the theming layer.**
+3. **Component tokens** (optional) — local decisions: `button-radius`, `card-padding`. Map to semantics; use only where components need controlled divergence.
+
+Rules:
+- Components consume **semantic (or component) tokens only** — never primitives, never raw hexes.
+- Primitives hold values; semantics hold intent; component tokens hold local UI decisions. Keep each layer doing one job.
+- Alias chains should resolve in ≤ 2–3 hops; deeper chains become undebuggable.
+
+## Naming convention
+
+Most widespread and recommended: **kebab-case, ordered general → specific**: `category-concept-property-variant-state-scale`.
+
+- `color-text-primary`, `color-text-on-brand`, `color-bg-danger-hover`, `spacing-inline-md`, `shadow-elevation-high`.
+- Primitives named by appearance (`red-100`); semantics named by role/intent, never by value — `color-action-primary`, not `color-blue-button`. If a token name contains a color word or a pixel number at the semantic tier, the name is wrong.
+- Include **state** (`-hover`, `-pressed`, `-disabled`, `-focus`) and **on-color pairs** (`surface` / `on-surface`) systematically.
+- Pick one taxonomy, document it, and enforce it with linting in CI.
+
+## Theming mechanics
+
+**Dark mode**: keep token *names* constant; swap the primitive each semantic token points to per theme. `color-surface-default` → `gray-50` (light) / `gray-900` (dark). Every component adapts automatically with zero component changes. Also re-map elevation: dark themes convey depth with lighter surfaces + subtle borders more than shadows.
+
+**Multi-brand**: add a brand dimension — each brand supplies its own primitive palette + semantic mapping file; product code stays identical. Complex systems (brand × theme × density × contrast) manage these as separate token sets composed at build time (Tokens Studio "themes", Style Dictionary source layering). The stable DTCG spec deliberately left multi-file/theming composition to tooling — Style Dictionary and Tokens Studio are the de facto standard there.
+
+**High contrast / accessibility themes**: treat as a first-class theme (Fluent does); also expose contrast *levels* (standard/medium/high) as Material 3 does.
+
+## Cross-platform pipeline
+
+Recommended toolchain (2026 standard):
+
+1. **Source of truth**: DTCG JSON in the code repo (edited via Tokens Studio/Figma Variables sync, or hand-maintained). Version it, review it in PRs, changelog it.
+2. **Transform**: **Style Dictionary** (v4+ has native DTCG support) or Terrazzo builds per-platform outputs:
+   - Web → CSS custom properties (+ `@media (prefers-color-scheme)` and `[data-theme]` scopes), Tailwind config
+   - iOS → Swift enums / asset catalogs
+   - Android → Compose theme objects / XML resources
+   - Flutter/React Native → Dart/TS theme maps
+3. **Distribute**: publish as versioned packages (npm/SPM/Maven); CI regenerates on token change so design updates ship like dependency bumps.
+
+**Unit strategy**: store dimensions unitless-or-rem-based where possible and transform per platform (px web, pt iOS, dp Android). Type scales: rem on web, Dynamic Type–compatible styles on iOS, sp on Android — map token *roles* (body, title) rather than raw sizes across platforms.
+
+**Motion tokens**: store durations (ms) and easing (cubicBezier) as tokens; note Material 3 Expressive uses spring physics (stiffness/damping) which the DTCG spec doesn't yet model — keep springs in `$extensions` or platform-specific sets.
+
+## Cross-platform theming judgment calls
+
+- Tokenize the **brand layer** (color, type ramp, radius, spacing, motion feel) globally; let the **structural layer** (nav patterns, control anatomy) stay platform-native: Liquid Glass capsule bars on iOS, M3 toolbars on Android, Fluent density on Windows/web.
+- Map semantic roles across systems rather than copying values: your `color-action-primary` feeds M3 `primary`, iOS tint color, Fluent `colorBrandBackground`.
+- Radius/elevation vocabularies differ per platform (M3 full-pill vs Fluent 4px) — encode these as per-platform semantic overrides, not forks of the whole token set.
+
+## Do / Don't
+
+**Do**
+- Adopt the DTCG format for anything new; migrate legacy token files with Style Dictionary/Tokens Studio converters.
+- Design light + dark palettes simultaneously; validate 4.5:1 (text) and 3:1 (UI) contrast per theme in CI.
+- Keep a published deprecation policy (`$deprecated` in spec) and semver your token package.
+- Document every semantic token with `$description` — an AI or new hire should know usage from the token file alone.
+
+**Don't**
+- Don't let components reference primitives or raw values ("token laundering" via one-off component tokens counts).
+- Don't encode values in semantic names (`color-primary-purple`), and don't create a token for every one-off — tokens are for *reused decisions*.
+- Don't fork token files per platform by hand; generate everything from one source.
+- Don't ship dark mode by CSS `filter: invert()` or ad-hoc overrides — it always breaks images, shadows, and brand color.
+
+## When to invest
+
+- **Always** (even solo projects): 2-tier tokens (primitives + semantics) as CSS variables — near-zero cost, enables dark mode later.
+- **Multi-platform or multi-brand product**: full DTCG + Style Dictionary pipeline with versioned packages.
+- **Overkill**: component-token tier and build pipelines for a single-page marketing site — semantics as CSS variables suffice.

package/knowledge/design-languages/fluent-2.md

@@ -0,0 +1,82 @@
+---
+id: fluent-2
+title: "Microsoft Fluent 2 Design System"
+category: design-language
+platform: cross-platform
+tags: [microsoft, fluent, windows, web, react, tokens, materials]
+sources: ["https://fluent2.microsoft.design/", "https://fluent2.microsoft.design/design-tokens", "https://fluent2.microsoft.design/elevation", "https://fluent2.microsoft.design/material", "https://fluent2.microsoft.design/motion", "https://learn.microsoft.com/en-us/windows/apps/design/signature-experiences/materials", "https://learn.microsoft.com/en-us/windows/apps/design/style/acrylic", "https://learn.microsoft.com/en-us/fluent-ui/web-components/design-system/design-tokens"]
+updated: 2026-07-08
+---
+
+# Microsoft Fluent 2 — Essentials
+
+Fluent 2 is Microsoft's current cross-platform design system (web/React, Windows/WinUI, iOS, Android, macOS), powering Microsoft 365, Teams, and Windows 11. It is the most token-driven of the big-three design languages and the strongest reference for enterprise/productivity UI. Internally ~293 Microsoft design teams use it, with component usage ~4× Fluent 1.
+
+## Principles
+
+Fluent's pillars: **Light, Depth, Motion, Material, Scale** — a softened, dimensional evolution of the flat Metro lineage. Fluent 2 adds a "one Microsoft" coherence goal: the same semantic token resolves to platform-appropriate values everywhere, so a Dialog feels native on Windows, web, and mobile without redesign.
+
+- **Clarity over spectacle**: Fluent motion and materials communicate spatial relationships and state; they are quieter than M3 Expressive or Liquid Glass.
+- **Accessibility as baseline**: 4.5:1 text contrast, full keyboard/focus-visible support, and high-contrast theme variants are built into the token system, not bolted on.
+
+## Token architecture (the heart of Fluent 2)
+
+Two primary layers (plus per-component overrides):
+
+1. **Global tokens** — context-free raw values: hex colors (e.g., a full color ramp per hue), font sizes, line heights, weights, border radii, stroke widths, animation curves/durations. Named by what they *are* (`colorPaletteBlueForeground2` style ramps).
+2. **Alias (semantic) tokens** — meaning-bearing mappings consumed by components: `colorNeutralForeground1`, `colorBrandBackground`, `colorNeutralStroke1`, `colorStatusDangerBackground1`. Theming (light, dark, high contrast, brand) works by re-mapping alias tokens only.
+3. **Component tokens** — local overrides (e.g., a button's specific radius) that resolve to aliases.
+
+Rule: **components consume aliases, never globals**. This is the pattern to copy in any design system.
+
+## Core specs
+
+**Corner radius** (global tokens): 2 / 4 / 6 / 8 / 12 / circular. Buttons and rectangular controls default to **4px**; elements under ~32px drop to 2px to stay proportional; cards commonly 8px; circular for avatars/pills.
+
+**Spacing**: a horizontal + vertical spacing ramp based on a 4px grid — tokens at 0, 2, 4, 6, 8, 10, 12, 16, 20, 24, 28, 32 (spacingHorizontalXXS…XXXL). Use the ramp; never arbitrary pixel values.
+
+**Elevation / shadow**: a generated shadow ramp named by blur size — shadow2, shadow4, shadow8, shadow16, shadow28, shadow64 (shadow2 ≈ 2px blur … shadow64 ≈ 64px blur). Mapping guidance: shadow2–4 for rest-state cards/inputs, shadow8 for dropdowns/tooltips, shadow16 for panels/popovers, shadow28–64 for dialogs and top-level surfaces. Each has a `brand` variant for tinted shadows.
+
+**Typography**: Segoe UI Variable on Windows; web ramp (Fluent UI React): Caption2 10px, Caption1 12px, Body1 14px (the default), Subtitle2 16px, Subtitle1 20px, Title3 24px, Title2 28px, Title1 32px, LargeTitle 40px, Display 68px — weights Regular/Medium/Semibold/Bold. Body text default is **14px** (denser than iOS/Android — appropriate for productivity software).
+
+**Motion** (Fluent UI React motion tokens): durations `ultraFast` 50ms, `faster` 100ms, `fast` 150ms, `normal` 200ms, `gentle` 250ms, `slow` 300ms, `slower` 400ms, `ultraSlow` 500ms. Curves: `accelerate`/`decelerate` cubic-beziers plus `easyEase` for small state changes. Guidance: micro state changes 50–150ms; component enter/exit 150–300ms; large surface transitions 300–500ms with decelerate-in, accelerate-out. Windows adds **connected animations** (shared-element transitions with velocity matching).
+
+## Materials
+
+Fluent supports four surface materials (Windows-first, with graceful fallbacks elsewhere):
+
+| Material | Nature | Use for |
+|---|---|---|
+| **Solid** | Opaque | Content surfaces, anything scrolling; web default |
+| **Mica** | Opaque, subtly tinted by the user's desktop wallpaper; cheap to render | App/window background layers on Windows 11 (replaced Acrylic for primary surfaces) |
+| **Acrylic** | Semi-transparent frosted blur | **Transient, light-dismiss surfaces only**: flyouts, context menus, tooltips |
+| **Smoke** | Dimming scrim | Behind modal dialogs to de-emphasize the app |
+
+Cross-platform rule: the same Dialog uses Acrylic on Windows (real-time compositor blur), a solid fill with subtle texture on web (backdrop-filter is a performance risk), and platform-native materials on iOS/Android. Material is a *token decision*, not a per-screen decision.
+
+## Components
+
+~40+ code-aligned components (Fluent UI React v9, Fluent UI Web Components, WinUI 3, Fluent UI iOS/Android): Button (primary/outline/subtle/transparent; 24/32/40px heights small/medium/large), Input, Combobox, DataGrid, Dialog, Drawer, Menu, Persona/Avatar, Badge, Card, Toast, Teaching Popover, Tree, TabList. Figma UI kits ("Fluent 2 Core" web/iOS/Android + the design-language variables file) are code-aligned so design/dev handoff is 1:1.
+
+**Interaction states**: every control defines rest / hover / pressed / focused / disabled via alias tokens — hover states matter far more here than in mobile-first systems. Focus indicators are 2px `colorStrokeFocus2` rings, always visible on keyboard focus.
+
+## Do / Don't
+
+**Do**
+- Theme exclusively by swapping alias-token values (light/dark/high-contrast/brand).
+- Keep body text at 14px and density high for data-heavy productivity screens; use the spacing ramp to loosen consumer-facing surfaces.
+- Reserve Acrylic for transient surfaces; use Mica (or solid) for persistent backgrounds.
+- Use shadow ramp + stroke (`colorNeutralStroke1`/`stroke2`) together to define surface edges in dark mode.
+
+**Don't**
+- Don't hardcode hex/px — everything visible should trace to a token.
+- Don't use Acrylic on large scrolling content or on web without a solid fallback.
+- Don't invent new elevation values outside the shadow ramp.
+- Don't remove focus rings or hover states — Fluent targets keyboard/mouse parity.
+
+## When to use Fluent 2
+
+- **Best fit**: enterprise software, productivity tools, admin dashboards, data-dense B2B apps, anything in or adjacent to the Microsoft 365/Windows ecosystem, Teams apps (required look), Power Platform.
+- **Good fit**: cross-platform desktop-first products wanting a mature, accessible, token-complete system (Fluent UI React v9 is production-grade and tree-shakeable).
+- **Poor fit**: expressive consumer mobile brands (choose M3 Expressive on Android, HIG/Liquid Glass on iOS); marketing sites (Fluent's density and neutrality read corporate).
+- Fluent 2's token layering is the **reference architecture** to imitate even when not using Fluent visuals — see design-tokens-theming.md.

package/knowledge/design-languages/ios-app-design.md

@@ -0,0 +1,205 @@
+---
+id: ios-app-design
+title: "iOS App Design — Complete Guide"
+category: design-language
+platform: mobile
+tags: [ios, apple, hig, navigation, app-store]
+sources: ["https://developer.apple.com/design/human-interface-guidelines/tab-bars", "https://developer.apple.com/design/human-interface-guidelines/navigation-bars", "https://developer.apple.com/videos/play/wwdc2025/323/", "https://developer.apple.com/videos/play/wwdc2025/284/", "https://www.donnywals.com/exploring-tab-bars-on-ios-26-with-liquid-glass/", "https://developer.apple.com/videos/play/wwdc2025/278/", "https://developer.apple.com/videos/play/wwdc2025/275/", "https://www.createwithswift.com/crafting-liquid-glass-app-icons-with-icon-composer/", "https://developer.apple.com/help/app-store-connect/reference/app-information/screenshot-specifications/", "https://appfollow.io/blog/aso-screenshots-best-practices", "https://developer.apple.com/design/human-interface-guidelines/playing-haptics", "https://developer.apple.com/design/human-interface-guidelines/typography", "https://www.createwithswift.com/making-the-tab-bar-collapse-while-scrolling/"]
+updated: 2026-07-08
+---
+
+# iOS App Design — Complete Guide (iOS 26 era)
+
+Structural, app-level guide for iPhone/iPad apps in the Liquid Glass era. For the material itself (glass variants, lensing, `.glassEffect`), see `apple-hig-liquid-glass`. This doc covers what to build: anatomy, navigation, controls, system surfaces, icon, and App Store presence.
+
+## 1. App anatomy — choose ONE primary structure
+
+- **Flat (tab bar)** — 2–5 peer sections. The default for most consumer apps. Never hide the tab bar when navigating deeper; never use a tab as an action button.
+- **Hierarchical (navigation stack)** — drill-down lists (Settings, Mail). Combine with tabs: each tab owns its own stack, and switching tabs preserves each stack's state.
+- **Modal** — self-contained tasks that interrupt the flow (compose, edit, onboarding). Always provide Cancel (top-leading) and a confirm verb (top-trailing); never trap the user.
+- Support **swipe-from-left-edge back** everywhere; never override it. Re-tapping the current tab pops its stack to root (and scrolls to top on second tap).
+- Deep-link every screen (universal links + App Intents) — widgets, Spotlight, and notifications all need stable routes into the hierarchy.
+
+### Tab bar (iOS 26)
+- Floating **Liquid Glass capsule**, inset from screen edges (~21pt sides/bottom), no longer a full-width 49pt strip. Selected tab gets a glass highlight capsule.
+- 2–5 tabs on iPhone. Icons: SF Symbols at ~25×25pt with 10pt labels; always label tabs.
+- **Minimize-on-scroll** (`tabBarMinimizeBehavior(.onScrollDown)`): bar collapses to a small pill while scrolling down, restores on scroll up. Enable for content-first feeds; skip for tool-like apps.
+- **Search tab role** (`Tab(role: .search)`): search detaches into its own trailing glass island next to the tab bar. Use it whenever search is a top-level destination (App Store, Music, Maps pattern).
+- **Bottom accessory** (`tabViewBottomAccessory`): a persistent app-wide bar above the tabs (e.g., Music's Now Playing). One only; it docks beside the minimized bar. Use for global state, not per-tab actions.
+- On iPad, the tab bar renders in the top bar and can morph into a sidebar (`tabViewStyle(.sidebarAdaptable)`).
+
+### Navigation bar
+- Compact bar: 17pt semibold centered title, 44pt-high touch region. **Large title: 34pt bold**, left-aligned, collapses to compact on scroll; prefer large titles at root level, compact when pushed.
+- Content scrolls **under** the glass bar; iOS 26 applies a scroll-edge effect (progressive blur/fade) automatically — never paint an opaque bar background.
+- Back button shows the previous screen's title (or chevron alone if long). Top-trailing: max 2–3 actions; overflow into a `...` pull-down menu.
+- Bottom toolbars: group related actions into shared glass capsules; keep destructive actions out of easy-thumb reach.
+- Design for the thumb zone: primary actions in the bottom half of the screen on iPhone; the top corners are the most expensive real estate to reach.
+
+### iPad: split views & size classes
+- **Two/three-column split**: sidebar ~320pt, supplementary column ~375pt, remainder content. Collapse to a stacked navigation stack in compact width (Slide Over, 1/3 split).
+- Design for regular AND compact width — an iPad app is judged by its compact behavior. Support Stage Manager: free window resizing, sensible 320pt-class minimum width.
+- Support hardware keyboard (arrow/Tab navigation, ⌘-shortcuts surfaced in the shortcut HUD via holding ⌘) and pointer hover effects (`.hoverEffect`) — iPad users increasingly run trackpads.
+- iPadOS 26 windows behave Mac-like (free resize, tiling, a menu-bar-style command surface) — an iPad layout that only works at exactly full-screen is now a defect.
+- Use popovers, context menus, and multi-column layouts on iPad rather than stretching the iPhone layout; a stretched iPhone UI at 12.9" is the most common iPad review complaint.
+
+### Sheets, popovers, full-screen covers
+- **Sheet** = default modal. Detents: `.medium` (~half screen) and `.large`; show the 36×5pt grabber when resizable. iOS 26 sheets are glass at partial height and become opaque when expanded; corner radii are concentric with the display.
+- **Popover**: iPad/regular-width only (min ~320pt wide), anchored to its trigger with an arrow; it becomes a sheet in compact width — design content to survive both.
+- **Full-screen cover**: only for immersive tasks (camera, video, onboarding). Everything else is a sheet.
+- **Alerts**: 270pt-wide, max 2–3 buttons, title ≤ ~1 line; destructive choice styled `.destructive`, Cancel on the left/bottom. Use confirmation dialogs (action sheets) for choices with more options.
+- Mark unsaved-changes sheets non-dismissable-by-swipe (`interactiveDismissDisabled`) and confirm discard instead of silently losing input.
+
+### Bar & container metrics — quick reference
+
+| Element | Spec |
+|---|---|
+| Status bar / Dynamic Island region | ~54–59pt top safe area on Face ID iPhones |
+| Compact navigation bar | 44pt bar height; 17pt semibold title |
+| Large-title region | adds ~52pt (34pt bold title) above content at scroll top |
+| Tab bar (legacy metric) | 49pt + 34pt home-indicator inset; iOS 26 renders as inset floating capsule |
+| Bottom toolbar | 44pt + home-indicator inset |
+| Sheet grabber | 36×5pt, centered, 5pt from top |
+| Popover minimum width | ~320pt (regular width only) |
+| Alert width | 270pt fixed |
+| List row minimum | 44pt; 60pt with subtitle; 76pt with thumbnail |
+| Default layout margins | 16pt compact / 20pt+ regular; 8pt spacing grid |
+| Home indicator | 34pt inset — keep interactive elements above it |
+
+## 2. Standard controls — when to use each
+
+| Control | Use when | Don't |
+|---|---|---|
+| Segmented control | 2–5 mutually exclusive **views/filters** | actions or on/off states; >5 segments |
+| Toggle/Switch | Instant binary setting, takes effect immediately | needing a confirm step |
+| Menu picker (`.menu`) | Choose 1 of 5–15 options inline in a form | long scrolling lists — use a pushed list |
+| Wheel picker | Dates/times, multi-component values | single short lists |
+| Stepper | Small precise increments (1–10 range) | large ranges — use slider or text field |
+| Slider | Continuous ranges where exact value is secondary | values users must type precisely |
+| Context menu | Secondary actions on **content** (long-press/haptic touch) | primary actions — must exist elsewhere too |
+| Pull-down menu | Multiple actions from one button (`...`, Sort, Add variants) | selection state — use pop-up/picker instead |
+| Swipe actions | Frequent row actions in lists (delete, archive, flag) | as the ONLY way to reach an action |
+
+- **Touch targets: 44×44pt minimum**, 60pt for primary CTAs. List rows ≥44pt. Spacing between tappables ≥8pt.
+- iOS 26 buttons are **capsule-shaped** by default; sizes mini/small/regular/large (large ≈ 50pt tall). One `.borderedProminent` (tinted) button per view; the rest bordered/plain.
+- Context menus and menus **morph out of their source control** in iOS 26 (glass); keep menus ≤ ~8 items, group with separators, destructive items last with `role: .destructive`.
+- Swipe actions: leading edge = positive (read/pin), trailing edge = negative, destructive action outermost with full-swipe to commit. Max 3 per side. Always mirror them in a context menu or edit mode.
+- **Pull-to-refresh** (`refreshable`) for user-initiated feed updates; never as the only sync mechanism.
+- Text fields: correct `keyboardType`, `textContentType` (enables AutoFill/one-time codes), and `submitLabel`; never block paste in credential fields.
+
+### Search placement (iOS 26)
+- On iPhone the search field **bottom-aligns** above the keyboard/tab bar for reachability (`searchable` in the toolbar, or the search tab role); on iPad it sits top-trailing in the navigation bar.
+- On focus, show recent searches + suggestions immediately; filter live per keystroke where the dataset allows; support search tokens/scopes for structured filtering.
+- Don't put a search bar at the top of an iPhone screen and a search tab at the bottom — pick one entry point.
+
+### Lists & forms
+- Inset-grouped is the default list style; plain lists for long indexes (with section index bar for A–Z datasets). Rows: 44pt single-line, ~60pt with subtitle, disclosure chevron only when a push follows.
+- Forms group related settings with 11–13pt uppercase section headers and footnote explanations under the group, not inline placeholder text.
+- Every list needs its states designed: **empty** (`ContentUnavailableView`: symbol + title + one-line guidance + optional CTA), **loading** (skeleton/redacted, never a full-screen spinner over 300ms), **error** (retry affordance).
+
+## 3. iOS 26 structural rules (beyond the material)
+
+- Bars, tab bars, sheets get Liquid Glass **automatically** when built with Xcode 26 against system components. Do not re-tint, re-background, or fake them — custom opaque bar backgrounds break scroll-edge effects and look legacy.
+- Keep the glass layer thin: fewer bars, actions grouped into capsules, icons over text labels in toolbars, system spacing between groups.
+- **Concentric corner radii**: nested containers derive radius from parent radius minus inset. Cards near the screen edge should use the container-relative shape, not hardcoded 12pt.
+- Tint sparingly: one accent color on glass for the single most important action; monochrome SF Symbols elsewhere.
+- Use semantic colors (`label`, `secondaryLabel`, `systemBackground`, `systemGroupedBackground`, system tint colors) so dark mode, increased contrast, and glass adaptation come free. Standard layout margins: 16pt (compact) / 20pt+ (regular); design on an 8pt spacing grid.
+- Test every screen over worst-case content (white background, busy photos) and with Reduce Transparency / Increase Contrast enabled — the system swaps glass for opaque surfaces and your layout must survive. Also verify Reduce Motion: replace parallax/spring travel with crossfades.
+
+## 4. System surfaces: widgets, Live Activities, App Intents
+
+### Widgets
+- Sizes: small (~170×170pt), medium (~364×170pt), large (~364×382pt), extraLarge (iPad); lock-screen accessories: circular, rectangular, inline. Content margins ~16pt (11pt tight).
+- A widget is a **glanceable view of one piece of information + one deep link** (small = whole-widget tap target; medium/large may have multiple `Link` areas). Not a mini app, no scrolling, no video.
+- Must render correctly in **tinted and clear modes** (iOS 26 Home Screen styles): rely on template/vibrant rendering, avoid full-bleed brand color backgrounds and baked-in photos as the only signal.
+- Interactive widgets can host buttons/toggles backed by App Intents — do the action in place, don't just launch the app.
+- Design for StandBy (full-color, viewed from 1–2m — bigger type, higher contrast) and CarPlay (iOS 26 pushes widgets there); use `containerBackground(for: .widget)` so the system can strip backgrounds per context.
+
+### Live Activities
+- Surfaces: Lock Screen banner (max height ~160pt), Dynamic Island **compact** (leading + trailing slivers around the sensor), **minimal** (tiny circle when multiple activities run), **expanded** (max ~160pt tall). Design all four states.
+- Content = live status of one user-initiated event (delivery, ride, score, timer). Hard rules: no ads, no static promos; end promptly when the event ends; 12-hour max lifetime.
+- Keep Lock Screen presentation legible on any wallpaper: use the system background material or a deliberate brand background with tested contrast; respect `activitySystemActionForegroundColor`.
+- Live Activities appear on Apple Watch Smart Stack and CarPlay automatically — check that compact leading/trailing views carry meaning alone (icon + number beats text).
+
+### App Intents
+- Model every core action and entity as an App Intent: this is the design surface for Siri, Spotlight, Shortcuts, Action button, Control Center, widgets, and Apple Intelligence.
+- iOS 26 adds **interactive snippets**: small glass result cards with buttons that appear in Spotlight/Siri/Visual Intelligence. Design them like a medium widget: one clear state, 1–2 actions, no navigation.
+- **Controls** (Control Center / Lock Screen / Action button): one symbol + short label + one intent. Provide a real toggle state for toggles.
+- Naming: intents use verb-first natural phrases ("Log Water", "Start Focus Timer"); entities need a display representation (title, subtitle, image) that reads well in system UI you don't control.
+
+## 5. App icon (iOS 26)
+
+- Author one **layered `.icon` file in Icon Composer** (ships with Xcode 26); the system generates: Default, Dark, Clear Light, Clear Dark, Tinted Light, Tinted Dark.
+- Structure: background layer (color/gradient) + 1–3 foreground layers (max 4 groups). The system adds the glass: specular highlights, depth, masking. **Never bake in** shadows, gloss, borders, or a pre-rounded mask.
+- Keep the foreground glyph identical across variants; only the background hue changes. Bold simple silhouette, centered, filling ~50–60% of the canvas; flat solid or semi-transparent fills beat photographic detail.
+- No text (except an essential brand letterform), no photos, no screenshots, no transparency at the outer edge. Canvas 1024×1024; design on Apple's icon grid.
+- Test all six modes plus small sizes (Spotlight 40pt, Settings 29pt). The tinted variant must survive as a monochrome glyph.
+- Alternate icons are allowed (settings-driven or paywalled) but each needs the full variant set; don't change the icon silently.
+
+## 6. App Store presence (design-side ASO)
+
+- **Screenshots**: 1–10 per localization; required master size 1320×2868 (6.9" portrait); Apple downscales for smaller iPhones. iPad: 2064×2752 (13"). Flattened PNG or JPEG, no alpha.
+- The listing is decided in ~7 seconds and the **first 2–3 screenshots** show in search results — front-load the core value; don't open with a splash/logo shot.
+- Formula per screenshot: one short benefit caption (≤5–6 words, rendered ≥60pt at export, top-aligned) + device frame or full-bleed UI. One background system across the set; sequential panorama layouts are fine but each frame must stand alone.
+- Show real UI (required by review), current-OS status bar, full battery, 9:41 time. Localize captions AND the UI language shown for top markets.
+- Caption copy: concrete outcomes ("Split bills in seconds"), not hype ("Best app ever") — salesy imperatives depress conversion and risk rejection.
+- **Preview videos**: 15–30s, up to 3, autoplay muted — design for no sound (on-screen captions), show actual app footage within the first 5s, portrait video occupies gallery slot 1 ahead of screenshots.
+- Use **Product Page Optimization** to A/B test icon/screenshots and Custom Product Pages per campaign; vary one variable per test so results read cleanly. A strong set lifts conversion 20–35%.
+- **In-app events** get their own 1080×1920 event card (30-char name, 50-char short description) surfaced in search and Today — design them like mini campaign posters, consistent with the app's visual system.
+- App name ≤30 chars, subtitle ≤30 chars carries the value proposition; the icon must remain recognizable at 60px search-result size next to competitors.
+
+## 7. Launch, first run, permissions
+
+- **Launch screen**: a static skeleton of the first real screen (backgrounds + bar placeholders). No logos, taglines, or spinners — the goal is perceived instant launch.
+- First-run: get to value in ≤3 screens or zero (learn by doing with contextual tips). Never front-load a tutorial carousel; never demand account creation before showing value unless the app is inherently account-based (and then offer Sign in with Apple).
+- **Permissions in context**: ask at the moment of need, preceded by your own one-line explainer of the benefit; a cold triple-prompt (notifications + tracking + location) at launch is the top uninstall trigger. Purpose strings must state the concrete benefit.
+- Ask for ratings (`SKStoreReviewController`) only after a success moment, never on launch; ask for notifications only after demonstrating what they'll contain (or use provisional authorization to deliver quietly first).
+- Notifications you send are UI too: lead with the payload not the app name, support rich attachments, group threads via `threadIdentifier`, and set interruption levels honestly (time-sensitive only when truly time-sensitive).
+
+## 8. Haptics vocabulary
+
+| Haptic | Meaning | Example |
+|---|---|---|
+| `.success` (notification) | Flow completed | payment done, upload finished |
+| `.warning` (notification) | Attention, recoverable | form invalid on submit |
+| `.error` (notification) | Action failed | auth failure, cannot process |
+| Impact `.light/.medium/.heavy` | Physical collision/snap of UI | drag hits a snap point, card docks |
+| Impact `.soft/.rigid` | Squishy vs crisp variants | pull-to-refresh engage / lock |
+| Selection | Value change while scrubbing | picker wheel, segmented drag, slider ticks |
+
+Rules:
+- Use system semantics — users have learned these meanings; misusing them (success haptic on every tap) dilutes the vocabulary.
+- Always pair haptics with a visible change; a haptic without visuals reads as a glitch.
+- Reserve success/warning/error for **flow completion**, not in-flight steps; use selection/impact for continuous interactions.
+- `prepare()` the generator just before likely use to kill first-fire latency; never fire haptics for passive events the user didn't cause; respect the system haptics toggle.
+- In SwiftUI use `.sensoryFeedback(_:trigger:)`; for custom textures (games, pro tools) design Core Haptics patterns (AHAP) but keep the system vocabulary for UI semantics.
+
+## 9. Dynamic Type
+
+Default (Large) text styles: largeTitle 34pt · title1 28 · title2 22 · title3 20 · headline 17 semibold · body 17 · callout 16 · subheadline 15 · footnote 13 · caption1 12 · caption2 11.
+
+- Use **text styles, never fixed sizes**; custom fonts via `UIFontMetrics` / `.custom(_:size:relativeTo:)` so they scale with the user's setting.
+- Support the full range: the 5 accessibility sizes scale body 17pt up to 53pt (~310%). Test at AX5; the minimum bar is no truncation or overlap at XXL.
+- At accessibility sizes: switch horizontal stacks to vertical (`ViewThatFits` / `dynamicTypeSize` checks), let text wrap (`lineLimit(nil)`), swap icon+label rows to stacked layouts, and let tap targets grow with content.
+- Never clamp below `.xxLarge` for body content; clamping is acceptable only for giant display numerals and tab bar labels the system already handles.
+- SF Pro tracks automatically (Text ≤19pt looser, Display ≥20pt tighter); don't add manual letter-spacing to system text. SF Symbols scale with their paired text style — use `imageScale` and symbol weights, not fixed-size PNGs.
+
+## 10. Accessibility beyond Dynamic Type
+
+- **VoiceOver**: every interactive element needs a label (what it is), a value (its state), and traits; group composite rows (`accessibilityElement(children: .combine)`) so a card reads as one sentence, not five stops. Custom gestures need `accessibilityAction` equivalents.
+- **Contrast**: 4.5:1 minimum for text, 3:1 for large text/icons — check labels sitting on glass over worst-case content. Never encode meaning in color alone; pair with a symbol or text.
+- **Reduce Motion**: replace parallax, springs with large travel, and zoom transitions with crossfades (`accessibilityReduceMotion`). **Reduce Transparency / Increase Contrast**: system swaps glass for opaque — verify custom overlays follow.
+- **Button Shapes / Bold Text / On-Off labels**: system settings that restyle standard controls — another reason to avoid fully custom controls.
+- Target: full app usable with VoiceOver + AX5 text + Reduce Motion simultaneously; run the Accessibility Inspector audit per screen.
+
+## 11. Ship checklist
+
+- [ ] One structure: tabs (2–5, labeled) or stack; edge-swipe back works everywhere
+- [ ] No custom bar backgrounds; scroll-edge effect intact; capsule tab bar behaviors configured
+- [ ] Search placed per iOS 26 pattern (bottom-aligned field or search tab role)
+- [ ] All controls system-standard; 44pt targets; swipe actions mirrored elsewhere
+- [ ] Empty/loading/error states designed for every list
+- [ ] Widget/Live Activity/App Intent surfaces designed incl. tinted/clear modes
+- [ ] Layered Icon Composer icon, six variants checked at small sizes
+- [ ] Screenshots: value in first 3, ≤6-word captions, 1320×2868 masters; preview video mute-friendly
+- [ ] Launch screen = first-screen skeleton; permissions asked in context with explainers
+- [ ] Haptics semantic and paired with visuals; Dynamic Type passes at AX5; Reduce Motion/Transparency verified