SPB Git

Repository Public License

design-system.md 13.3 KB

# Design system

Sources: 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.

The 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.

# Colour tokens

Every 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).

# Interface palette — ORIX.Palette

Token Light Dark Role
canvas #F4F5FA #0A0D18 Page background
surface #FFFFFF #141828 Card background
surfaceRaised #EEF0F7 #1D2236 Meter tracks, tags, empty chart areas
hairline #DDE0EA #262C42 Card borders, chart grid lines
textPrimary #0E1222 #F2F4FB Values, titles
textSecondary #596078 #A3AAC2 Labels, captions
textTertiary #5F657D #9097B0 Explanatory notes, axis labels
success #0A7446 #34D399 Normal state, active interface, "no active alert"
warning #8F5200 #FBBF24 Warning severity, quality badges, paused indicator
danger #C0283A #FF6B76 Critical severity, volume above 90 % used, battery below 15 %
accent #0B6E8A #22D3EE App tint, info severity, bookmarks, drop target outline
accentSecondary #5B5BF0 #8484FF Page-header tile for non-hardware pages, bookmark rules on charts

The 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).

# Metric palette — MetricFamily

One 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.

Standard palette ("one hue per family, tuned for contrast on both canvases"):

Family SF Symbol Light Dark
cpu cpu #2563EB #60A5FA
gpu square.stack.3d.up #7C3AED #A78BFA
memory memorychip #059669 #34D399
disk internaldrive #C2620A #FBBF24
network network #0891B2 #22D3EE
power bolt.fill #4D7C0F #A3E635
thermal thermometer.medium #DB2777 #F472B6
system desktopcomputer #596078 #A3AAC2

Colour-blind-safe palette (Okabe–Ito, "distinguishable under the common forms of colour-vision deficiency"):

Family Light Dark
cpu #0072B2 #56B4E9
gpu #AA4499 #CC79A7
memory #007A5A #009E73
disk #B07800 #E69F00
network #2A7FB8 #88CCEE
power #8A7A00 #F0E442
thermal #D55E00 #FF8A3D
system #596078 #A3AAC2

Notes:

  • 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.
  • The switch is a single preference, "Colour-blind-safe chart colours" (Settings › General), propagated as the colorBlindSafe environment value.
  • 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.

# Derived colour use

Use Colours
Memory breakdown (MemoryBar.colors) app = memory, wired = disk, compressed = gpu, cached = network at 45 % opacity
CPU user / system series cpu / thermal
Second series in two-series charts (write, upload) gpu
Severity (Severity.color) info = accent, warning = warning, critical = danger
Thermal level (ThermalText.color) nominal = success, fair = textPrimary, serious = warning, critical = danger

# Fixed colours outside the tokens

  • PDFReportRenderer uses the light values of textPrimary, textSecondary, hairline, canvas and accent directly, so PDFs look the same in either appearance.
  • The menu bar image is drawn in black and marked as a template image; macOS tints it.
  • The icon and DMG background use the icon colours (see icon design).

# Typography — ORIX.Typeface

All text uses the system font (San Francisco). Numbers that change use monospaced digits so they do not jitter.

Token Definition Use
readout(_ size: 28) system, semibold, rounded design, monospaced digits Large numeric readouts (sizes used: 20–34)
label system 11 pt, semibold, small caps Card titles, table headers
value system 13 pt, medium, monospaced digits Values in rows and tables
caption system 11 pt, monospaced digits Captions, notes, axis labels
mono system 12 pt, monospaced design BSD names, source APIs, paths, addresses

Other sizes appear inline: page titles 20 pt bold, body explanations 12 pt, quality badges 9 pt semibold uppercase.

# Spacing and radii

ORIX.Space pt ORIX.Radius pt
xxs 4 chip 6
xs 8 control 8
sm 12 card 14
md 16
lg 24
xl 32

Cards use continuous-corner rounded rectangles with a 1 pt hairline border and no shadow.

# Density

DensityChoice (Settings › General) sets the density environment value, a multiplier applied to card padding, card spacing, page padding and dashboard row height.

Choice Multiplier
Compact 0.72
Regular (default) 1.00
Comfortable 1.25

Density 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.

# Layout

Mechanism Behaviour
Page Scroll view on canvas; content column capped at 1500 pt and centred; padding lg × density
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
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
Main window Minimum 860 × 560, default 1280 × 860; sidebar 190–280 pt
Processes page Table plus an inspector shown only when the pane is at least 640 pt wide (width min(320, 36 %))

# Component inventory — Components.swift

Component Purpose Notes
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
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
Readout A large number with a caption Shrinks to 60 % before truncating; numeric-text content transition
KeyValueRow Label left, value right; optional colour swatch and quality badge Value is selectable; row is one accessibility element
UnavailableRow The honest placeholder: label, "Unavailable" badge, reason Default reason: "Not available through supported system interfaces."
SegmentBar Horizontal bar of proportional segments Memory breakdown
Meter Thin 0…1 level bar Volumes, battery, swap, process contribution
Sparkline Dependency-free line (Canvas), optional fill and fixed ceiling "Draws real samples only; an empty input draws nothing"
LivePoint, LiveSeries Data types for live charts —
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
PageHeader Icon tile, title, subtitle Tile uses the family colour, or accentSecondary when a custom symbol is given
Page Scrollable page container —
AdaptiveRowLayout, CardRow Responsive card row —
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

Shared 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).

# Accessibility decisions

# Never colour alone

  • Quality is a word in a badge, not a tint. QualityBadge's comment: "Never colour alone: the label carries the meaning."
  • Severity is always shown with a distinct symbol (info.circle.fill, exclamationmark.triangle.fill, exclamationmark.octagon.fill) and, where space allows, its name.
  • 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."
  • Interface status is text ("Active", "Up, no address", "Down"); capability presence is a labelled icon ("Available" / "Not available").
  • Charts with several series show a legend, and the breakdown rows next to them repeat each series name with its swatch and value.
  • The menu bar item is monochrome by construction (template image); an active alert adds a dot, and the accessibility label spells out the count.

# Chart accessibility summaries

Charts are drawings, so each one is collapsed into a single accessibility element with a textual summary:

Chart VoiceOver reads
LiveChart For each series: name, latest value, minimum and maximum of the window (accessibilitySummary)
HistoryChart Metric name; minimum, average, maximum and the number of gaps
CoreHeatmap "Busiest core right now: n at x %"
CoreGrid cells "Core n", value "x %"
CoreBars The percentage of every core, in order
Sparkline, Meter, SegmentBar, ThermalScale Hidden from accessibility; the adjacent text carries the value

Other 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.

# Reduce Motion

Two 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.

# Text and localisation

  • Interface strings are in a string catalogue with English as the source language and Canadian French translations (see setup).
  • Numbers, percentages, byte counts, durations, temperatures and dates are formatted with the user's locale through ValueFormatter.
  • The privacy mask replaces addresses, host and user names with "•••" for screenshots and screen sharing.

# Limitations and gaps

  • Fixed point sizes. Fonts are declared with explicit sizes (.system(size:)), so they do not follow Dynamic Type-style text scaling.
  • 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.
  • Increase Contrast and Differentiate Without Colour system settings are not read explicitly; the "never colour alone" rules above are applied unconditionally instead.
  • 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.
  • 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.
  • Density does not scale type or charts.
  • One accent pair, one theme. There is no user-selectable theme beyond light / dark / system.
Files main
Menu

Theme