SPB Git

Repository Public

UI_CONVENTIONS.md 4.7 KB

# 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 = amber Color.accentColor); see Components/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 an extension AppModel in your own file following the same pattern (store call, then syncNow()).
  • 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 with type == "database" rows the app cannot edit only where stated; SmartList gives 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).

Files main
Menu

Theme