view-specifications

How to Write a View Spec

This guide teaches Claude how to write specification documents for SwiftUI views. Use this alongside the template section below as your reference.

Key Concepts

View Principles

1. Composed from views — Views arrange reusable child views with appropriate spacing
2. Callback navigation — Views receive closures (onDismiss, onSelectItem); they don't know where to navigate
3. Data independent — Views accept only primitive inputs (IDs, strings, values) and derive display data themselves. A view should never require its caller's data model.
4. Layout-aware — Every view provides portrait and landscape layouts where appropriate
5. Animation coordination — Views assign animation offsets to each element
6. Platform-agnostic requirements — All sections above Implementation Reference describe WHAT to build using prose, tables, and diagrams. Platform-specific code (Swift, Kotlin, etc.) belongs exclusively in Implementation Reference

View Scope: What to Think About vs. Trust the System

View specs should focus thinking on view-level concerns and trust other systems for everything else.

Requirements vs. implementation details: Specs capture what the view must do (requirements from the wireframe) — not how the code achieves it. If the wireframe says "scrolling text should not receive a visual effect," the spec states that requirement in the Notes section. It does not prescribe the layering approach, modifier chain, or rendering technique. The implementor decides the approach.

Platform-Agnostic Vocabulary

Instead of...	Write...
VStack / HStack	"vertical stack" / "horizontal stack"
ScrollView	"scrollable area"
struct MyView: View { let x: Type }	Interface table (see Section 10)
@State private var x: Type	View State table (see Section 10)
ForEach(items) { ... }	"For each item in the collection"
.cancellationAction / .bottomBar	"top-left" / "bottom bar"
Content VStack / Left VStack	"Content column" / "Left column"