@karmo-co/drift-kit-reference 0.0.0-stage → 23.5.0

package/manifest/migrations/16.0.0.md

@@ -0,0 +1,196 @@
+## 16.0.0 - 2026-09-22
+
+- **Select's keyboard exists.** Until now the arrow keys opened the menu and
+  then nothing worked: ArrowUp, ArrowDown, Home and typing all left focus on the
+  trigger with no way to reach an option, and Tab walked out of the page while
+  the menu stayed open. There was no way to choose a value without a mouse. It
+  is the APG's select-only combobox now, with focus staying on the trigger and
+  `aria-activedescendant` naming the highlighted option:
+
+  ```text
+  ArrowDown / ArrowUp   open, or move the active option
+  Alt+ArrowDown         open without moving
+  Home / End            first / last
+  PageDown / PageUp     ten at a time
+  Enter / Space         choose
+  Escape                close, keep the value
+  Tab                   close and let the page have it
+  any printable key     typeahead, 700ms buffer, cycles, skips disabled
+  ```
+
+  Opening lands on the CURRENT SELECTION, which is where a reader expects to be
+  and what a native select does. Hovering moves the active option rather than
+  painting a second highlight, so the pointer and the keyboard never light two
+  different rows.
+- **Forge's `check:contract` asserts the keyboard**, for any component that
+  declares one: open with a key, move with a key, choose with a key, and leave
+  the value alone on Escape. The old behaviour passed every gate in the repo
+  while being unusable, which is the whole argument for adding it. Verified by
+  breaking the arrow keys on purpose and watching it fail.
+- **Its own token collection: 74 where there were 12.** Eight of the twelve
+  pointed straight at `--dk-component-input-*` and the stylesheet read Input's
+  collection another eleven times, which is component-to-component, a tier the
+  kit does not have, and the same fault Input's label was moved off
+  `--dk-component-eyebrow-*` for. The rungs are derived from the same primitives
+  by the same arithmetic rather than quoted, so both move together, and
+  `check:contract`'s field cohort is what asserts a select and a text field
+  still paint the same box.
+- **BREAKING: `.dk-component-select--disabled` is gone.** The last BEM-style
+  modifier in a kit that uses attributes everywhere else, on a component whose
+  trigger is a real `<button>`. It was worse than untidy: it painted a trigger
+  without disabling it, so a select that looked locked still opened, still took
+  focus and still changed its value. Use the native `disabled` attribute on
+  `.dk-component-select__trigger`.
+- **The field grammar it never had**: a label, a caption, an error with
+  `aria-invalid`, and the required asterisk, so a select and a text field in one
+  form can say the same things.
+- **The menu can carry more**: option groups under real headings (a labelled
+  `role="group"`, which the keyboard walks past), a second line on an option, a
+  disabled option that is actually skipped, and an empty state for a menu with
+  nothing in it.
+- **The floating surface is named for the shape, not the component.**
+  `--dk-component-menu-*` replaces `--dk-component-select-menu-radius` and
+  `-shadow` and picks up the literals beside them. Forge hand-rolls this box
+  five times over (seven `role="menu"` popups across the prototypes, the card
+  actions menu, the icon picker), and a Dropdown built later is menu semantics
+  on a surface that already exists rather than a second stylesheet that drifts.
+- **On a phone the menu is a bottom sheet, by default and not by request.**
+  Below the kit's mobile breakpoint it stops being a dropdown: full width, off
+  the bottom edge where the thumb already is, with a scrim, a heading taken from
+  the label, 44px rows, and the page behind it locked from scrolling. A dropdown
+  anchored to a 100px trigger on a 375px screen is the worst of both, flipping
+  when there is no room below and clipping against the viewport.
+
+  It is not an option because a design system's defaults are what ship: an
+  opt-in would mean most call sites never opt in and mobile users keep the
+  cramped menu. `data-sheet="never"` is the escape hatch for the one case that
+  is genuinely wrong, a select inside something that is already a sheet or a
+  full-screen modal, and `data-sheet="always"` forces it at any width, which is
+  how the docs demonstrate it on a desktop.
+
+  THE BREAKPOINT IS DECLARED ONCE, in the stylesheet, and the behaviour reads it
+  back as a custom property when the menu opens. A media query cannot switch
+  JavaScript on, and a width hardcoded in both languages drifts the first time
+  one of them moves.
+- **The sheet leaves the way it arrived.** It slid up and then vanished on the
+  frame the selection landed, which reads as the screen glitching rather than as
+  a panel closing: the thing you just touched is gone before you have finished
+  touching it. It slides out now, faster than it came in, and the scrim fades
+  with it, because the scrim is the sheet's own shadow and fading the element
+  fades the dim in one gesture. `aria-expanded` flips to false immediately: the
+  state a screen reader reads should not wait on an animation.
+- **A sheet on its way out answers "closed" to everything that asks.** Tapping
+  the trigger mid-exit was swallowed, because the click handler asked whether
+  the menu was open, got true from an attribute that is still set while the
+  sheet slides, and called close, which returned since it was already leaving.
+  Tapping something and having nothing happen is the worst answer available.
+  Now the exit is cancelled and the sheet comes back up rather than a second one
+  animating in behind it.
+- **The scrim is a box-shadow, not an element**: a 100vmax spread paints the
+  whole viewport in one declaration, so there is no node to create, none to
+  leak, and nothing to clean up if a page tears the menu out from under us. It
+  is not a hit target and does not need to be, since the outside-click handler
+  that closes the menu was already listening on the document.
+- **New: `--dk-surface-backdrop-soft`**, 40% black, beside upstream's 80%.
+  A modal is the page for as long as it is open and a backdrop that heavy says
+  so; a select's sheet is a menu that happens to be full width, and dimming the
+  form behind it to black takes away the context you are choosing for. Declared
+  below the upstream fence, in both themes.
+- **The highlight belongs to whichever input moved last.** Hovering an option
+  and then moving the pointer out of the menu left the row lit: one rule painted
+  both the hovered option and the ACTIVE one, and the active one is the
+  keyboard's cursor, which must exist the whole time the menu is open because
+  `aria-activedescendant` has to point at something. So the pointer's position
+  became permanent. The menu records `data-nav` now: on `pointer` the `:hover`
+  paints and stops the moment the pointer leaves, with the active option still
+  set silently for the screen reader and the next keypress; on `keyboard` the
+  active option paints and `:hover` is suppressed, or arrowing past a row the
+  pointer happens to be resting on would light two at once. A menu opened by
+  click starts in pointer mode and paints nothing until you are over a row.
+- **The options are inset and rounded**, rather than running edge to edge. The
+  menu carries the inset, `--dk-component-menu-padding-inline`, and the option
+  carries the rest, and the two are chosen so their SUM is unchanged: nothing
+  moves but the highlight, which now stops short of the menu's edge and rounds.
+  The radius is concentric rather than chosen by eye, `--dk-border-radius-100`
+  against the menu's `-300` across a `spacing-2` inset, so the two curves sit
+  parallel; a rounder option looks deliberate on its own and wrong inside the
+  menu's own corner. The group headings keep their text on the option text's
+  line.
+- **`data-raised` on the trigger**, the same attribute Input carries and the
+  same trade: the shadow is the whole of it, since padding belongs to the size
+  rung. It stacks with the focus ring rather than replacing it, in both of the
+  states that draw one, focused and open, because a select has two where a field
+  has one. Readable on the root or on the trigger, so a lone trigger can be
+  raised too, and the forced states carry the lift so the docs' state control
+  does not show a raised select losing its shadow on hover. React takes
+  `raised`.
+- **The type rides with the box: 14 / 16 / 18**, on the same rungs a field
+  reads. The trigger was a rung low at small and medium, so a select and a text
+  field in one form were the same height and not the same type; the heights
+  matching all along is what let it go unseen, since the box arithmetic reads a
+  line-height rung and the value reads a text rung, and only one of the two was
+  Input's. And an option is the text you are about to get, so it is set at the
+  rung the trigger will show it at: options were fixed at 16/24 at every size, a
+  rung larger than the trigger's value with four more pixels of leading, so a
+  14px control opened a 16px list. The menu is portalled, so `init()` mirrors
+  `data-size` onto it the way `dk.scope.adopt` mirrors the token legs.
+- **The menu's width is its own, not the trigger's.** It took the trigger's
+  width outright, which reads fine on a 320px field and badly everywhere else:
+  Forge's own control rail opens 100px selects, and a 100px menu truncates every
+  option in it. A trigger only ever holds one line, so it is a poor guide to how
+  much room a list needs. The rule is now a floor, a fit and a cap: never
+  narrower than its trigger, as wide as its widest option needs,
+  `--dk-component-menu-max-width` (328px) and the viewport behind it.
+- **`dk.position` gains `align`**, and finding that it needed one is the second
+  half of the same story. Alignment was inferred from `matchWidth`, which worked
+  only because a menu exactly as wide as its trigger centres and start-aligns to
+  the same number. The moment the menu could be wider, a 152px menu on a 117px
+  trigger sat 17px to the left of it. `align: 'start' | 'center' | 'end'` is
+  explicit now and `matchWidth` means only what its name says; Tooltip keeps the
+  centred default.
+- **React `Select`**, which did not exist: the docs' TSX pointed at
+  `@karmo-co/component-library`, a different product. Uncontrolled by design,
+  because the menu is built and mutated by `behaviour.js` in DOM React does not
+  own; `defaultValue` seeds it and `onChange` reports it.
+
+### Rename map: `migrations/16.0.0-select-keyboard.json`
+
+```json
+{
+  "version": "16.0.0",
+  "summary": "Select gains the keyboard it never had, its own token collection, and the field grammar (label, caption, error, required). The only breaking change is the removal of .dk-component-select--disabled.",
+  "breaking": {
+    "dk-component-select--disabled": {
+      "replacement": "the native disabled attribute on .dk-component-select__trigger",
+      "why": "It painted a trigger without disabling it, so a select that looked locked still opened, still took focus and still changed its value. It was also the last BEM-style modifier in a kit that uses attributes everywhere else.",
+      "before": "<div class=\"dk-component-select dk-component-select--disabled\">…<button class=\"dk-component-select__trigger\">…",
+      "after": "<div class=\"dk-component-select\">…<button class=\"dk-component-select__trigger\" disabled>…",
+      "javascript": "root.classList.toggle('dk-component-select--disabled', locked)  →  root.querySelector('.dk-component-select__trigger').disabled = locked"
+    }
+  },
+  "rename": {
+    "--dk-component-select-menu-radius": "--dk-component-menu-radius",
+    "--dk-component-select-menu-shadow": "--dk-component-menu-shadow"
+  },
+  "unchanged": {
+    "markup": "Every class is the same and every existing select keeps working: the root, __trigger, __value, __chevron, __menu and __option all mean what they meant, and the hidden input still carries the value. role=\"combobox\", aria-controls, aria-activedescendant and the option ids are written by init(), so markup from before 16.0.0 gets the keyboard without being touched.",
+    "api": "root.__dcSelect keeps setOptions / select / value / open / close, and the bubbling dk-component-select:change CustomEvent keeps its detail { value }. setOptions gained three optional fields per option: description, group and disabled.",
+    "sizes": "data-size=\"small|large\" mean what they meant, 38 and 52 against the unmarked 44."
+  },
+  "added": {
+    "keyboard": "Arrows, Home, End, PageUp, PageDown, Enter, Space, Escape, Tab and typeahead. Focus stays on the trigger; aria-activedescendant names the active option.",
+    "dk-component-select__label / __caption / __error": "The field grammar. Pair the error with aria-invalid=\"true\" on the trigger and aria-describedby pointing at the message.",
+    "dk-component-select__group / __group-label": "Options under a heading. The heading is a labelled role=\"group\", not an option, so the keyboard walks past it.",
+    "dk-component-select__option-text / __option-desc": "A second line on an option. The trigger shows the label alone.",
+    "dk-component-select__empty": "What a menu with nothing in it says.",
+    "--dk-component-menu-*": "The floating surface, named for the shape rather than for this component so a Dropdown can share it.",
+    "React Select": "import { Select } from '@karmo-co/drift-kit/react'. Uncontrolled: defaultValue seeds it, onChange reports it.",
+    "--dk-component-menu-max-width / --dk-component-menu-viewport-gap": "The menu sizes to its content now, floored by the trigger's width and capped by these two. It used to take the trigger's width outright, so a narrow select opened a narrow menu that truncated every option in it.",
+    "dk.position({ align })": "'start' | 'center' | 'end'. Alignment used to be inferred from matchWidth, which only ever agreed with the intent because the menu was exactly as wide as its trigger. Tooltip keeps the centred default.",
+    "data-raised": "The trigger lifted onto an elevation, the same attribute Input carries. The shadow is the whole of it: padding and height still come from the size rung. It stacks with the focus ring rather than replacing it.",
+    "data-sheet": "auto | always | never. On a phone the menu is a bottom sheet by default: full width, off the bottom edge, with a scrim, a heading, 44px rows and the page locked from scrolling. 'never' opts out for a select inside something that is already a sheet; 'always' forces it at any width. Nothing to change in existing markup: the default is the new behaviour.",
+    "--dk-surface-backdrop-soft": "40% black, beside upstream's 80% --dk-surface-backdrop-black. A sheet dims the page without owning it the way a modal does."
+  }
+}
+```
+

