SPB Git

Repository Public License

design-system.md 13.3 KB 204 lines markdown

1<!--2ORIX Monitor3File: docs/design/design-system.md4Author: Simon-Pierre Boucher5Contact: contact@spboucher.ai6-->78# Design system910Sources: `App/Sources/DesignSystem/Tokens.swift`, `App/Sources/DesignSystem/Components.swift`, plus shared helpers in `App/Sources/Features/DashboardView.swift` and settings in `App/Sources/App/AppSettings.swift`.1112The design system has two files: **tokens** (the `ORIX` namespace, `MetricFamily`, environment values) and **components** (reusable SwiftUI views). Feature pages are composed from those; raw hex values do not appear in feature code.1314## Colour tokens1516Every colour is defined with a light and a dark sRGB value through `Color(light:dark:)`, which builds a dynamic `NSColor` that resolves against the effective appearance (`.aqua` / `.darkAqua`). The app's appearance follows the system by default and can be forced to light or dark (`AppearanceChoice`).1718### Interface palette — `ORIX.Palette`1920| Token | Light | Dark | Role |21|---|---|---|---|22| `canvas` | `#F4F5FA` | `#0A0D18` | Page background |23| `surface` | `#FFFFFF` | `#141828` | Card background |24| `surfaceRaised` | `#EEF0F7` | `#1D2236` | Meter tracks, tags, empty chart areas |25| `hairline` | `#DDE0EA` | `#262C42` | Card borders, chart grid lines |26| `textPrimary` | `#0E1222` | `#F2F4FB` | Values, titles |27| `textSecondary` | `#596078` | `#A3AAC2` | Labels, captions |28| `textTertiary` | `#5F657D` | `#9097B0` | Explanatory notes, axis labels |29| `success` | `#0A7446` | `#34D399` | Normal state, active interface, "no active alert" |30| `warning` | `#8F5200` | `#FBBF24` | Warning severity, quality badges, paused indicator |31| `danger` | `#C0283A` | `#FF6B76` | Critical severity, volume above 90 % used, battery below 15 % |32| `accent` | `#0B6E8A` | `#22D3EE` | App tint, info severity, bookmarks, drop target outline |33| `accentSecondary` | `#5B5BF0` | `#8484FF` | Page-header tile for non-hardware pages, bookmark rules on charts |3435The comment on the palette reads "The family palette, shared with the other ORIX apps"; `accent` / `accentSecondary` are "ORIX Monitor's accent pair: the cyan pulse over the family indigo". The asset catalogue's `AccentColor` holds the same accent pair, and `AppEnvironment` applies `.tint(ORIX.Palette.accent)`.3637### Metric palette — `MetricFamily`3839One hue per subsystem, used for chart series, card icons, meters and page-header tiles. `MetricFamily.color(colorBlindSafe:)` returns the standard or the colour-blind-safe value.4041**Standard palette** ("one hue per family, tuned for contrast on both canvases"):4243| Family | SF Symbol | Light | Dark |44|---|---|---|---|45| `cpu` | `cpu` | `#2563EB` | `#60A5FA` |46| `gpu` | `square.stack.3d.up` | `#7C3AED` | `#A78BFA` |47| `memory` | `memorychip` | `#059669` | `#34D399` |48| `disk` | `internaldrive` | `#C2620A` | `#FBBF24` |49| `network` | `network` | `#0891B2` | `#22D3EE` |50| `power` | `bolt.fill` | `#4D7C0F` | `#A3E635` |51| `thermal` | `thermometer.medium` | `#DB2777` | `#F472B6` |52| `system` | `desktopcomputer` | `#596078` | `#A3AAC2` |5354**Colour-blind-safe palette** (Okabe–Ito, "distinguishable under the common forms of colour-vision deficiency"):5556| Family | Light | Dark |57|---|---|---|58| `cpu` | `#0072B2` | `#56B4E9` |59| `gpu` | `#AA4499` | `#CC79A7` |60| `memory` | `#007A5A` | `#009E73` |61| `disk` | `#B07800` | `#E69F00` |62| `network` | `#2A7FB8` | `#88CCEE` |63| `power` | `#8A7A00` | `#F0E442` |64| `thermal` | `#D55E00` | `#FF8A3D` |65| `system` | `#596078` | `#A3AAC2` |6667Notes:6869- The dark column carries the canonical Okabe–Ito values where one exists (`#56B4E9` sky blue, `#CC79A7` reddish purple, `#009E73` bluish green, `#E69F00` orange, `#F0E442` yellow); the light column uses darkened variants so the hues keep enough contrast on a white surface (`#0072B2` and `#D55E00` are themselves Okabe–Ito blue and vermillion). `#88CCEE`, `#AA4499`, `#2A7FB8`, `#007A5A`, `#B07800`, `#8A7A00` and `#FF8A3D` are adjustments or neighbours chosen for the same purpose rather than members of the original eight-colour set.70- The switch is a single preference, "Colour-blind-safe chart colours" (Settings › General), propagated as the `colorBlindSafe` environment value.71- `MetricID.family` assigns every stored metric to a family. Battery temperature belongs to `thermal`; process count and ORIX Monitor's own CPU and memory belong to `system`.7273### Derived colour use7475| Use | Colours |76|---|---|77| Memory breakdown (`MemoryBar.colors`) | app = memory, wired = disk, compressed = gpu, cached = network at 45 % opacity |78| CPU user / system series | cpu / thermal |79| Second series in two-series charts (write, upload) | gpu |80| Severity (`Severity.color`) | info = `accent`, warning = `warning`, critical = `danger` |81| Thermal level (`ThermalText.color`) | nominal = `success`, fair = `textPrimary`, serious = `warning`, critical = `danger` |8283### Fixed colours outside the tokens8485- `PDFReportRenderer` uses the light values of `textPrimary`, `textSecondary`, `hairline`, `canvas` and `accent` directly, so PDFs look the same in either appearance.86- The menu bar image is drawn in black and marked as a template image; macOS tints it.87- The icon and DMG background use the icon colours (see [icon design](icon-design.md)).8889## Typography — `ORIX.Typeface`9091All text uses the system font (San Francisco). Numbers that change use monospaced digits so they do not jitter.9293| Token | Definition | Use |94|---|---|---|95| `readout(_ size: 28)` | system, semibold, rounded design, monospaced digits | Large numeric readouts (sizes used: 20–34) |96| `label` | system 11 pt, semibold, small caps | Card titles, table headers |97| `value` | system 13 pt, medium, monospaced digits | Values in rows and tables |98| `caption` | system 11 pt, monospaced digits | Captions, notes, axis labels |99| `mono` | system 12 pt, monospaced design | BSD names, source APIs, paths, addresses |100101Other sizes appear inline: page titles 20 pt bold, body explanations 12 pt, quality badges 9 pt semibold uppercase.102103## Spacing and radii104105| `ORIX.Space` | pt | | `ORIX.Radius` | pt |106|---|---|---|---|---|107| `xxs` | 4 | | `chip` | 6 |108| `xs` | 8 | | `control` | 8 |109| `sm` | 12 | | `card` | 14 |110| `md` | 16 | | | |111| `lg` | 24 | | | |112| `xl` | 32 | | | |113114Cards use continuous-corner rounded rectangles with a 1 pt `hairline` border and no shadow.115116## Density117118`DensityChoice` (Settings › General) sets the `density` environment value, a multiplier applied to card padding, card spacing, page padding and dashboard row height.119120| Choice | Multiplier |121|---|---|122| Compact | 0.72 |123| Regular (default) | 1.00 |124| Comfortable | 1.25 |125126Density scales **padding and spacing only**; font sizes do not change. The dashboard's row height is `176 × max(density, 0.85)`, so rows do not shrink below 85 % in compact mode.127128## Layout129130| Mechanism | Behaviour |131|---|---|132| `Page` | Scroll view on `canvas`; content column capped at 1500 pt and centred; padding `lg × density` |133| `CardRow` / `AdaptiveRowLayout` | Lays cards side by side at equal height when the row is at least 720 pt wide, otherwise stacks them. Cards with a maximum width keep it; the others share the rest |134| `FlowGrid` (dashboard) | 1 to 4 equal columns depending on width (minimum column 250 pt); each widget spans 1, 2 or all columns (`WidgetSize.small` / `.medium` / `.large`); fixed row height |135| Main window | Minimum 860 × 560, default 1280 × 860; sidebar 190–280 pt |136| Processes page | Table plus an inspector shown only when the pane is at least 640 pt wide (width `min(320, 36 %)`) |137138## Component inventory — `Components.swift`139140| Component | Purpose | Notes |141|---|---|---|142| `Card` | The standard panel: optional small-caps title, family icon, quality badge, content | The badge is drawn only for `estimated`, `bestEffort` and `unavailable`; `measured` and `derived` show none |143| `QualityBadge` | States how a value was obtained: Measured, Derived, Estimate, Best effort, Unavailable | Text carries the meaning; tooltip and accessibility label give the full sentence |144| `Readout` | A large number with a caption | Shrinks to 60 % before truncating; numeric-text content transition |145| `KeyValueRow` | Label left, value right; optional colour swatch and quality badge | Value is selectable; row is one accessibility element |146| `UnavailableRow` | The honest placeholder: label, "Unavailable" badge, reason | Default reason: "Not available through supported system interfaces." |147| `SegmentBar` | Horizontal bar of proportional segments | Memory breakdown |148| `Meter` | Thin 0…1 level bar | Volumes, battery, swap, process contribution |149| `Sparkline` | Dependency-free line (Canvas), optional fill and fixed ceiling | "Draws real samples only; an empty input draws nothing" |150| `LivePoint`, `LiveSeries` | Data types for live charts | — |151| `LiveChart` | Line or stacked-area chart over the in-memory window, drawn on a SwiftUI `Canvas` (grid, axis labels, legend). It replaced a Swift Charts version whose per-sample animation measured at about 10 % of a core; stored history (`HistoryChart`) still uses Swift Charts | Fixed or automatic y domain, caller-supplied formatter, optional explicit ticks, "Collecting samples…" overlay with fewer than two points |152| `PageHeader` | Icon tile, title, subtitle | Tile uses the family colour, or `accentSecondary` when a custom symbol is given |153| `Page` | Scrollable page container | — |154| `AdaptiveRowLayout`, `CardRow` | Responsive card row | — |155| `SourcesCard` | "Sources and methods": for each metric its name, quality badge, source API and method, straight from `MetricCatalog` | Present at the bottom of every hardware page |156157Shared components defined next to the dashboard: `FlowGrid`, `WidgetView`, `CoreBars`, `PressureBadge`, `MemoryBar`, `ThermalScale`. Chart components defined with their pages: `CoreGrid`, `CoreHeatmap`, `ProcessContribution` (CPU page), `HistoryChart` (History page), `ReportTableView` (Reports page).158159## Accessibility decisions160161### Never colour alone162163- **Quality** is a word in a badge, not a tint. `QualityBadge`'s comment: "Never colour alone: the label carries the meaning."164- **Severity** is always shown with a distinct symbol (`info.circle.fill`, `exclamationmark.triangle.fill`, `exclamationmark.octagon.fill`) and, where space allows, its name.165- **Memory pressure** (`PressureBadge`) and **thermal state** show the level name; the thermal scale's comment reads "The label next to it carries the meaning; colour is secondary."166- **Interface status** is text ("Active", "Up, no address", "Down"); capability presence is a labelled icon ("Available" / "Not available").167- **Charts with several series** show a legend, and the breakdown rows next to them repeat each series name with its swatch and value.168- **The menu bar item** is monochrome by construction (template image); an active alert adds a dot, and the accessibility label spells out the count.169170### Chart accessibility summaries171172Charts are drawings, so each one is collapsed into a single accessibility element with a textual summary:173174| Chart | VoiceOver reads |175|---|---|176| `LiveChart` | For each series: name, latest value, minimum and maximum of the window (`accessibilitySummary`) |177| `HistoryChart` | Metric name; minimum, average, maximum and the number of gaps |178| `CoreHeatmap` | "Busiest core right now: *n* at *x* %" |179| `CoreGrid` cells | "Core *n*", value "*x* %" |180| `CoreBars` | The percentage of every core, in order |181| `Sparkline`, `Meter`, `SegmentBar`, `ThermalScale` | Hidden from accessibility; the adjacent text carries the value |182183Other measures: decorative icons are hidden (`accessibilityHidden(true)`); composite rows are combined into one element; icon-only buttons have explicit labels ("Delete bookmark", "Remove CPU", "Pause Sampling"); `PageHeader` is exposed as a header with the subtitle as its value.184185### Reduce Motion186187Two places animate, and both read `accessibilityReduceMotion`: `Readout` replaces the rolling-digit transition with an instant change, and the dashboard applies widget moves and edit-mode changes without the `snappy` animation. `LiveChart` does not animate at all: it redraws once per sample.188189### Text and localisation190191- Interface strings are in a string catalogue with English as the source language and Canadian French translations (see [setup](../development/setup.md)).192- Numbers, percentages, byte counts, durations, temperatures and dates are formatted with the user's locale through `ValueFormatter`.193- The privacy mask replaces addresses, host and user names with "•••" for screenshots and screen sharing.194195## Limitations and gaps196197- **Fixed point sizes.** Fonts are declared with explicit sizes (`.system(size:)`), so they do not follow Dynamic Type-style text scaling.198- **No automated contrast verification.** The palettes are documented as "tuned for contrast", but no test computes contrast ratios, and this document does not claim a WCAG level.199- **Increase Contrast and Differentiate Without Colour** system settings are not read explicitly; the "never colour alone" rules above are applied unconditionally instead.200- **Reduce Motion** has not been checked with the system setting switched on by a person; the two code paths above are the whole of it.201- **Colour-blind-safe mode changes the metric palette only.** `success`, `warning` and `danger` keep their values; they are always paired with text or a symbol.202- **Density does not scale type or charts.**203- **One accent pair, one theme.** There is no user-selectable theme beyond light / dark / system.204
Files main
Menu

Theme