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