swiftui-ui

name

swiftui-ui

description

Build native-feeling SwiftUI screens for the iOS 26 Liquid Glass era with Swift 6 — view composition, native-component selection, state-driven navigation, animations, @Observable view models, anti-AI-slop design rules, and a self-audit checklist. Use when asked to build, structure, improve, or review SwiftUI views or screens — "build a SwiftUI view", "make a screen", "my UI looks off", "NavigationStack", "sheet / detents", "TabView", "glassEffect / Liquid Glass", "List vs LazyVStack", "WidgetKit / Live Activity", "rich text editor", "drag and drop" — even when the user does not say "SwiftUI". For pure HIG audits defer to apple-hig; for Figma→code defer to figma-to-swiftui.

swiftui-ui

Write SwiftUI that looks and feels like it shipped with iOS — native components, state-driven navigation, GPU-cheap animation, and the spacing/typography/color restraint that separates a polished app from AI slop. This is your pre-flight checklist and reference set for any view, navigation flow, animation, or UI audit in the iOS 26 Liquid Glass / Swift 6 era.

Scope vs sibling skills. This skill is about building the SwiftUI UI: view structure, component choice, navigation, animation, design quality, audit. For the canonical Apple HIG spec/audit reference use apple-hig. For turning a Figma comp into code use figma-to-swiftui. They compose — cite HIG values from apple-hig, build the views with this one.

---

The two failure modes this skill prevents

Almost every weak AI-built SwiftUI screen fails in one of two ways. Read this before writing anything.

1. Over-customization — fighting the system instead of letting it work. Applying .glassEffect() to content rows, stacking glass on glass, hand-rolling nav bars and tab bars, custom-styled text inputs, custom dividers, bespoke gradients on ordinary cards, LazyVStack where List belongs, animating the network request instead of the result. iOS 26 gives you enormous polish for free — but only if you reach for native components first.

2. Visual incoherence (slop) — arbitrary spacing (.padding(26), spacing: 18), seven font sizes with no system, hardcoded Color.white.opacity(0.44) everywhere, mismatched stroke widths, 22pt corner radii. The eye reads the inconsistency as "off" even when it can't name why. Restraint over decoration — fewer colors, fewer sizes, fewer spacing values, used consistently.

---

Pre-flight checklist (read before every change)

0. Am I writing code inside the current project directory? All UI code belongs in the working tree. For a brand-new project, scaffold a buildable .xcodeproj first (see references/project-setup.md) — never hand off a project that doesn't compile. And if the request is vague about style ("make it look better", "what style?") and no design direction is set, run the design-direction advisor first (references/design-direction.md) — offer 2-3 directions, don't guess one.
1. Is there a native component for this? Navigation, tabs, search, toolbars, sheets, alerts, menus, toggles, sliders, pickers, forms, paywalls all have first-party solutions. Check the catalog in references/native-components.md. Use them.
2. Is my glass only on the navigation layer? .glassEffect() belongs on floating controls above content (FABs, floating toolbars, mini-players) — never on list rows, cards, or backgrounds, never glass-on-glass. (references/liquid-glass.md)
3. Is my view model @MainActor @Observable? Not ObservableObject, not @StateObject, not @Published. (references/state-and-architecture.md)
4. Is my spacing on the grid and my type scale ≤ 5 sizes? 4/8/12/16/20/24/32/40/48 only; hierarchy through weight, not a zoo of sizes; semantic system colors, not hardcoded opacities. (references/design-quality.md)
5. Am I using List for long homogeneous content? Not ScrollView + LazyVStack unless the layout genuinely can't be a list.
6. Am I animating the result, not the request? withAnimation wraps the state change when data lands, never the await that fetches it. (references/animations.md)
7. Is navigation state-driven? NavigationStack + value-based destinations, not a bare ZStack pretending to be a screen, not deprecated NavigationView. (references/navigation.md)

---

View architecture — one pattern, no bikeshedding

Views/ → ViewModels/ (@MainActor @Observable, one per screen) → Services/ (actors) → Models/ (@Model + Sendable DTOs); the full layout tree is in state-and-architecture.md.

The rule: Views own state via @State on an @Observable view model. View models call actor services. Services never touch UI. Dependencies flow via initializer injection (screen-local) or @Environment (cross-cutting: auth, router, current user).

Split views aggressively. Each View struct does ONE thing. @State lives at the lowest owner that needs it. No business logic inside body — delegate to the view model. A subtree over ~15 lines or used more than once becomes its own view.

Full pattern with the ViewState<T> loading/error/loaded enum, @Observable migration table, and DI setup: references/state-and-architecture.md.

---

Native component priority (reach here first)

Every common need has a first-party answer — NavigationStack/TabView, List, .sheet, .contextMenu/.swipeActions, Form+TextField, .refreshable, .searchable, ContentUnavailableView, glass button styles, SubscriptionStoreView, SignInWithAppleButton, Gauge, PhotosPicker. The need→use→NOT priority table and the full catalog (each with the one-liner that gives you Liquid Glass for free) are in native-components.md.

