# Design pack audit → Triage status

**Subject:** the mail-triage design pack (`mail-triage-design-system/`,
extracted from `vjsyong/mail-triage @ fd29e794`, 2026-10-02) and **Triage
0.1.0**, the generic system built from it.
**Audit:** 2026-10-06, by an AI design-agent, at the owner's request.
**Method:** read the pack end-to-end; compute contrast with the WCAG 2.x
relative-luminance formula against the served CSS; trace each component family
through tokens → CSS → JS → docs → running render; diff against the source
app's current `master`; then run the full rename sweep and rebuild the system
(`build.py --check`). The live site computes the same numbers at render
time (`/audit`).

## Verdict

The pack is a coherent, unusually well-documented single-app design language.
Its gaps were extraction completeness, tokenisation and four marginal contrast
misses. **Triage 0.1.0 resolves the extraction and tokenisation gaps by
construction** (P1–P3 merged at build time, tokens.json as source of truth,
full rename), leaving the contrast findings and hygiene items as the open
work.

## Measured contrast (WCAG 2.2: 4.5:1 normal text · 3:1 large/non-text)

| Pair | Ratio | Requirement | Result |
|---|---|---|---|
| `--fg` on `--bg` | 20.12 | 4.5 | pass |
| `--fg` on `--card` | 21.00 | 4.5 | pass |
| `--dim` on `--bg` / `--card` | 5.50 / 5.74 | 4.5 | pass |
| `--acc` link on `--card` | 4.55 | 4.5 | pass (marginal) |
| `--acc` link on `--bg` | **4.36** | 4.5 | **fail** (marginal) |
| Focus outline `--acc` on card | 4.55 | 3.0 | pass |
| Focus ring `--focus` composited on card | **1.65** | 3.0 | **fail alone** (F8) |
| `--ok` on card / `--tint-ok` | 5.41 / 5.07 | 4.5 | pass |
| `--warn` on card | 4.67 | 4.5 | pass |
| `--warn` on `--tint-warn` | **4.42** | 4.5 | **fail** (marginal) |
| `--err` on card / `--tint-err` | 5.24 / 4.77 | 4.5 | pass |
| `.note` text `#003a8c` on `--tint-acc` | 9.81 | 4.5 | pass |
| `.nav-label` `#999` on card | **2.85** | 4.5 | **fail** |
| placeholder `#9d9d9d` on card | **2.71** | 4.5 | **fail** |
| terminal green/amber/red on `--codebg` | 11.36 / 11.86 / 7.16 | 4.5 | pass |
| `--panel-dim` on `--panel` | 8.33 | 4.5 | pass |
| border `--line` / `--line2` on card | **1.26 / 1.48** | 3.0 | **fail** (bounds carried by label/shape/focus) |
| chip text `#3f3f46` on card | 10.44 | 4.5 | pass |

## Adversarial review — 0.3.0

Four independent adversarial reviewers (foundations, components, accessibility/platform,
enforcement) audited 0.2.0. Their findings are addressed as follows; the open list is
now explicitly growth, not integrity.

| Finding (0.2) | 0.3 status |
|---|---|
| Tarball missing core JS + fonts | fixed; contents verified at build time |
| Linter crashes on modern CSS / JS hex | fixed + 8 hardening tests |
| rem base off by 6.67% | `html{font-size:var(--base-size)}` (1rem = 16px; `_rem` divides by the same base) |
| Type/spacing tokens unused by core | core consumes fs/space/fw/lh/op tokens; TDS runs on the site too |
| State matrix substring placebo | selector-level verification; missing states shipped |
| Forced-colors focus loss on inputs | fixed; progress/skeleton/tooltip covered |
| Destructive dialog backdrop close / no autofocus | `data-dlg-static`; example autofocus |
| RTL broken transforms | [dir=rtl] overrides for drawer/tooltip/knob/flow/dock |
| Dark shadows / light-only TDS011 | dark shadow values; both themes checked |
| Dataviz status collision + CVD collapse | Okabe–Ito derived, CVD-checked |
| Legacy toast, duplicate copy, 4 scrims, 3 confirms | toast/copy/rail deduped; popover backdrop removed; dialog is the confirm primitive |
| Site not dogfooded (0/100) | site in scope — 24 files at 100/100 |

