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. hairlineagainst 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
surfaceRaiseddisc, a 270 degree track inhairline, a value arc in the tint, and atextPrimarypointer. Withbipolarset, 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
showsValueis 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
welltrack, an optional centre mark (centreDetent, used by the crossfader and the tempo fader), and asurfaceRaisedcap 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
hairlineto 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.
5.11 Related shared controls outside Components.swift
| 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.
- 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. - 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
accessibilityLabelandaccessibilityValue; values carry their unit ("-3.0 dB", "50 % B", "clipping"). - Continuous controls are adjustable.
Knob,Fader, the platter, the overview waveform and the recording trim handles implementaccessibilityAdjustableAction. - Keyboard.
KnobandFaderare 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). - 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".
- Decorative items are hidden. The brand mark, the beat lamps, flow arrows and separators use
accessibilityHidden(true). - 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. - 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.