Repository Public License
1<!-- ORIX Clean / File: docs/design/design-system.md / Author: Simon-Pierre Boucher / Contact: contact@spboucher.ai -->2# Design system34The tokens and components that the application actually uses. Everything here is taken from5`App/Sources/DesignSystem/Tokens.swift` and `Components.swift`; a value that is not in those files is not a6token.78## Principles910- **System first.** Standard SwiftUI controls, system fonts and text styles, SF Symbols, system materials11 (`.bar`, `.regularMaterial`). The design system adds colour roles, spacing, radii and a small set of12 components; it does not restyle controls.13- **Numbers are content.** Sizes and counts use monospaced digits so columns do not shift.14- **Meaning never depends on colour alone.** Risk levels have distinct shapes; bars always have the value as15 text next to them.16- **Calm.** No alarm styling; a banner states a fact and offers one action.1718## Colour tokens1920All colours are defined as light and dark pairs in sRGB through `Color(light:dark:)`, which resolves against21the current appearance (`.darkAqua` or `.aqua`).2223| Token | Light | Dark | Role |24|---|---|---|---|25| `canvas` | `#F4F5FA` | `#0A0D18` | Window background behind grouped content; map background |26| `surface` | `#FFFFFF` | `#141828` | Cards, progress lines |27| `surfaceRaised` | `#FFFFFF` | `#1B2034` | Folder frames in the storage map |28| `hairline` | `#E3E6EF` | `#262C44` | Borders, bar tracks, small capsules |29| `textSecondary` | `#5A6072` | `#9AA2B8` | Secondary text |30| `textTertiary` | `#8A90A2` | `#6B738C` | Tertiary text, unchecked boxes |31| `accent` | `#0A9E96` | `#2DD4BF` | ORIX Clean accent ("clear water" teal); also the asset-catalogue `AccentColor` and the window tint |32| `accentSecondary` | `#5B5BF0` | `#8484FF` | ORIX family indigo; banners, folder glyphs |33| `low` | `#16A34A` | `#4ADE80` | Low risk |34| `review` | `#D97706` | `#FBBF24` | Review required; low free space on a volume bar |35| `high` | `#DC2626` | `#F87171` | High risk; the permanent-delete button |3637`brandGradient` is a linear gradient from `#2DD4BF` through `#06B6D4` to `#5B5BF0`, top-leading to38bottom-trailing. Primary text uses the system primary colour.3940## Spacing and radii4142| Scale | Values (points) |43|---|---|44| `ORIX.Space` | `xs` 4, `s` 8, `m` 12, `l` 16, `xl` 24, `xxl` 32 |45| `ORIX.Radius` | `s` 6, `m` 10, `l` 14 |4647Cards use radius `l` with continuous corners, banners and progress lines `m`, thumbnails `s`.4849## Typography5051There are no custom type tokens. The components use system text styles: `largeTitle` and `title3` in52onboarding, `title2` for sheet titles and stat values, `title3` semibold for section titles, `headline`,53`callout`, `caption` and `caption2`. Sizes, counts and dates add `.monospacedDigit()`. The storage map draws54labels at fixed sizes (10.5 and 9.5 points) because they are painted in a `Canvas`.5556## Density5758`Density` has two cases, stored under the `density` user default and chosen in Settings.5960| Case | `rowPadding` |61|---|---|62| `comfortable` (default) | 7 |63| `compact` | 3 |6465In 1.0.0 the setting is read by the Large Files list only (`LargeFilesView`), where compact rows also use a66smaller file icon (18 instead of 26 points) and omit the path line; the other lists use fixed spacing.6768## Risk: colour and shape6970| Risk | Title | Colour token | SF Symbol | Shape |71|---|---|---|---|---|72| `low` | Low risk | `low` | `checkmark.circle.fill` | circle with a check mark |73| `review` | Review required | `review` | `eye.circle.fill` | circle with an eye |74| `high` | High risk | `high` | `exclamationmark.triangle.fill` | triangle |7576`RiskBadge` shows the symbol and the title in a capsule tinted at 13 % of the risk colour; its accessibility77label is the title. Deletion outcomes in the results sheet follow the same idea, each with its own symbol:78`trash.circle.fill`, `xmark.bin.circle.fill`, `arrow.uturn.right.circle`, `exclamationmark.octagon.fill`,79`hand.raised.circle.fill`.8081## Storage map palettes8283`MapPalette` assigns a base colour to each `FileCategory`. Two palettes exist; the choice is stored under84`mapPalette`.8586| Category | Symbol | ORIX | Colour-blind friendly |87|---|---|---|---|88| Video | `film` | `#8B5CF6` | `#CC79A7` |89| Audio | `waveform` | `#EC4899` | `#D55E00` |90| Images | `photo` | `#F59E0B` | `#E69F00` |91| Archives | `archivebox` | `#64748B` | `#7F7F7F` |92| Disk images | `externaldrive` | `#0EA5E9` | `#56B4E9` |93| Installers | `shippingbox` | `#EF4444` | `#B34700` |94| Documents | `doc.text` | `#22C55E` | `#009E73` |95| Code | `chevron.left.forwardslash.chevron.right` | `#06B6D4` | `#0072B2` |96| Applications | `app.badge` | `#6366F1` | `#F0E442` |97| Other | `doc` | `#94A3B8` | `#A9A9A9` |9899The colour-blind set is built on the Okabe–Ito palette: seven of its eight colours are used as published100(`#CC79A7`, `#D55E00`, `#E69F00`, `#56B4E9`, `#009E73`, `#0072B2`, `#F0E442`). Okabe–Ito black is not used;101three values were added for the remaining categories (two greys, and a darker orange `#B34700` for installers).102103How the map applies a palette (`StorageMapView.draw`):104105- each level of depth darkens the base colour by 3.5 %, up to seven levels;106- plain folders that are too small to open are drawn in `accentSecondary` at 55 % opacity, aggregated107 "smaller items" cells in `textTertiary` at 45 %;108- labels are white, except on the yellow Applications colour of the colour-blind palette, where they are109 near-black;110- when a search is active, non-matching cells drop to 22 % opacity;111- hover is a white outline with a dark inner line, selection a dashed accent outline, and cells in the cleanup112 selection a dashed white outline.113114The legend in the map footer shows a swatch and the category name for all ten categories.115116## Components117118| Component | Purpose | Notes |119|---|---|---|120| `Card` | Grouped content | `surface` background, `hairline` border, radius `l`, padding `l` |121| `SectionTitle` | Title and optional subtitle | Combined accessibility element with the header trait |122| `RiskBadge` | Risk level | See above |123| `SizeText` | A byte count | `ByteFormat.string`, monospaced digits |124| `ProportionBar` | A fraction | Capsule track and fill, minimum 2 points wide; hidden from accessibility because the value is always given as text beside it |125| `EmptyState` | Nothing to show yet | Symbol, title, message, optional prominent action |126| `InfoBanner` | A fact and one action | `accentSecondary` at 8 % background; never styled as an alarm |127| `ProgressLine` | A running analysis | Title, determinate or indeterminate bar, detail line, optional Cancel |128| `FileIcon` | Finder icon of a path | `NSWorkspace.icon(forFile:)`, hidden from accessibility |129| `Thumbnail` | Quick Look thumbnail | `QLThumbnailGenerator`, falls back to the Finder icon |130| `PathText` | Parent folder of a path | Home abbreviated to `~`, middle truncation, full path in the tooltip |131| `FileMenu` | Context menu for any file | Reveal in Finder, Quick Look, Copy Path |132| `Checkbox` | Selection for cleanup | Plain button with a labelled toggle trait and a Selected / Not selected value |133| `StatTile` | A labelled figure | Combined accessibility element |134135## Layout constants136137| Element | Value |138|---|---|139| Main window | minimum 980 by 620, default 1280 by 820, unified toolbar |140| Sidebar | 190 to 260 points, ideal 212 |141| Cleanup preview sheet | minimum 820 by 600 |142| Results sheet | minimum 780 by 520 |143| Settings window | 640 by 430 |144| Map side list | 260 to 460 points |145146## Appearance147148Light and dark are both supported through the token pairs. Settings offers Match System, Light and Dark149(`appearance` default); the launch argument `-ORIXAppearance` overrides it for tests and screenshots.150151## Not in the system152153- No custom fonts, no custom control styles, no animation tokens. The only explicit animation is the 0.25 s154 transition when the map changes folder, and it is disabled under Reduce Motion.155- No high-contrast token set: contrast changes rely on system controls and materials.156- Contrast ratios of the token pairs have not been measured with an instrument (see `docs/ACCESSIBILITY.md`).157