## Findings and status (0.2)

All 0.1 integrity findings are resolved; the open list is growth, not integrity.

| ID | Finding | Status in 0.2 |
|---|---|---|
| F1 | Four text pairs below 4.5:1 | **resolved** — accent #0068e0 (4.96:1 on --bg), warning #a85708 (4.93:1 on tint), nav labels use --text-secondary (5.74:1), placeholders use --placeholder (4.54:1); enforced by TDS011 |
| F2 | Control boundaries below 3:1 | **resolved** — form controls use --border-control (#8f8f8f, 3.23:1); decorative --line stays light by design |
| F3 | Micro-text 9.6–9.9px | **resolved (0.9.0)** — labels raised to ≥12px at both densities; compact keeps the floor at its 15px root |
| F4 | Spacing untokenised | **resolved** — 47 spacing tokens emitted; core consumes them and lints clean |
| F5 | Missing token groups | **resolved** — typography, spacing, motion, z-index, shadows, sizes, borders, opacity, dark values, data-viz |
| F6 | Off-palette red #d33 | **resolved** — mapped to --status-danger |
| F7 | Dead radius declarations | **resolved** — removed; allowRadius documents the spinner circle |
| F8 | Flow-segment focus ring 1.65:1 | **resolved** — solid --interactive outline |
| F9 | Duplicate icons, no sprite | **resolved (0.4.0)** — 174-glyph Lucide set, sprite + registry + individual files, duplicate-path detection in CI, old names aliased |
| F10 | No dark mode | **resolved** — dark values per primitive + prefers-color-scheme/[data-theme]; surfaces rise instead of shadows |
| F11 | Extraction gaps (.px-sw/arm-del/cond-rows) | **resolved** — merged in core; spec/states.json verifies state selectors in CI |
| F12 | Hard-coded literals | **resolved in core** — 0 findings under the repo's own rules (100/100); TDS002/TDS009/TDS012 hold consumers to it |
| F13 | No sequential/diverging dataviz ramp | **partly resolved (0.3)** — categorical series re-derived from Okabe–Ito and CVD-checked; ordered ramp still open |
| F14 | Distribution manual | **resolved** — package.json + verified tarball (core JS/fonts included) + metrics artifacts in CI |

## Research register (hole-filling)

| Source | Used for |
|---|---|
| W3C DTCG, *Design Tokens Format Module 2025.10* — designtokens.org | tokens.json structure (`$value`/`$type`, groups, aliases), `application/design-tokens+json`, alias-tier recommendation |
| Material Design 3, *Easing and duration* — m3.material.io | motion-token comparison and the derived durations/easings |
| Sara Soueidan, *Accessible focus indicators* (SC 2.4.7 / 1.4.11 / 2.4.13) + WCAG 2.2 | focus audit; 3:1 / 2px-perimeter model; 24×24 target minimum |
| Tcules, *How to audit a design system* | the layer checklist (scope → tokens → component contract → design/code agreement → a11y → docs → release → product use) |
| USWDS *Spacing units* | 8px-multiple model vs the observed 4px-grid distribution |
| Nathan Curtis, *Naming tokens in design systems* | two-tier (primitive + semantic) alias design |

## Limitations

- The audit reads the pack/system CSS; it does not exercise a product backend
  (the system is presentation + UI engine by design).
- Contrast pairs are representative, not exhaustive; every literal is listed on
  `/foundations/color`.
- The rename sweep is mechanical and reviewed by `--check` + live rendering; a
  semantic review of each renamed pattern is still worthwhile before external
  adoption.
