Feature Directory Structure

Features with many files must use nested subdirectories. Flat is fine up to a point; past that, subfolders are required.

The Rule

Flat — up to 5 files total per feature

When a feature has 5 or fewer files, keep it flat:

Features/Profile/
  ProfileView.swift
  ProfileViewModel.swift
  ProfileView+Header.swift

Three files, still scannable. No need for subfolders.

Nested — 6+ files per feature

Past ~5 files, group into subfolders by role:

Features/Home/
  HomeView.swift          ← main shell (body is table of contents)
  HomeViewModel.swift     ← one @Observable class
  Sections/               ← extracted body sections (View+X.swift)
    HomeView+Idle.swift
    HomeView+Recording.swift
    HomeView+Result.swift
  Sheets/                 ← .sheet / .fullScreenCover contents
    PillarDetailSheet.swift
    HistoryBrowseSheet.swift
  Overlays/               ← ZStack overlays, toasts, celebration
    CelebrationOverlay.swift
    StreakToastView.swift
  Backdrop/               ← ambient backgrounds, visual effects
    AmbientBackdrop.swift

The shell (HomeView.swift + HomeViewModel.swift) stays at the feature root. Everything else goes into a subfolder.

Canonical Subfolder Names

Use these names consistently across features. Don't invent new ones.

When NOT to split

Don't create a subfolder for a single file. Sheets/PillarDetailSheet.swift alone is fine only if you expect another sheet to land in v1.1 — otherwise keep it at the feature root until a second sheet forces the split.

Don't mirror the folder structure into the shell view's body. The body is a table of contents of section properties; subfolders are for the filesystem, not for SwiftUI hierarchy.

Rules

1. Only use subfolders when the feature has more than ~5 files. Below that, flat is more scannable.
2. The shell (View + ViewModel) stays at the feature root even in nested structures.
3. Use the canonical subfolder names above. Consistency across features matters more than any one naming preference.
4. One type per file still applies. Nesting doesn't dissolve that rule.
5. Features/Common/ is for cross-feature shared views. Feature-local reusable views go in Features/<Name>/Components/.
6. Hard line limit stays 200 lines per file, target 150. Subfolders don't change file-size rules — they solve folder browsability, not file size. If a single file is too big, split with View+Section.swift extensions inside Sections/.

Examples

Home feature (rich, nested)

Features/Home/
  HomeView.swift
  HomeViewModel.swift
  Sections/
    HomeView+Idle.swift
    HomeView+Recording.swift
    HomeView+Result.swift
  Sheets/
    PillarDetailSheet.swift

Onboarding feature (many steps → nested)

Features/Onboarding/
  OnboardingView.swift
  OnboardingViewModel.swift
  OnboardingTopBar.swift
  Steps/
    OnboardingWelcomeStep.swift
    OnboardingGoalStep.swift
    OnboardingPaywallStep.swift
    ... (more steps)

Steps/ is a valid subfolder name here — it's the canonical term for an onboarding flow's per-screen views. Prefer Steps/ over Sections/ for step-by-step flows.

Small feature (stays flat)

Features/AuthGate/
  AuthGateView.swift
  AuthGateViewModel.swift

Two files, no subfolders needed.

Why this matters

A Features/Home/ with 15 flat files named HomeView.swift, HomeView+Hero.swift, HomeView+TopBar.swift, HomeView+Challenge.swift, HomeView+Activity.swift, HomeCelebrationOverlay.swift, HomeAmbientBackdrop.swift, StreakToastView.swift, HomeViewModel.swift, HomeViewModel+Contracts.swift, HomeViewModel+Progression.swift forces the reader to parse filename prefixes to understand the structure. With nested folders, the structure is visible from the file tree alone — the reader opens Sections/ to see body sections and Overlays/ to see overlays without reading any code.