# Migration guide — 0.6 → 0.12

How to move a product that adopted Triage at **0.6.x** up to **0.12.0**. The
changes are additive plus a few deliberate visual moves; no public class or token
was renamed or removed in this range (`rename-map.json` is unchanged since
0.1.0). Work through the checklist at the end.

If you adopted later than 0.6, skip the sections for versions you already run;
each section is self-contained.

## First: know what is canonical and what is generated

The repository is split in two, and this is the single most useful habit to
adopt:

| Kind | Where it lives | Edit it? |
|---|---|---|
| **Canonical sources** | `src/core/*.css`, `tokens/tokens.json`, `core/components.js`, `core/i18n.js`, `core/shell.js`, `core/app.js`, `spec/*` | **yes** — this is the source of truth |
| **Generated** | `core/base.css`, `core/patterns.css`, `core/scoped.css`, `core/reset.css`, `tokens/tokens.css`, `icons/*`, `brand/*`, `exports/*`, `spec/token-consumers.json` | **no** — regenerate |

- Core stylesheets: edit `src/core/**` then run `python3 build.py core`.
- Tokens: edit `tokens/tokens.json` then run `python3 build.py tokens`.
- `tokens/tokens.css` contains the only `:root` in the system; `core/*.css` carry
  no token definitions of their own.
- `python3 build.py check` fails if any generated file has drifted, and the
  scoped/reset stylesheets are covered by the same drift check.

## 0.7 — core stylesheets are generated

`core/base.css` and `core/patterns.css` are now composed from `src/core/**` by
`tools/build_core.py` instead of being hand-edited pack output. If you copied
`core/base.css` into your app and edited it, move those edits into `src/core/**`
of a fork (or into your own stylesheet) and consume the generated file. Runtime
behaviour is unchanged.

## 0.8 — relative root and token-driven breakpoints

- `--base-size` is emitted and `html{font-size:var(--base-size)}` makes the whole
  `rem` type scale follow a user text-size preference. If you had hard-coded a px
  `html` font-size, remove it so the token wins.
- Breakpoints are substituted at compose time from `misc.breakpoint`; do not
  hard-code `@media (max-width: 767px)` if you extend `src/core/**` — use the
  `{bp-phone}` placeholder.

## 0.9 — comfortable 16px base, compact opt-in, `--fs-table`

This is the migration most products will notice.

- **The design base moves 15px → 16px** and every `--fs-*` step is authored at
  its intended px (body 16, label 13, badges/copy ≥12). Nothing meaningful
  computes below 12px any more.
- **Keep the comfortable default** and let the raised tokens carry the new sizes.
- **If you want the old denser rendering, opt in:** set
  `<html data-density="compact">`. Compact lowers the root to 15px (body ~15px,
  controls/table ~13px) while every label stays ≥12px. Comfortable is the default
  when the attribute is absent.
- **`--fs-table`** is the new table-content role (14px); `.tbl th`/`.tbl td`
  consume it. If you targeted table cell font-size, retarget to `--fs-table`.

## 0.10 — spacing roles, layout dimensions, and reflow (P3b)

- **Semantic spacing roles** are the preferred way to consume spacing:
  `--space-page` (24, page padding), `--space-card` (16, card padding),
  `--space-field` (8, label/field gap and form-field padding) and
  `--space-control` (12, control inline padding). The preferred numeric scale is
  `2/4/8/12/16/24/32/48`; the finer legacy steps remain emitted for
  compatibility but should not be used for new work (`TDS005` flags off-scale
  px).
- **Layout dimensions** are their own group, not spacing: `--layout-sidebar`
  (236), `--layout-content-max` (1160), `--layout-dock` (352). Use them for fixed
  chrome/column widths instead of inventing px.
- **Deliberate visual snaps** (no renames): `.content` page padding 26→24px,
  `.card` horizontal padding 18→16px, `.btn` inline padding 13→12px, and the
  label→field gap 4→8px. If your layouts were tuned to the old numbers, re-check
  spacing.
- **P3b reflow / echo (only where you are affected):** to meet WCAG 1.4.4 at 200%
  text, `.badge`/`.status-chip` now wrap instead of `white-space:nowrap`, and
  `.btn` / bottom-nav links can shrink and wrap (`min-height` + `overflow-wrap`).
  If you relied on a single-line badge or a fixed-width button, expect wrapping
  rather than overflow. The `.proposal` / `.action-row` / `.kv` long-path and
  address wrapping is likewise a content fix, not an API change.

## 0.11 — reference-screen honesty (no consumer API change)

The example screens, dashboard aggregate and phone proposal collapse changed.
Nothing in this release alters a public class, token or behaviour contract;
products are unaffected unless they copied the examples.

## 0.12 — scoped bundle + reset

New, additive consumption paths. `core/base.css` remains the default and its
behaviour is unchanged, so existing global consumers need do nothing.

- **Scoped path** — `core/scoped.css` wraps the component rules in
  `@layer triage.components { @scope (.triage) { … } }`, so nothing outside a
  `.triage` subtree is restyled. `@font-face`/`@keyframes` stay global (they
  cannot be scoped). Pair it with `core/reset.css` (below) so root sizing and
  density match the global bundle.
- **Reset (recommended with the scoped path)** — `core/reset.css` is a minimal,
  global `@layer triage.reset` (box-sizing, body background/text/font, link
  colour) that owns the root rem base. Loaded with `core/scoped.css` it gives
  global parity: the 16px comfortable base and `data-density="compact"` (15px)
  both apply, and the body margin is zeroed.
- **Scoped without the reset** — if you load `core/scoped.css` alone, the host
  owns root sizing/typography: at default density a 16px host root matches the
  global bundle, but `data-density="compact"` has no root effect (the `.triage`
  body/components stay at the host root rather than shrinking to the global
  compact 15px, ~6.7% larger) and the host body margin is kept. Use this only
  when the host deliberately owns root sizing/typography.
- **Layer order** — `@layer triage.reset, triage.components;` is declared in both
  generated files, so reset never overrides a component and the order is robust
  whichever loads first.
- **Browser support** — `@scope` ships in current Chrome/Edge, Safari and
  Firefox; where it is unavailable, fall back to the global `core/base.css` path.

See the scoped quickstart in the [README](README.md) and on `/system`.

## Checklist

- [ ] Regenerate everything: `python3 build.py core && python3 build.py tokens`
      (plus `icons`, `exports`, `brand` if you carry them) and commit the output.
- [ ] Remove any hard-coded `html` font-size; let `--base-size` drive the root.
- [ ] Decide comfortable (default) vs `data-density="compact"` on `<html>`.
- [ ] Replace ad-hoc spacing with `--space-page/card/field/control`; replace fixed
      chrome/column widths with `--layout-*`.
- [ ] Retarget table typography to `--fs-table`.
- [ ] Re-check spacing around `.content`, `.card`, `.btn` and labels after the
      0.10 snaps.
- [ ] Check badges/buttons/proposals at 200% text and at narrow widths after the
      0.10 reflow change.
- [ ] If adopting the scoped path: wrap your markup in `.triage`, load
      `tokens.css` + `core/scoped.css` **+ `core/reset.css`** (the supported
      pairing — it owns the root rem base and compact density), and confirm host
      content outside `.triage` is untouched.
- [ ] Run the lint gate on your product:
      `python3 lint/triage_lint.py /path/to/product --strict`.