package/manifest/migrations/17.0.0.md

@@ -0,0 +1,19 @@
+## 17.0.0 - 2026-09-24
+
+### Migration
+
+Two renames, both on Modal, and both mechanical:
+
+- **`data-size` on `.dk-component-modal__box`: `sm` / `md` / `lg` become
+  `small` / `medium` / `large`**, and `xlarge` joins them at 800px. Every other
+  component in the kit says small / medium / large; the modal was the one that
+  did not. `medium` is still the unmarked default, so a box with no `data-size`
+  is unaffected.
+- **`.is-closing` on the overlay becomes `[data-closing]`.** It was the last
+  state-carrying class in a kit that spells every other state as an attribute.
+  Anything that ADDS the class to play the exit, or reads it to know a dialog is
+  leaving, has to move; `dk.component.modal.open()` and `.close()` already do.
+  The keyframe names are deliberately unchanged, because an animation's name is
+  an identifier consumers observe (`animationName === "dk-component-modal-slide-out"`),
+  and renaming it would break that silently.
+

package/manifest/migrations/18.0.0.md

@@ -0,0 +1,23 @@
+## 18.0.0 - 2026-10-01
+
+### Migration
+
+- **Table's loading row uses the Loading spinner.** `.dk-component-table__spinner`
+  and its tokens (`spinner-size`, `spinner-track`, `spinner-head`,
+  `spinner-duration`) are gone; put a
+  `<div class="dk-component-loading-spinner" data-variant="ring" data-size="small" data-animation="enter">`
+  with a `__message` in the loading cell. React `loadingLabel` is now a string.
+- **Table's `sort-icon-color-active` token now means pressed**, not sorted; the
+  sorted colour is `sort-icon-color-sorted`.
+- **Dropzone's root is a container now.** The `<label>` that was the root
+  becomes `label.dk-component-dropzone__area` inside a
+  `div.dk-component-dropzone`, which can also hold a field label, a file list,
+  a caption and an error. Wrap the old markup in the div and rename the
+  label's class. `root.__dcDropzone.reset()` and `refresh()` keep working.
+- **Tag's `data-pill` (React `pill`) is removed.** A tag's corner now always
+  comes from the theme's `data-border-radius` (sharp, normal, bubbly), like
+  every other component's. Delete the attribute or prop; nothing replaces it.
+  Under bubbly a tag is already nearly round, and a filter chip that must look
+  different will be its own clickable component. This is breaking, so the next
+  release is a major.
+

