swift-front/SKILL.md

---
name: swift-front
description: 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:

```swift
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

```swift
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.