SPB Git

Repository Public License

design-system.md 11.2 KB

# Design system

The design system has two layers:

  • Packages/ORIXDesign — tokens, reusable components and haptics shared by the ORIX apps. It knows nothing about findings.
  • App/Sources/Core/Presentation.swift — the app-level components that give assessment states, severities and readings their appearance.

Everything below is read from those files. Values are sRGB hex.

# Tokens (Packages/ORIXDesign/Sources/ORIXDesign/Tokens.swift)

# Palette

Every colour is declared once with a light and a dark value (Color(light:dark:)) and resolves with the trait collection, so no view chooses between light and dark itself.

Token (ORIX.Palette) Light Dark Role
canvas #F4F5FA #0A0D18 app background behind grouped content
surface #FFFFFF #141828 cards and rows
surfaceRaised #EEF0F7 #1D2236 nested surfaces, ring track, progress track
hairline #DDE0EA #262C42 0.5 pt card borders
textPrimary #0E1222 #F2F4FB titles and values
textSecondary #596078 #A3AAC2 labels and supporting text
textTertiary #8A90A6 #6F7690 notes, chevrons, inactive states
success #12925A #34D399 verified
warning #B86A00 #FBBF24 attention recommended
danger #D4313F #FF6B76 high-severity attention only; error banners
info #2563EB #7AA5FF neutral information, "confirmed by you"
onAccent #FFFFFF #FFFFFF text on the accent gradient

Accent (ORIXAccent.secure, injected with .environment(\.orixAccent, .secure) in ORIXSecureApp.swift):

Light Dark
primary — violet #7C3AED #A78BFA
secondary — mint "guard ring" #0E9F6E #34D399
gradient (primary buttons) #9F7AEA → #7C3AED → #5B21B6, top-leading to bottom-trailing same

One more colour is defined in Presentation.swift, for the "user confirmation required" state: #8A93AE light, #7A84A3 dark. The asset catalog carries AccentColor (#7C3AED / #A78BFA) and LaunchBackground (#F4F5FA / #0A0D18), generated by design/icon/build.py with the same values.

Contrast ratios have not been measured with a tool; that is an open item for an accessibility audit.

# Spacing (ORIX.Space, 4-point scale)

xxs xs sm md lg xl xxl
4 8 12 16 20 28 40

# Radii (ORIX.Radius, continuous corners)

chip control card hero
10 14 20 28

# Motion (ORIX.Motion)

Token Definition Use
quick snappy(duration: 0.22) pressed states of controls
standard smooth(duration: 0.35) layout changes, progress bar
expressive spring(response: 0.5, dampingFraction: 0.72) the summary ring

# Typography (Font.orix…)

All styles are built on Dynamic Type text styles, so they scale with the user's text size. No font is bundled.

Token Text style Design Weight
orixDisplay .largeTitle rounded bold
orixTitle .title2 rounded semibold
orixHeadline .headline default semibold
orixBody .body default regular
orixCallout .callout default regular
orixCaption .caption default medium
orixOverline .caption2 default semibold (used uppercased for block titles)
orixMono .footnote monospaced regular (hashes, evidence values)

# Other

ORIX.minimumTarget = 44 — the minimum touch target.

# Components (Packages/ORIXDesign/Sources/ORIXDesign/Components.swift)

Component What it is
.orixCard(padding:) card surface: surface fill, card radius, 0.5 pt hairline border
.orixLift() the single elevation: a soft shadow (black 14 %, radius 10, y 4). Everything else is flat.
.orixPrimary button style accent gradient, white headline text, full width, minimum height 52 pt; 45 % opacity when disabled
.orixSecondary button style accent text on a 12 % accent tint, full width, minimum height 48 pt
.orixTile button style card-like tile, minimum height 84 pt
ORIXGlyph SF Symbol on a tinted rounded square (default 36 pt), hidden from accessibility
ORIXSectionHeader title in orixTitle with the header trait, optional trailing content
ORIXChip capsule with optional symbol and text on a 12 % tint
ORIXEmptyState symbol in a 96 pt circle, title, message, optional actions; content limited to 420 pt wide
ORIXBanner inline message of kind info, success, warning or error: each kind has its own symbol and colour; children combined into one accessibility element
ORIXProgressBar 6 pt determinate bar, primary → secondary gradient, exposes its value as a percentage to accessibility
ORIXMark the ORIX Secure mark drawn in a Canvas: four arcs, guard ring, core (see icon-design.md)

Haptics (Haptics.swift, ORIXHaptics): tick (selection), success, warning, failure (notification feedback), press (medium impact). They compile to nothing where UIKit is absent.