package/manifest/migrations/19.0.0.md

@@ -0,0 +1,15 @@
+## 19.0.0 - 2026-10-06
+
+### Migration
+
+- **Stepper's `data-labels="beside"` is removed** (React `labels` is now
+  `'visible' | 'hidden'`). Each variant puts its labels where they read best:
+  beside the number for `data-variant="inline"`, below the indicator for the
+  rest. For the inline look, use `data-variant="inline"`; `data-labels="hidden"`
+  is unchanged.
+- **Stepper's narrow summary line is removed** (`.dk-component-stepper__summary`
+  and `messages.summary`). On a narrow stepper the current step now keeps its
+  own words in place instead; see Changes.
+- **Stepper's `--dk-component-stepper-connector-gap` token is removed**:
+  connectors now touch the indicators in both orientations.
+

package/manifest/migrations/2.0.0.md

@@ -0,0 +1,18 @@
+## 2.0.0 — 2026-09-09
+
+- The `dk` vocabulary: every token is `--dk-…`, tier words `primitive` /
+  `responsive` / `dynamic` / `component`, classes `.dk-component-{name}`, JS
+  namespace `dk.component.{name}.{fn}`. Component-library / Figma name parity
+  dropped by decision; `refresh:tokens`, `check:upstream` and the upstream
+  parity test removed. Map in `migrations/2.0.0-dk-vocabulary.json`.
+- Components added since 1.0.0: body, heading, hero, eyebrow, icon (with the
+  Karmo glyph runtime); surface levels and tone scopes (`data-surface`,
+  `data-tone`, `data-tone-fill`); fixed Karmo alias rungs for body, overline and
+  input type.
+
+### Rename map: `migrations/2.0.0-dk-vocabulary.json`
+
+Token names before → after the dk vocabulary. Classes: dc-{x} → dk-component-{x}. JS: window.dc{X} → dk.component.{x}.{fn}.
+
+The full map is `migrations/2.0.0-dk-vocabulary.json` in the drift-kit repo.
+

