origam 2.16.0 → 2.17.1

package/CHANGELOG.md

@@ -1,10 +1,15 @@
 # origam — Changelog
 
-This changelog tracks releases of the `origam` package itself. Token-value
-churn (Tokens Studio sync from Figma, semantic primitive shifts) lives in
-[`tokens/CHANGELOG.md`](./tokens/CHANGELOG.md) — keep them separate so
-"the design moved" never blocks a release of "the code shipped a new
-component".
+This changelog tracks releases of the `origam` package itself.
+
+⛔ It used to point token-value churn at `tokens/CHANGELOG.md`, on the
+grounds that "the design moved" should never block a release of "the code
+shipped a new component". That file no longer exists: the Style Dictionary
++ Tokens Studio pipeline, and the whole `packages/ds/tokens/` tree with it,
+were removed on 2026-08-31. Token values are now hand-maintained directly in
+`packages/ds/src/assets/css/tokens/*.css` and their SCSS twins, so a token
+change is an ordinary code change and belongs in the sections below like any
+other.
 
 Format inspired by [Keep a Changelog](https://keepachangelog.com).
 This project follows [Semantic Versioning](https://semver.org).
@@ -13,6 +18,782 @@ This project follows [Semantic Versioning](https://semver.org).
 
 ## [Unreleased]
 
+## [2.17.1] - 2026-09-14
+
+Hotfix. Quatre correctifs, **aucune rupture d'API**. Trois des quatre ont
+invalidé le diagnostic du ticket qui les demandait — les causes réelles sont
+consignées ci-dessous, parce qu'elles sont plus instructives que les correctifs.
+
+### Fixed
+
+- **`border` / `outlined` sur les champs ne coupe plus le label flottant** (#726).
+  La hiérarchie DOM est l'inverse de ce que les noms suggèrent : `origam-input`
+  est l'élément EXTÉRIEUR, `origam-field` est à l'intérieur. `useBorder` peignait
+  donc un rectangle SANS encoche dont le bord haut traversait le label.
+  `IFieldProps` étend désormais `IBorderProps` et route largeur / style / couleur
+  vers le canal de tokens que lisent les trois pattes `__outline` — l'encoche
+  s'ouvre d'elle-même. Mesure de l'aire d'intersection label × bande de bordure,
+  Chromium : TextField `61,41 px² → 0`, Select sans aucune prop `35,59 px² → 0`,
+  Select `border="thick"` `71,19 px² → 0`.
+  ⚠️ `OrigamSelect` déclare `border: true` dans son propre `withDefaults` : il
+  était donc cassé PAR DÉFAUT, sans qu'un consommateur passe quoi que ce soit.
+  Les 12 consommateurs d'`OrigamInput` ont été audités : 4 emboîtent un field
+  (corrigés), 8 n'en ont aucun et gardent `useBorder` sur leur racine.
+  Les valeurs directionnelles (`border="top"`, `borderBlock`…) ne peignent plus
+  rien sur les champs à encoche : un trait horizontal y couperait le label.
+
+- **Le track de `OrigamSwitch` a de nouveau une bordure par défaut** (#727).
+  Les deux tokens étaient déclarés et LUS PAR PERSONNE — ils figuraient dans la
+  baseline `token-var-channels-dormant`. Changer leurs valeurs seules n'aurait
+  rien produit ; il fallait ajouter la déclaration qui les lit. Défaut :
+  `1px solid var(--origam-color__border---default)`, donc le switch suit le thème
+  actif. Mesure : `0px / none → 1px / solid`. La surcharge reste entière
+  (`border="thick"` → 2px, `border="top"` ramène les autres côtés à 0).
+
+- **`OrigamMasonry` patche ses enfants au lieu de les reconstruire** (#735).
+  `:is="{ render: () => child }"` reconstruisait un objet littéral à CHAQUE passe
+  de rendu : Vue voyait un type différent et détruisait / recréait tout le
+  sous-arbre. Mesure Chromium sur UN SEUL redimensionnement, 9 enfants :
+  117 nœuds ajoutés, 117 retirés, 0 enfant conservant son nœud DOM. Les enfants
+  perdaient focus, scroll, lecture média, transitions et état de composant, et
+  rejouaient leurs `onMounted`. Corrigé par `:is="child"` — branche `isVNode` de
+  `createVNode`. Survivants `0/9 → 9/9`. Présent depuis la naissance du
+  composant (2026-05-15), ce n'est pas une régression.
+
+- **`OrigamVirtualScroll` rend de nouveau** (#736).
+  L'erreur `$setup.convertToUnit is not a function` désignait la victime, pas le
+  coupable : `convertToUnit` était bien importé ET exposé. `items?` était
+  optionnelle SANS défaut, `useVirtual` lit `items.value.length` synchroniquement
+  dans le `setup()`, le setup tombait, Vue n'assemblait jamais `__returned__`, et
+  le template échouait sur le premier symbole rencontré. Corrigé par
+  `items: () => []`. La doc annonçait déjà ce défaut — elle dit enfin vrai.
+  Balayage : 0 composant sur 218 appelle un symbole absent de son setup ;
+  sur la famille réelle (prop optionnelle lue sans garde), 35 → 34, les 34
+  restants étant 18 refus délibérés et 16 props `required: true`.
+
+
+## [2.17.0] - 2026-09-14
+
+> ### ⛔ DÉROGATION ASSUMÉE — cette version MINEURE porte 8 ruptures d'API
+>
+> Le versioning sémantique, et la règle de ce dépôt (`CLAUDE.md`, « Work
+> priorities and versioning »), imposent une **majeure** pour une rupture.
+> Les 8 entrées `⚠️ BREAKING` ci-dessous en sont, et elles sortent malgré
+> tout en `2.17.0`.
+>
+> **C'est une décision explicite du mainteneur**, prise le 2026-09-14 après
+> que la recommandation inverse (`3.0.0`, ou `3.0.0-rc.1` validée par le
+> site marketing) lui ait été présentée avec ses conséquences.
+>
+> **Ce que ça implique concrètement** : un consommateur épinglé en
+> `^2.16.0` reçoit ces 8 ruptures **automatiquement**, sans action de sa
+> part, et son build peut casser sans avertissement. Les recettes de
+> migration sont dans chaque entrée ci-dessous — il n'y a pas de
+> `docs/migration/v2-to-v3.md`, la ROADMAP le prévoyait pour une v3.
+>
+> Suivi de remédiation : voir le ticket ouvert le jour de cette release.
+
+
+### ⚠️ BREAKING — aspect ratio now uses CSS `aspect-ratio`; an explicit `height` also constrains the width
+
+`<OrigamResponsive>`, `<OrigamImg>`, `<OrigamCarouselItem>` and `<OrigamVideo>`
+held their ratio through a `__sizer` child (`padding-block-end` as a
+percentage) paired with a pull-back `margin-block-start: -N%` on `__content`.
+That pair is replaced by the native `aspect-ratio` property.
+
+**Why it had to change.** The pull-back margin cancelled the sizer's own
+contribution to the container height — but only when the default slot was
+filled (`__content` is `v-if="slots.default"`). `<OrigamImg>` renders into
+`#additional`, never `#default`, so it never emitted the margin and appeared
+healthy. Measured in Chromium, parent `max-width: 480px`:
+
+| case | before | after |
+|---|---|---|
+| `<OrigamResponsive>` 16/9 | **`480 × 26`** | **`480 × 270`** |
+| `<OrigamResponsive>` prop `aspectRatio` 16/9 | aspect **1.473** | aspect **1.778** |
+| `<OrigamResponsive>` prop `aspectRatio` 4/3 | aspect **1.070** | aspect **1.334** |
+| `<OrigamImg>` (3 cases) | — | **identical to the pixel** |
+| `<OrigamCarouselItem>` | `596 × 500` | `596 × 500` |
+
+Both ratios resolved to the **same height** before: the `aspectRatio` prop of
+`<OrigamResponsive>` did nothing at all.
+
+**What changes for you.** `aspect-ratio` resolves the *missing* axis in both
+directions; the padding hack could only derive height from width. An explicit
+`height` therefore now constrains the width too:
+
+```
+height: 120px on a 16/9 box    before: 480 × 120    after: 213.33 × 120
+```
+
+**Migration** — if you set a height and want the full width (a banner, for
+instance), set the width explicitly as well:
+
+```vue
+<origam-responsive :aspect-ratio="16 / 9" height="120px" width="100%"/>
+```
+
+This was a deliberate decision: the component's job is to hold its ratio, and
+honouring it in both axes is the faithful behaviour. Measured:
+`height` + `width: 400px` renders `400 × 120`.
+
+**Removed:** the `__sizer` child and its SCSS rule, `contentStyles` (the
+pull-back margin), the 4 `__sizer` tokens across the 4 token sheets, and the
+dead `.origam-img--booting :deep(.origam-responsive__sizer)` rule with its
+local token. The `aspect-ratio-{default,square,portrait}` tokens stay —
+already dormant beforehand, separate debt.
+
+`<OrigamVideo>` was a fourth consumer, not listed in the ticket. It carried a
+`test.fail` describing this exact fix word for word; removed, the test passes.
+
+### ⚠️ BREAKING — `inline` removed from `IResponsiveProps` (so from `<OrigamResponsive>`, `<OrigamImg>`, `<OrigamCarouselItem>`)
+
+**The prop made the component disappear.** It is not a tuning problem, it is
+a design contradiction: `inline` painted `display: inline-flex`, which makes
+the root resolve its width *shrink-to-fit*. `<OrigamResponsive>` holds its
+aspect ratio through a `__sizer` whose height is a `padding-block-end`
+expressed as a **percentage** — and percentages resolve against the **width**.
+Width `auto` → `0` → padding `0` → height `0`.
+
+Measured in Chromium against Histoire (one story rendering the three
+consumers side by side, `aspect-ratio` 16/9, parent `600px`, **no explicit
+width** — the realistic case), bounding box of the rendered content and the
+sizer's resolved `padding-block-end`:
+
+| Component | `inline` off | `inline` on |
+|---|---|---|
+| `<OrigamResponsive>` | `600 × 0`, sizer `337.5px` | **`0 × 0`**, sizer `0px` |
+| `<OrigamImg>` | `600 × 338`, sizer `337.5px` | **`0 × 0`**, sizer `0px` |
+| `<OrigamCarouselItem>` | `600 × 500`, sizer `1054.69px` | **`0 × 500`**, sizer `0px` |
+
+All three collapse the **width** to `0`. On `<OrigamCarouselItem>` the height
+survives only because the carousel imposes it (`height: inherit` on the
+slide) — the image is still `0` wide, so still invisible.
+
+The two stories that appeared to demonstrate the prop both passed an explicit
+`:width`/`:height` alongside it (`40px`), which is precisely the workaround
+the collapse forces. The e2e test that covered it asserted only that
+`display` *contained* `"inline"` — a bar a plain `inline` clears too — so it
+never measured the consequence.
+
+**Removed:**
+
+- `inline?: boolean` from `IResponsiveProps` (reaches `IImgProps` and
+  `ICarouselItemProps` by extension);
+- the `.origam-responsive--inline` modifier class and its SCSS rule in
+  `OrigamResponsive.vue`;
+- the two now-dead tokens `--origam-responsive--inline---display` and
+  `--origam-responsive--inline---flex`, in `light.css`, `dark.css` (both the
+  `[data-theme="dark"]` block and the `prefers-color-scheme` one),
+  `_light.scss`, `_dark.scss`, and the regenerated `main.css`. They were
+  never listed in `tokens.type.ts`, so nothing to remove there;
+- `'inline'` from the `pick(...)` whitelist `OrigamImg` forwards to
+  `<origam-responsive>`;
+- the story controls (Img `Functional` + `Default`, Responsive `Functional` +
+  `Default`) and the Responsive `Prop — inline` Variant;
+- the doc sections and rows (`OrigamResponsive.md` "Inline mode", props
+  interface, anatomy, token table; `OrigamCarouselItem.md` props row);
+- the marketing API-reference seed entries for `responsive` (prop, anatomy
+  class, playground switch, "Inline mode" example).
+
+**Migration:** nothing to do in the common case. A leftover `inline`
+attribute is no longer a declared prop, so it falls through to `$attrs` and
+lands on the root `<div>` as an inert HTML attribute — measured, mount + one
+tick: `<div id="origam-responsive-v-0" class="origam-responsive"
+inline="true">`. It paints nothing, and no pixel moves, because the prop
+already painted a zero-sized box. The root simply goes back to
+`display: flex`, i.e. block-level in the flow instead of an invisible inline
+box.
+
+⛔ **Not offered here: a "wrap it in an inline-block" recipe.** It was tried
+and **measured wrong**, so it is not documented as a workaround: a bare
+`<OrigamResponsive aspect-ratio="1/1">` inside a
+`<span style="display:inline-block;width:40px">` renders `40 × 0` — the sizer
+resolves correctly (`padding-block-end: 40px`) but the root box does not take
+its height. That is a **separate, pre-existing** behaviour of
+`<OrigamResponsive>` used standalone, unrelated to `inline` and unchanged by
+this removal — measured identically before it, with `inline` off: `Design`
+`480 × 26` for a sizer of `480 × 270`, `Slots - Default` idem. `<OrigamImg>`
+is unaffected (`600 × 338`), because it sets its own height. Opened as
+**#709**, not fixed here.
+
+Tracked as **#703**.
+
+### ⚠️ BREAKING — `label` removed from `IValidationProps` (so from `<OrigamInput>`)
+
+**No rendered output changes.** The prop painted nothing: measured at mount
+plus one tick with `label="PROBE_LABEL"`, `<OrigamInput>` produced **zero**
+`<label>` elements. What changes is the type — `<origam-input label="…">` is
+no longer a declared prop and now falls through to `$attrs`.
+
+A validation mixin has no display surface. `useValidation` never read
+`label`, and the one component whose prop set comes from this mixin —
+`<OrigamInput>` — is layout chrome: a four-area grid (prepend / control /
+append / messages) whose accessible name belongs to the control handed in
+through its `#default` slot, not to the wrapper `<div>`.
+
+The two alternatives were tried and **measured wrong**, not argued away:
+
+- **Wiring it** would have given six components a DUPLICATE label. Each
+  already renders its own — Checkbox 1, Switch 1, TextField 2 (static +
+  floating), RatingField 1, SliderField 1, RadioGroup 1.
+- **Warning on it** fired on `<OrigamCheckbox label>`, `<OrigamTextField
+  label>` and `<OrigamSwitch label>` — **correct** calls. Each forwards its
+  own props into `<origam-input>` through `filterProps`, which carries
+  exactly the keys the wrapper declares. Dropping the declaration is what
+  stops that forwarding at its source.
+
+**Migration:** none for the six components above — they keep their `label`,
+which now lives on the interfaces whose components actually render one:
+`IFieldProps`, `ISelectionControlProps`, `ISliderFieldProps`, and
+`IRatingFieldProps` (added here, since the mixin was its only source).
+A consumer passing `label` to a bare `<origam-input>` was passing a no-op and
+should move it to the control inside the slot.
+
+### ⚠️ BREAKING — `<OrigamContainer>` breakpoint `max-width` scale realigned to the design tokens
+
+The component's responsive `max-width` ladder was hardcoded as SCSS literals
+(`900/1200/1800/2400px`) that had silently drifted away from
+`component/container.json`'s `max-width-{md,lg,xl,xxl}` tokens
+(`768/992/1280/1440px`) — the token file even carried its own comment
+flagging the gap. The fix makes the component read the tokens (with a
+matching literal fallback), which is a **visible breakpoint-value change**
+for every consumer, not a null-op:
+
+| Min viewport | Old `max-width` | New `max-width` |
+|---|---|---|
+| `>= 960px` | `900px` | `768px` |
+| `>= 1280px` | `1200px` | `992px` |
+| `>= 1920px` | `1800px` | `1280px` |
+| `>= 2560px` | `2400px` | `1440px` |
+
+The viewport thresholds themselves (`960/1280/1920/2560px`) are unchanged —
+only the resulting `max-width` at each rung. A 5th token,
+`max-width-sm` (`576px`), is declared in the same token file but was
+**not** wired into the ladder: `OrigamContainer`'s own doc has always
+documented `< 960px → 100%` (no cap), never a `576px` tier — the token
+stays dormant by design (naming-scale completeness with the Bootstrap-style
+`sm/md/lg/xl/xxl` set, not a missing rung).
+
+Any consumer relying on the exact prior pixel values (custom layouts tuned
+to `900/1200/1800/2400px` breakpoints) should audit their layout after
+upgrading.
+
+### ⚠️ BREAKING — 88 dead typography (component, prop) pairs removed across 40 components
+
+`useTypography(props, prefix)` writes an inline CSS custom property per
+typography prop passed (`fontFamily` / `fontSize` / `fontWeight` /
+`lineHeight` / `letterSpacing`) — but writing the variable paints nothing
+until some stylesheet rule reads it back. Issue #501 measured 94 (component,
+prop) pairs across 40 components where no rule ever did: typed, offered by
+autocompletion, documented — and completely inert. The arbitrated fix is the
+opposite of wiring 94 SCSS rules to force an effect: these props are
+**removed** from the components that never painted them. `fontSize` is
+untouched everywhere (98 % already painted); it was never part of this cut.
+
+**The real count is 88, not 94** — re-measuring found the ticket's own
+scanner had 2 false positives, both from the SAME blind spot: it checks
+whether a component's OWN CSS-var prefix is read, but cannot see a prop
+value reaching ANOTHER component's prefix through prop-forwarding.
+`<OrigamField>` forwards its full prop set to a nested `<OrigamLabel>`
+(`useProps().filterProps()`), and `OrigamLabel` has its own
+`useTypography(props, 'label')` call that DOES read `fontWeight` /
+`lineHeight` / `letterSpacing` — confirmed with `@vue/test-utils` +
+`nextTick()` (the forward lands on the second render; `useTypography`'s own
+doc explains why that's still what a real paint sees). `<OrigamTextareaField>`
+forwards to both `<OrigamInput>` and `<OrigamField>` (which forwards again to
+`<OrigamLabel>`), so it inherits the same three, plus `fontSize`, plus a
+second live path: `fontWeight` cascades from `<OrigamInput>`'s own painted
+root `font-weight` into the `mode="rich"` contenteditable div (an ordinary
+CSS-inherited property, unblocked — confirmed via `getComputedStyle` against
+a live Histoire render, 400→700 on both elements). Only `fontFamily` is
+genuinely dead on every path for both components. `OrigamOtpInputField` was
+independently verified NOT to share this leak (it forwards only to
+`<origam-field>` with `label` excluded, so no nested `<OrigamLabel>` renders
+in the default case) — its 4 dead props stand as measured. See
+`packages/ds/scripts/audit-unconsumed-props.mjs` for the parser bug this
+also surfaced (a `Pick<X, 'a' | 'b'>` heritage clause was mis-split on its
+internal comma, corrupting sibling parents — fixed alongside this removal).
+
+**GLOBAL vs SPECIFIC** — the triage the removal follows:
+- **`fontFamily` (37 of the 88) is a project-level setting**: every origam
+  app is wrapped in `<OrigamApp>`, so the font family is configured once,
+  globally — never per component instance. All 37 dead `fontFamily`
+  occurrences are removed without a case-by-case visual-effect argument;
+  the architecture argument alone is sufficient. Migration: set the family
+  via your theme's `vars.typo.family.*` (see
+  `packages/ds/src/themes/origam.theme.ts`), not via a component prop.
+- **`fontWeight` (8) / `lineHeight` (20) / `letterSpacing` (23) are
+  component-specific** and were judged one at a time: a pair is removed
+  only where no stylesheet rule — including through a forwarding chain —
+  ever reads the resulting CSS variable. Migration: there is no drop-in
+  prop replacement; restyle via the component's own semantic tokens
+  (`--origam-{component}---*`) in your theme, or via the component's
+  `color`/`variant`/`density` props where the effect is actually themeable.
+
+**Removed, by component:**
+
+| Component | Removed props |
+|---|---|
+| `OrigamAlert` | `fontFamily` |
+| `OrigamAudio` | `fontFamily`, `letterSpacing` |
+| `OrigamAvatar` | `fontFamily` |
+| `OrigamBadge` | `fontFamily`, `lineHeight`, `letterSpacing` |
+| `OrigamBracket` | `fontFamily`, `lineHeight` |
+| `OrigamBracketCompetitor` | `fontFamily`, `lineHeight`, `letterSpacing` |
+| `OrigamBracketRound` | `fontFamily`, `lineHeight` |
+| `OrigamBtn` | `fontFamily` |
+| `OrigamCardHeader` | `fontFamily` |
+| `OrigamCardText` | `fontFamily`, `lineHeight` |
+| `OrigamChip` | `fontFamily`, `lineHeight`, `letterSpacing` |
+| `OrigamClipboard` | `fontFamily`, `lineHeight`, `letterSpacing` |
+| `OrigamCode` | `fontWeight`, `letterSpacing` |
+| `OrigamCommandPalette` | `fontFamily`, `fontWeight`, `lineHeight`, `letterSpacing` |
+| `OrigamDataList` | `fontFamily` |
+| `OrigamEmptyState` | `letterSpacing` |
+| `OrigamExpansionPanelHeader` | `fontFamily`, `fontWeight`, `letterSpacing` |
+| `OrigamField` | `fontFamily` |
+| `OrigamFileFieldDragNDropItem` | `fontFamily`, `lineHeight`, `letterSpacing` |
+| `OrigamFileFieldListItem` | `fontFamily`, `lineHeight`, `letterSpacing` |
+| `OrigamForm` | `fontFamily` |
+| `OrigamInfiniteScroll` | `fontFamily`, `fontWeight`, `lineHeight`, `letterSpacing` |
+| `OrigamInlineEdit` | `fontFamily`, `lineHeight`, `letterSpacing` |
+| `OrigamInput` | `fontFamily`, `letterSpacing` |
+| `OrigamKbd` | `lineHeight`, `letterSpacing` |
+| `OrigamLabel` | `fontFamily` |
+| `OrigamListItem` | `fontFamily` |
+| `OrigamListSubheader` | `fontFamily`, `letterSpacing` |
+| `OrigamMessages` | `fontFamily`, `fontWeight`, `letterSpacing` |
+| `OrigamOtpInputField` | `fontFamily`, `fontWeight`, `lineHeight`, `letterSpacing` |
+| `OrigamPagination` | `fontFamily`, `lineHeight`, `letterSpacing` |
+| `OrigamPickerTitle` | `fontFamily`, `lineHeight` |
+| `OrigamSnackbarItem` | `fontFamily`, `fontWeight`, `lineHeight`, `letterSpacing` |
+| `OrigamSystemBar` | `fontFamily` |
+| `OrigamTab` | `fontFamily`, `lineHeight` |
+| `OrigamTable` | `fontFamily`, `lineHeight`, `letterSpacing` |
+| `OrigamTextareaField` | `fontFamily` |
+| `OrigamToolbar` | `fontFamily` |
+| `OrigamTooltip` | `fontFamily`, `letterSpacing` |
+| `OrigamVideo` | `fontFamily`, `fontWeight`, `lineHeight`, `letterSpacing` |
+
+**Migration:**
+
+```diff
+- <OrigamBtn font-family="mono">Copy</OrigamBtn>
++ <!-- fontFamily is a project-level setting — configure it once via -->
++ <!-- your theme's vars.typo.family, not per component instance. -->
++ <OrigamBtn>Copy</OrigamBtn>
+```
+
+```diff
+- <OrigamBadge line-height="tight" letter-spacing="wide">3</OrigamBadge>
++ <!-- no drop-in replacement — line-height/letter-spacing on Badge never -->
++ <!-- read a stylesheet rule on any surface. Restyle via a theme override -->
++ <!-- of --origam-badge__badge---line-height / ---letter-spacing directly. -->
++ <OrigamBadge>3</OrigamBadge>
+```
+
+**Not affected** — `OrigamCode` (`fontFamily`/`fontSize`/`lineHeight`
+kept), `OrigamKbd` (`fontFamily`/`fontSize`/`fontWeight` kept), `OrigamTitle`,
+`OrigamBlockquote`, `OrigamTextMask` (fully painted, untouched) all keep
+their full typed surface — every prop on those genuinely reaches a
+stylesheet rule. `OrigamField` / `OrigamTextareaField` keep `fontSize` /
+`fontWeight` / `lineHeight` / `letterSpacing` (see above) — only
+`fontFamily` was removed from either.
+
+Ref: issue #501.
+
+### ⚠️ BREAKING — `activeBgColor` / `hoverBgColor` / `activeColor` / `hoverBgColor` removed
+
+The flat per-state color override props — `activeBgColor`, `hoverBgColor`,
+`activeColor`, `hoverColor` — no longer exist on any component
+(`Pagination`, `Field`, `DataText`, `DataTitle` were the last ones still
+declaring them, all marked `@deprecated`). They were folded into the
+`hover` / `active` object props during the `useStateFlag` refactor, and
+the deprecated flat props were left behind by mistake instead of being
+purged in the same pass.
+
+**Migration** — pass the override as a key on the `hover` / `active`
+object prop instead of a separate flat prop:
+
+```diff
+- <Btn hover-color="success" />
++ <Btn :hover="{ color: 'success' }" />
+
+- <Btn active-color="success" />
++ <Btn :active="{ color: 'success' }" />
+
+- <Card hover-bg-color="success" />
++ <Card :hover="{ bgColor: 'success' }" />
+
+- <Card active-bg-color="success" />
++ <Card :active="{ bgColor: 'success' }" />
+```
+
+(See `packages/ds/src/interfaces/Commons/color.interface.ts` for the
+canonical documentation of this mapping.)
+
+**No functional regression measured**: every real call site was audited
+individually before removal. `Field` was the only component where the
+override still painted something live (focus + active state); its
+`color` / `bgColor` axis now reads from the `active` object instead of
+the removed flat props, with the exact same `isActive && isFocused` gate
+preserved. Every other declared instance (`Pagination`, `DataText`,
+`DataTitle`) had already gone dead independently of this removal —
+either forwarded to a child that no longer read the prop, or gated by an
+`isHover` flag that was never actually toggled — so no visible behaviour
+changes there. `useColorEffect`'s own flat-prop resolution path is also
+removed: its only two real callers (`OrigamAudio`, `OrigamVideo`) never
+declared these props and call the composable without `isHover`/`isActive`
+refs, so the path was unreachable in practice; the only place it was
+still exercised was a unit test using `as any` to bypass the type system.
+
+**Known pre-existing gaps surfaced, not fixed by this change** (tracked
+separately): `OrigamRadio` has no prop that colors the checked glyph
+per active state (only a static `bgColor`); `OrigamSwitch`'s track never
+visually distinguished the active/checked state via the removed props
+either, in this DS version or the marketing themes that configured it.
+
+### ⚠️ BREAKING — `origam/tokens/css/themes-all` and `origam/tokens/scss/themes-all` removed
+
+Both export subpaths, their two generated files
+(`dist/src/assets/css/tokens/themes-all.css`,
+`dist/src/assets/scss/tokens/_themes-all.scss`), and the dead aggregation
+step in `build-tokens.mjs` that produced them are gone.
+
+**Why**: `$themes.json` has held only 2 entries (`light`, `dark`) for a
+while, with zero `<brand>-<mode>` combos — the generator's aggregation
+branch only ran when at least one combo existed, so it had become a
+silent no-op. The ~2.1 MB CSS file and ~2.1 MB SCSS file left on disk
+were a stale hand-edited snapshot from when brand combos still existed,
+not a build output: no `tokens:build` run touched them, and nothing in
+the codebase actually loaded them (`grep`'d for `@import` / `href` /
+`url()` — zero hits; the two "references" found were comments). Shipping
+them cost every install ~4.5 MB of dead weight (`files: ["dist/src/", …]`
+embeds the whole directory) for zero runtime benefit.
+
+**Migration** — anyone who imported the aggregate switches to the
+per-theme sheets, which are current and still generated on every
+`tokens:build`:
+
+```diff
+- import 'origam/tokens/css/themes-all'
++ import 'origam/tokens/css/light'
++ import 'origam/tokens/css/dark'
+```
+
+```diff
+- @use 'origam/tokens/scss/themes-all';
++ @use 'origam/tokens/scss/light';
++ @use 'origam/tokens/scss/dark';
+```
+
+Ref: issue #497.
+
+### ⚠️ BREAKING — 12 unused `tokens/component/*.json` files removed (206 CSS custom properties)
+
+`checkbox`, `checkbox-btn`, `radio`, `select`, `contextual-menu`, `img`,
+`rating-field`, `dialog-confirmation`, `highlight`, `date-picker-field`,
+`lazy` and `transition` are gone from `packages/ds/tokens/component/` and
+from `$themes.json`. Also removed: `qrcode` and `watermark` (handed over
+from #436-A — registered nowhere, zero lines emitted either way) and
+`sound` (same, plus the component itself no longer exists).
+
+**Why**: measured, component by component, that none of the 206 CSS
+custom properties these files declared was read by any component under
+`packages/ds/src`, under any name — not the declared name, not a
+plausible rename, not a nested `var()` fallback. `highlight.json` and
+`sound.json` are more extreme still: `OrigamHighlight` and `OrigamSound`
+do not exist anywhere in the repo (the same shape as the already-closed
+`section.json` precedent). `dialog-confirmation.json`'s target component
+(`OrigamDialogConfirmation`) has no `<style>` block at all. Full
+per-component investigation, including the 3 files that turned out to be
+divergences (real bugs) rather than vestiges and were therefore **not**
+removed, is in #436.
+
+Measured effect on the generated stylesheets:
+
+```
+light.css   187293 → 171736 bytes  (-15557, -8.3%)
+dark.css    380189 → 348663 bytes  (-31526, -8.3%)
+```
+
+**This is a breaking change if you overrode any of these variables** —
+whether from inside this repo (nothing did, verified) or from an external
+consumer we have no visibility into. If you did, the property no longer
+exists; there is no fallback to migrate to, because nothing in the DS
+ever painted with it. The full list, for anyone auditing a diff against a
+previous `origam` version:
+
+<details><summary><code>checkbox.json</code> — 26 variables</summary>
+
+```
+--origam-checkbox---flex
+--origam-checkbox---min-height
+--origam-checkbox---transition-duration
+--origam-checkbox---transition-easing
+--origam-checkbox__icon---color
+--origam-checkbox__icon---color-disabled
+--origam-checkbox__icon---color-error
+--origam-checkbox__icon---color-unchecked
+--origam-checkbox__icon---opacity
+--origam-checkbox__input---background-color
+--origam-checkbox__input---background-color-checked
+--origam-checkbox__input---background-color-disabled
+--origam-checkbox__input---background-color-error
+--origam-checkbox__input---background-color-indeterminate
+--origam-checkbox__input---border-color
+--origam-checkbox__input---border-color-checked
+--origam-checkbox__input---border-color-disabled
+--origam-checkbox__input---border-color-error
+--origam-checkbox__input---border-color-focused
+--origam-checkbox__input---border-radius
+--origam-checkbox__input---border-style
+--origam-checkbox__input---border-width
+--origam-checkbox__input---opacity-disabled
+--origam-checkbox__label---color
+--origam-checkbox__label---color-disabled
+--origam-checkbox__label---color-error
+```
+</details>
+<details><summary><code>checkbox-btn.json</code> — 20 variables</summary>
+
+```
+--origam-checkbox-btn---background-color
+--origam-checkbox-btn---background-color-checked
+--origam-checkbox-btn---background-color-disabled
+--origam-checkbox-btn---background-color-hover
+--origam-checkbox-btn---border-color
+--origam-checkbox-btn---border-color-checked
+--origam-checkbox-btn---border-color-error
+--origam-checkbox-btn---border-radius
+--origam-checkbox-btn---border-style
+--origam-checkbox-btn---border-width
+--origam-checkbox-btn---color
+--origam-checkbox-btn---color-checked
+--origam-checkbox-btn---color-disabled
+--origam-checkbox-btn---font-size
+--origam-checkbox-btn---font-weight
+--origam-checkbox-btn---opacity-disabled
+--origam-checkbox-btn---padding-block
+--origam-checkbox-btn---padding-inline
+--origam-checkbox-btn---transition-duration
+--origam-checkbox-btn---transition-easing
+```
+</details>
+<details><summary><code>radio.json</code> — 23 variables</summary>
+
+```
+--origam-radio---opacity-disabled
+--origam-radio__dot---background-color
+--origam-radio__dot---background-color-disabled
+--origam-radio__dot---background-color-error
+--origam-radio__dot---border-radius
+--origam-radio__dot---scale-from
+--origam-radio__dot---scale-to
+--origam-radio__dot---size
+--origam-radio__input---background-color
+--origam-radio__input---background-color-disabled
+--origam-radio__input---border-color
+--origam-radio__input---border-color-checked
+--origam-radio__input---border-color-disabled
+--origam-radio__input---border-color-error
+--origam-radio__input---border-radius
+--origam-radio__input---border-width
+--origam-radio__input---size
+--origam-radio__input---transition-duration
+--origam-radio__label---color
+--origam-radio__label---color-disabled
+--origam-radio__label---color-error
+--origam-radio__label---font-size
+--origam-radio__label---padding-inline
+```
+</details>
+<details><summary><code>select.json</code> — 39 variables</summary>
+
+```
+--origam-select---min-width
+--origam-select---no-data-color
+--origam-select---no-data-font-size
+--origam-select---no-data-padding
+--origam-select---no-data-text-align
+--origam-select__chevron---color
+--origam-select__chevron---color-active
+--origam-select__chevron---transition-duration
+--origam-select__chevron---transition-timing-function
+--origam-select__chip---background-color
+--origam-select__chip---border-radius
+--origam-select__chip---color
+--origam-select__chip---gap
+--origam-select__chip---max-width
+--origam-select__chip---padding-block
+--origam-select__chip---padding-inline
+--origam-select__item---background-color
+--origam-select__item---background-color-active
+--origam-select__item---background-color-hover
+--origam-select__item---background-color-selected
+--origam-select__item---color
+--origam-select__item---color-selected
+--origam-select__item---min-height
+--origam-select__item---opacity-disabled
+--origam-select__item---padding-block
+--origam-select__item---padding-inline
+--origam-select__item---transition-duration
+--origam-select__list---background-color
+--origam-select__list---border-radius
+--origam-select__list---box-shadow
+--origam-select__list---color
+--origam-select__list---max-height
+--origam-select__list---padding-block
+--origam-select__list---padding-inline
+--origam-select__list---z-index
+--origam-select__search---background-color
+--origam-select__search---border-bottom-color
+--origam-select__search---padding-block
+--origam-select__search---padding-inline
+```
+</details>
+<details><summary><code>contextual-menu.json</code> — 16 variables</summary>
+
+```
+--origam-contextual-menu---background
+--origam-contextual-menu---border-radius
+--origam-contextual-menu---box-shadow
+--origam-contextual-menu---color
+--origam-contextual-menu---max-height
+--origam-contextual-menu---offset-bottom
+--origam-contextual-menu---offset-left
+--origam-contextual-menu---offset-right
+--origam-contextual-menu---offset-top
+--origam-contextual-menu---position
+--origam-contextual-menu---transition-duration
+--origam-contextual-menu---transition-timing-function
+--origam-contextual-menu---z-index
+--origam-contextual-menu__content---max-width
+--origam-contextual-menu__content---overflow
+--origam-contextual-menu__content---padding
+```
+</details>
+<details><summary><code>img.json</code> — 14 variables</summary>
+
+```
+--origam-img---background-color
+--origam-img---border-radius
+--origam-img---border-radius-circle
+--origam-img---border-radius-rounded
+--origam-img---color
+--origam-img---opacity-loaded
+--origam-img---opacity-loading
+--origam-img---transition-duration
+--origam-img---transition-timing-function
+--origam-img--error---background-color
+--origam-img--error---color
+--origam-img__placeholder---background-color
+--origam-img__placeholder---color
+--origam-img__placeholder---font-size
+```
+</details>
+<details><summary><code>rating-field.json</code> — 13 variables</summary>
+
+```
+--origam-rating-field---gap
+--origam-rating-field---opacity-disabled
+--origam-rating-field---transition-duration
+--origam-rating-field__item---color
+--origam-rating-field__item---color-active
+--origam-rating-field__item---color-disabled
+--origam-rating-field__item---font-size
+--origam-rating-field__item---scale-active
+--origam-rating-field__item---scale-hover
+--origam-rating-field__item---transition-duration
+--origam-rating-field__label---color
+--origam-rating-field__label---font-size
+--origam-rating-field__label---padding-inline
+```
+</details>
+<details><summary><code>dialog-confirmation.json</code> — 12 variables</summary>
+
+```
+--origam-dialog-confirmation---actions-gap
+--origam-dialog-confirmation---description-color
+--origam-dialog-confirmation---description-font-size
+--origam-dialog-confirmation---icon-color-danger
+--origam-dialog-confirmation---icon-color-default
+--origam-dialog-confirmation---icon-color-info
+--origam-dialog-confirmation---icon-color-success
+--origam-dialog-confirmation---icon-color-warning
+--origam-dialog-confirmation---icon-size
+--origam-dialog-confirmation---title-color
+--origam-dialog-confirmation---title-font-size
+--origam-dialog-confirmation---title-font-weight
+```
+</details>
+<details><summary><code>highlight.json</code> — 12 variables</summary>
+
+```
+--origam-highlight---background-color
+--origam-highlight---border-radius
+--origam-highlight---color
+--origam-highlight---font-weight
+--origam-highlight---padding-block
+--origam-highlight---padding-inline
+--origam-highlight--danger---background-color
+--origam-highlight--danger---color
+--origam-highlight--info---background-color
+--origam-highlight--info---color
+--origam-highlight--success---background-color
+--origam-highlight--success---color
+```
+</details>
+<details><summary><code>date-picker-field.json</code> — 6 variables</summary>
+
+```
+--origam-date-picker-field---max-width
+--origam-date-picker-field---menu-offset
+--origam-date-picker-field---min-width
+--origam-date-picker-field__icon---color
+--origam-date-picker-field__icon---color-error
+--origam-date-picker-field__icon---color-hover
+```
+</details>
+<details><summary><code>lazy.json</code> — 4 variables</summary>
+
+```
+--origam-lazy---placeholder-background-color
+--origam-lazy---placeholder-min-height
+--origam-lazy---transition-duration
+--origam-lazy---transition-timing-function
+```
+</details>
+<details><summary><code>transition.json</code> — 21 variables</summary>
+
+```
+--origam-transition---dialog-bottom-duration
+--origam-transition---dialog-bottom-easing
+--origam-transition---dialog-bottom-translate-distance
+--origam-transition---slide-x-duration
+--origam-transition---slide-x-easing
+--origam-transition---slide-x-translate-distance
+--origam-transition---slide-y-duration
+--origam-transition---slide-y-easing
+--origam-transition---slide-y-translate-distance
+--origam-transition__default---duration
+--origam-transition__default---easing
+--origam-transition__dialog---duration
+--origam-transition__dialog---easing
+--origam-transition__expand---duration
+--origam-transition__expand---easing
+--origam-transition__expand---max-height-from
+--origam-transition__fade---duration
+--origam-transition__fade---easing
+--origam-transition__scale---duration
+--origam-transition__scale---easing
+--origam-transition__scale---scale-from
+```
+</details>
+
+Ref: issue #436.
+
 ## [2.16.0] - 2026-08-19
 
 A release about **things that were declared but did nothing**. Seven