swift-front/SKILL.md

name, description

name	description
swift-front	Use when building new SwiftUI views, screens, or apps where visual design quality matters - creating distinctive, production-grade iOS interfaces that avoid generic aesthetics. Triggers on requests to build SwiftUI components, design iOS screens, or create visually striking Apple platform interfaces.

Swift Front

Create distinctive, production-grade SwiftUI interfaces with exceptional visual design. Combines bold aesthetic direction with modern SwiftUI correctness, grounded in Apple's Human Interface Guidelines.

Core principle: Every SwiftUI screen should feel designed, not generated. Commit to a clear aesthetic vision and execute it with the full power of SwiftUI's rendering pipeline.

Design Thinking

Before writing any SwiftUI code, understand the context and commit to a BOLD aesthetic direction:

• Purpose: What does this screen solve? Who uses it — quick glance or deep immersion?
• Tone: Pick an extreme and commit: brutally minimal, maximalist chaos, retro-futuristic, organic/natural, luxury/refined, playful/toy-like, editorial/magazine, brutalist/raw, art deco/geometric, soft/pastel, industrial/utilitarian, liquid glass, skeuomorphic revival. Use these for inspiration but design one true to the aesthetic.
• Platform Context: iOS has its own design language — work WITH it. Liquid Glass, materials, SF Symbols, Dynamic Type are tools, not constraints.
• Differentiation: What's the ONE thing someone remembers about this interface?

CRITICAL: Bold maximalism and refined minimalism both work. The key is intentionality, not intensity. Generic = forgettable. No two designs should look the same.

HIG Compliance Check

After choosing your aesthetic direction and before implementing, load the relevant HIG reference files to ensure your design works within Apple's guidelines:

Building...	Load reference
Typography / text hierarchy	references/hig-typography.md
Color system / dark mode	references/hig-color.md
Layout / responsive design	references/hig-layout.md
Materials / Liquid Glass / depth	references/hig-materials.md
Animations / transitions	references/hig-motion.md
Icons / SF Symbols / app icon	references/hig-icons.md
Navigation / modals / search	references/hig-components.md

For topics not covered in curated references, search data/apple-hig-index.json for the article, then read the full content from data/categories/<category>.json.

When HIG and Bold Design Conflict

The swift-front skill encourages breaking conventions — the HIG enforces them. Here's the boundary:

HIG Rule Type	Compliance Level	Example
Accessibility	NON-NEGOTIABLE	44pt min tap targets, Dynamic Type, contrast ratios, Reduce Motion
Component behavior	STRONGLY RECOMMENDED	NavigationStack patterns, sheet presentation, alert conventions
Visual styling	SUGGESTIONS — override with intent	Default List appearance, standard spacing, system font defaults

You can break visual conventions if you replace them with something better and intentional. You cannot break accessibility rules or fundamental component behavior.

SwiftUI Aesthetics Guidelines

Typography

• Never default to system font without consideration. SF Pro is fine when intentional, but explore:
  • SF Pro Display for large titles, SF Pro Rounded for playful UIs, SF Mono for data-dense screens
  • Custom fonts: .font(.custom("FontName", size:, relativeTo:)) — always use relativeTo: for Dynamic Type
  • @ScaledMetric for custom sizing that respects accessibility (iOS 18−), .font(.body.scaled(by:)) (iOS 26+)
  • Pair a distinctive display font with a readable body font
• Use bold() not fontWeight(.bold) — let the system choose context-appropriate weight
• Don't scatter fontWeight(.medium) or .semibold — every weight choice needs hierarchy purpose
• Avoid .caption2 (extremely small) and use .caption carefully
• HIG minimum sizes: iOS 11pt, macOS 10pt, visionOS 12pt — never go below these

Color & Theme

• Commit to a cohesive palette. Dominant colors with sharp accents outperform timid, evenly-distributed palettes.
• Create a shared Design constants enum for all colors, spacing, corner radii — consistency is non-negotiable
• Use semantic system colors (.primary, .secondary) as foundation, layer custom accents on top
• foregroundStyle() with hierarchical styles (.secondary, .tertiary) before reaching for manual opacity
• Gradients: LinearGradient, RadialGradient, MeshGradient (iOS 18+), EllipticalGradient — use intentionally, not decoratively
• Design dark mode from the start — use asset catalog colors or conditional logic
• Never use UIKit colors (UIColor) in SwiftUI code
• HIG contrast: minimum 4.5:1; aim for 7:1 in small text
• Even single-appearance apps must provide light+dark colors for Liquid Glass adaptivity

Motion & Animation

• withAnimation(.bouncy) or .spring() as default — linear animations feel mechanical
• Chain animations with completion: closures, NEVER multiple withAnimation() with delays:

withAnimation(.spring) {
    scale = 2
} completion: {
    withAnimation(.spring) {
        scale = 1
    }
}

• Always provide a value: .animation(.bouncy, value: score) — never the deprecated parameterless variant
• Use @Animatable macro over manual animatableData; mark non-animatable properties @AnimatableIgnored
• sensoryFeedback() for haptics — pair with visual transitions for multi-sensory delight
• Staggered reveals on appear create more impact than scattered micro-interactions
• PhaseAnimator for looping multi-phase sequences, KeyframeAnimator for complex choreography
• contentTransition(.numericText()) for number changes, .symbolEffect() for SF Symbol animations
• Respect accessibilityReduceMotion — replace large animations with opacity crossfades (HIG: non-negotiable)

Spatial Composition

• Break the grid intentionally. Overlap with .offset() or ZStack alignment. Asymmetric layouts.
• containerRelativeFrame() over GeometryReader for responsive sizing
• Generous negative space OR controlled density — never the muddy middle
• .visualEffect() for scroll-driven parallax and transforms
• ScrollView with .scrollTargetBehavior(.paging) or .viewAligned for snappy scroll UX
• Never use UIScreen.main.bounds — use containerRelativeFrame() or visualEffect()

