SPB Git

Repository Public

design-system.md 24.0 KB

# ORIX DJ design system

This document describes the visual and interaction vocabulary of the ORIX DJ interface as it is implemented in code. The sources are App/Sources/DesignSystem/Tokens.swift, App/Sources/DesignSystem/Components.swift, App/Sources/App/RootView.swift, App/Sources/App/AppSettings.swift and the asset catalog App/Resources/Assets.xcassets. It reflects the code as read on 2026-11-21; the interface folders were still being edited on that day.

Related documents: brand guidelines, icon design, accessibility report, waveform architecture, architecture overview.

# 1. Where the tokens live

All tokens are static members of one namespace, enum ORIX, in Tokens.swift:

Group Type Purpose
ORIX.Palette Color constants Surfaces, text, status and accent colours
ORIX.deck(_:) function Int -> Color One colour per deck (A to D)
ORIX.hotCueColors, ORIX.hotCueHex arrays of 8 Hot-cue pad and marker colours
ORIX.Space CGFloat constants Spacing scale
ORIX.Radius CGFloat constants Corner radii
ORIX.Typeface Font constants and one function Type styles

Two helpers in the same file format numbers for display: formatTime(_:tenths:) (3:07.4, or –:–– for a non-finite value) and formatBPM(_:) (one decimal, or – when the tempo is unknown).

Colours with a light and a dark value are built with Color(light:dark:), which wraps a dynamic NSColor and picks the dark value when the effective appearance best matches .darkAqua. All hex values are sRGB. The asset catalog holds only two things: the application icon set and AccentColor. Palette colours do not live in the catalog.

# 2. Colour

# 2.1 Palette

Token Light Dark Use
canvas #F4F5FA #0A0D18 Window background (RootView)
surface #FFFFFF #141828 Cards, section bar, status strip, deck and mixer panels
surfaceRaised #EEF0F7 #1D2236 Unlit buttons, knob body, fader cap, selected section tab
well #E3E6F0 #070912 Fader tracks, level-meter background, platter
hairline #DDE0EA #262C42 One-point borders and dividers
textPrimary #0E1222 #F2F4FB Titles, readouts, knob pointer
textSecondary #596078 #A3AAC2 Labels, secondary text
textTertiary #5F657D #9097B0 Captions, placeholders, disabled-looking text
success #0A7446 #34D399 Meter below -6 dB, "audio running", Run buttons
warning #8F5200 #FBBF24 Meter from -6 dB to 0 dBFS, overloads, missing files, time under 30 s
danger #C0283A #FF6B76 Meter above 0 dBFS, clipping, recording, errors
accent #6541E0 #9B7CFF Violet: selection, focus rings, enabled effects, brand mark
accentSecondary #0B6E8A #22D3EE Cyan: limiter chip, beat lamps 2 to 4, Auto DJ status
waveformWell #05070E #05070E Waveform background, identical in both appearances

The asset-catalog AccentColor is a single (universal) sRGB colour with components 0.486, 0.361, 0.988, which rounds to #7C5CFC. It is the system accent for standard AppKit and SwiftUI controls (default buttons, switches, text selection) and sits between the light and dark values of ORIX.Palette.accent; it is not appearance-specific. The same violet appears in Scripts/icon.swift (the glow behind the icon mark) and Scripts/dmg-background.swift.

# 2.2 Deck colours

ORIX.deck(index) returns the colour of a deck. The comment in the source states the rule: letters always accompany the colour.

Deck Index Light Dark Name
A 0 #0B6E8A #22D3EE Cyan
B 1 #B4500F #FF9F43 Orange
C 2 #6541E0 #A78BFA Violet
D 3 and above #0A7446 #4ADE80 Green

Deck A uses the same pair as accentSecondary; deck C shares its light value with accent and uses a lighter violet in dark mode; deck D shares its light value with success.

# 2.3 Hot-cue colours

Eight fixed colours, the same in both appearances, indexed by pad number:

Pad Hex Pad Hex
1 #FF4B3A 5 #22D3EE
2 #FF9F43 6 #4D8DFF
3 #FBBF24 7 #A78BFA
4 #4ADE80 8 #F472B6

They fill a pad when a cue is stored and draw the half-height markers on the overview waveform. The Metal waveform shader carries the same eight colours as constants.

# 2.4 Colours used outside the token file

A few literals appear directly in views. They are listed here so that they are not mistaken for tokens:

