Repository Public License
1<!--2ORIX Scan3File: docs/design/design-system.md4Author: Simon-Pierre Boucher5Contact: contact@spboucher.ai6-->78# ORIX design system910The design system is the `ORIXDesign` library in `Packages/ORIXKit/Sources/ORIXDesign/`. It depends only on SwiftUI (and11UIKit or AppKit for dynamic colours and haptics), knows nothing about documents, and is meant to be imported by other ORIX12apps as it is.1314| File | Content |15|---|---|16| `Tokens.swift` | Colour roles, accent pair, spacing, radii, motion, typography, environment key |17| `Components.swift` | Surfaces, button styles, glyph, section header, chip, empty state, banner, progress bar, page frame, scan beam, mark |18| `Haptics.swift` | `ORIXHaptics` |1920## Tokens2122### Colour roles — `ORIX.Palette`2324Every colour is a role with a light and a dark value (`Color(light:dark:)`, sRGB).2526| Role | Light | Dark | Use |27|---|---|---|---|28| `canvas` | `#F4F5FA` | `#0A0D18` | App background behind grouped content |29| `surface` | `#FFFFFF` | `#141828` | Cards and rows |30| `surfaceRaised` | `#EEF0F7` | `#1D2236` | Fields inside cards, chips, tool buttons |31| `desk` | `#E4E7F0` | `#05070E` | Backdrop behind document pages; never pure white, so page edges stay visible |32| `hairline` | `#DDE0EA` | `#262C42` | Borders and separators |33| `textPrimary` | `#0E1222` | `#F2F4FB` | Main text |34| `textSecondary` | `#596078` | `#A3AAC2` | Supporting text |35| `textTertiary` | `#8A90A6` | `#6F7690` | Placeholders, inactive marks |36| `success` | `#12925A` | `#34D399` | Completed, good |37| `warning` | `#B86A00` | `#FBBF24` | Advice, uncertain values |38| `danger` | `#D4313F` | `#FF6B76` | Errors, destructive |39| `onAccent` | white | white | Content on the accent gradient |4041### Accent — `ORIXAccent`4243The family shares every token above; each app brings one accent pair.4445| | Light | Dark |46|---|---|---|47| `ORIXAccent.scan.primary` (indigo) | `#5B5BF0` | `#8484FF` |48| `ORIXAccent.scan.secondary` (cyan, the "optical beam") | `#0FB5CF` | `#22D3EE` |4950`gradient` is the indigo gradient of primary surfaces (`#7673FF` → `#5B5BF0` → `#3F3BD6`); `beam` fades the secondary colour51in and out horizontally. Components read the accent from the environment (`\.orixAccent`), never from a constant.5253### Spacing — `ORIX.Space` (4-point scale)5455`xxs` 4 · `xs` 8 · `sm` 12 · `md` 16 · `lg` 20 · `xl` 28 · `xxl` 405657### Radii — `ORIX.Radius` (continuous corners)5859`page` 5 (paper is almost square) · `chip` 10 · `control` 14 · `card` 20 · `hero` 286061### Typography6263All styles are built on Dynamic Type text styles, so they follow the user's text size.6465| Token | Definition |66|---|---|67| `Font.orixDisplay` | `.largeTitle`, rounded, bold |68| `Font.orixTitle` | `.title2`, rounded, semibold |69| `Font.orixHeadline` | `.headline`, semibold |70| `Font.orixBody` | `.body` |71| `Font.orixCallout` | `.callout` |72| `Font.orixCaption` | `.caption`, medium |73| `Font.orixOverline` | `.caption2`, semibold |74| `Font.orixMono` | `.footnote`, monospaced (measured values, patterns) |7576### Motion — `ORIX.Motion`7778| Token | Curve | Use |79|---|---|---|80| `quick` | `snappy(duration: 0.22)` | State changes of controls |81| `standard` | `smooth(duration: 0.35)` | Layout changes, content moving |82| `expressive` | `spring(response: 0.5, dampingFraction: 0.72)` | Emphasis: the detected crop snapping into place |8384`ORIX.minimumTarget` is 44 points.8586## Components8788**Card** — the standard surface: `surface` fill, `card` radius, hairline border.8990```swift91VStack { … }.orixCard() // default padding ORIX.Space.md92```9394**Lift** — the single elevation used under pages and floating controls: `.orixLift()`.9596**Button styles**9798```swift99Button("Recognize Text") { … }.buttonStyle(.orixPrimary) // accent gradient, 52 pt high, the main action of a screen100Button("Import Files") { … }.buttonStyle(.orixSecondary) // tinted fill101Button { … } label: { … }.buttonStyle(.orixTile) // card-like tile for quick actions102```103104**`ORIXGlyph`** — an SF Symbol on a tinted rounded square; the leading mark of rows and tiles. Hidden from VoiceOver.105106```swift107ORIXGlyph("folder", size: 32)108ORIXGlyph("wand.and.stars", tint: accent.secondary)109```110111**`ORIXSectionHeader`** — a title with the header trait and an optional trailing view.112113```swift114ORIXSectionHeader("Recent Documents") { Button("See All") { … } }115```116117**`ORIXChip`** — compact status or metadata.118119```swift120ORIXChip(Text("32 lines"), systemName: "text.alignleft")121```122123**`ORIXEmptyState`** — symbol, title, message and optional actions, centered.124125```swift126ORIXEmptyState(systemName: "books.vertical", title: "Your Library Is Empty", message: "Scan a document…") {127 Button("Scan Document") { … }.buttonStyle(.orixPrimary)128}129```130131**`ORIXBanner`** — inline message of kind `info`, `success`, `warning` or `error`. Each kind has its own symbol as well as132its own colour, and the banner is one accessibility element.133134```swift135ORIXBanner(.warning, title: Text("Low contrast"), message: Text("Try the Black & White filter…")) { Menu { … } label: { … } }136```137138**`ORIXProgressBar`** — determinate progress with the indigo-to-cyan gradient; exposes its value as a percentage.139140```swift141ORIXProgressBar(value: progress)142```143144**Page frame** — frames an image as paper: near-square corners, a hairline, the lift.145146```swift147Image(uiImage: page).resizable().aspectRatio(contentMode: .fit).orixPage()148```149150**Scan beam** — the ORIX signature: a thin luminous line sweeping over content while it is being processed.151152```swift153DocumentThumbnail(id: id).orixScanBeam(active: isRecognizing)154```155156**`ORIXMark`** — the mark drawn in code with `Canvas`: four viewfinder arcs forming the "O", crossed by the beam.157158```swift159ORIXMark().frame(width: 96)160ORIXMark(ring: .white) // on the accent gradient161```162163**`ORIXHaptics`** — `tick()` for a discrete change, `press()` for a physical-feeling action, `success()`, `warning()`,164`failure()` for outcomes. No-ops where UIKit is unavailable.165166## Accessibility rules built in167168- **Dynamic Type.** Every font token is a text style; no fixed point sizes for text. Layouts that cannot hold large text169 side by side switch axis (`HomeView` uses `dynamicTypeSize.isAccessibilitySize`).170- **Targets.** Interactive elements are at least `ORIX.minimumTarget` (44 pt): primary buttons are 52 pt high, secondary171 48 pt, icon buttons 44 × 44.172- **Reduce Motion.** `ORIXScanBeam` does not animate when `accessibilityReduceMotion` is on.173- **Never colour alone.** Banners pair colour with a symbol and text; chips and status rows carry a label; selected174 states also set the `isSelected` trait.175- **Decoration is hidden.** `ORIXGlyph`, `ORIXMark`, chip icons and the beam are hidden from VoiceOver; the progress bar176 and banners are single elements with a value or a combined label.177- **Light and dark.** All palette roles have both values; nothing in the system uses a fixed black or white for text.178179## Adopting the system in another ORIX app1801811. Add the package and import `ORIXDesign`.1822. Define the app's accent pair and inject it once at the root:183184```swift185extension ORIXAccent {186 static let audio = ORIXAccent(primary: Color(light: 0x…, dark: 0x…), secondary: Color(light: 0x…, dark: 0x…))187}188189RootView()190 .environment(\.orixAccent, .audio)191 .tint(ORIXAccent.audio.primary)192```1931943. Use the tokens and components unchanged. Everything that is accent-coloured follows the environment value.195196Two things are still specific to ORIX Scan and would need generalizing for a second app: the fixed stops of197`ORIXAccent.gradient`, and the default value of the environment key (`.scan`).198