Triage design system v0.13.1-experiment
Home / Review / System package

System package

What Triage is made of, how to consume it, how it is versioned, and the path to full decoupling.
The package. Triage ships as a package built and verified by build.py; the artifacts under tokens/ · core/ · examples/ are canonical and hash-tracked, and the package is what products consume. Read the full document at system/README.md or download pieces below.

How a consumer wires it

load order: tokens → base → patterns → scripts; base.css carries no :root
<link rel="stylesheet" href="/tokens/tokens.css">
<link rel="stylesheet" href="/core/base.css">
<link rel="stylesheet" href="/core/patterns.css">  <!-- only what you use -->

<div class="app">
  <aside class="side" id="side">…</aside>
  <div class="main"><main class="content">…</main></div>
</div>
<div class="toasts" id="toasts" aria-live="polite"></div>
<script src="/core/shell.js"></script>
<script src="/core/app.js"></script>

Two consumption paths

scoped.css wraps the components in @layer triage.components { @scope (.triage) { … } }; reset.css is the paired @layer triage.reset (box-sizing + body typography + link colour) and owns the root rem base, so the comfortable/compact density matches the global bundle. Both generated files declare @layer triage.reset, triage.components; so reset never beats a component. Font-face and keyframes stay global (they cannot be scoped); without reset the host owns root sizing/typography, and fall back to base.css where @scope is unavailable.
<!-- global: the whole system -->
<link rel="stylesheet" href="/tokens/tokens.css">
<link rel="stylesheet" href="/core/base.css">

<!-- scoped: only style inside .triage -->
<link rel="stylesheet" href="/tokens/tokens.css">
<link rel="stylesheet" href="/core/scoped.css">
<link rel="stylesheet" href="/core/reset.css">  <!-- pairs with scoped: owns the root rem base -->

<div class="triage"> … components … </div>

Token pipeline

tokens.json (DTCG) is the single source of truth. build.py generates tokens.css from it; core/base.css contains no :root at all. Theming means editing tokens.json and rebuilding — one file, one pipeline, one place for a future design-tool export.

Runtime custom properties come in two tiers: primitives (--bg, --dim, --err, --acc…) and semantic aliases (--surface-page, --text-secondary, --status-danger, --interactive, --ink-panel…). Product code should prefer aliases.

Versioning & change control

suggested lightweight governance for a single-owner system
PracticeHow it works here
Versionsystem/VERSION (SemVer) + CHANGELOG.md per change
Breaking changeclass / token / global renames or removals (the 0.1.0 rename sweep is the baseline)
Drift guardpython3 build.py --check fails if a pre-rename name survives
Provenance.provenance.json records input/output hashes; a pack re-export shows as a diff
Reviewproposal → token/API diff → live demo on this site → version bump → downstream adoption

Decoupling roadmap

Done in 0.2.0: all token groups emitted (incl. dark values); core consumes semantic aliases only and lints 100/100; dark theme, RTL, forced-colors and print covered; dialog/tooltip/popover/spinner + form-error contract; 13 lint rules + component state matrix; package.json + tools/package.py tarball; compliance metrics recorded per run; the repo lives in its own GitHub repository.

Next:

  1. Split core/patterns.css into per-pattern files for independent adoption.
  2. Make the chat endpoints configurable (window.chatEndpoints).
  3. Neutralise example copy so screenshots read generically.
  4. Sequential/diverging data-viz ramp; icon sprite + disambiguation.

Download / inspect

everything under /system/ is the package
ArtifactLink
Token source of truthtokens.json + served with the DTCG media type
Generated CSStokens.css
Core stylesheetsbase.css · patterns.css · scoped.css · reset.css
Interaction & migrationINTERACTION.md · MIGRATION.md
Core scriptsshell.js · app.js · keyboard-fit.js
Examplesshell.html … seven pages
Assemblerbuild.py · patches/ · rename-map.json
Triage Design System v0.13.1-experiment — the central, app-agnostic UI design authority. Source of truth: /tokens/tokens.json. Showcase chrome only: site/.