Repository Public
1<!--2SP Notes iOS3File: docs/UI_CONVENTIONS.md4Author: Simon-Pierre Boucher5Contact: contact@spboucher.ai6-->7# Conventions for everyone writing screens of SP Notes iOS89Product: a premium, sober, truly native notes app (think Apple Notes' simplicity with a richer editor). iPhone first (one-handed use),10real iPad layout. The app is **offline first**: every screen reads the local database and every action is written locally at once;11nothing in the interface waits for the network, and nothing may be presented as done when it is not.1213## Hard rules14- Swift 6 strict concurrency, SwiftUI (UIKit where needed), iOS 18 deployment target. **No web view of any kind** (no WKWebView, no15 SFSafariViewController); external links open with `UIApplication.shared.open`.16- Every file starts with the header: `// SP Notes iOS` / `// File: <relative path>` / `// Description: …` / `//` /17 `// Author: Simon-Pierre Boucher` / `// Contact: contact@spboucher.ai`. Code and comments in English.18- User-facing text in **French** (source language), written as SwiftUI literals / `String(localized:)`. Informal "tu", sentence case,19 typographic apostrophe ’. The note title shown for the server's "Untitled" is « Sans titre » (`AppModel.displayTitle`).20- Colours by asset name (`Color.spBackground`, `.spSurface`, `.spSurface2`, `.spBorder`, `.spText`, `.spTextSecondary`, `.spMuted`,21 `.spDanger`, `.spSuccess`, `.spWarning`, accent = amber `Color.accentColor`); see `Components/Theme.swift` (`EmptyStateView`,22 `PrimaryButtonStyle`, `BrandMark`, `Haptics`, `Date.listLabel`). System materials and SF Symbols; no custom fonts.23- Accessibility: Dynamic Type everywhere (no fixed heights around text), hit targets ≥ 44 pt, VoiceOver labels on icon-only controls,24 state not conveyed by colour alone, Reduce Motion respected. `accessibilityIdentifier` (kebab-case) on the controls UI tests need.25- Works in light and dark, portrait and landscape, iPhone and iPad (including Split View widths and Stage Manager resizing).26- Do not edit files you do not own. Shared files: `App/AppModel.swift`, `Components/Theme.swift`, `Editor/*`, `Core/*`, `project.yml`,27 `Resources/*` — ask (in your final report) instead of changing them. Add small helpers in your own files.2829## Data access30- `@Environment(AppModel.self) private var app`. Read with the store (an actor): `try await app.store.summaries(list: .recent)`,31 `children(of:)`, `folderTree()`, `tags()`, `counts()`, `search(query:filters:)`, `page(id:)`, `conflicts()`, `localVersions(pageId:)` …32 (full list and semantics: `../SPNotesCore/docs/STORE_API.md`). Reload when the database changes:33 `.task(id: app.revision) { … }` (cheap queries; summaries never load note content).34- Write only through `AppModel` (`createNote`, `save`, `rename`, `setPinned`, `setFavorite`, `setArchived`, `setTags`, `move`, `trash`,35 `restore`, `purge`, `duplicate`, `fileInboxItem`, `attach…`, `deleteAttachment`): it schedules the synchronisation and updates the36 widgets. If an operation you need is missing, write it in an `extension AppModel` in your own file following the same pattern37 (store call, then `syncNow()`).38- Notes model: a note = a page. Folder = a page with `isFolder` (children = notes inside). Sections: `notes`, `documents`,39 `projects`, `research` (+ `databases`, read-only here). Favourite ≠ pinned. Lists must hide pages with `type == "database"` rows the40 app cannot edit only where stated; `SmartList` gives all / recent / pinned / favorites / inbox / archived / trash.41- Sync state: `app.syncStatus` (`phase`, `pending`, `conflicts`, `needsReauth`, `lastSuccess`), `app.network.isOnline`,42 `app.session` (`signedOut` → welcome; `signedIn`; `expired` → the app keeps working locally and offers to sign in again).43- Navigation requests from outside (widgets, Siri, notifications, mentions): `app.pendingRoute` (`.note(id)`, `.newNote`, `.search(q)`).4445## Build and test (use your own derived-data path; several people build at the same time)46 Scripts/build.sh generate # after adding files (xcodegen)47 xcodebuild -project SPNotes.xcodeproj -scheme SPNotes -configuration Debug -destination "platform=iOS Simulator,name=iPhone 17 Pro" -derivedDataPath build/DD-<you> build 2>&1 | grep -E "error|BUILD" | sort -u | head -4048A compile error in a file that is not yours is someone's work in progress: wait a minute and retry; never "fix" it.49Debug environment variables (launch arguments of UI tests): `SPNOTES_STORE=memory` (throw-away database), `SPNOTES_SESSION=local`50(use the app without a server), `SPNOTES_SEED=1` (sample notes from `App/SampleData.swift`), `SPNOTES_BASE_URL` + `SPNOTES_TOKEN`51(development server through `ssh -N -L 8482:localhost:8482 M4M64c`; never production).52