System package
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| Practice | How it works here |
|---|---|
| Version | system/VERSION (SemVer) + CHANGELOG.md per change |
| Breaking change | class / token / global renames or removals (the 0.1.0 rename sweep is the baseline) |
| Drift guard | python3 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 |
| Review | proposal → 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:
- Split core/patterns.css into per-pattern files for independent adoption.
- Make the chat endpoints configurable (window.chatEndpoints).
- Neutralise example copy so screenshots read generically.
- Sequential/diverging data-viz ramp; icon sprite + disambiguation.
Download / inspect
everything under /system/ is the package| Artifact | Link |
|---|---|
| Token source of truth | tokens.json + served with the DTCG media type |
| Generated CSS | tokens.css |
| Core stylesheets | base.css · patterns.css · scoped.css · reset.css |
| Interaction & migration | INTERACTION.md · MIGRATION.md |
| Core scripts | shell.js · app.js · keyboard-fit.js |
| Examples | shell.html … seven pages |
| Assembler | build.py · patches/ · rename-map.json |