Audit & findings
Normative, historical, proposals — how to read this site
when documents disagree, the normative layer wins — drift between them is a bug- Normative (follow these): spec/rules.json — the enforceable rules; spec/states.json — the component contract matrix; tokens/tokens.json — the token source; INTERACTION.md — the binding interaction standard.
- Historical (decisions and findings): this page, CHANGELOG.md, PROVENANCE.md. Statuses are kept current; nothing here overrides the normative layer.
- Open proposals: spec/proposals/ — draft changes under review, never binding until merged.
Contrast — resolved and enforced
The accent darkened to #0068e0 (4.96:1 on --bg), warning text to #a85708 (4.93:1 on its tint), nav labels now use --text-secondary (#666, 5.74:1), placeholders use --placeholder (#767676, 4.54:1). All text pairs pass; lint rule TDS011 now fails CI if any configured token pair drops below 4.5:1 / 3:1.
Control boundaries — resolved
Form controls now use --border-control (#8f8f8f, 3.23:1) for the 3:1 non-text boundary; the decorative --line border stays light by design. TDS011 covers the control-boundary pair.
Micro-text floor — raised to 12px
0.9.0 raised badges/nav labels/proposal tags and copy/kbd/table-header labels to ≥12px (0.75–0.875rem) at the default 16px root; the compact density keeps them ≥12px at its 15px root.
Spacing — tokenised
tokens.json now publishes 47 spacing steps (main scale + fine/observed) as --space-*; core consumes tokens and lints clean.
All token groups — emitted
Typography, spacing, motion, z-index, shadows, icon sizes, border widths, opacity and a data-viz series are all emitted as custom properties from tokens.json; core consumes semantic aliases only (TDS012).
Off-palette red — removed
The tokenizer mapped the last literal red (#d33) to --status-danger; core contains no raw colour literals.
Dead radius declarations — removed
The nullified 3px/8px radii are gone; radius policy is zero with a documented exception (allowRadius: 50%% for the spinner).
Flow-segment focus ring — fixed
The translucent --focus-ring outline was replaced by the solid --interactive outline (5.18:1), matching the global ring.
Icon system — sprite shipped
174 Lucide glyphs (ISC) ship as icons/sprite.svg with icons.json and size tokens; core consumes the sprite from its icon block. Keep duplicate meanings disambiguated when adding new screens.
Dark mode — shipped
Every colour primitive (and data-viz series) has a dark value; tokens.css emits prefers-color-scheme + [data-theme=dark]; surfaces rise by luminance instead of shadows; forced-colors and print covered.
Extraction gaps — merged and matrix-verified
.px-sw, the armed-delete delegate and the current condition rows are in core; spec/states.json now verifies every component's state selectors in CI, and the rename sweep is checked on every build.
Hard-coded literals — eliminated in core
Core consumes tokens only (0 findings under its own rules, 100/100). The pack-era literal list is kept as history on /foundations/color.
Data-viz ramp — categorical only
The 8-colour categorical series ships with light+dark values and contrast checks, but ordered data (heatmaps, scales) has no sequential/diverging ramp yet.
Distribution — packaged
make package builds dist/triage-design-system-
Coverage matrix
the pack is presentation-only; behaviour columns point at the scripts it ships or the source app it came from| Family | Live at | CSS | Behaviour | Source-app tests |
|---|---|---|---|---|
| Buttons | /components/buttons | base.css .btn/.iconbtn/.seg/.copy | shell.js copy; app.js guardApply | T58 (source app) |
| Forms | /components/forms | base.css inputs/label/fieldset/.savebar | shell.js submit guard docs | T58 |
| Switch | /components/forms#switch | core/base.css (P1 merged) | app.py __triageArmDel sibling (P2) | T58 pins markup |
| Table / list | /components/data | base.css .tbl/.rowacts/.bulkbar/.pager + mcards | page scripts in app | T58/source |
| Badges / chips / dots | /components/data | base.css | — | — |
| Feedback / toast | /components/feedback | base.css .msg/.note/.empty/.toast2 | shell.js toast() | T58 |
| Chat / assistant | /components/chat | base.css chat block + app.js engine | app.js chatEngine + SSE | source app |
| Menus / armed delete | /components/overlays | core/base.css menu + P2 | core/shell.js armed delete | T58 |
| Shell / nav | /components/navigation | base.css shell block | shell.js drawer/menus | source app |
| Patterns ×7 | /patterns/dashboard | patterns.css (labelled sections) | page scripts in app | UX suites in source app |
Layer checklist (research model — statuses updated to 0.12)
| Layer | Verdict for this system | Evidence |
|---|---|---|
| Scope & ownership | Single-app system, one owner (the app repo); no consumed-by matrix | README/PORTING |
| Tokens & foundations | All foundations tokenised and emitted (F4/F5): palette, spacing, type, motion, z-index, shadows, radius; TDS002/TDS005/TDS006/TDS009 guard the layer | /foundations/* |
| Component contract | States documented component-by-component (default/hover/focus/disabled/busy/error/empty/overflow) in components.md + live demos | /components/* |
| Design–code agreement | By construction: the pack is a mechanical extraction (css/base.css ↔ BASE_TMPL). Drift exists only vs later app commits (F11) | pitfalls §14, AUDIT P1/P2 |
| Accessibility | WCAG 2.2 scorecard with measured contrast; all text pairs pass; TDS011/TDS014/TDS015 enforce pairs, alt text and accessible names | /foundations/accessibility |
| Documentation | Complete: INTERACTION.md (binding), MIGRATION.md, PROVENANCE.md, RENAME-MAP.md, tokens.json, docs index | /docs |
| Contribution & release | Versioned (VERSION), packaged (make package), provenance pipeline (PROVENANCE.md); consumer telemetry out of scope by design | /system |
| Product use | The running product here is the skeleton kit itself; no telemetry on copies/detaches | /screens |
Research register (what filled the holes)
all links verified reachable 2026-10-06| Source | Publisher | What it informed |
|---|---|---|
| Design Tokens Format Module 2025.10 (DTCG) | W3C Design Tokens Community Group | tokens.json structure: $value/$type tokens, groups, aliases with {group.token}, application/design-tokens+json media type. The kit has no token file; this portfolio emits one. |
| Easing and duration — Material Design 3 | Google Material | Motion-token comparison: suggested 200–500ms ranges per transition type (enter/exit/on-screen) against the system's 120–400ms values; the motion page's token table. |
| A guide to designing accessible, WCAG-conformant focus indicators | Sara Soueidan | Focus audit: SC 2.4.7 (visible indicator), SC 1.4.11 (3:1 against adjacent colours), SC 2.4.13 (2px perimeter + 3:1 change). Used to score the kit's global :focus-visible ring and input ring. |
| How to Audit a Design System, with a Checklist | Tcules | The audit page's layer checklist (scope/ownership, tokens, component contract, design–code agreement, accessibility, documentation, contribution/release, product use) and the trace-a-component approach. |
| Spacing units | U.S. Web Design System | Spacing-scale comparison: USWDS uses multiples of 8px plus small-step tokens. Informed the spacing page's 2/4px-grid normalisation of the observed values. |
| Naming Tokens in Design Systems | Nathan Curtis | Token-naming guidance (scale + semantic two-tier naming) behind the proposed colour alias tier in tokens.json. |
| Web Content Accessibility Guidelines (WCAG) 2.2 | W3C | Contrast thresholds applied in the colour audit: 4.5:1 normal text, 3:1 large text and non-text UI (1.4.11), 24×24 CSS px minimum target (2.5.8, AA), 44px shown as the kit's own stronger target. |
Where things stand
- Open findings: F13 — add a sequential/diverging ramp for ordered data-viz; F14 residual — a CI metrics trend artifact.
- Open proposals (spec/proposals/): four verification levels with rule-traceable evidence; a formal machine-action provenance contract; splitting core invariants from theme opinions; density and border discipline.
- Resolution log: historical fixes live in CHANGELOG.md; this register keeps current statuses only and is never normative.