summaryrefslogtreecommitdiff
path: root/Docs/ACCESSIBILITY.md
diff options
context:
space:
mode:
authorChristian Cleberg <[email protected]>2026-07-20 18:16:01 -0500
committerChristian Cleberg <[email protected]>2026-07-20 18:50:57 -0500
commiteb8a0d30da0cc150e95d44bad998c13ee2defc25 (patch)
tree1ad349e302b5b48bbc9f79d17a66bcfc31dace11 /Docs/ACCESSIBILITY.md
parent1e25fb947d3c01fc983b481fff5b064ed82349ab (diff)
downloaddomain-dig-eb8a0d30da0cc150e95d44bad998c13ee2defc25.tar.gz
domain-dig-eb8a0d30da0cc150e95d44bad998c13ee2defc25.tar.bz2
domain-dig-eb8a0d30da0cc150e95d44bad998c13ee2defc25.zip
feat(a11y): semantic colour system (#21 phase 1)
Replaces every hard-coded colour with semantic asset colours that adapt to light, dark, and Increase Contrast. Dark mode stays locked, so this is a pure refactor: the audit reports the same findings before and after. The accent is now blue rather than cyan, per the tech/DNS theme. Why custom values rather than the system palette: every system colour fails WCAG AA in light mode. Measured on white — systemYellow 1.51:1, systemOrange 2.20:1, systemGreen 2.22:1, systemCyan 2.54:1, systemRed 3.55:1. All of them pass in dark mode, which is why the dark-locked app looked fine, and why unlocking light mode was never a matter of deleting .preferredColorScheme(.dark). Every new value clears 4.5:1 as text on its page, its card, and its own 16% badge tint — the way AppStatusBadgeView actually draws it. The accent needed splitting in two. As text on a dark background it must be light; as a fill behind a white label it must be dark. #4DA3FF reads 8.00:1 as text on black but 2.63:1 behind white text, so StatusInfo / AccentColor cover the foreground role and AccentFill covers .borderedProminent. AppOnAccent is the label colour for a solid fill and flips by scheme. Colours live in Shared/Colors.xcassets rather than the app catalog: the Shared folder is already a synchronized group in all three targets, so the widget and share extension pick the palette up with no project-file surgery. AccentColor stays in the app catalog as the global tint — and is now actually defined, having been an empty colorset that silently left system controls rendering in stock blue while custom chrome used cyan. Two deliberate visual changes: orange folds into StatusWarning and pink into StatusCritical. They encoded the same severity as the colours they now share, and both sites also carry a text label. Audit findings drop 15 to 14, and one of the originals turned out to be a phantom: the Inspect contrast failure was the Run button in its disabled state, which WCAG 1.4.3 exempts. testInspectScreen now types a domain first so the audit measures an enabled control. Findings also carry the offending element now, so the remaining clipped-text items name themselves ("No Portfolio Yet", "Search domains") instead of being anonymous.
Diffstat (limited to 'Docs/ACCESSIBILITY.md')
-rw-r--r--Docs/ACCESSIBILITY.md58
1 files changed, 58 insertions, 0 deletions
diff --git a/Docs/ACCESSIBILITY.md b/Docs/ACCESSIBILITY.md
index 1045df9..128bf3f 100644
--- a/Docs/ACCESSIBILITY.md
+++ b/Docs/ACCESSIBILITY.md
@@ -6,6 +6,58 @@ large Dynamic Type, element descriptions, trait correctness, and Dynamic Type
support — the same ground the accessibility pass tracked in
[issue #21](https://github.com/zerolabsco/domain-dig/issues/21) covers.
+## The colour palette
+
+Semantic colours live in `Shared/Colors.xcassets`, which is inside the `Shared`
+file-system-synchronized group and therefore reaches the app, the widget, and
+the share extension automatically. `AccentColor` stays in
+`DomainDig/Assets.xcassets` because it is the system-wide tint resolved via
+`ASSETCATALOG_COMPILER_GLOBAL_ACCENT_COLOR_NAME`.
+
+Use the generated asset symbols — `Color(.statusCritical)`, `Color(.appSurface)`
+— never a literal. `ASSETCATALOG_COMPILER_GENERATE_SWIFT_ASSET_SYMBOL_EXTENSIONS`
+is on, so these are compile-time checked; a typo will not build.
+
+Every value clears WCAG AA (4.5:1) as text on its page, on its card, **and on
+its own 16% badge tint** — the way `AppStatusBadgeView` actually draws it. The
+worst of those three is shown:
+
+| Role | Light | Dark | Worst light | Worst dark |
+| --- | --- | --- | --- | --- |
+| `StatusInfo` / `AccentColor` | `#0000FF` | `#4DA3FF` | 5.50 | 5.85 |
+| `StatusPositive` | `#146C2E` | `#30D158` | 4.65 | 7.32 |
+| `StatusWarning` | `#7A5600` | `#FFD60A` | 4.74 | 9.61 |
+| `StatusCritical` | `#B3261E` | `#FF6961` | 4.51 | 5.54 |
+| `StatusNeutral` | `#5A5A5F` | `#A1A1A6` | 4.92 | 5.88 |
+
+High Contrast variants push further in the same direction. Surfaces
+(`AppBackground`, `AppSurface`, `AppSurfaceElevated`, `AppSeparator`) carry no
+meaning, so they get Any/Dark and, where useful, High Contrast — but no status
+semantics.
+
+Why custom values instead of the system palette: **every** system colour fails
+in light mode. Measured on white — systemYellow 1.51:1, systemOrange 2.20:1,
+systemGreen 2.22:1, systemCyan 2.54:1, systemRed 3.55:1. All of them pass in
+dark mode, which is why the dark-locked app looked fine and why unlocking light
+mode is impossible without this work.
+
+### The accent has two roles, and they conflict
+
+An accent used as **text on a dark background** must be light. The same accent
+used as a **fill behind a white label** must be dark. One value cannot do both:
+`#4DA3FF` reads at 8.00:1 as text on black, but only 2.63:1 behind white text.
+
+So there are two colours:
+
+- `StatusInfo` / `AccentColor` — the accent as *foreground*: text, icons,
+ bordered-button labels, tab bar.
+- `AccentFill` — the accent as a *filled background* behind a label, used by
+ `.borderedProminent`. Stays dark in both schemes so a white label clears AA
+ (8.59:1 light, 7.56:1 dark).
+
+`AppOnAccent` is the label colour for a solid accent fill and flips by scheme —
+white on the light accent, black on the dark one.
+
## Findings are reported, not enforced
The audit surfaces violations that exist today, so failing on all of them would
@@ -85,6 +137,12 @@ pre-commit that blocks every commit. A hook routinely bypassed with
## Notes
+- **Disabled controls are a false positive.** WCAG 1.4.3 exempts inactive
+ components from contrast requirements, but the audit flags them anyway. The
+ Inspect screen's Run button is disabled until a domain is typed, and auditing
+ the empty state reported a contrast failure that was never a real defect —
+ which is why `testInspectScreen` types a domain before auditing. Watch for
+ this before "fixing" a contrast finding on a disabled control.
- Audits retry up to three times. Slower machines can miss the audit's internal
deadline (`Audit failed to complete in time`, code `-56`), which is a tooling
timeout, not an app defect. A screen that still cannot be audited is reported