package/manifest/migrations/20.0.0.md

@@ -0,0 +1,43 @@
+## 20.0.0 - 2026-10-12
+
+### Migration
+
+- **Tabs is now the underline tabs; the old Tabs is Segmented control.** The
+  sliding pill in a raised frame (`.dk-component-tabs` > `.dk-component-tab`
+  + `.dk-component-tab-indicator`) is `.dk-component-segmented` > `__option`
+  + `__indicator`, with radio semantics (`role="radiogroup"`, `role="radio"`,
+  `aria-checked`, written by the runtime); `.active` is no longer read. Its
+  tokens are `--dk-component-segmented-*`, its runtime
+  `dk.component.segmented`, its event `dk-component-segmented:change`
+  `{ value, values, option }`. The full map is
+  `migrations/20.0.0-tabs-to-segmented.json`. React `Tabs` keeps its name and
+  props but renders the new tabs; use `SegmentedControl` for the old look.
+
+### Rename map: `migrations/20.0.0-tabs-to-segmented.json`
+
+```json
+{
+  "version": "20.0.0",
+  "summary": "Tabs is now the underline tabs Forge's design system pages use (with a pill variant); the old Tabs, a sliding pill in a raised frame, is now Segmented control, with radio semantics, and gains multiple selection, icon-only options and full width.",
+  "rename": {
+    ".dk-component-tabs (with .dk-component-tab children)": ".dk-component-segmented",
+    ".dk-component-tab": ".dk-component-segmented__option",
+    ".dk-component-tab-indicator": ".dk-component-segmented__indicator",
+    ".dk-component-tab-ico": ".dk-component-segmented__icon",
+    "--dk-component-tabs-*": "--dk-component-segmented-*",
+    "dk.component.tabs (the slider)": "dk.component.segmented",
+    "dk-component-tabs:change { index, tab }": "dk-component-segmented:change { value, values, option }"
+  },
+  "semantics": {
+    "role=\"tablist\" + role=\"tab\" + aria-selected": "role=\"radiogroup\" + role=\"radio\" + aria-checked (the runtime writes them). A strip that switched panels keeps doing so: aria-controls on an option shows its panel.",
+    ".active": "no longer read or written; aria-checked is the state"
+  },
+  "added": {
+    ".dk-component-tabs": "New: a tablist of .dk-component-tabs__tab (with __icon, __label, __count), an underline by default and data-variant=\"pill\", data-size, data-full-width, data-activation=\"manual\"; the runtime adds the __indicator.",
+    ".dk-component-segmented[data-multiple]": "Several chosen: a group of toggle buttons with aria-pressed, each pressed option on its own pill.",
+    "React": "Tabs keeps its name and props and renders the new tabs (adds variant, count, fullWidth, activation); SegmentedControl is new (options, multiple, value/defaultValue/onChange, size, fullWidth)."
+  },
+  "migrate": "Replace the classes as in rename. Leave role, aria-selected and tabindex to the runtime, or write role=\"radio\" with aria-checked yourself."
+}
+```
+

