Triage Design System v0.13.1-experiment

Rules & prohibitions

triage-evolution

Rules

15 enforceable checks

TDS001 · deprecated-name

rule

Uses a pre-Triage (mail-triage era) class, id or global instead of the renamed vocabulary.

fix: Rename via /RENAME-MAP.md (or run: python3 tools/assemble_from_pack.py --apply-map <files>).

severity: error

TDS002 · raw-colour

rule

A colour literal appears where a token exists (palette match = error) or that is not in the palette (off-system colour = warning).

fix: Use var(--token) (prefer semantic aliases: --surface-*, --text-*, --status-*) or add the colour to tokens.json.

severity: warning

TDS003 · non-zero-radius

rule

A non-zero border-radius (CSS property or JS style key).

fix: Remove the radius, or fork the system deliberately by changing the token and deleting the global rule.

severity: error

TDS004 · focus-removed

rule

outline:none / outline:0 without a visible focus replacement in the same rule.

fix: Keep the global ring, or provide :focus-visible with a 2px+ ring or a compensating box-shadow/border change.

severity: error

TDS005 · off-scale-spacing

rule

Margin/padding/gap/inset px values outside the normalised spacing scale.

fix: Snap to the nearest scale value or extend the scale in tokens.json deliberately.

severity: warning

TDS006 · off-token-motion

rule

Transition/animation duration not in the motion token set.

fix: Use a motion duration token value (100/120/150/180/200/240/250/280/400ms).

severity: info

TDS007 · off-ladder-zindex

rule

z-index outside the documented ladder.

fix: Use a ladder value or extend misc.zindex in tokens.json.

severity: info

TDS008 · off-system-font

rule

font-family declaration not using Geist / Geist Mono (or inherit).

fix: Use the system stacks (or var(--mono)), or change the token in tokens.json for a deliberate rebrand.

severity: error

TDS009 · token-override

rule

A project stylesheet redefines a Triage custom property (--bg, --acc, --surface-* …).

fix: Edit tokens/tokens.json and regenerate, or use a distinct non-system variable name for local values.

severity: error

TDS010 · unknown-class

rule

A class used in markup that core.css / patterns.css do not define (opt-in, may be a project class).

fix: Use a system class, or allowlist the project class in .triagerc.json.

severity: info

TDS011 · contrast

rule

A defined token pair fails WCAG contrast (4.5:1 text / 3:1 non-text).

fix: Adjust the token value(s) so the pair meets the threshold, or extend .triagerc.json contrastPairs for intentional exceptions.

severity: error

TDS012 · primitive-use

rule

A product stylesheet consumes a primitive token directly where a semantic alias exists.

fix: Use the alias (e.g. var(--surface-card) instead of var(--card)). Definitions inside tokens.css are exempt.

severity: warning

TDS013 · physical-direction

rule

Physical direction property (margin-left, left:, text-align:left …) instead of logical properties.

fix: Use margin-inline-start/end, padding-inline-*, border-inline-*, inset-inline-*, text-align:start/end.

severity: warning

TDS014 · image-alt

rule

<img> without an alt attribute.

fix: Add alt with a description, or alt="" when the image is decorative.

severity: error

TDS015 · accessible-name

rule

Interactive element with no accessible name (empty button/link, no aria-label), or a positive tabindex.

fix: Add text or aria-label; never use tabindex > 0.

severity: error

Prohibitions

prohibit/rounded-corners

prohibition

Non-zero border-radius anywhere — zero radius is a system policy (enforced globally).

signals: rounded corner, border-radius, rounded edges, soft corners, rounded, corner radius, pill-shaped

prohibit/remove-focus-ring

prohibition

Removing focus outlines without an equivalent visible :focus-visible replacement.

signals: remove focus, remove the focus, hide the outline, no focus ring, disable outline, outline: none, outline none

prohibit/raw-color

prohibition

Raw colour literals where tokens exist; off-palette colours must be added to the token source deliberately, not inlined.

signals:

prohibit/off-system-font

prohibition

Off-system font stacks (Geist / Geist Mono or inherit only).

signals: comic sans, futura, custom typeface, off-system font, different font family, helvetica

prohibit/token-override

prohibition

Redefining a system custom property (--bg, --acc, --surface-*, …) in product CSS.

signals: override the css variable, redefine the token, change --bg, redefine --, override --

prohibit/color-only-status

prohibition

Conveying status by colour alone.

signals: colour only, color only, by colour, by color, colored dot only, coloured dot only

prohibit/custom-confirm-for-entity-delete

prohibition

A confirm() dialog or custom modal to delete a listed entity — entity deletes use the armed two-step pattern instead.

signals: confirm before deleting, popup to confirm delete

prohibit/page-local-toast

prohibition

Page-local toast markup or query-param toasts — the shared toast host owns feedback.

signals: page-local toast, query param toast, query-param toast

prohibit/ad-hoc-chart-colors

prohibition

Chart colours chosen ad hoc instead of the dataviz palette (CVD-checked, greyscale-safe).

signals: chart colors, chart colours, graph colors, graph colours

Fallbacks

Plain content on system surfaces

fallback

Render plain content using the system type scale, spacing roles and layout tokens: system text styles on a system surface, no new visual language, no invented component skin.

scope: layout, content, typography, status

Native control, token-conformant

fallback

If no system control fits, use the platform's native element with minimal token-conformant styling; keep native semantics and degrade without JS.

scope: forms, controls, input

Omit and report

fallback

When nothing sanctioned fits and any fallback would mislead users, omit the feature area rather than inventing canon, and report a gap.

scope: *

Triage Design System · design authority v0.13.1-experiment — rendered live from authorities/triage-evolution; updates when the pack updates.