Literal Where Use
#FF9F0A DeckView.swift, PerformanceView.swift, WaveformViews.swift CUE button text and border, cue-point marker on the overview
#FBBF24 MixerView.swift, RecordingView.swift Headphone-cue chip, Cue Mix and Phones knobs, trim handles
#C0283A with white text PerformanceView.swift The large Emergency Stop button (same value in both appearances)
Color.black.opacity(0.88) Components.swift and deck/mixer views Text on a lit (filled) control
Color.white at 0.55 and 0.75 opacity WaveformViews.swift Messages and zoom buttons drawn over the waveform

# 2.5 Waveform palettes

The three-band waveform colours are not tokens but a user setting, WaveformPalette in AppSettings.swift, stored under the defaults key ui.palette (default spectrum). Both the Metal scrolling waveform and the Canvas overview read settings.palette.bands.

Case Title in Settings Low Mid High
spectrum Spectrum (red / green / blue) #FF4B3A #3BDC6E #4D8DFF
ember Ember (amber / white / cyan) #FF8A1F #F2F4FB #22D3EE
colorBlindSafe Colour-blind safe (blue / orange / yellow) #0072B2 #E69F00 #F0E442
mono Monochrome #6E7592 #A3AAC2 #F2F4FB

The Appearance tab of Settings shows each palette as three swatches lettered L, M, H on the waveform background. The overview draws the bands as nested outlines scaled 0.94, 0.8 and 0.66 of the half height, so the bands also differ by size, not only by hue.

# 2.6 Computed contrast

The token file carries the comment "Text colours reach at least 4.5:1 (WCAG AA) on canvas, surface and raised surface, in both appearances." The ratios below were computed for this document with the WCAG 2 relative-luminance formula from the hex values above, using a short script (/tmp/orixdj-a11y/contrast.py, not part of the repository). They are arithmetic on the tokens, not measurements of rendered pixels.

Text and status colours on the four backgrounds:

Foreground Light: canvas surface raised well Dark: canvas surface raised well
textPrimary 17.09 18.61 16.35 14.93 17.63 16.04 14.32 18.08
textSecondary 5.72 6.23 5.47 5.00 8.38 7.63 6.81 8.60
textTertiary 5.29 5.76 5.06 4.62 6.68 6.08 5.43 6.85
success 5.36 5.83 5.12 4.68 10.08 9.17 8.19 10.34
warning 5.72 6.22 5.46 4.99 11.61 10.56 9.43 11.90
danger 5.35 5.82 5.11 4.67 7.03 6.39 5.71 7.21
accent 5.70 6.20 5.45 4.97 6.20 5.64 5.04 6.36
accentSecondary / deck A 5.34 5.81 5.11 4.66 10.72 9.76 8.71 11.00
deck B 4.71 5.13 4.50 4.11 9.50 8.64 7.71 9.74
deck C 5.70 6.20 5.45 4.97 7.12 6.48 5.78 7.30
deck D 5.36 5.83 5.12 4.68 11.12 10.12 9.03 11.40

Findings from these numbers:

  • The source comment holds: the three text tokens are at or above 5.06:1 on canvas, surface and raised surface in both appearances. The status and accent colours also clear 4.5:1 on those three backgrounds.
  • The lowest value on the three main backgrounds is deck B (orange) on the light raised surface, 4.50:1. On the light well, deck B falls to 4.11:1.
  • hairline against its neighbours is between 1.14:1 and 1.40:1 in both appearances. Borders are decorative separators; they do not reach the 3:1 that WCAG 1.4.11 asks of a boundary that is the only indication of a control.

Text on lit controls (Color.black.opacity(0.88) composited over the fill):

Fill Light Dark
accent 3.18 6.02
accentSecondary / deck A 3.38 10.00
deck B 3.80 8.91
deck C 3.18 6.84
deck D 3.37 10.25
danger 3.40 6.79
warning 3.16 10.67
textSecondary (crossfader-side selector) 3.14 7.96
#FBBF24 (headphone cue chip) 10.67 10.67
Hot-cue colours 1 to 8 5.74 to 10.67 same

In the light appearance the near-black label of a lit ToggleChip, PadButton, DeckBadge or play button is between 3.14:1 and 3.80:1 on the token fills, below 4.5:1. The deck fills were chosen dark enough to serve as text on light surfaces, which makes them too dark to carry black text. The dark appearance, which is the default (ui.appearance defaults to dark), has no such case.

Other literals:

