Repository Public License
1<!--2ORIX OS Automation3File: docs/architecture/ui-contracts.md4Author: Simon-Pierre Boucher5Contact: contact@spboucher.ai6-->7# UI feature contracts89Binding for everyone writing a feature package. Read `docs/architecture/module-contracts.md` "Ground rules" first10(headers, Swift 6, no third-party code, never `pkill -f`, never commit, stay inside your package). The product brief is11`CLAUDE.md` at the repository root: §4 (design system and sections) and the sections for your feature.12`~/Desktop/Cluster/apple/CLAUDE.md` (KHAELOR) is unrelated — ignore it.1314## Shape1516- One Swift package per feature group under `Packages/ORIXFeature<Name>/`, depending **only** on `../ORIXAppUI`17 (`import ORIXAppUI` re-exports Core, Services, AgentRuntime, WorkflowEngine, Scheduler, Skills, Persistence,18 Security, AppleAutomation, ProviderAdapters, ToolRegistry). `platforms: [.macOS(.v15)]`, Swift 6 mode,19 `defaultLocalization: "en"`.20- Read before writing: every file in `Packages/ORIXAppUI/Sources/ORIXAppUI/` (design tokens, components, `AppModel`,21 approval/plan/question cards, `RunEventList`, `ShotRenderer`, `PreviewEnvironment`) and22 `Packages/ORIXServices/Sources/ORIXServices/*.swift` (what the UI may call: `ORIXServices`, `RunManager`,23 `WorkflowService`, `ProviderHub`, `ApprovalCenter`, `InteractionCenter`, store adapters, `AppSettings`).24 Do not edit those packages; list what you needed and did not find under "Contract requests" in your report.25- Each package exposes public root views that take no arguments beyond what is listed for it, read26 `@Environment(AppModel.self) private var model`, and reload their data with `.task(id: model.revision)` (the27 revision ticks on every store change, from this process or the background agent).28- A product `orix-preview-<name>` (executable target) renders every screen of the package with29 `ShotRenderer.render(view.environment(model), size:, dark:, to:)` on a `PreviewEnvironment.make()` model:30 `swift run orix-preview-<name> --shot <dir>` writes `<screen>-dark.png` and `<screen>-light.png`. **Open your own31 PNGs with the Read tool and iterate until the screens are genuinely good**: aligned, readable in both appearances,32 no clipped text, no empty boxes. An executable needs `_ = NSApplication.shared` and a main run loop33 (`Task { …; exit(0) }; RunLoop.main.run()`).3435## Rules for every screen3637- **Real state only.** Every number, list and status comes from services. No placeholder rows, no hardcoded38 metrics. Nothing to show → `EmptyState` with one sentence and, where it makes sense, the action that fixes it.39- **Every control works.** A button that says run, save, stop, retry, export, delete, enable does exactly that40 through services, shows progress while it runs, and reports failure with `model.report(error)` or an inline41 `Banner`. If a capability does not exist in services, do not draw the control; put it under "Not built" in your report.42- Destructive actions ask for confirmation (`confirmationDialog`) and say what will be lost.43- Design: use `Theme` tokens and the shared components; SF Symbols; restrained violet/blue accent; generous spacing;44 no gradients beyond the accent; no emoji. Dark and light must both look intentional. Compact window target45 1100×700, large 1600×1000: use `ViewThatFits`/adaptive grids, never a fixed width that clips.46- Motion: `Theme.spring(reduceMotion)`; nothing loops except `PulseDot` on live items.47- Accessibility: every icon-only button has `.accessibilityLabel`; meaningful groups are combined; status is never48 colour alone (use `StatusBadge`); every interactive element reachable by keyboard; add49 `.accessibilityIdentifier("<section>.<element>")` on the main controls (UI tests use them).50- Text: English in code through `LocalizedStringKey` / `String(localized:)`. Plain words, sentence case, no jargon51 about internals. Also write `Packages/<YourPackage>/Localization/fr.json`: a flat JSON object mapping every52 user-facing English string of your package (exactly as written in code, including `%@`/`%lld` placeholders for53 interpolations) to its French (Canada) translation. The lead merges these into the app's string catalog.54- Lists that can grow (runs, events, logs, files) are virtualised (`List`/`LazyVStack`) and paginated from the store.55- Known SwiftUI traps on this macOS: `.inspector` + `Table` inside `NavigationSplitView` in a narrow window can abort56 the app (use an `HSplitView`/side panel); animating Swift Charts on every sample is expensive; `ViewThatFits` picks57 the vertical layout when a child has long `fixedSize` text.58- Tests (Swift Testing): logic in view models is unit-tested against a `PreviewEnvironment` model (real services on59 a temp folder); one render test per screen asserts a non-trivial PNG. No test may need user interaction.6061## Report6263Public views and their initialisers, what each control does, screenshots written (paths), test counts,64"Not built" (anything in the brief for your section that you did not implement, with the reason), contract requests.65