Repository Public License
1<!--2ORIX Secure3File: docs/design/design-system.md4Author: Simon-Pierre Boucher5Contact: contact@spboucher.ai6-->78# Design system910The design system has two layers:1112- `Packages/ORIXDesign` — tokens, reusable components and haptics shared by the ORIX apps. It knows nothing about13 findings.14- `App/Sources/Core/Presentation.swift` — the app-level components that give assessment states, severities and15 readings their appearance.1617Everything below is read from those files. Values are sRGB hex.1819## Tokens (`Packages/ORIXDesign/Sources/ORIXDesign/Tokens.swift`)2021### Palette2223Every colour is declared once with a light and a dark value (`Color(light:dark:)`) and resolves with the trait24collection, so no view chooses between light and dark itself.2526| Token (`ORIX.Palette`) | Light | Dark | Role |27|---|---|---|---|28| `canvas` | `#F4F5FA` | `#0A0D18` | app background behind grouped content |29| `surface` | `#FFFFFF` | `#141828` | cards and rows |30| `surfaceRaised` | `#EEF0F7` | `#1D2236` | nested surfaces, ring track, progress track |31| `hairline` | `#DDE0EA` | `#262C42` | 0.5 pt card borders |32| `textPrimary` | `#0E1222` | `#F2F4FB` | titles and values |33| `textSecondary` | `#596078` | `#A3AAC2` | labels and supporting text |34| `textTertiary` | `#8A90A6` | `#6F7690` | notes, chevrons, inactive states |35| `success` | `#12925A` | `#34D399` | verified |36| `warning` | `#B86A00` | `#FBBF24` | attention recommended |37| `danger` | `#D4313F` | `#FF6B76` | high-severity attention only; error banners |38| `info` | `#2563EB` | `#7AA5FF` | neutral information, "confirmed by you" |39| `onAccent` | `#FFFFFF` | `#FFFFFF` | text on the accent gradient |4041Accent (`ORIXAccent.secure`, injected with `.environment(\.orixAccent, .secure)` in `ORIXSecureApp.swift`):4243| | Light | Dark |44|---|---|---|45| `primary` — violet | `#7C3AED` | `#A78BFA` |46| `secondary` — mint "guard ring" | `#0E9F6E` | `#34D399` |47| `gradient` (primary buttons) | `#9F7AEA` → `#7C3AED` → `#5B21B6`, top-leading to bottom-trailing | same |4849One more colour is defined in `Presentation.swift`, for the "user confirmation required" state: `#8A93AE` light,50`#7A84A3` dark. The asset catalog carries `AccentColor` (`#7C3AED` / `#A78BFA`) and `LaunchBackground`51(`#F4F5FA` / `#0A0D18`), generated by `design/icon/build.py` with the same values.5253Contrast ratios have not been measured with a tool; that is an open item for an accessibility audit.5455### Spacing (`ORIX.Space`, 4-point scale)5657| `xxs` | `xs` | `sm` | `md` | `lg` | `xl` | `xxl` |58|---|---|---|---|---|---|---|59| 4 | 8 | 12 | 16 | 20 | 28 | 40 |6061### Radii (`ORIX.Radius`, continuous corners)6263| `chip` | `control` | `card` | `hero` |64|---|---|---|---|65| 10 | 14 | 20 | 28 |6667### Motion (`ORIX.Motion`)6869| Token | Definition | Use |70|---|---|---|71| `quick` | `snappy(duration: 0.22)` | pressed states of controls |72| `standard` | `smooth(duration: 0.35)` | layout changes, progress bar |73| `expressive` | `spring(response: 0.5, dampingFraction: 0.72)` | the summary ring |7475### Typography (`Font.orix…`)7677All styles are built on Dynamic Type text styles, so they scale with the user's text size. No font is bundled.7879| Token | Text style | Design | Weight |80|---|---|---|---|81| `orixDisplay` | `.largeTitle` | rounded | bold |82| `orixTitle` | `.title2` | rounded | semibold |83| `orixHeadline` | `.headline` | default | semibold |84| `orixBody` | `.body` | default | regular |85| `orixCallout` | `.callout` | default | regular |86| `orixCaption` | `.caption` | default | medium |87| `orixOverline` | `.caption2` | default | semibold (used uppercased for block titles) |88| `orixMono` | `.footnote` | monospaced | regular (hashes, evidence values) |8990### Other9192`ORIX.minimumTarget = 44` — the minimum touch target.9394## Components (`Packages/ORIXDesign/Sources/ORIXDesign/Components.swift`)9596| Component | What it is |97|---|---|98| `.orixCard(padding:)` | card surface: `surface` fill, `card` radius, 0.5 pt hairline border |99| `.orixLift()` | the single elevation: a soft shadow (black 14 %, radius 10, y 4). Everything else is flat. |100| `.orixPrimary` button style | accent gradient, white headline text, full width, minimum height 52 pt; 45 % opacity when disabled |101| `.orixSecondary` button style | accent text on a 12 % accent tint, full width, minimum height 48 pt |102| `.orixTile` button style | card-like tile, minimum height 84 pt |103| `ORIXGlyph` | SF Symbol on a tinted rounded square (default 36 pt), hidden from accessibility |104| `ORIXSectionHeader` | title in `orixTitle` with the header trait, optional trailing content |105| `ORIXChip` | capsule with optional symbol and text on a 12 % tint |106| `ORIXEmptyState` | symbol in a 96 pt circle, title, message, optional actions; content limited to 420 pt wide |107| `ORIXBanner` | inline message of kind `info`, `success`, `warning` or `error`: each kind has its own symbol and colour; children combined into one accessibility element |108| `ORIXProgressBar` | 6 pt determinate bar, primary → secondary gradient, exposes its value as a percentage to accessibility |109| `ORIXMark` | the ORIX Secure mark drawn in a `Canvas`: four arcs, guard ring, core (see [icon-design.md](icon-design.md)) |110111Haptics (`Haptics.swift`, `ORIXHaptics`): `tick` (selection), `success`, `warning`, `failure` (notification112feedback), `press` (medium impact). They compile to nothing where UIKit is absent.113114## App-level components (`App/Sources/Core/Presentation.swift`)115116| Component | What it is |117|---|---|118| `StateBadge` | an `ORIXChip` with the state's symbol and its title in words |119| `FindingRow` | state symbol, title, "state · severity" line, first piece of evidence, chevron; one combined accessibility element with the button trait |120| `FindingList` | findings on a card, each opening `FindingDetailView` in a sheet; identifier `finding.<id>` |121| `FindingDetailView` | everything a finding carries, in fixed order: state, severity and confidence chips; "What it means"; "Recommended action"; "Evidence" (label, monospaced selectable value, source); "How it was established"; "What was not inspected"; assessment date. Content limited to 720 pt wide. |122| `FlowChips` | a `Layout` that wraps chips onto several lines, so chips never truncate at large text sizes |123| `ReadingRow` | a label and a `Reading`: a measured value, or "Not available" with a `minus.circle` symbol and the reason underneath. Never a placeholder number. |124| `LimitsCard` | collapsible list, each line with an `eye.slash` symbol, of what no app can see; shown wherever a result could be over-read |125| `SummaryRing` | segmented ring of finding states, one segment per state in the state's colour. It shows how much was assessed and with what result; it is not a score. |126| `ScreenScroll` | screen scaffold: scrolling column on `canvas`, content limited to 860 pt wide |127| `NavigationTile` | hub row: glyph, title, optional detail, chevron; identifier `tile.<destination>` |128129## State vocabulary130131Every `AssessmentState` has its own SF Symbol, its own words and a colour. The three always appear together.132133| State | Label (English source) | Symbol | Colour |134|---|---|---|---|135| `verified` | Verified | `checkmark.circle.fill` | `success` |136| `attention` | Attention recommended | `exclamationmark.triangle.fill` | `warning` |137| `attention` with `high` severity | Attention recommended · High severity | `exclamationmark.octagon.fill` | `danger` |138| `userConfirmed` | Confirmed by you | `person.crop.circle.badge.checkmark` | `info` |139| `userConfirmationRequired` | User confirmation required | `questionmark.circle` | `#8A93AE` / `#7A84A3` |140| `notAvailable` | Not available | `minus.circle` | `textTertiary` |141| `notAssessed` | Not assessed | `circle.dashed` | `textTertiary` |142143Rules encoded in `Presentation.swift`:144145- **Red is reserved.** `Finding.tint` returns `danger` only when `state == .attention && severity == .high`. Low and146 moderate attention findings are amber. Nothing else in a finding list is red.147- **"Confirmed by you" is blue, not green.** What the user reports is not something the app verified, and it does148 not borrow the colour of verification.149- **Unknown is grey.** "Not available" and "Not assessed" use the tertiary text colour: absence of information is150 neither good nor bad.151- Severity (`None`, `Low`, `Moderate`, `High`) is shown in words and only for attention findings. Confidence152 (`Measured`, `Heuristic`, `Reported by you`, `No basis`) and the verification method are always shown in words in153 the detail sheet.154155## Accessibility rules implemented156157- **Dynamic Type.** Every `Font.orix…` token is a system text style. Two decorative sizes are fixed: the glyph158 symbol (scaled to its square) and the 34–38 pt symbols of detail headers and empty states. `FlowChips` wraps159 instead of truncating.160- **Never colour alone.** A state is always symbol + words + colour (`StateBadge`, `FindingRow`); banners carry a161 symbol per kind; an unavailable reading says "Not available" and why. The ring, which is colour-coded, is hidden162 from accessibility and its counts are given as text next to it.163- **Touch targets.** `ORIX.minimumTarget` is 44 pt; primary and secondary buttons are at least 52 and 48 pt high,164 tiles 84 pt; checklist answer controls apply `minHeight: ORIX.minimumTarget`. Finding rows extend their hit area165 to the full row with `contentShape(Rectangle())`.166- **Reduce Motion.** `SummaryRing` reads `accessibilityReduceMotion`: with the setting on, the ring is drawn167 complete at once; otherwise it sweeps in with `Motion.expressive`. The remaining animations are short state168 transitions (`quick`, `standard`); they do not check the setting individually.169- **Combined elements.** `FindingRow`, each evidence block, `ReadingRow` and `ORIXBanner` use170 `accessibilityElement(children: .combine)`, so VoiceOver reads one sentence per row instead of fragments.171 Decorative images (`ORIXGlyph`, `ORIXMark`, chevrons, state symbols next to their label) are hidden.172- **Headers.** Section titles and detail block titles carry the header trait.173- **Selectable values.** Evidence values and measured readings enable text selection.174- **Identifiers.** Interactive elements carry stable accessibility identifiers, which the UI tests use.175176Not verified: a VoiceOver pass by a person, measured contrast ratios, the largest accessibility text sizes on every177screen. See [testing.md](../development/testing.md).178179## Light and dark180181Both appearances come from the same tokens; there is no separate dark layout. Dark surfaces are blue-black182(`#0A0D18` canvas, `#141828` cards), not pure black; status and accent colours switch to lighter, less saturated183values in dark so they stay legible on those surfaces. The user can follow the system or force light or dark184(`AppearancePreference`: `system`, `light`, `dark`). The launch screen uses the `LaunchBackground` colour set and185the dark-appearance mark, which reads on both backgrounds.186187## iPad layout188189`App/Sources/Core/RootView.swift` switches on the horizontal size class: five tabs on iPhone and in compact widths, a190grouped sidebar with a detail column (`NavigationSplitView`) on iPad. Both drive the same screens. Readable widths191are capped rather than stretched: 860 pt for screens (`ScreenScroll`), 720 pt for finding details, 420 pt for empty192states. All four orientations are supported on iPad, three on iPhone (`Info.plist`), and `UIRequiresFullScreen` is193false, so the app can be resized in Split View.194