Pair Ratio
CUE label #FF9F0A on surfaceRaised, dark 7.66
CUE label #FF9F0A on surfaceRaised, light 1.81
Knob arc #FBBF24 on surfaceRaised, dark / light 9.43 / 1.47
White on #C0283A (Emergency Stop in Perform) 5.82
White at 55 % on waveformWell (waveform messages) 6.23
White at 75 % on waveformWell (zoom buttons) 11.17

Waveform band colours on waveformWell (#05070E): Spectrum 6.06 / 11.17 / 6.30; Ember 8.54 / 18.32 / 11.14; Colour-blind safe 3.88 / 8.94 / 15.22; Monochrome 4.43 / 8.71 / 18.32 (low / mid / high). All are graphical elements above 3:1.

The light-appearance results for the CUE label, the amber knob arcs and the lit-control text are recorded as gaps in the accessibility report.

# 3. Spacing, radii and sizes

ORIX.Space (points):

Token Value
xxs 4
xs 8
sm 12
md 16
lg 24
xl 32

ORIX.Radius (points, always with the continuous corner style):

Token Value Used by
chip 6 ToggleChip, PadButton, hot-cue pads, sidebar rows, StudioIconButton
control 8 Section tabs, transport buttons, waveform clip shape, rack buttons
card 14 Panel, deck card, mixer card, effect module

Sizes that are fixed in code rather than tokenised:

Element Size
Main window minimum 1180 x 800, default 1440 x 900
Section bar 44 pt high; section tabs 28 pt high
Status strip 28 pt high, 11 pt text
Knob default 40 pt; 32 pt in mixer strips (28 pt with four decks); 36 pt in effect modules
Fader cap 22 pt (vertical) or 26 pt (horizontal) long; track 6 pt thick
ToggleChip minimum height 24 pt
PadButton default minimum 30 x 26 pt
DeckBadge default 20 pt; corner radius 0.28 of its size; letter 0.6 of its size
Mixer column in Studio 232 pt (two decks) or 300 pt (four decks)

Many views use literal spacings of 2 to 10 pt for dense rows instead of the Space scale; the scale is applied to panel padding and page-level layout.

# 4. Typography

ORIX.Typeface uses the system font throughout (San Francisco); there is no bundled typeface.

Token Definition Use
readout(size) system, semibold, rounded design, monospaced digits, default 28 pt BPM, time, key readouts (called with 13 to 34 pt)
label 10 pt semibold, small caps Knob labels, SectionLabel (which also applies uppercase)
value 12 pt medium, monospaced digits Numeric values in tables and settings
caption 11 pt, monospaced digits Counts, secondary numbers
mono 12 pt, monospaced design Console, masked key, code
title 15 pt semibold Panel titles, empty-state titles

All sizes are fixed point sizes (Font.system(size:)), not text styles. They therefore do not follow a system text-size setting; see the Dynamic Type section of the accessibility report. Numbers that change while music plays use monospaced digits so that readouts do not shift horizontally. The script editor uses NSFont.monospacedSystemFont(ofSize: 12.5, weight: .regular).

# 5. Components

Every reusable control is in Components.swift. The header of that file states the intent: "Every control is keyboard and VoiceOver adjustable and reports its value in words."

# 5.1 Panel

A card: its content on surface, corner radius card, a one-point hairline border, default padding Space.sm, stretched to the available width and leading-aligned. It adds no accessibility semantics of its own.

# 5.2 SectionLabel

A small heading: Typeface.label, textSecondary, uppercase. It takes a LocalizedStringKey. It is plain text for assistive technology and does not carry the header trait.

# 5.3 Knob

A rotary control for a normalised value from 0 to 1.

  • Drawing: a surfaceRaised disc, a 270 degree track in hairline, a value arc in the tint, and a textPrimary pointer. With bipolar set, the arc is drawn from the centre (EQ, filter, trim) instead of from the minimum. The value is therefore shown by arc length and pointer angle, not by colour.
  • Pointer input: vertical drag (160 pt for the full range; holding Shift scales movement by 0.25), scroll wheel (delta / 300), double-click to reset.
  • Keyboard: the knob is focusable. Up and Right add 0.02, Down and Left subtract 0.02, Delete resets. Focus is shown by a 1.5 pt ring in the tint, 3 pt outside the disc.
  • Label and value: the label is always drawn under the knob. The value text is drawn when showsValue is true; dense layouts (the mixer strips) hide it, and it remains in the tooltip (.help) and in the accessibility value.
  • Accessibility: one element (children: .ignore) with the label, the display string as its value, and an adjustable action that steps by 0.05.

ParamKnob is a Knob bound to an engine parameter by ParamAddress: it reads model.position(address) and model.display(address) and writes through model.setPosition and model.reset. The display string comes from the engine, so the spoken value carries its unit.

# 5.4 Fader

A linear control, vertical by default, horizontal on request, for a value from 0 to 1.

  • Drawing: a 6 pt well track, an optional centre mark (centreDetent, used by the crossfader and the tempo fader), and a surfaceRaised cap with a 2 pt line in the tint.
  • Pointer input: dragging the cap moves it; clicking elsewhere on the track jumps there; Shift scales movement by 0.25; scroll wheel; double-click to reset.
  • Keyboard: focusable. Up / Down for a vertical fader, Right / Left for a horizontal one, in steps of 0.02. Focus changes the cap border from hairline to the tint. Unlike the knob, there is no keyboard reset.
  • Accessibility: one element with the label, the display string as value, and an adjustable action of 0.05. The fader draws no label or value of its own; callers place text next to it where needed, and it has no tooltip.

# 5.5 LevelMeter

A peak meter drawn in a Canvas. The linear peak is converted to decibels and mapped from -48 dB to +6 dB. Three segments are filled: success up to -6 dB, warning from -6 dB to 0 dBFS, danger above 0 dBFS, with a one-point textTertiary mark at 0 dBFS. The colour change is doubled by position along the bar and by the fixed 0 dBFS mark. For assistive technology it is one element with a label and a value: the level rounded to whole decibels, or the word "clipping" when the caller passes clipped. It is not interactive.

# 5.6 ToggleChip

A latching button (SYNC, KEY LOCK, QUANT, CUE, LIMIT and others): an optional SF Symbol and an 11 pt semibold title. Off: textPrimary on surfaceRaised with a hairline border. On: near-black text on a fill in the tint. State is shown by the fill inverting the whole chip, and exposed as the isSelected trait plus the accessibility value "on" or "off". It is a standard Button, so it is reachable with full keyboard access and activates with Space.

# 5.7 PadButton

A momentary button with an optional symbol and a verbatim title (digits are monospaced). filled draws it lit, in the same inverted style as a chip that is on; it is used to show the active loop length and the selected crossfader curve. Callers add isSelected when they use filled as state, and add an accessibility label when the title is empty or a symbol such as "×2". Because the title parameter is a String shown with Text(verbatim:), pad titles are not localised.

# 5.8 DeckBadge

A rounded square in the deck colour containing the deck letter, with the accessibility label "Deck A" and so on. It exists so that a deck is never identified by colour alone.

# 5.9 EmptyState

A centred message for empty lists and missing content: a 30 pt light SF Symbol in textTertiary, a title, a message limited to 420 pt wide, and an optional standard button.

# 5.10 FlowLayout

A Layout that places children left to right and wraps to a new line when the row is full (default spacing and line spacing 4 pt). The deck transport, loop and grid rows use it so that controls wrap instead of clipping when four decks share the window. The order of children is preserved, so the reading order for assistive technology matches the visual order.

Control File Notes
StudioIconButton Features/AutomationStudio/AutomationStudioState.swift Toolbar button; the title is always the tooltip and the accessibility label, and is drawn only when showsTitle is set
PaneHeader same file 30 pt header with a SectionLabel and trailing controls
RatingStars Features/Library/LibrarySupport.swift Five star buttons ("1 stars" to "5 stars") inside a "Rating" container with the value "n of 5"
SettingsCard, SettingsRow, SettingsNote, SettingsReadout Features/Settings/SettingsSupport.swift Building blocks of the Settings tabs

# 6. Layout of the main window

RootView is a vertical stack of three regions on the canvas colour:

flowchart TD
    W["Main window (min 1180 x 800)"] --> SB["SectionBar, 44 pt"]
    W --> C["Active section"]
    W --> ST["StatusStrip, 28 pt"]
    SB --> SB1["Brand mark and name"]
    SB --> SB2["Ten section tabs"]
    SB --> SB3["MasterClockReadout"]
    SB --> SB4["RecordIndicator (only while recording)"]
    C --> S1["Studio, Library, Effects, Auto DJ, Automation"]
    C --> S2["Docs, Claude, Record, MIDI, Perform"]
    ST --> ST1["Audio device, DSP load, overloads, clipping"]
    ST --> ST2["Analysis, MIDI, Auto DJ, running automations"]
    ST --> ST3["Emergency Stop"]

Section bar. The brand mark (SF Symbol circle.circle.fill in accent) and the name "ORIX DJ" are hidden from assistive technology. Then one tab per AppSection, in this order, each with a symbol and a title:

Order Case Title Symbol View
1 studio Studio dial.medium StudioView
2 library Library music.note.list LibraryView
3 effects Effects slider.horizontal.3 EffectsView
4 autoDJ Auto DJ arrow.triangle.2.circlepath AutoDJView
5 automation Automation chevron.left.forwardslash.chevron.right AutomationStudioView
6 docs Docs book DocsView
7 claude Claude sparkles ClaudeStudioView
8 recording Record record.circle RecordingView
9 midi MIDI pianokeys MIDIView
10 performance Perform play.square.stack PerformanceView

The selected tab has a surfaceRaised background, semibold text in textPrimary, and the isSelected trait. On the right are the master clock (four beat lamps, the BPM readout and "Master A" or "Free clock") and, only while a recording is running, the red REC capsule with its elapsed time, which is also a button that opens the Record section.

Content. Exactly one section view fills the space between the two dividers.

Status strip. Left to right: audio state (symbol and text: device name, sample rate, buffer frames, output latency, or "Silent mode (no audio device)", or "Audio stopped", or the error text), the DSP load as a percentage, an overload count and a "Clipped" label when they apply; then, right-aligned, the analysis progress, the MIDI device count, the Auto DJ state, the number of running automations, and the Emergency Stop button. Every status item is a symbol with words.

Notice. Transient messages (model.notice) appear as a capsule at the top of the window with a 0.15 s opacity transition. This is the only animation declared in the SwiftUI code.

Studio. StudioView is the default section: a small toolbar (deck count, deck layout, shortcuts to Effects and Perform), then decks on both sides of the mixer, then the compact library browser underneath. With two decks the row is deck A, mixer, deck B. With four decks the left column is A above C, the right column B above D, and the mixer strips are ordered C, A, B, D. A deck has four layouts (DeckMode): Standard, Vinyl (adds the platter), Performance (large hot-cue pads) and Minimal (waveforms and transport only).

Settings is a separate window (Settings scene) with seven tabs: Audio, Mixer, Library, Appearance, AI, Automation, About.

# 7. Appearance

The theme is a setting (ui.appearance: system, dark or light, default dark) applied with preferredColorScheme to the main window and to Settings. A launch option can force it for screenshots. Because every palette colour is a dynamic colour, a theme change needs no view code. The waveform well and the hot-cue colours do not change with the theme, by design, so waveform colours keep the same contrast in both.

# 8. Accessibility rules of the design system

These are the rules the components implement. The accessibility report records how far each screen follows them, and where it does not.

  1. No state by colour alone. A deck is a colour and a letter (DeckBadge). A latching control inverts its fill and exposes on/off. A meter shows level by length and has a fixed 0 dBFS mark. Warnings are a symbol and words ("Clipped", "CLIP" / "OK", "3 overloads", "RECORDING" / "READY"). Waveform bands differ by size as well as hue, and a colour-blind-safe and a monochrome palette are offered.
  2. Every custom control has a label and a value in words. Knobs, faders, meters, the platter and the overview collapse to one accessibility element with accessibilityLabel and accessibilityValue; values carry their unit ("-3.0 dB", "50 % B", "clipping").
  3. Continuous controls are adjustable. Knob, Fader, the platter, the overview waveform and the recording trim handles implement accessibilityAdjustableAction.
  4. Keyboard. Knob and Fader are focusable and respond to the arrow keys; focus is drawn in the control's tint. Buttons are standard SwiftUI buttons. Global actions have menu commands with shortcuts (see the report for the table).
  5. Containers are named. Each deck, each mixer channel, the master strip, the mixer and each effect module is an accessibility container with a label, so a control such as "High" is read in the context "Channel A".
  6. Decorative items are hidden. The brand mark, the beat lamps, flow arrows and separators use accessibilityHidden(true).
  7. Reduce Motion. The design system declares no decorative animation: the only SwiftUI animation is the 0.15 s opacity fade of the notice capsule. Motion in the interface is data (meters, playheads, the scrolling waveform, the rotating platter marker). The code does not read accessibilityReduceMotion; there is therefore no reduced-motion variant of the scrolling waveform. This is stated as a gap in the report.
  8. Not implemented. There is no handling of Increase Contrast or Differentiate Without Colour beyond what the default design already does, and text sizes are fixed.

Nobody has walked the interface with VoiceOver or audited it with Accessibility Inspector; the rules above are verified by reading the code only.

Files main
Menu

Theme