package/manifest/migrations/21.0.0.md

@@ -0,0 +1,97 @@
+## 21.0.0 - 2026-10-14
+
+### Migration
+
+- **Segmented control is now Glider.** `.dk-component-segmented` and its
+  parts are `.dk-component-glider`, `__option`, `__indicator`, `__icon` and
+  `__label`; its tokens are `--dk-component-glider-*`, its runtime
+  `dk.component.glider`, its event `dk-component-glider:change`, and React's
+  `SegmentedControl` is `Glider` (types `GliderProps`, `GliderOption` and so
+  on). Nothing else changes. The map is
+  `migrations/21.0.0-segmented-to-glider.json`.
+- **Tabs has no pill variant.** Tabs is the underline alone:
+  `data-variant="pill"` and React's `variant` are gone, with the pill's
+  tokens (`--dk-component-tabs-pill-*`, `-count-on-pill-surface`); the
+  count's corner is `--dk-component-tabs-count-radius`. A pill look that
+  picks a value, one or several, is the Glider's. The map is
+  `migrations/21.0.0-tabs-pill-removed.json`.
+- **Motion is a scale and patterns.** Seven durations became four (quick 120,
+  brisk 200, moderate 320, slow 480) and five easings four (standard,
+  emphasized, exit, spring). Components read patterns: state, press, travel,
+  enter, enter-large, exit, exit-large, expand, feedback, loop and cascade.
+  The old names are removed; the map is `migrations/21.0.0-motion-scale.json`.
+
+### Rename map: `migrations/21.0.0-motion-scale.json`
+
+```json
+{
+  "version": "21.0.0",
+  "summary": "Motion is four durations, four easings and the patterns components read (13 Oct: snappy and fluid). Read a pattern by its job; the scale names below map to the nearest step, but a component should move to a pattern, not to the step.",
+  "rename": {
+    "--dk-motion-duration-snap": "--dk-motion-duration-quick (or --dk-motion-state-duration)",
+    "--dk-motion-duration-fast": "--dk-motion-duration-quick (or --dk-motion-state-duration)",
+    "--dk-motion-duration-default": "--dk-motion-duration-brisk (or --dk-motion-press-duration)",
+    "--dk-motion-duration-slower": "--dk-motion-duration-slow (or --dk-motion-enter-large-duration)",
+    "--dk-motion-duration-slowest": "--dk-motion-duration-slow (or --dk-motion-enter-large-duration)",
+    "--dk-motion-easing-in-out": "--dk-motion-easing-standard (or --dk-motion-state-easing)",
+    "--dk-motion-easing-out": "--dk-motion-easing-standard (or --dk-motion-state-easing)",
+    "--dk-motion-easing-ease": "--dk-motion-easing-standard (or --dk-motion-state-easing)",
+    "--dk-primitive-motion-duration-125": "--dk-primitive-motion-duration-120",
+    "--dk-primitive-motion-duration-150": "--dk-primitive-motion-duration-120",
+    "--dk-primitive-motion-duration-250": "--dk-primitive-motion-duration-200",
+    "--dk-primitive-motion-duration-300": "--dk-primitive-motion-duration-320",
+    "--dk-primitive-motion-duration-400": "--dk-primitive-motion-duration-480",
+    "--dk-primitive-motion-duration-500": "--dk-primitive-motion-duration-480",
+    "--dk-primitive-motion-easing-in-out": "--dk-primitive-motion-easing-standard",
+    "--dk-primitive-motion-easing-out": "--dk-primitive-motion-easing-standard",
+    "--dk-primitive-motion-easing-ease": "--dk-primitive-motion-easing-standard"
+  },
+  "changed": {
+    "--dk-motion-duration-moderate": "250ms -> 320ms",
+    "--dk-motion-duration-slow": "300ms -> 480ms",
+    "reduced motion": "fades at 120 to 160ms instead of cutting to 0.01ms"
+  },
+  "migrate": "Inside drift-kit every component already reads patterns."
+}
+```
+
+### Rename map: `migrations/21.0.0-segmented-to-glider.json`
+
+```json
+{
+  "version": "21.0.0",
+  "summary": "Segmented control is renamed Glider (13 Oct). Same markup, tokens, behaviour and semantics under the new name.",
+  "rename": {
+    ".dk-component-segmented": ".dk-component-glider",
+    ".dk-component-segmented__option": ".dk-component-glider__option",
+    ".dk-component-segmented__indicator": ".dk-component-glider__indicator",
+    ".dk-component-segmented__icon": ".dk-component-glider__icon",
+    ".dk-component-segmented__label": ".dk-component-glider__label",
+    "--dk-component-segmented-*": "--dk-component-glider-*",
+    "dk.component.segmented": "dk.component.glider",
+    "dk-component-segmented:change": "dk-component-glider:change",
+    "React SegmentedControl": "React Glider",
+    "React SegmentedControlProps, SegmentedSingleProps, SegmentedMultipleProps, SegmentedOption, SegmentedSize": "GliderProps, GliderSingleProps, GliderMultipleProps, GliderOption, GliderSize"
+  },
+  "migrate": "Replace the names as in rename; nothing else changes."
+}
+```
+
+### Rename map: `migrations/21.0.0-tabs-pill-removed.json`
+
+```json
+{
+  "version": "21.0.0",
+  "summary": "Tabs loses its pill variant (13 Oct): tabs are the underline alone, and a pill look that picks a value is the Glider's.",
+  "removed": {
+    "[data-variant=\"pill\"] on .dk-component-tabs": "Gone. Tabs that switch panels drop the attribute and become the underline; a pill strip that picks a value becomes a .dk-component-glider (data-multiple for several).",
+    "React Tabs variant, TabsVariant": "Gone; drop the prop.",
+    "--dk-component-tabs-pill-gap, -pill-height, -pill-small-height, -pill-large-height, -pill-padding-inline, -pill-small-padding-inline, -pill-large-padding-inline, -pill-surface, -pill-selected-color, -pill-surface-hover, -count-on-pill-surface": "Gone with the variant."
+  },
+  "rename": {
+    "--dk-component-tabs-pill-radius": "--dk-component-tabs-count-radius"
+  },
+  "migrate": ""
+}
+```
+

