ios-ui-refactor

Apple HIG SwiftUI iOS 26 / Swift 6.2 Best Practices A principal designer's lens for evaluating and refactoring SwiftUI interfaces to Apple-quality standards, grounded in Rams, Segall, and Edson. Contains 51 rules across 8 categories, each grounded in specific principles from three foundational design texts: Dieter Rams — Ten Principles for Good Design ("less, but better," "design should be honest") Ken Segall — Insanely Simple (simplicity as a core principle for intuitive, beautiful products) John Edson — Design Like Apple (design-focused culture, prototyping to perfection, the product is the marketing) Categories are ordered by a visual review process: start with what to remove, then what to clarify, then what to make honest, invisible, systematic, thorough, enduring, and finally what to refine. Scope & Relationship to Sibling Skills This skill is the refactoring and review lens — it evaluates existing UI and identifies visual anti-patterns to fix. When loaded alongside ios-design (building new UI), ios-hig (HIG compliance), or swift-refactor (code-level refactoring), this skill supersedes overlapping rules with more detailed "incorrect -> correct" transformations and "When NOT to apply" guidance. Use this skill for auditing and improving existing screens; use the siblings for greenfield implementation. Clinic Architecture Contract (iOS 26 / Swift 6.2) All guidance in this skill assumes the clinic modular MVVM-C architecture: Feature modules import Domain + DesignSystem only (never Data , never sibling features) App target is the convergence point and owns DependencyContainer , concrete coordinators, and Route Shell wiring Domain stays pure Swift and defines models plus repository, *Coordinating , ErrorRouting , and AppError contracts Data owns SwiftData/network/sync/retry/background I/O and implements Domain protocols Read/write flow defaults to stale-while-revalidate reads and optimistic queued writes ViewModels call repository protocols directly (no default use-case/interactor layer) When to Apply Reference these guidelines when: Reviewing existing SwiftUI screens for visual quality issues Auditing whether every element on screen earns its place (Rams #10) Evaluating if the interface is self-explanatory without tooltips (Rams #4) Checking that colors, states, and hierarchy tell the truth (Rams #6) Ensuring animations and materials are invisible, not decorative (Rams #5) Verifying spacing, radii, and colors form a coherent system (Edson "Systems Thinking") Confirming edge cases — reduce motion, touch targets, safe areas — are handled (Rams #8) Adopting iOS 26 / Swift 6.2 APIs that refine previously impossible interactions (Edson "Design Out Loud") Rule Categories by Priority Priority Category Principle Impact Prefix Rules 1 Less, But Better Rams #10 + Segall "Think Minimal" CRITICAL less- 7 2 Self-Evident Design Rams #4 + Segall "Think Human" CRITICAL evident- 6 3 Honest Interfaces Rams #6 + Segall "Think Brutal" CRITICAL honest- 6 4 Invisible Design Rams #5 + Edson "Product Is Marketing" HIGH invisible- 6 5 Systems, Not Pieces Edson "Systems Thinking" + Rams #8 HIGH system- 6 6 Thorough to the Last Detail Rams #8 + Rams #2 HIGH thorough- 7 7 Enduring Over Trendy Rams #7 + Edson "Design With Conviction" MEDIUM-HIGH enduring- 5 8 Refined Through Iteration Edson "Design Out Loud" + Rams #1/#3 MEDIUM refined- 8 Quick Reference 1. Less, But Better (CRITICAL) Rams #10: "Good design is as little design as possible." Segall: Apple succeeded by saying no to a thousand things. less-single-focal - One primary focal point per screen less-type-restraint - Limit to 3-4 distinct type treatments per screen less-one-typeface - One typeface per app, differentiate with weight and size less-color-restraint - Reserve saturated colors for small interactive elements less-one-color-purpose - Each semantic color serves exactly one purpose less-purposeful-motion - Every animation must communicate state change or provide feedback less-fewer-controls - Remove controls that do not serve the core task 2. Self-Evident Design (CRITICAL) Rams #4: "Good design makes a product understandable." Segall: interfaces must speak in terms people understand. evident-visual-weight - Combine size, weight, and contrast for hierarchy evident-whitespace-grouping - Use whitespace to separate conceptual groups evident-progressive-disclosure - Use progressive disclosure for dense information evident-reading-order - Align visual weight with logical reading order evident-navigation-intent - Sheets for tasks and creation, push for drill-down hierarchy evident-label-clarity - Use clear labels over ambiguous icons 3. Honest Interfaces (CRITICAL) Rams #6: "Good design is honest." Segall: clarity without sugar-coating. honest-semantic-colors - Use semantic colors, never hard-coded black or white honest-contrast - Ensure WCAG AA contrast ratios honest-dark-mode - Define light and dark variants for every custom color honest-foreground-style - Use foregroundStyle over foregroundColor honest-depth-cues - Use materials for layering, not drop shadows for depth honest-loading-states - Show real progress, not indefinite spinners 4. Invisible Design (HIGH) Rams #5: "Good design is unobtrusive." Edson: the product itself is the marketing. invisible-spring-physics - Default to spring animations for all UI transitions invisible-spring-presets - Use .smooth for routine, .snappy for interactive, .bouncy for delight invisible-no-easing - Prefer springs over linear and easeInOut for UI elements invisible-system-materials - Use system materials, not custom semi-transparent backgrounds invisible-symbol-effects - Use built-in symbolEffect, not manual symbol animation invisible-content-transitions - Use contentTransition for changing text and numbers 5. Systems, Not Pieces (HIGH) Edson: "Design is systems thinking." Rams #8: nothing must be arbitrary or left to chance. system-spacing-grid - Use a 4pt base unit for all spacing system-consistent-padding - Use consistent padding across all screens system-corner-radii - Standardize corner radii per component type system-alignment - Consistent alignment per content type within a screen system-color-naming - Name custom colors by role, not hue system-brand-integration - Map brand palette onto iOS semantic color roles 6. Thorough to the Last Detail (HIGH) Rams #8: "Care and accuracy in the design process show respect for the user." Rams #2: if the user cannot reliably use it, the product has failed. thorough-reduce-motion - Always provide reduce motion fallback thorough-touch-targets - All interactive elements at least 44x44 points thorough-safe-areas - Always respect safe areas thorough-readable-weights - Avoid light font weights for body text thorough-vibrancy-levels - Match vibrancy level to content importance thorough-material-thickness - Choose material thickness by contrast needs thorough-background-interaction - Enable background interaction for peek-style sheets 7. Enduring Over Trendy (MEDIUM-HIGH) Rams #7: "Good design is long-lasting." Edson: commit to a voice that persists across product generations. enduring-system-text-styles - Use Apple text styles, never fixed font sizes enduring-weight-not-caps - Use weight for emphasis, not ALL CAPS enduring-swipe-back - Never break the system back-swipe gesture enduring-zoom-navigation - Use zoom transitions for collection-to-detail navigation enduring-card-modularity - Use self-contained cards for dashboard layouts 8. Refined Through Iteration (MEDIUM) Edson: "Design out loud" — prototype relentlessly until every interaction feels inevitable. Rams #1: innovation serves genuine purpose. refined-scroll-transitions - Use scrollTransition for scroll-position visual effects refined-phase-animator - Use PhaseAnimator for multi-step animation sequences refined-mesh-gradients - Use MeshGradient for premium dynamic backgrounds refined-text-renderer - Use TextRenderer for hero text animations only refined-inspector - Use inspector for trailing-edge detail panels refined-multi-detent - Provide multiple sheet detents with drag indicator refined-matched-geometry - Use matchedGeometryEffect for contextual origin transitions refined-no-hard-cuts - Always animate between states, even minimally How to Use Read individual reference files for detailed explanations and code examples: Section definitions - Category structure, principle sources, and impact levels Rule template - Template for adding new rules Reference Files File Description references/_sections.md Category definitions and principle grounding assets/templates/_template.md Template for new rules metadata.json Version and reference information