---

Design quality — the anti-slop rules

These are what reviewers catch. They are the difference between "ships with iOS" and "obviously AI-generated." Apply them to every view: spacing only on the 4/8/12/16/20/24/32/40/48 grid; ≤ 5 font sizes with hierarchy through weight (Dynamic Type styles, never .system(size:)); semantic system colors, never Color.white.opacity(…) stacks; cards on .secondarySystemBackground at 10pt radius; matching stroke widths; ≤ 2 tracking values; shorter copy; no minimumScaleFactor hacks. The at-a-glance rule list (§12) and the full bad/good code pairs are in design-quality.md.

---

Navigation — state-driven, not imperative

NavigationStack + value-based destinations replaces the push/present/pop model with a NavigationPath-as-state model: lazy NavigationLink(value:) + .navigationDestination(for:) (never eager destination:), .sheet(item:) over .sheet(isPresented:), one NavigationStack per tab, and a @MainActor @Observable Router when flows outgrow view-local @State. The core-pattern code, routing strategies, deep links, UIKit interop, and the 10 most common navigation mistakes are in navigation.md.

---

Animations — transforms and opacity, not layout

Good iOS animation is GPU-cheap (transforms + opacity). Bad animation forces layout recalculation inside scroll views. Core rules: .animation(_:value:) declarative / withAnimation {} imperative; animate when the value lands, never wrap the await; matchedGeometryEffect before .frame(); inside lists animate scaleEffect/opacity, never frame/padding; completion handlers over DispatchQueue delays. The at-a-glance list (§6), toolbox table, Liquid Glass animation APIs, and the jank anti-patterns are in animations.md.

---

iOS 26 Liquid Glass — one rule that matters most

Liquid Glass is a navigation-layer material, not a content material (Apple says this verbatim). Recompiling against the iOS 26 SDK gives you glass on nav bars, tab bars, toolbars, sheets, popovers, menus, alerts, search fields, toggles, sliders, and pickers for free. Custom .glassEffect() is the exception, reserved for floating controls that hover above content (the canonical FAB example, container grouping, tinting rules, Regular-vs-Clear, tab-bar/toolbar APIs, and the automatic accessibility behavior — never override it — are in liquid-glass.md). Group adjacent glass in ONE GlassEffectContainer; tint only the primary CTA; never mix Regular and Clear.

---

Accessibility — non-negotiable minimums

Labels + hints on icon-only buttons, .accessibilityHidden(true) on decorative images, combined elements, header traits; tap targets ≥ 44×44 pt; color never carries meaning alone; guard motion via accessibilityReduceMotion; Dynamic Type text styles, never fixed sizes. Code block in ui-audit.md ("Accessibility minimums").

---

UX patterns that apply to every screen

Six recurring patterns — full detail in native-components.md ("UX patterns" section): inline button loading (spinner inside the tapped button, no layout shift, track which button via @State var loadingButton: ButtonID?); consistent button sizing within a group; native Form for data entry; PhotosPicker for user images; sheets with detents + drag indicator + NavigationStack toolbar; onboarding as a conditional root-view flow, not a modal.

---

Self-audit — run before declaring a view done

Quick pass (full 13-domain audit framework with severity ratings is in references/ui-audit.md):