package/manifest/migrations/22.0.0.md

@@ -0,0 +1,17 @@
+## 22.0.0 - 2026-10-15
+
+### Migration
+
+- **Breadcrumb's separator is a slash, drawn as text.**
+  `--dk-component-breadcrumb-separator-icon` is gone; the separator's colour
+  is still `--dk-component-breadcrumb-separator-color`. Past pages are now
+  subtle neutral pills rather than primary links, and an item with a menu
+  wraps its link (or current page) and its `__more` in `span.__pill`. The
+  old markup still renders; it only lacks the joined pair.
+- **Edged buttons are 2px smaller.** Plain, raised and outline Buttons and
+  Icon buttons now take their border out of their padding, so they are the
+  size borderless ones are (44px at medium, was 46). A layout that measured
+  around the old size moves by that much.
+- **App shell sits on white.** `--dk-component-app-shell-surface` is the page
+  surface, not the grey canvas.
+

package/manifest/migrations/23.0.0.md

@@ -0,0 +1,86 @@
+## 23.0.0 - 2026-10-17
+
+### Breaking
+
+- **Box has five sizes** (16 Oct): `xsmall` (12), `small` (18), `medium`
+  (24, the default), `large` (32) and `xlarge` (40). Past medium the corner
+  and the header grow too (radius 300 and 400, an h5 and an h4 title over a
+  body-md description). The tokens moved with the names:
+  `--dk-component-box-padding` is now 24, `-small-padding` 18 and
+  `-large-padding` 32; `-xsmall-*`, `-xlarge-*`, `-large-radius`,
+  `-xlarge-radius` and the large and xlarge title and description tokens are
+  new.
+
+### Migration
+
+| Was | Now, for the same box |
+|---|---|
+| `data-size="small"` (`size="small"`) | `data-size="xsmall"` |
+| no `data-size` (`size="medium"`) | `data-size="small"` |
+| `data-size="large"` (`size="large"`) | no `data-size` (`size="medium"`) |
+
+An override of `--dk-component-box-padding`, `-small-padding` or
+`-large-padding` moves the same way.
+
+### Behaviour changes
+
+- **Glider labels a rung smaller, with more air** (17 Oct): small, medium and
+  large labels are 10, 12 and 14px (were 12, 14, 16), the padding beside them
+  12, 16 and 20px (were 8, 12, 16), and the icons 12, 14 and 16px (were 14,
+  16, 20). Heights are unchanged (36, 44, 52). An option is wider than it was.
+
+- **Card is rebuilt** (16 Oct). Same markup (`__media`, `__body`, `__title`,
+  `__subtitle` still render), new look and reach:
+  - `data-variant` raised (default), outline, flat; `data-size` small,
+    medium, large; `data-orientation="horizontal"`; `data-media="inset"`;
+    `__media` takes `data-ratio` (16/9 default, 1/1, 4/3, 3/2, 21/9) and
+    `data-fit="contain"`; new `__eyebrow`, `__meta`, one full-width `__cta`,
+    and `__corner[data-corner="start|end"]` for buttons over the top corners
+    (a heart toggle that fills when pressed, a Dropdown menu); with either,
+    a `__link` in the title stretches over the card. `data-corners="hover"`
+    fades the corners in under the pointer or the focus (a pressed toggle and
+    an open menu stay shown; a screen that cannot hover always shows them);
+    shown always on a card with no media, they take a row above the words,
+    and beside the body both sit on the media.
+  - It paints the kit surface, so `data-tone`, `data-tone-fill` and
+    `data-surface` drive it, and hover and press climb that surface's
+    control rungs. It is no longer a tone boundary: on a solid or tinted
+    panel it takes the panel's colours, as Box does. `data-surface="0"`
+    gives it the page back.
+  - Surface tier: grows on hover, presses on the surface rung. Only a link,
+    a button, a tab stop or a stretched card moves; a static card is still.
+  - The corner is radius 300 (was a literal 14px), the media is 16/9 (was
+    132px), the title body-md (was 15px), and the subtitle wraps to two
+    lines (was one) through `--dk-component-card-subtitle-lines`.
+  - Selected (`aria-pressed`, `aria-current`) wears the primary edge;
+    `aria-disabled` stills it and dims it; the focus ring is an outline.
+  - React `Card` gains variant, size, orientation, tone, toneFill, surface,
+    eyebrow, meta, cta, cornerStart, cornerEnd, mediaRatio, mediaFit,
+    mediaInset, selected and disabled.
+- **Two control press rungs** (16 Oct): text-width controls (Button, Glider,
+  Tabs, Breadcrumb and Top bar links, the phone sidebar tabs) press to 0.97;
+  small squares take the new compact rung, 0.93 (Icon button, Pagination
+  pages, Calendar days, Day of month cells), with `--dk-interactive-press-compact`
+  and `data-interactive="compact"`. Accordion headers press on the panel rung
+  (0.99): full width, they lurched at the item rung.
+- **The quiet ramp follows the tone.** `--dk-interactive-surface-hover` and
+  `-active` and the nested fill read the control fills: the same greys on a
+  plain surface, the tone's and the level's next rung on a toned one.
+- **Words step a rung per state** on Breadcrumb, Sidebar, Pagination, Glider,
+  Tabs and Top bar links (they rest a step lighter); Dropdown and Select menu
+  words stay full strength. On a solid tone the quiet word ramp steps to the
+  tone's white.
+- **Presses:** Dropdown and Select options, Sidebar items and the Action bar
+  summary press on the item rung; Breadcrumb and Top bar links on the control
+  rung, Pagination, Calendar and Day of month cells on the compact rung (see
+  above); Choice card grows on hover.
+- **Selected and highlighted:** the Sidebar's current item, Pagination's
+  current page and a picked day read the foundation's selected; a checked
+  Table row its highlighted tint.
+- **Sidebar** items press a rung past hover and hover with the fill alone.
+- **Accordion** sits on the surface it is on, and **Dropzone** on the control
+  fill, so both follow the tone, the level and the fill; Dropzone's hover,
+  press, chosen-file and focus states follow a status tone too.
+- **Inset Glider** words go full strength inside a status tone, as inset
+  Breadcrumb's do; an inset Select chevron keeps its tone colour on hover.
+