# App-level components (App/Sources/Core/Presentation.swift)

Component What it is
StateBadge an ORIXChip with the state's symbol and its title in words
FindingRow state symbol, title, "state · severity" line, first piece of evidence, chevron; one combined accessibility element with the button trait
FindingList findings on a card, each opening FindingDetailView in a sheet; identifier finding.<id>
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.
FlowChips a Layout that wraps chips onto several lines, so chips never truncate at large text sizes
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.
LimitsCard collapsible list, each line with an eye.slash symbol, of what no app can see; shown wherever a result could be over-read
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.
ScreenScroll screen scaffold: scrolling column on canvas, content limited to 860 pt wide
NavigationTile hub row: glyph, title, optional detail, chevron; identifier tile.<destination>

# State vocabulary

Every AssessmentState has its own SF Symbol, its own words and a colour. The three always appear together.

State Label (English source) Symbol Colour
verified Verified checkmark.circle.fill success
attention Attention recommended exclamationmark.triangle.fill warning
attention with high severity Attention recommended · High severity exclamationmark.octagon.fill danger
userConfirmed Confirmed by you person.crop.circle.badge.checkmark info
userConfirmationRequired User confirmation required questionmark.circle #8A93AE / #7A84A3
notAvailable Not available minus.circle textTertiary
notAssessed Not assessed circle.dashed textTertiary

Rules encoded in Presentation.swift:

  • Red is reserved. Finding.tint returns danger only when state == .attention && severity == .high. Low and moderate attention findings are amber. Nothing else in a finding list is red.
  • "Confirmed by you" is blue, not green. What the user reports is not something the app verified, and it does not borrow the colour of verification.
  • Unknown is grey. "Not available" and "Not assessed" use the tertiary text colour: absence of information is neither good nor bad.
  • Severity (None, Low, Moderate, High) is shown in words and only for attention findings. Confidence (Measured, Heuristic, Reported by you, No basis) and the verification method are always shown in words in the detail sheet.

# Accessibility rules implemented

  • Dynamic Type. Every Font.orix… token is a system text style. Two decorative sizes are fixed: the glyph symbol (scaled to its square) and the 34–38 pt symbols of detail headers and empty states. FlowChips wraps instead of truncating.
  • Never colour alone. A state is always symbol + words + colour (StateBadge, FindingRow); banners carry a symbol per kind; an unavailable reading says "Not available" and why. The ring, which is colour-coded, is hidden from accessibility and its counts are given as text next to it.
  • Touch targets. ORIX.minimumTarget is 44 pt; primary and secondary buttons are at least 52 and 48 pt high, tiles 84 pt; checklist answer controls apply minHeight: ORIX.minimumTarget. Finding rows extend their hit area to the full row with contentShape(Rectangle()).
  • Reduce Motion. SummaryRing reads accessibilityReduceMotion: with the setting on, the ring is drawn complete at once; otherwise it sweeps in with Motion.expressive. The remaining animations are short state transitions (quick, standard); they do not check the setting individually.
  • Combined elements. FindingRow, each evidence block, ReadingRow and ORIXBanner use accessibilityElement(children: .combine), so VoiceOver reads one sentence per row instead of fragments. Decorative images (ORIXGlyph, ORIXMark, chevrons, state symbols next to their label) are hidden.
  • Headers. Section titles and detail block titles carry the header trait.
  • Selectable values. Evidence values and measured readings enable text selection.
  • Identifiers. Interactive elements carry stable accessibility identifiers, which the UI tests use.

Not verified: a VoiceOver pass by a person, measured contrast ratios, the largest accessibility text sizes on every screen. See testing.md.

# Light and dark

Both appearances come from the same tokens; there is no separate dark layout. Dark surfaces are blue-black (#0A0D18 canvas, #141828 cards), not pure black; status and accent colours switch to lighter, less saturated values in dark so they stay legible on those surfaces. The user can follow the system or force light or dark (AppearancePreference: system, light, dark). The launch screen uses the LaunchBackground colour set and the dark-appearance mark, which reads on both backgrounds.

# iPad layout

App/Sources/Core/RootView.swift switches on the horizontal size class: five tabs on iPhone and in compact widths, a grouped sidebar with a detail column (NavigationSplitView) on iPad. Both drive the same screens. Readable widths are capped rather than stretched: 860 pt for screens (ScreenScroll), 720 pt for finding details, 420 pt for empty states. All four orientations are supported on iPad, three on iPhone (Info.plist), and UIRequiresFullScreen is false, so the app can be resized in Split View.

Files main
Menu

Theme