app-spec

App Spec

Produce the two documents that govern your entire build. This still happens in Claude chat.

When to Use

• You've completed the app-vision skill
• You're ready to create the project repo
• You need a CLAUDE.md and app spec before touching Claude Code

Document 1: CLAUDE.md

This file lives in the root of your repo. Claude Code reads it automatically at the start of every session. It contains rules, not descriptions.

Required Sections

# [App Name] - Development Rules

## Core Principles
- Use native SwiftUI components exclusively unless explicitly told to build custom
- Target iOS [version]
- Follow Apple HIG for all spacing, typography, layout, and interaction patterns
- Use SF Symbols for all icons unless a custom asset is specified
- Use system fonts unless a specific typeface is called out

## Navigation
- [Tab-based / Single stack / Other] navigation pattern
- List every navigation path: what presents what, and how (push, sheet, menu)
- Define presentation rules:
  - Sheets for: [creation, editing, multi-step flows]
  - Menus for: [action lists, quick selections]
  - Pickers for: [constrained value selection]
  - Context menus for: [long-press actions on list items]

## Architecture
- SwiftUI + [SwiftData / Core Data / UserDefaults] for persistence
- [MVVM / other] pattern
- File structure conventions:
  - /Components for shared components
  - /Models for data models
  - /Views/[Feature] for feature-specific views

## Color and Theming
- Primary tint: [hex or semantic description]
- Support light and dark mode from day one
- Use semantic colors (Color.primary, Color.secondary) for text
- [Liquid Glass / Material / other] treatment for system chrome

## Custom Components (the exceptions)
- List ONLY the components that cannot be built with native SwiftUI
- Each one gets a name and a one-line description of what it does
- These will be specced in detail during the build phase

## What NOT to Do
- Do not wrap native components in custom abstractions
- Do not use UIKit unless SwiftUI has no equivalent
- Do not create custom navigation transitions unless specified
- Do not add animations beyond SwiftUI defaults unless specified
- Do not hardcode strings