@horka/app-forge 0.1.0

package/templates/packs/swift-ios/docs-architecture/CONVENTIONS.md

@@ -0,0 +1,246 @@
+# CONVENTIONS — SwiftUI Architecture & Swift 6.2 Concurrency
+
+Conventions for {{PROJECT_NAME}} (Swift 6.2, iOS 26, strict concurrency). Prescriptive — follow as written.
+
+## 1. Architecture: VVM-I (View + ViewModel + Interactor + Translate)
+
+Every **screen** lives in `App/<Screen>/`, split into up to 4 files:
+
+| File | Type | Role |
+|---|---|---|
+| `App<Screen>.swift` | `struct ... : View` | Layout only. Reads state, delegates to Interactor. |
+| `App<Screen>ViewModel.swift` | `@Observable final class` | UI state only (nav path, selection, sheet flags). No domain logic, no IO. |
+| `App<Screen>Interactor.swift` | `struct` | Actions + derived data. The ONLY layer that talks to Stores/services. |
+| `App<Screen>+Translate.swift` | `nonisolated enum` | User-facing strings + pure formatting. No state. |
+
+```swift
+// App/Feed/AppFeed.swift
+extension App {
+    struct Feed: View {
+        @Environment(ItemStore.self) private var store
+        @State private var viewModel = ViewModel()
+        private var interactor: Interactor { Interactor(store: store, viewModel: viewModel) }
+    }
+}
+
+extension App.Feed {
+    var body: some View {
+        NavigationStack(path: $viewModel.path) {
+            // sections read interactor.<derived>, call interactor.<action>()
+        }
+        .navigationTitle(Translate.title)
+        .navigationDestination(for: ItemGroup.self) { App.GroupDetail(group: $0) }
+    }
+}
+
+// App/Feed/AppFeedViewModel.swift
+extension App.Feed {
+    @Observable final class ViewModel {
+        var path: [ItemGroup] = []    // this tab's nav stack — pushed by the Interactor
+        var selectedBadgeID: String?  // drives an anchored popover
+    }
+}
+
+// App/Feed/AppFeedInteractor.swift
+extension App.Feed {
+    struct Interactor {
+        let store: ItemStore
+        let viewModel: ViewModel
+        var invitations: [ItemGroup] { store.pendingInvitations }              // derived data
+        func openGroup(_ group: ItemGroup) { viewModel.path.append(group) }    // navigation
+        func accept(_ group: ItemGroup) async { await store.acceptInvitation(group) } // side effect
+    }
+}
+
+// App/Feed/AppFeed+Translate.swift
+extension App.Feed {
+    nonisolated enum Translate {
+        static let title = "Activity"
+        static func greeting(_ name: String) -> String { "Hi \(name)" }
+    }
+}
+```
+
+Rules:
+- Interactor is a **stateless struct**, recreated each render via a computed property. State lives in ViewModel (UI) or Store (domain) — never in the Interactor.
+- Navigation goes through the Interactor (`viewModel.path.append(...)`), never inline in `body`.
+- Each tab owns its `NavigationStack` + value-based `.navigationDestination(for:)`. No global path-based coordinator.
+- **When each part is optional:** pure-display bricks = View only. Screen with UI state but no store actions = View + ViewModel + Translate (skip Interactor). Translate exists as soon as a file has user-facing copy — never inline strings in `body`.
+
+Folder layout:
+- `App/` — screens (one folder per screen, VVM-I files).
+- `Module/` — reusable UI bricks (`Module/Map/`, `Module/Badge/`…): plain Views, closure-driven, store-free.
+- `Store/` — `@MainActor @Observable` domain facades.
+- `Packages/` — SPM: `Core` (pure domain, zero IO → `swift test` runs without a simulator), `DataLayer` (persistence/cloud), `{{PROJECT_NAME}}DS` (design system).
+
+## 2. Swift 6.2 strict concurrency
+
+- App target sets `SWIFT_DEFAULT_ACTOR_ISOLATION = MainActor` — everything is MainActor unless marked otherwise. UI packages opt in with `.defaultIsolation(MainActor.self)` in `Package.swift`.
+- The pure domain package keeps **nonisolated** default + `.swiftLanguageMode(.v6)`. Engines are `enum`s of static pure functions:
+
+```swift
+// Core package — pure, nonisolated, deterministic, instantly testable
+public enum BadgeEngine {
+    public static func satisfiedIDs(profile: Profile, items: [Item],
+                                    calendar: Calendar = .current) -> Set<String> {
+        var ids = Set<BadgeID>()              // typed ID enum: a typo is a compile error
+        if items.count >= 1 { ids.insert(.first) }
+        // … all rules are pure functions of (profile, items, calendar) — injected Calendar
+        return Set(ids.map(\.rawValue))       // convert to stored String slugs at the boundary
+    }
+}
+```
+
+- `async/await` everywhere. **No completion handlers.** Framework delegate callbacks (e.g. `CLLocationManagerDelegate`) are `nonisolated`; hop back to the main actor explicitly to publish state.
+- **Never `@unchecked Sendable`.** `nonisolated(unsafe)` is tolerated only in tests, with a comment explaining exactly which sending check it silences and why it is safe.
+- View-lifetime async work: `.task { await store.bootstrap() }` and `.task(id:)` — auto-cancelled on disappear. Fire-and-forget from a tap: `Button { Task { await interactor.accept(group) } }`. Parallel fan-out: `withTaskGroup` / `async let`. No detached tasks.
+- Mark `Translate` enums `nonisolated` explicitly: under MainActor default isolation they would otherwise be actor-isolated, blocking use from nonisolated formatting/background code.
+
+## 3. The Store: `@MainActor @Observable` domain facade
+
+```swift
+@MainActor @Observable
+final class ItemStore {
+    private(set) var items: [Item] = []      // ALL read state is private(set)
+    private(set) var isReady = false
+    var lastError: String?                   // user-facing; one alert binds to it
+    private var service: ItemService?
+
+    func bootstrap() async {
+        guard service == nil else { return } // idempotent — .task can re-fire
+        // pick cloud backend if account available, else in-memory seeded with sample data
+    }
+
+    @discardableResult
+    func addItem(_ draft: ItemDraft) async -> Bool {
+        guard let service else { lastError = "Service unavailable."; return false }
+        lastError = nil                      // start the action clean
+        do { _ = try await service.add(draft); await refresh(); return true }
+        catch {
+            log.error("addItem failed: \(error, privacy: .public)")
+            lastError = "Couldn't save. Try again."
+            return false
+        }
+    }
+}
+
+extension ItemStore {
+    static func preview() -> ItemStore { /* seeded with SampleData for #Preview */ }
+}
+```
+
+Rules: mutations only through async funcs; every catch logs the operation name + maps to a human `lastError`; write actions return `Bool` so sheets dismiss **only when the write landed**; always provide a `static preview()` factory; in-memory backend doubles as offline/demo mode and is forced by a launch argument in UI tests.
+
+> ⚠️ **Gotcha:** alert shows a stale error from a *previous* action. Cause: `lastError` survives across actions. Fix: reset `lastError = nil` as the first line of every store action.
+
+> ⚠️ **Gotcha:** spinner never ends when the first load fails. Cause: `isReady` only set on success. Fix: set `isReady = true` in the catch too — surface an empty state + error, never spin forever.
+
+> ⚠️ **Gotcha:** UI tests hang on a cold simulator. Cause: the cloud account-status probe stalls the first load. Fix: check `ProcessInfo.processInfo.arguments.contains("-uitest-mock")` in `bootstrap()` and wire the in-memory backend — deterministic and instant.
+
+> ⚠️ **Gotcha:** first cloud sync fires a local notification for every pre-existing remote item. Cause: "new since last refresh" has no baseline. Fix: on first load, just seed the persisted "seen IDs" set without notifying; only diff against it on subsequent refreshes.
+
+## 4. Namespacing by extension scoping
+
+Scope feature views inside the domain type they render; scope screens inside `App`:
+
+```swift
+extension Item      { struct DetailCard: View { … } }  // call site: Item.DetailCard(item:)
+extension ItemGroup { struct InviteCard: View { … } }  // call site: ItemGroup.InviteCard(group:…)
+extension App       { struct Feed: View { … } }        // call site: App.Feed()
+```
+
+> ⚠️ **Gotcha:** the `App` namespace collides with the `SwiftUI.App` protocol. Two rules make it
+> safe: (1) declare the namespace once — `enum App {}` in `App/AppNamespace.swift` (the scaffold
+> ships it); (2) the @main entry point must be declared `struct {{PROJECT_NAME}}App: SwiftUI.App`
+> (fully qualified) or it won't compile.
+
+> ⚠️ **Gotcha:** a multi-statement `var body: some View` inside an `extension App.X` silently
+> loses the implicit `@ViewBuilder` in some configurations — annotate `@ViewBuilder var body`
+> explicitly in extension-scoped views, or keep `body` a single expression.
+
+- File name = call-site path without the dot: `ItemDetailCard.swift`, `AppFeed.swift`, `AppFeed+Translate.swift`. **One type per file.**
+- Why: free namespacing without submodules, no name clashes (`Item.DetailCard` vs `SharedItem.DetailCard` coexist), call sites read as domain language.
+- Shared/non-domain bricks (skeletons, rating controls, generic map) stay top-level structs in `Module/`.
+
+## 5. Closures as module boundaries
+
+Module bricks never import Stores. Parents inject actions as closures; the brick stays reusable and testable in isolation:
+
+```swift
+extension ItemGroup {
+    struct InviteCard: View {
+        let group: ItemGroup
+        // Side effect to know: a View storing closures can't be Equatable, so SwiftUI can't
+        // skip its body via the Equatable fast-path. The parent recreates these closures every
+        // render → this card re-renders with the parent. That's FINE: closures run on tap (not
+        // render), @State persists by position, no retain cycle (struct), no stale capture
+        // (value capture of `group`, reference to the store). Keep the design — it decouples
+        // the brick from the store. If a large list ever hurts: conform Equatable on group.id.
+        var onAccept: () -> Void
+        var onDecline: () -> Void
+    }
+}
+```
+
+- Use optional closures (`var onDelete: (() -> Void)? = nil`) when absence changes the UI (e.g. hide the delete button).
+- **Document the re-render side effect once** on a reference brick and point other bricks to it.
+
+Generic bricks take the same idea further — one component, callers inject types and views:
+
+```swift
+struct ItemMap<Item: Identifiable, Marker: View, Detail: View>: View where Item.ID == UUID {
+    @Binding var position: MapCameraPosition
+    let items: [Item]
+    let coordinate: (Item) -> Coordinate
+    var onCenterChange: ((Coordinate) -> Void)? = nil   // reported continuously on camera move
+    @ViewBuilder let marker: (Item) -> Marker
+    @ViewBuilder let detail: (Item) -> Detail           // shown in a popover ANCHORED to the marker
+    @State private var selectedID: UUID?
+}
+```
+
+One map brick serves the personal screen AND every group screen; each injects its own typed marker/detail. Detail UI is an anchored `.popover` + `.presentationCompactAdaptation(.popover)` — never a centered sheet. Don't re-stamp glass effects; iOS 26 applies them natively on nav/toolbar/sheet/popover.
+
+> ⚠️ **Gotcha:** after deleting an item, SwiftUI keeps re-creating the dead annotation on every camera change. Cause: the selection still points at the removed item, so the orphaned popover resurrects it. Fix: clear the selection when the item disappears:
+> ```swift
+> .onChange(of: items.map(\.id)) { _, ids in
+>     if let s = selectedID, !ids.contains(s) { selectedID = nil }
+> }
+> ```
+
+> ⚠️ **Gotcha:** delete-from-popover glitches (popover orphans mid-removal). Cause: the destructive closure removes the item while its anchored popover is still presented. Fix: `dismiss()` **first**, then call `onDelete?()`.
+
+> ⚠️ **Gotcha:** map stutters while panning. Cause: continuous camera callbacks recompute derived state (clustering) every frame. Fix: only refresh when zoom changes meaningfully (e.g. >5% span delta), not on every pan frame.
+
+## 6. Logging (OSLog)
+
+```swift
+import OSLog
+let log = Logger(subsystem: "{{BUNDLE_ID}}", category: "Store")
+log.notice("bootstrap: backend=\(label, privacy: .public) items=\(items.count)")
+```
+
+- One `Logger` per layer (`category: "Store"`, `"Sync"`, …). Every `catch` logs the failed operation by name.
+- Stream from a device: `log stream --device --predicate 'subsystem == "{{BUNDLE_ID}}"'` — put this command in a doc comment next to the Logger.
+
+> ⚠️ **Gotcha:** device logs show `<private>` instead of values. Cause: OSLog redacts interpolations by default. Fix: annotate non-sensitive debug values with `privacy: .public`. Never apply it to user content or tokens.
+
+## 7. Naming quick reference
+
+- Actions: verbs (`addItem`, `acceptInvitation`); derived data: nouns (`invitations`, `unlockedCount`).
+- Booleans read as assertions: `isReady`, `needsDisplayName`, `isArchived`.
+- Extension files: `TypeName+Role.swift` (`AppFeed+Translate.swift`).
+- Centralize magic values: design tokens in `DS.Padding/Radius/Size`, the app display name and container IDs in single constants.
+- Comments explain **why** (the decision, the side effect, the trap), never what the code already says.
+
+
+## One type per file — the sanctioned exception
+A repository **contract and its InMemory reference implementation may share one file**
+(`Repository/ItemRepository.swift`): they form one teaching unit and ship/replace together.
+Everything else stays one type per file. (Generated code violated the strict rule in every
+audited project — codifying the exception beats pretending.)
+
+> ⚠️ **Gotcha (previews):** Symptom — a preview renders empty while the app works. Cause — the
+> preview built TWO store instances (one injected into the view, a different one bootstrapped
+> with data). Fix — create ONE `Store.preview()` instance, seed it, and inject THAT everywhere
+> in the preview.

