Triage design system v0.13.1-experiment
Home / Review / Spec & enforcement

Spec & enforcement

The normative rule catalogue and how triage-lint measures products against it.
Enforceable, not aspirational. Every rule below is implemented by lint/triage_lint.py and runs in CI. Rule IDs are stable and citable in code review and agent reports. Default severities are the contract; projects tune them in .triagerc.json. The engine is stdlib-only Python and scans CSS, HTML/JSX/Vue/Svelte, JS/TS and template strings.

Rule catalogue — v0.12.1

raw catalogue: /spec/rules.json
IDDefaultNameChecksFix
TDS001errordeprecated-nameUses a pre-Triage (mail-triage era) class, id or global instead of the renamed vocabulary.Rename via /RENAME-MAP.md (or run: python3 tools/assemble_from_pack.py --apply-map <files>).
TDS002warningraw-colourA colour literal appears where a token exists (palette match = error) or that is not in the palette (off-system colour = warning).Use var(--token) (prefer semantic aliases: --surface-*, --text-*, --status-*) or add the colour to tokens.json.
TDS003errornon-zero-radiusA non-zero border-radius (CSS property or JS style key).Remove the radius, or fork the system deliberately by changing the token and deleting the global rule.
TDS004errorfocus-removedoutline:none / outline:0 without a visible focus replacement in the same rule.Keep the global ring, or provide :focus-visible with a 2px+ ring or a compensating box-shadow/border change.
TDS005warningoff-scale-spacingMargin/padding/gap/inset px values outside the normalised spacing scale.Snap to the nearest scale value or extend the scale in tokens.json deliberately.
TDS006infooff-token-motionTransition/animation duration not in the motion token set.Use a motion duration token value (100/120/150/180/200/240/250/280/400ms).
TDS007infooff-ladder-zindexz-index outside the documented ladder.Use a ladder value or extend misc.zindex in tokens.json.
TDS008erroroff-system-fontfont-family declaration not using Geist / Geist Mono (or inherit).Use the system stacks (or var(--mono)), or change the token in tokens.json for a deliberate rebrand.
TDS009errortoken-overrideA project stylesheet redefines a Triage custom property (--bg, --acc, --surface-* …).Edit tokens/tokens.json and regenerate, or use a distinct non-system variable name for local values.
TDS010infounknown-classA class used in markup that core.css / patterns.css do not define (opt-in, may be a project class).Use a system class, or allowlist the project class in .triagerc.json.
TDS011errorcontrastA defined token pair fails WCAG contrast (4.5:1 text / 3:1 non-text).Adjust the token value(s) so the pair meets the threshold, or extend .triagerc.json contrastPairs for intentional exceptions.
TDS012warningprimitive-useA product stylesheet consumes a primitive token directly where a semantic alias exists.Use the alias (e.g. var(--surface-card) instead of var(--card)). Definitions inside tokens.css are exempt.
TDS013warningphysical-directionPhysical direction property (margin-left, left:, text-align:left …) instead of logical properties.Use margin-inline-start/end, padding-inline-*, border-inline-*, inset-inline-*, text-align:start/end.
TDS014errorimage-alt<img> without an alt attribute.Add alt with a description, or alt="" when the image is decorative.
TDS015erroraccessible-nameInteractive element with no accessible name (empty button/link, no aria-label), or a positive tabindex.Add text or aria-label; never use tabindex > 0.

Run it

exit 0 conforms · 1 findings · 2 usage/config
# human report for a product
python3 lint/triage_lint.py /path/to/product

# machine report: findings, counts, per-rule, score 0-100
python3 lint/triage_lint.py /path/to/product --json

# CI gate: any warning fails too
python3 lint/triage_lint.py . --strict

# see the catalogue / restrict rules
python3 lint/triage_lint.py --list-rules
python3 lint/triage_lint.py src --rules TDS001,TDS002,TDS003

Score, suppression and config

Score = max(0, 100 − (errors×8 + warnings×2 + info×0.5)), from spec/rules.json. CI fails on any error; --strict and --max-warnings N tighten it.

Deliberate exceptions use triage-allow TDSxxx on the same or previous line, or triage-disable-file; both belong in review, not in silent overrides.

Per-project config (.triagerc.json): ignore globs, rules severity overrides / off, allowColors, spacingScale, zIndexLadder, allowTokenOverrides, checkUnknownClasses, allowRadius, zIndexLocal (values ≤5 are treated as local stacking), contrastPairs.

Component state matrix

The companion contract for components — the states each must ship and their a11y notes — lives in spec/states.json and is verified against core CSS on every CI run. See the full matrix at /components/catalog.

Agent contract

AGENTS.md is the central authority statement: tokens are the only themable source, components come from core/, the interaction standard is binding, generated files are not hand-edited, and the lint gate must pass before UI work is declared done.

CI wiring for any consumer project:

- uses: actions/setup-python@v5
  with:
    python-version: '3.12'
- run: python3 lint/triage_lint.py . --strict

Dogfood

The system lints its own examples/ at 100/100, zero findings (python3 lint/triage_lint.py . --strict), and python3 build.py check validates token sync, the rename sweep, the rule catalogue and 21 engine unit tests on every CI run.

Triage Design System v0.13.1-experiment — the central, app-agnostic UI design authority. Source of truth: /tokens/tokens.json. Showcase chrome only: site/.