/axiom-swiftui

name: axiom-swiftui
description: Use when building, fixing, or improving ANY SwiftUI UI — views, navigation, layout, animations, gestures, debugging, iOS 26 features, iPhone Duo, view-level performance, feature architecture.
license: MIT

SwiftUI

**You MUST use this skill for ANY SwiftUI work including views, state, navigation, layout, animations, architecture, gestures, and debugging.**

**Bundled tools on Claude Code:** if `command -v <tool>` finds nothing (hooks off or `--bare`), use `<plugin-root>/tools/<tool>` in place of the bare name; `<plugin-root>` is two levels above this skill's `Base directory for this skill:` path.

<!-- AXIOM_AUDITOR_INLINE_BEGIN — rewritten for Codex by scripts/build-codex.ts; do not hand-edit --> > **Auditors are skills here.** Where this router says "Launch `some-auditor` agent", invoke the > matching Codex skill instead — same procedure, no Claude Code agent required. > > Available: `axiom-analyze-swiftui-performance`, `axiom-audit-liquid-glass`, `axiom-audit-swiftui-architecture`, `axiom-audit-swiftui-layout`, `axiom-audit-swiftui-nav`, `axiom-audit-textkit`, `axiom-audit-ux-flow`. > > The ones that shell out — builds, tests, simulators, crash symbolication — need shell access to run. <!-- AXIOM_AUDITOR_INLINE_END -->

Quick Reference

| Symptom / Task | Reference | |----------------|-----------| | View not updating | See `skills/debugging.md` | | View update still broken after debugging | See `skills/debugging-diag.md` | | Slow previews / building good previews / `@Previewable` / `PreviewModifier` / variant matrix | See `skills/previews.md` | | Preview API reference (`#Preview`, traits, modes, Development Assets) | See `skills/previews-ref.md` | | Preview crashes / won't load | See `skills/debugging.md` (Preview Crashes section) | | Hot reload / live editing / edit the running app on device | See `skills/hot-reload.md` | | Navigation issues | See `skills/nav.md` | | Navigation still broken after debugging | See `skills/nav-diag.md` | | Navigation API reference | See `skills/nav-ref.md` | | Layout breaks on iPad/rotation | See `skills/layout.md` | | State lost on resize/rotation (scroll, selection, focus, drafts) | See `skills/layout.md` (State Survives the Transition) | | Layout API reference | See `skills/layout-ref.md` | | Performance/lag/slow scroll | See `skills/swiftui-performance.md` | | Architecture/testability | See `skills/architecture.md` | | `@State` object rebuilt every view init, or an `init` assignment ignored at runtime | See `skills/architecture.md` (`@State` is a macro now) | | Animation issues | See `skills/animation-ref.md` | | Stacks/grids/outlines | See `skills/containers-ref.md` | | Custom containers / List replacement (iOS 18+) | See `skills/containers-ref.md` Part 7 | | Search implementation | See `skills/search-ref.md` | | Toolbars, ToolbarItem, sheet button placement, customization | See `skills/toolbars.md` | | Navigation subtitle: `navigationSubtitle`, `.title` / `.subtitle` / `.largeTitle` / `.largeSubtitle` placements (iOS 26) | See `skills/toolbars.md` (Pattern 14) | | Sheets, detents, popovers, fullScreenCover, presentation adaptation | See `skills/presentations.md` | | Multi-column Table, sortable/resizable columns (iPad/Mac; collapses to first column in compact) | See axiom-macos (skills/swiftui-differences.md) | | Inspector panel (`.inspector` — trailing column in regular width, sheet in compact) | See axiom-macos (skills/swiftui-differences.md) | | Gesture conflicts | See `skills/gestures.md` | | Section index — the vertical A–Z index strip / alphabet scrubber on a list's trailing edge, jump-to-section | See `skills/26-ref.md` (Section Index) | | List section margins / insets around a `Section` | See `skills/26-ref.md` (Section Margins) | | Web content — `WebView` / `WebPage`, scroll modifiers, WebView-in-NavigationStack | See `skills/26-ref.md` (WebView & WebPage) | | iPhone Duo / foldable iPhone: poses, vertical bars, the fold, arrangements, hinge, scene accessories (SwiftUI and UIKit) | See `skills/iphone-duo.md` | | iOS 26 features | See `skills/26-ref.md` |

Non-SwiftUI UI Routes

These topics are part of the broader iOS UI domain but live in separate suites:

UIKit issues

• Auto Layout conflicts → See axiom-uikit (skills/auto-layout-debugging.md)
• Animation timing → See axiom-uikit (skills/uikit-animation-debugging.md)
• SwiftUI ↔ UIKit bridging → See axiom-uikit (skills/uikit-bridging.md)

Design & guidelines

• Liquid Glass adoption → See axiom-design (skills/liquid-glass.md)
• SF Symbols → See axiom-design (skills/sf-symbols.md)
• HIG compliance → See axiom-design (skills/hig.md)
• Typography → See axiom-design (skills/typography-ref.md)
• TextKit/rich text → See axiom-uikit (skills/textkit-ref.md)

Other

• tvOS (focus, remote, text input) → See axiom-swift (skills/tvos.md)
• App-level composition (root, auth, scenes) → See axiom-design (skills/app-composition.md)
• Drag/drop, sharing, copy/paste → See axiom-swift (skills/transferable-ref.md)
• VoiceOver, Dynamic Type → `/skill axiom-accessibility`
• UI test flakiness → `/skill axiom-testing`
• UX dead ends, dismiss traps → `axiom-audit-ux-flow`

watchOS-specific patterns

• Glanceable UI, watch navigation, Smart Stack widgets → See axiom-watchos

Conflict Resolution

**axiom-swiftui vs axiom-performance**: When UI is slow (e.g., "SwiftUI List slow"): 1. **Try axiom-swiftui FIRST** — Domain-specific fixes (LazyVStack, view identity, @State optimization) often solve UI performance in 5 minutes 2. **Only use axiom-performance** if domain fixes don't help — Profiling takes longer and may confirm what domain knowledge already knows

Decision Tree

digraph swiftui {
    start [label="SwiftUI issue" shape=ellipse];
    what [label="What's wrong?" shape=diamond];

    start -> what;
    what -> "skills/debugging.md" [label="view not updating"];
    what -> "skills/nav.md" [label="navigation"];
    what -> "skills/sw