package/manifest/migrations/3.0.0.md

@@ -0,0 +1,34 @@
+## 3.0.0 — 2026-09-09
+
+### Breaking
+
+- `data-theme` values are lowercase: `data-theme="light"` / `data-theme="dark"`,
+  matching every other Drift attribute (`data-surface`, `data-tone`,
+  `data-density`, `data-border-radius`, `data-border-width`). `Light` / `Dark`
+  no longer match any selector. Kit selectors are normalised to the quoted form
+  `[data-theme="light"]` (238 selectors; the 3 unquoted `[data-alignment=…]`
+  selectors are quoted too). Token values are unchanged — 1,542 tokens across
+  six theme/surface/tone scopes compare equal between 2.0.0 with `Light`/`Dark`
+  and 3.0.0 with `light`/`dark`.
+- Consumers: set `<body data-theme="light|dark">`, lowercase any stored theme
+  preference on read, and update your own `[data-theme=Light|Dark]` selectors
+  and `=== 'Light'` / `'Dark'` comparisons. Map in
+  `migrations/3.0.0-data-theme.json`.
+
+### Rename map: `migrations/3.0.0-data-theme.json`
+
+```json
+{
+ "version": "3.0.0",
+ "date": "2026-09-09",
+ "summary": "data-theme values are lowercase like every other Drift attribute. Selectors in the kit are quoted [data-theme=\"light\"] / [data-theme=\"dark\"].",
+ "attributes": {
+  "data-theme": {
+   "Light": "light",
+   "Dark": "dark"
+  }
+ },
+ "consumers": "Set <body data-theme=\"light|dark\">; lowercase any stored preference on read; update your own [data-theme=Light|Dark] selectors and === 'Light'/'Dark' comparisons. Token values are unchanged (1,542 tokens x 6 scopes compared equal)."
+}
+```
+