Spec & enforcement
Rule catalogue — v0.12.1
raw catalogue: /spec/rules.json| ID | Default | Name | Checks | Fix |
|---|---|---|---|---|
| TDS001 | error | deprecated-name | Uses 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>). |
| TDS002 | warning | raw-colour | A 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. |
| TDS003 | error | non-zero-radius | A 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. |
| TDS004 | error | focus-removed | outline: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. |
| TDS005 | warning | off-scale-spacing | Margin/padding/gap/inset px values outside the normalised spacing scale. | Snap to the nearest scale value or extend the scale in tokens.json deliberately. |
| TDS006 | info | off-token-motion | Transition/animation duration not in the motion token set. | Use a motion duration token value (100/120/150/180/200/240/250/280/400ms). |
| TDS007 | info | off-ladder-zindex | z-index outside the documented ladder. | Use a ladder value or extend misc.zindex in tokens.json. |
| TDS008 | error | off-system-font | font-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. |
| TDS009 | error | token-override | A 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. |
| TDS010 | info | unknown-class | A 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. |
| TDS011 | error | contrast | A 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. |
| TDS012 | warning | primitive-use | A 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. |
| TDS013 | warning | physical-direction | Physical 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. |
| TDS014 | error | image-alt | <img> without an alt attribute. | Add alt with a description, or alt="" when the image is decorative. |
| TDS015 | error | accessible-name | Interactive 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 . --strictDogfood
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.