Materials & Depth

• .ultraThinMaterial, .regularMaterial, .thickMaterial — native glass effects
• Layer materials over vibrant backgrounds for depth
• shadow(color:radius:x:y:) — sparingly but effectively; soft large-radius shadows for elevation
• clipShape(.rect(cornerRadius:)) — .continuous is the default, matches iOS system rounding
• Custom Shape conformances for non-rectangular clipping
• Canvas for high-performance custom drawing (particles, generative backgrounds, data visualizations)
• MeshGradient for rich, organic color fields
• HIG: Liquid Glass is for controls/navigation ONLY — never in the content layer
• HIG: Use glassEffect(_:in:) for custom Liquid Glass; regular variant for most, clear variant over media

SF Symbols

• 6000+ symbols — always check for the right one before creating custom assets
• .symbolEffect(.bounce), .symbolEffect(.pulse), .symbolRenderingMode(.hierarchical) for rich treatments
• Variable color symbols for progress indicators
• Always include text labels: Button("Add", systemImage: "plus", action: addItem)
• HIG: Gradients on symbols (SF Symbols 7+), Draw On/Off animations, Magic Replace

Implementation Rules

Beautiful AND correct — these are non-negotiable:

1. Extract views into separate View structs in their own files — never computed properties returning some View
2. Button actions go in methods, not inline closures
3. @Observable for shared state (not ObservableObject), marked @MainActor
4. @State must be private, owned by the creating view
5. NavigationStack with navigationDestination(for:) — never NavigationView
6. Minimum 44×44pt tap targets — Apple's strict minimum (HIG)
7. task() over onAppear() for async work (auto-cancels on disappear)
8. Ternary for toggling modifier values — preserves structural identity, avoids _ConditionalContent
9. LazyVStack/LazyHStack in ScrollView for large data sets
10. #Preview — never PreviewProvider
11. async/await — never DispatchQueue
12. Each type in its own Swift file

REQUIRED: For full API correctness validation after implementation, use swiftui-pro.

Anti-Patterns — The "AI Slop" Checklist

NEVER produce SwiftUI that looks like every other AI-generated app:

AI Slop	Instead
Default system font with no hierarchy	Intentional typography with clear display/body pairing
Blue accent on white background	Committed palette with dominant + accent strategy
List with default styling for everything	Custom layouts with intentional spacing and composition
Identical padding/spacing everywhere	Varied rhythm — tight grouping + generous breathing room
No animations or only .default	Spring animations, staggered reveals, symbol effects
Gray placeholder backgrounds	Materials, gradients, mesh gradients, Canvas drawings
Uniform corner radii	Varied radii — larger containers, tighter chips/badges
No haptic feedback	sensoryFeedback() on key interactions
Every screen looks the same	Each screen has character appropriate to its content
Overused purple gradients	Context-specific color stories

Quick Reference — Design Tokens Pattern

enum Design {
    enum Spacing {
        static let xs: CGFloat = 4
        static let sm: CGFloat = 8
        static let md: CGFloat = 16
        static let lg: CGFloat = 24
        static let xl: CGFloat = 32
        static let xxl: CGFloat = 48
    }

    enum Corner {
        static let sm: CGFloat = 8
        static let md: CGFloat = 12
        static let lg: CGFloat = 20
        static let pill: CGFloat = .infinity
    }

    enum Palette {
        static let accent = Color("AccentPrimary")
        static let surface = Color("Surface")
        static let surfaceElevated = Color("SurfaceElevated")
    }
}

Customize this for each project's aesthetic. Never reuse identical tokens across different apps — each app deserves its own design language.

Common Mistakes

Mistake	Fix
GeometryReader for responsive layout	containerRelativeFrame() or visualEffect()
foregroundColor()	foregroundStyle()
cornerRadius() modifier	clipShape(.rect(cornerRadius:))
Stored DateFormatter properties	Text(date, format: .dateTime.day().month())
NavigationView	NavigationStack or NavigationSplitView
@StateObject / @ObservedObject	@State with @Observable classes
Icon-only buttons	Button("Label", systemImage: "icon", action: tap)
animation() without value	.animation(.spring, value: isExpanded)
Manual animatableData	@Animatable macro
DispatchQueue.main.async	@MainActor / Task / async/await
onTapGesture() for buttons	Button (accessible by default)
Binding(get:set:) in body	@State binding + onChange()
overlay(Text("x"))	overlay { Text("x") }
String(format: "%.2f")	Text(value, format: .number.precision(...))
Liquid Glass in content layer	Liquid Glass for controls/navigation only
Ignoring Reduce Motion	Always provide opacity crossfade fallback

References

• references/hig-typography.md — Text sizes, Dynamic Type scales, font specs per platform
• references/hig-color.md — System colors, dark mode, Liquid Glass color, contrast requirements
• references/hig-layout.md — Safe areas, device dimensions, size classes, grid specs
• references/hig-materials.md — Liquid Glass variants, standard materials, vibrancy levels
• references/hig-motion.md — Animation principles, Reduce Motion, visionOS motion comfort
• references/hig-icons.md — App icon specs, SF Symbols rendering/animations, standard symbols
• references/hig-components.md — Component categories, modality rules, search patterns
• data/apple-hig-compact.json — Quick-lookup tips/notes from 45 HIG articles
• data/apple-hig-index.json — Full 134-article index for deep lookups

Remember: Claude is capable of extraordinary creative work in SwiftUI. Don't produce another generic app — commit to a vision and execute with precision. Show what's possible when design intentionality meets SwiftUI's full rendering power.