• Every spacing value is on the grid (4/8/12/16/20/24/32/40/48).
• ≤ 5 distinct font sizes; one font design; Dynamic Type text styles, no .system(size:).
• Semantic system colors, not hardcoded Color.white.opacity(…) stacks.
• Background/foreground strokes share lineWidth; cards 10pt radius on .secondarySystemBackground.
• Native component used wherever one exists (no hand-rolled nav/tab/divider/input).
• Glass only on the navigation layer; no glass-on-glass; only the primary CTA tinted.
• View model is @MainActor @Observable; services are actors; DTOs are Sendable.
• NavigationStack + lazy value-based destinations (not bare ZStack, not NavigationView).
• .sheet(item:) for data-driven sheets; one NavigationStack per tab.
• Animations are transform/opacity; withAnimation wraps the landed value, not the await.
• Reduce-Motion / Reduce-Transparency respected (don't override); tap targets ≥ 44pt.
• Async buttons show inline spinners with no layout shift; sibling buttons disabled.
• (iPad) .sheet() sizing checked caller-side; (widgets) Gauge + .containerBackground(.fill.tertiary, for: .widget).
• Verified in the simulator (Light AND Dark) with a screenshot, not just "looks right" in code.

---

Hard stops — never ship these

The full 19-row anti-pattern/why/fix table is in ui-audit.md ("Hard stops"). Headlines: no .glassEffect() on content or glass-on-glass; no ObservableObject in new code; List over LazyVStack for >50 rows; withAnimation after the await, never around it; no NavigationView or eager NavigationLink(destination:); no .system(size:) or opacity-zoo colors; .task {} over .onAppear { Task }; @MainActor over DispatchQueue.main.async; 10pt card radius; tint only the primary CTA.

---

Beyond the basics — when to reach for which reference

Capability areas that have their own deep reference (all iOS 26 / current-SDK):

• Embed web content → references/webkit.md — SwiftUI WebView + WebPage (not a WKWebView wrapper); the callJavaScript(arguments:)-not-interpolation rule is load-bearing. OAuth still uses ASWebAuthenticationSession (ios-security).
• Rich text editing → references/rich-text-editor.md — TextEditor bound to AttributedString; the fontResolutionContext gotcha for toolbar state. (The text-editing skill defers this here.)
• Widgets / Live Activities / Dynamic Island / Control Center → references/widgetkit-live-activities.md (functional); widget visual design is in design-quality.md §8; Liquid-Glass widget rendering in the liquid-glass skill.
• 3D charts → references/charts-3d.md (Chart3D/SurfacePlot; the read-only-.chart3DPose mistake).
• Drag and drop → references/drag-and-drop.md (.draggable/.dropDestination, DropDelegate live-reorder, iOS 26 multi-item drag).
• Canvas / Shape stroke geometry → references/canvas-stroke-geometry.md (selection-border insets, hairlines, marching-ants flicker).
• watchOS / visionOS / iPad input → references/platform-inputs.md (Digital Crown, spatial hover-privacy, double-tap primary action).
• Pre-release whole-app audit → references/workflow-audit.md — the outside-in flow audit that finds unreachable views and unwired data (run per-app; run ui-audit.md per-view).

Reference files

File	Covers
references/liquid-glass.md	iOS 26 Liquid Glass: free-on-recompile list, custom .glassEffect() rules, GlassEffectContainer, tab-bar/toolbar APIs, tinting, Regular/Clear/.identity variants, accessibility, background extension
references/native-components.md	Native component catalog; iOS 17/26 ScrollView modifiers; iOS 26 Slider ticks; hover/pointer; settings-row alternative; anchored popovers; iOS 26 gotchas; search/toast/Siri components; per-domain SF Symbol seed
references/design-quality.md	Anti-slop rules with bad/good code: spacing, typography (SF-Pro axes, smallCaps, reading width), color, cards (accent bar, pills, gradient-divider exception), strokes, editors, nested-safeAreaInset trap, AI-slop visual tropes, the one signature detail
references/navigation.md	NavigationStack/Path, routing, sheets/detents, TabView + Tab(role) gotcha, Router, @Entry/callAsFunction env actions, toolbar customization, UIKit interop (make-once/update-many), gesture bridging, in-app Safari, testing, mistakes
references/animations.md	Animation toolbox, SF Symbol effects catalog, .scrollTransition, transaction keys, @Animatable/KeyframeTimeline, MeshGradient/TextRenderer, Liquid Glass animation APIs, jank anti-patterns
references/state-and-architecture.md	@MainActor @Observable view models, @ObservationIgnored+debounce, optimistic updates/rollback/high-stakes, progressive rendering, @Observable migration + traps, @Previewable, environment scoping, Swift 6 concurrency
references/ui-audit.md	5-dimension triage score + 13-domain audit (space, hierarchy, density, interaction, a11y, HIG, dark mode + same-as-background bug, performance + geometry-loop, design-system, color, iPad sheets, hit region)
references/project-setup.md	XcodeGen project.yml (app target, SPM packages:, unit-test target wiring, free-team error + mock-auth) + minimal Assets.xcassets
references/webkit.md	iOS 26 SwiftUI WebView + WebPage: load/navigation events, injection-safe callJavaScript(arguments:), WKContentWorld isolation, custom URL schemes, snapshot/PDF/archive, private browsing
references/widgetkit-live-activities.md	Functional widget half: timeline + reload budget, App Groups, interactive widgets, Live Activities (4 KB, push, lifecycle), Dynamic Island, Control Center controls, Lock Screen/StandBy, Activity Rings
references/rich-text-editor.md	iOS 26 TextEditor(text: $AttributedString), selection-aware toolbar + fontResolutionContext, formatting constraints, inline images, custom attribute keys + cross-boundary round-trip, Markdown traps, text-color traps
references/charts-3d.md	Chart3D + SurfacePlot, the chart3DPose($binding) read-only mistake, projection, auto-rotation
references/drag-and-drop.md	.draggable/.dropDestination/Transferable multi-fidelity, move/copy + spring-loading, DropDelegate live-reorder, iOS 26 selection-driven multi-item drag
references/canvas-stroke-geometry.md	Stroke centering, inset/outset for selection borders, 1/displayScale hairlines, pixel alignment, marching-ants flicker, pixel-art AA, optical centering
references/workflow-audit.md	Outside-in cross-app flow audit (complements per-view ui-audit): enumerate-then-verify, 5-layer pipeline, entry-point grep recipes + zero-match discipline, 32-category flow-bug taxonomy
references/platform-inputs.md	Digital Crown, visionOS spatial input (hover-privacy contract, comfort constants), watchOS haptics + double-tap primary action, combined Magnify+Rotate gestures
references/design-direction.md	Pre-build design-direction advisor: 5-school taxonomy with reference-app anchors; offer 2-3 directions, never one final