package/templates/packs/swift-ios/docs-architecture/DESIGN_SYSTEM.md

@@ -0,0 +1,272 @@
+# Design System Package — {{PROJECT_NAME}}DS
+
+All visual tokens (colors, fonts, spacing, radius, gradients, reusable chrome) live in a dedicated local SPM package: `Packages/{{PROJECT_NAME}}DS`. App code **never** hardcodes a color, font size, padding, or corner radius. If a view needs a visual value, it imports `{{PROJECT_NAME}}DS` and uses a token.
+
+## Why a package (not a folder in the app target)
+
+- **Enforced via imports.** A file that uses `Color.DS.accent` must `import {{PROJECT_NAME}}DS`. Raw values (`Color(red:...)`, `.padding(17)`, `.font(.system(size: 13))`) are instantly visible in review/lint — they are the *only* place numbers appear outside the package.
+- **Previewable standalone.** The package builds without the app. Components (`DSCard`, and any chrome you add) get previews inside the package; designers iterate without app build times.
+- **AI agents cannot "forget" it.** Agents grep the package for the token vocabulary; any raw value they emit stands out in the diff. Prescribe in CLAUDE.md: *"Visual values come from {{PROJECT_NAME}}DS tokens only."*
+- **Reusable.** The same `DS.*` API shape ports between projects; only token values change.
+
+## Package layout (what the skeleton actually ships)
+
+```
+Packages/{{PROJECT_NAME}}DS/
+├── Package.swift
+└── Sources/{{PROJECT_NAME}}DS/
+    ├── DS.swift              # namespace: Padding, Radius, Size, ratio, Gradients
+    ├── Color+DS.swift        # Color.DS.* palette
+    ├── DSFont.swift          # enum DS.Font type scale + .designSystem(font:) modifier
+    └── Components/
+        └── DSCard.swift      # starter card container (token-only, domain-blind)
+```
+
+That is the entire starter surface. The four token files plus `DSCard` are the contract every
+example below uses. Anything richer (an app-wide background, a glass card, semantic button styles)
+is something you **add at kickoff** — see "Components to add at kickoff" at the end. Do not reference
+an API the package doesn't ship yet; add the file first, then use it.
+
+```swift
+// Package.swift — matches the shipped skeleton (iOS 26 everywhere; app target and packages bump together)
+// swift-tools-version: 6.2
+import PackageDescription
+
+let package = Package(
+    name: "{{PROJECT_NAME}}DS",
+    platforms: [.iOS(.v26), .macOS(.v15)],
+    products: [.library(name: "{{PROJECT_NAME}}DS", targets: ["{{PROJECT_NAME}}DS"])],
+    targets: [
+        .target(
+            name: "{{PROJECT_NAME}}DS",
+            swiftSettings: [
+                .swiftLanguageMode(.v6),
+                .defaultIsolation(MainActor.self),
+            ]
+        ),
+    ]
+)
+```
+
+> ⚠️ **Gotcha:** Swift 6 strict concurrency rejects the token statics. Symptom: `Static property 'brand' is not concurrency-safe because non-'Sendable' type 'LinearGradient'…` on every gradient/color token. Cause: `static let` of non-Sendable SwiftUI types in a nonisolated namespace. Fix: set `.defaultIsolation(MainActor.self)` on the package target (tokens are UI-only anyway). If you later replace the shipped `enum DS.Font` with a value-carrying `struct` that must cross isolation, mark it `Sendable` then.
+
+Add to the app as a **local package reference** (`Packages/{{PROJECT_NAME}}DS` relative path) and link the library product to the app target.
+
+## Starter token set
+
+### Namespace + layout tokens — `DS.swift`
+
+```swift
+import SwiftUI
+
+public enum DS {
+    /// Responsive scaling hook. 1.0 for now; derive from screen class later.
+    public static let ratio: CGFloat = 1.0
+
+    public enum Padding {
+        public static let xs: CGFloat = 4 * DS.ratio
+        public static let s: CGFloat = 8 * DS.ratio
+        public static let m: CGFloat = 16 * DS.ratio
+        public static let l: CGFloat = 24 * DS.ratio
+        public static let xl: CGFloat = 40 * DS.ratio
+    }
+
+    public enum Radius {
+        public static let s: CGFloat = 10 * DS.ratio
+        public static let m: CGFloat = 16 * DS.ratio
+        public static let l: CGFloat = 24 * DS.ratio
+        public static let pill: CGFloat = 999
+    }
+
+    public enum Size {
+        public static let hairline: CGFloat = 1
+        public static let icon: CGFloat = 24 * DS.ratio
+    }
+
+    /// Signature gradients live in the DS namespace (NOT in the Color extension).
+    public enum Gradients {
+        public static let brand = LinearGradient(
+            colors: [Color.DS.accent, Color.DS.accentSecondary],
+            startPoint: .topLeading, endPoint: .bottomTrailing
+        )
+    }
+}
+```
+
+> ⚠️ **Gotcha:** `DS.ratio` is baked in at first static access (`static let`). Symptom: changing `ratio` at runtime does nothing. Cause: tokens are constants, not computed. Keep it as a build-time/launch-time knob; if you need live scaling, make tokens computed `static var` — accepting the perf cost — don't half-migrate.
+
+### Semantic colors — `Color+DS.swift`
+
+```swift
+import SwiftUI
+
+public extension Color {
+    enum DS {
+        // Brand
+        public static let accent = Color(red: 0.35, green: 0.45, blue: 1.00)
+        public static let accentSecondary = Color(red: 0.55, green: 0.30, blue: 0.95)
+        // Dark-first base: surfaces are white-alpha layered over the background
+        public static let background = Color(red: 0.039, green: 0.039, blue: 0.059)
+        public static let surface = Color.white.opacity(0.06)
+        public static let surfaceStrong = Color.white.opacity(0.10)
+        public static let stroke = Color.white.opacity(0.12)
+        public static let textPrimary = Color.white
+        public static let textSecondary = Color.white.opacity(0.6)
+        public static let textTertiary = Color.white.opacity(0.4)
+        // Status
+        public static let success = Color(red: 0.20, green: 0.85, blue: 0.45)
+        public static let danger = Color(red: 1.00, green: 0.27, blue: 0.36)
+    }
+}
+```
+
+Gradients (`DS.Gradients.brand`) live in `DS.swift` (shown above), not in this file — the Color
+extension holds only flat colors.
+
+> ⚠️ **Gotcha:** `Color.DS` shadows the top-level `DS` namespace inside `extension Color`. Symptom: `DS.ratio` / `DS.Padding` "not found" or resolves to the wrong type in that file. Cause: Swift name lookup prefers the nested `Color.DS`. Fix: qualify with the module name (`{{PROJECT_NAME}}DS.DS.ratio`) inside `Color+DS.swift`, or keep raw values local to that file (it's the one file allowed to contain them).
+
+> ⚠️ **Gotcha:** Opacity-based surfaces stack. Symptom: a card nested inside another card is visibly lighter than the spec. Cause: `white.opacity(0.06)` over `white.opacity(0.06)` compounds. Fix: never nest `surface` in `surface`; inner emphasis uses `surfaceStrong` deliberately, or restructure the layout.
+
+### Type scale + modifier — `DSFont.swift`
+
+The skeleton ships `DS.Font` as a **case enum** mapping each role to a system font — call sites read
+`.designSystem(font: .h3)`. (A value-carrying `struct` with `size`/`weight`/`design` is a valid V2
+upgrade if you bundle a custom font; until then the enum is the shipped, simpler shape — extend it,
+don't swap it just to match older prose.)
+
+```swift
+import SwiftUI
+
+public extension DS {
+    /// Typography scale. Use through `.designSystem(font:)` — never `.font(.system(...))` in app code.
+    enum Font {
+        case largeTitle, title, h2, h3, body, callout, caption, button, mono
+
+        var font: SwiftUI.Font {
+            switch self {
+            case .largeTitle: .system(size: 34, weight: .bold)
+            case .title:      .system(size: 28, weight: .bold)
+            case .h2:         .system(size: 22, weight: .semibold)
+            case .h3:         .system(size: 17, weight: .semibold)
+            case .body:       .system(size: 17)
+            case .callout:    .system(size: 15)
+            case .caption:    .system(size: 12)
+            case .button:     .system(size: 17, weight: .semibold)
+            case .mono:       .system(size: 15, design: .monospaced)
+            }
+        }
+    }
+}
+
+public extension View {
+    func designSystem(font: DS.Font) -> some View { self.font(font.font) }
+}
+```
+
+> ⚠️ **Gotcha:** `DS.Font` shadows `SwiftUI.Font` inside the `DS` extension. Symptom: `'Font' has no member 'system'` / circular reference errors. Cause: unqualified `Font` resolves to the enum being defined. Fix: the mapping property's return type is written `SwiftUI.Font` (fully qualified) inside `DSFont.swift`; do the same for any `SwiftUI.Font.Weight` / `.Design` you reference.
+
+### Components (chrome, not features)
+
+The `Components/` folder owns visual chrome reused everywhere — kept feature-agnostic (no domain
+types, no networking). **The skeleton ships exactly one: `DSCard`.**
+
+```swift
+// Components/DSCard.swift — the one component that ships
+public struct DSCard<Content: View>: View {
+    private let content: Content
+    public init(@ViewBuilder content: () -> Content) { self.content = content() }
+
+    public var body: some View {
+        content
+            .padding(DS.Padding.m)
+            .frame(maxWidth: .infinity, alignment: .leading)
+            .background(Color.DS.surface, in: RoundedRectangle(cornerRadius: DS.Radius.m))
+            .overlay(
+                RoundedRectangle(cornerRadius: DS.Radius.m)
+                    .stroke(Color.DS.stroke, lineWidth: DS.Size.hairline)
+            )
+    }
+}
+```
+
+Call site: `DSCard { Text("Hello").designSystem(font: .body) }`.
+
+### Components to add at kickoff (NOT shipped — build them when a slice needs them)
+
+These are the usual next bricks. They do **not** exist in the skeleton — add the file, then use the
+API. Don't call any of them before you've written it (the compiler will tell you, but the doc won't
+pretend they're there):
+
+- **`DSBackground` + `.dsBackground()`** — `ZStack { Color.DS.background; radial accent glows }.ignoresSafeArea()`,
+  exposed as a `.dsBackground()` modifier that wraps content in a `ZStack` (background behind, content
+  stays in safe area). Gotcha to anticipate: applying it via plain `.background(DSBackground())` clips
+  the glows to the view's bounds — wrap in a `ZStack` and let `DSBackground` call `.ignoresSafeArea()`
+  so consumers never manage safe areas for the backdrop.
+- **`GlassCard { … }`** — a heavier card than `DSCard`: `surface` fill, `Radius.l` continuous corners,
+  `stroke` hairline border, optional iOS 26 glass effect.
+- **Semantic button styles** — `DSPrimaryButtonStyle` / `DSSecondaryButtonStyle`, exposed via
+  `static var dsPrimary` / `dsSecondary` on `ButtonStyle` so call sites read `.buttonStyle(.dsPrimary)`.
+
+Add each as its own file under `Components/`, token-only, with a `#Preview`. Once it exists it's a
+first-class part of the vocabulary above.
+
+## Dark-first design
+
+The app is dark-first: `background` is near-black, text is white-alpha, surfaces are white-alpha overlays. Tokens are *semantic* (`textSecondary`, `surfaceStrong`, `stroke`) — never named after raw values (`white60`, `gray2`). Call sites express intent; a future light theme means editing one file.
+
+> ⚠️ **Gotcha:** Dark palette without dark scheme. Symptom: sheets, alerts, and keyboards render system-light — white sheet, white `textPrimary` text = invisible content. Cause: hardcoded dark tokens don't switch UIKit-managed chrome. Fix: set `.preferredColorScheme(.dark)` at the app root so system chrome matches the palette.
+
+## Usage style (consumer)
+
+```swift
+import SwiftUI
+import {{PROJECT_NAME}}DS
+
+struct ItemDetailCard: View {
+    let item: Item
+
+    var body: some View {
+        VStack(alignment: .leading, spacing: DS.Padding.m) {
+            HStack(spacing: DS.Padding.m) {
+                Image(systemName: item.icon)
+                    .foregroundStyle(AnyShapeStyle(DS.Gradients.brand))
+                    .background(Color.DS.surfaceStrong, in: Circle())
+                Text(item.name)
+                    .designSystem(font: .h3)
+                    .foregroundStyle(Color.DS.textPrimary)
+            }
+            Text(item.detail)
+                .designSystem(font: .body)
+                .foregroundStyle(Color.DS.textSecondary)
+            Divider().overlay(Color.DS.stroke)
+            Label(item.status, systemImage: "checkmark.seal.fill")
+                .designSystem(font: .callout)
+                .foregroundStyle(Color.DS.success)
+        }
+        .padding(DS.Padding.l)
+        .clipShape(RoundedRectangle(cornerRadius: DS.Radius.m, style: .continuous))
+    }
+}
+```
+
+Note the pattern: `.designSystem(font:)` sets typography only; color is always a separate `.foregroundStyle(Color.DS.*)`. Mixing a gradient and a color in one conditional requires `AnyShapeStyle(...)` on both branches.
+
+## How to add a token
+
+1. **Check it doesn't exist** — grep `Sources/{{PROJECT_NAME}}DS/` first. Prefer reusing a semantic token over adding a near-duplicate.
+2. Add the `static let` in the right file (`Color+DS.swift`, `DS.swift`, or `DSFont.swift`) with a **semantic name** (what it's *for*, not what it *looks like*).
+3. Multiply layout values by `DS.ratio`.
+4. Use it from the app via the token only. Never copy the raw value to a call site "just this once".
+
+## Rules (for humans and AI agents)
+
+- Do use `DS.Padding.*`, `DS.Radius.*`, `Color.DS.*`, `DS.Gradients.*`, `.designSystem(font:)` for every visual value. Never `.padding(12)`, `Color(red:...)`, `.font(.system(...))` in app code — raw values belong only inside the DS package.
+- Do put reusable visual chrome (cards, backgrounds, button styles) in `Components/`. Never put feature logic, models, or networking in the DS package — it stays dependency-free.
+- Corner shapes: always `RoundedRectangle(cornerRadius: DS.Radius.*, style: .continuous)`.
+- Hairlines: `DS.Size.hairline` with `strokeBorder(Color.DS.stroke, ...)`.
+
+
+> Note — this doc describes ONLY what `Packages/{{PROJECT_NAME}}DS/Sources/{{PROJECT_NAME}}DS/`
+> actually ships (the four token files + `Components/DSCard.swift`). Everything under "Components to
+> add at kickoff" is a future addition, not an existing API. If code and doc ever disagree, THE
+> SCAFFOLD FILES ARE THE TRUTH — extend them rather than rewriting them to match prose.