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

package/manifest/migrations/13.0.0.md

@@ -0,0 +1,50 @@
+## 13.0.0 - 2026-09-19
+
+**Breaking: the icon button's `plain` variant now has a border.** The borderless
+treatment it used to have is called `ghost`. Rename `data-variant="plain"` to
+`data-variant="ghost"` to keep the old look, or leave it to gain the edge.
+
+- **Button and the icon button now carry the same neutral ladder**, four rungs
+  meaning the same thing in both: `ghost` has no chrome until you touch it,
+  `subtle` is a filled tint, `plain` is flat on its surface with an edge,
+  `raised` is lifted above it. `plain` used to mean borderless in one component
+  and bordered in the other, which is the whole reason for this release.
+- **New: `ghost` on Button.** It had no borderless rung at all. `accent` looks
+  like one and is not: it paints on-solid text for a coloured backdrop, so on an
+  ordinary page it is invisible rather than quiet.
+- **New: `ghost` on the icon button**, which is its old `plain`, unchanged.
+- **New: a bordered `plain` on the icon button**, mirroring Button's exactly:
+  the panel's own colour at rest, read by its edge, where `raised` is lifted.
+- Button's `plain` and `raised` are untouched. `check:button` reports 24 of 24
+  existing combos byte-identical, and the gate now covers `ghost` at all four
+  sizes from its first day.
+- A bordered rung is 2px taller than a borderless one at the same size, in both
+  components. That is the existing deliberate behaviour, not a new one, and it
+  is why `check:contract`'s height cohorts measure the default variant.
+- **Fix: `ghost` and `plain` read the control family unshifted.** They start a
+  state late at REST, which is what makes them what they are, and they used to
+  run a state behind for the whole interaction as well, so every label sat on a
+  fill it was not chosen for. On dark warning level 2, where the ladder
+  legitimately flips from a light rung to a dark one between rest and hover, a
+  pressed label picked for `surface-control-active` landed on
+  `surface-control-hover` at 2.76:1. They now differ from `subtle` and `raised`
+  at rest and nowhere else.
+- **Fix: a border must clear the PANEL, not only its own fill.** `plain` rests
+  on the panel, so its edge sits on the panel: on dark warning level 1 the rung
+  one step from `surface-control-default` is 800, which IS the panel's rung, and
+  the edge measured 1.00 against it. Invisible, in the variant whose whole job is
+  to be read by its edge.
+- **Fix: `data-status="error"` did nothing on `ghost`.** The playground offered
+  the status and no CSS rule existed for it, so selecting it changed nothing.
+  `ghost · error` is now the same ladder `subtle` and `plain` carry, minus the
+  resting fill and minus the edge: transparent with an error label and glyph at
+  rest, one step of the error ramp on hover, two on press. Its readings are
+  identical to `plain · error`'s, combo for combo.
+- `check:contrast` now measures `ghost`, `ghost · error` and `plain · error`.
+  The last of those has existed since 7.1.0 and had never been gated.
+- Those two fixes move 20 of Button's contrast readings. Twelve improve and
+  three of them cross UP over AA (`Light s2 raised hover` 3.82 to 7.14,
+  `Light s2 raised active` 4.19 to 6.45, `Dark s2 raised active` 3.44 to 4.58);
+  eight decrease and all stay above it, the lowest at 4.58. Readings below AA go
+  from 172 to 169. Both baselines re-saved deliberately.
+

package/manifest/migrations/14.0.0.md

@@ -0,0 +1,148 @@
+## 14.0.0 - 2026-09-22
+
+- **BREAKING: Search bar is gone. It is `data-raised` on Input.** The component
+  called itself "a preset of Input, not a second field implementation" in its
+  own header, and by the end that was literally true: its heights, its type, its
+  border, its radius, its placeholder colour, its slot gap, its glyph size, its
+  font weight and both halves of its transition all resolved through
+  `--dk-component-input-*`. What it still owned was a lift, a roomier padding
+  and a magnifier that tinted on focus. A preset costing 145 lines of CSS, nine
+  tokens, a documentation page and an entry in four gates is an expensive way to
+  say "Input with a shadow".
+
+  ```text
+  <label class="dk-component-search-bar">          →  <div class="dk-component-input" data-raised data-size="large">
+    <svg class="dk-component-search-bar__icon">…   →    <div class="dk-component-input__field">
+    <input class="dk-component-search-bar__input"> →      <span class="dk-component-input__leading">…</span>
+  </label>                                         →      <input type="search" aria-label="Search vehicles">
+                                                   →    </div>
+                                                   →  </div>
+  ```
+
+  The bar was the LARGE rung, so keep `data-size="large"`: Input's unmarked
+  default is medium. The `aria-label` is still required and for the same reason,
+  now that there is no visible label rather than no label text.
+- **`data-raised` is the shadow and nothing else.** The bar's roomier inline
+  padding came across with it and was cut on review: it made one attribute two
+  unrelated changes, and a field whose text starts further in than the field
+  below it reads as a different component rather than the same one lifted.
+  Padding comes from the size rung, where every other field reads it from, so a
+  raised field and a flush field of the same size are the same box with a
+  shadow under one of them.
+- **Nothing else about the look changed.** A raised, large, unlabelled Input was
+  measured against the old bar on eight properties before the component was
+  deleted, and matched on all eight, at 52.0px both. The inline padding is the
+  one deliberate difference: 10px at every rung rather than the bar's 16px.
+- **The focus ring survives the hover shadow**, which it did not before. Both
+  are `box-shadow`, so the bar's hover shadow overwrote the ring and a focused
+  search bar under the pointer had no focus state at all. The raised rules write
+  both in one declaration.
+- **The magnifier still goes primary on focus, and one rung on hover**, and that
+  now happens on every `__leading` slot rather than only a raised one: tying a
+  glyph's colour to whether its field has a shadow is a coupling nobody would
+  guess. It reads `--dk-border-field-focus` rather than the old
+  `--dk-icon-primary-default`, which a status tone remaps; the field palette
+  escapes the tone, and the glyph now escapes it with the ring it matches.
+- **Clicking the box focuses the control.** The field paints `cursor: text`
+  across its whole width, which is a promise it did not keep: a click on the
+  padding or on the leading glyph landed nowhere, and from a focused field it
+  blurred. Search bar had this for free, its wrapper being a `<label>`. One
+  delegated listener, no `init()` call needed, every field.
+- **The clear button is not search-only, and never was.** Nothing in the CSS,
+  the behaviour or the React component ever checked the type; the docs implied
+  otherwise by deriving the button from `type="search"`, so a reader could not
+  see one on a text field and the TSX would not emit `clearable` for one. It is
+  its own control in the playground now, with search merely suggesting it. A
+  long name, a filter or a reference number are all fields somebody may want to
+  empty in one go.
+- **React renders the in-field actions in the documented order**: clear, reveal,
+  then help. Help used to render between the other two, which said the opposite
+  of its own comment and put React one element out of step with the same field
+  written by hand.
+- **React: `raised`, and `label` is optional when a name arrives another way.**
+  `InputProps` is a union now, so a field with no label and no `aria-label` or
+  `aria-labelledby` does not compile. An unnamed field announces as "edit text"
+  and is the most common field defect there is.
+- Tokens: `--dk-component-search-bar-*` (9) are gone, and
+  `--dk-component-input-raised-{shadow,shadow-hover}` (2) replace the two that
+  were genuinely the preset's own.
+  `migrations/14.0.0-search-bar-into-input.json` maps every class and every
+  token, including the six that were already aliases of an Input token.
+- **New: `drift-kit.min.css`,** the same stylesheet without the prose. The
+  readable build is 1,277 KB and 375 KB of that is comments, because this kit
+  writes down why every number is the number it is. That is the right trade in
+  source and the wrong one over the wire:
+
+  ```text
+  readable    181 KB gzip    126 KB brotli
+  minified     61 KB gzip     34 KB brotli
+  ```
+
+  Two thirds off what a consumer downloads. Exported as
+  `@karmo-co/drift-kit/drift-kit.min.css`; the readable build stays the one to
+  debug against, and stays what Forge's docs read, because the tokens page finds
+  its component segments by the `drift-kit:layer` banners and its upstream
+  halves by the `END UPSTREAM` fences, and both are comments.
+- **The minifier removes comments and whitespace and nothing else.** Nothing is
+  renamed, reordered, merged, shortened or rewritten: colours stay as written,
+  shorthands stay as written, duplicate rules stay duplicated. The value of this
+  file is that its declarations are the ones in the source in the order the
+  cascade sees them.
+- Whitespace only disappears beside `{ } ;` and `,`, which is narrower than the
+  usual rule and deliberately so. Deleting a space next to `:` turns
+  `.a :hover` into `.a:hover`, a different selector; deleting one next to `+`
+  turns `calc(1px + 2px)` into something invalid. The safe rule costs 12 KB raw
+  and, after gzip, nothing.
+- `test/minified.test.js` compares the two files rule by rule and declaration by
+  declaration, in order, because order is the cascade. A minifier is a program
+  that rewrites every line of a design system's output and the only honest way
+  to ship one is to prove the rewrite changed nothing a browser can see.
+
+### Rename map: `migrations/14.0.0-search-bar-into-input.json`
+
+```json
+{
+  "version": "14.0.0",
+  "summary": "Search bar is no longer a component. It is data-raised on Input, which is what it had become in everything but name: its heights, border, radius, placeholder colour, slot gap, glyph size, font weight and both halves of its transition already resolved through --dk-component-input-*.",
+  "markup": {
+    "note": "One element becomes two, because Input separates the grid root from the bordered box. The wrapper was a <label> with no text, so the aria-label on the control is what named it and still is. data-size=\"large\" is not optional: the bar's unmarked rung was large and Input's unmarked rung is medium.",
+    "before": "<label class=\"dk-component-search-bar\">\n  <svg class=\"dk-component-search-bar__icon\">…</svg>\n  <input type=\"search\" class=\"dk-component-search-bar__input\" aria-label=\"Search vehicles\">\n</label>",
+    "after": "<div class=\"dk-component-input\" data-raised data-size=\"large\">\n  <div class=\"dk-component-input__field\">\n    <span class=\"dk-component-input__leading\" aria-hidden=\"true\"><svg>…</svg></span>\n    <input type=\"search\" aria-label=\"Search vehicles\">\n  </div>\n</div>"
+  },
+  "classes": {
+    "dk-component-search-bar": "dk-component-input with data-raised, plus a dk-component-input__field inside it",
+    "dk-component-search-bar__icon": "a dk-component-input__leading span wrapping the glyph, which is the slot every Input already had",
+    "dk-component-search-bar__input": "no class at all: the field styles its own control"
+  },
+  "unchanged": {
+    "clearButton": "dk-component-input__action with data-input-clear was already Input's own element and is untouched, as is the dk.component.input.init() call that wires it.",
+    "size": "data-size=\"small\" and \"medium\" mean what they meant. The unmarked rung is the only one that moves, from large to medium."
+  },
+  "rename": {
+    "--dk-component-search-bar-shadow": "--dk-component-input-raised-shadow",
+    "--dk-component-search-bar-shadow-hover": "--dk-component-input-raised-shadow-hover"
+  },
+  "removedFromTheSystem": {
+    "note": "Six of the nine tokens were already aliases of an Input token, so there is nothing to point them at that Input does not say more directly. The seventh, the padding, is a deliberate change: data-raised is the shadow alone, and a raised field takes its inline padding from its size rung like every other field.",
+    "tokens": {
+      "--dk-component-search-bar-height": "--dk-component-input-large-height",
+      "--dk-component-search-bar-small-height": "--dk-component-input-small-height",
+      "--dk-component-search-bar-medium-height": "--dk-component-input-height",
+      "--dk-component-search-bar-font-weight": "--dk-component-input-font-weight",
+      "--dk-component-search-bar-transition-duration": "--dk-motion-duration-default",
+      "--dk-component-search-bar-transition-easing": "--dk-motion-easing-in-out",
+      "--dk-component-search-bar-padding-inline": "--dk-component-input-padding-inline, which is 10px rather than the bar's 16px. A raised field is the flush field with a shadow under it; nothing else about the box moves."
+    }
+  },
+  "react": {
+    "note": "There was never a SearchBar export. Input gained a raised prop, and label became optional in the type when an aria-label or aria-labelledby is present: InputProps is a union, so a field with no name at all does not compile.",
+    "example": "<Input type=\"search\" raised size=\"large\" aria-label=\"Search vehicles\" leading={<Search size={20} />} clearable />"
+  },
+  "alsoFixed": {
+    "focusRing": "The bar's hover shadow overwrote its focus ring, so a focused search bar under the pointer had no focus state at all. The raised rules write the lift and the ring in one box-shadow declaration.",
+    "clickTarget": "Clicking the box now focuses the control on every Input, not only a raised one. The field paints cursor: text across its whole width and did not honour it; the old wrapper being a <label> is the only reason the bar did.",
+    "leadingGlyph": "The magnifier still goes primary on focus and one rung on hover, and every leading slot does now. It reads --dk-border-field-focus rather than --dk-icon-primary-default, which a status tone remaps; the field palette escapes the tone and the glyph escapes it with the ring it matches."
+  }
+}
+```
+

package/manifest/migrations/15.0.0.md

@@ -0,0 +1,140 @@
+## 15.0.0 - 2026-09-22
+
+- **Switch is a real component.** It had one token, a hardcoded 34x20 track, a
+  white thumb read straight from the primitives, no label, no description, no
+  sizes, no group, no React component and no documentation beyond two examples.
+  It now carries Checkbox's grammar, because a switch row and a checkbox row in
+  one settings list are the same line of text:
+
+  ```text
+  <label class="dk-component-switch">
+    <input type="checkbox" role="switch" class="dk-component-switch__input">
+    <span class="dk-component-switch__track"></span>
+    <span class="dk-component-switch__text">
+      <span class="dk-component-switch__label">Weekly summary</span>
+      <span class="dk-component-switch__desc" id="x" aria-hidden="true">A digest.</span>
+    </span>
+  </label>
+  ```
+
+  63 tokens where there was 1, three sizes, hover, press, focus and two disabled
+  looks, a group with a legend, a settings-row treatment, and a `Switch` and
+  `SwitchGroup` in the React package.
+- **BREAKING: `dk-component-switch-field` is gone**, and only half of it came
+  across. The half that did is the ARRANGEMENT, the control at the far end of
+  the row, which is `data-align="end"` and belongs to this component because it
+  orders the component's own children. The half that did not is the recessed
+  BOX: a padded, bordered container is something a page draws around whatever it
+  likes, not something a control owns. Its fill and edge also read
+  `--dk-surface-neutral-subtle` and `--dk-border-raised-subtle`, neither of
+  which steps with the surface level, so the row was the same colour on the
+  page, on a card and inside a nested panel. A page drawing its own box with
+  `--dk-surface-nested-default` and `--dk-border-nested-default` gets that for
+  free.
+
+  ```text
+  <label class="dk-component-switch-field">      →  <div style="padding: 12px 16px; background: var(--dk-surface-nested-default); …">
+    <span class="dk-component-switch">…</span>   →    <label class="dk-component-switch" data-align="end">
+    <span class="…-field__icon">…</span>         →      <input type="checkbox" role="switch" class="dk-component-switch__input">
+    <span class="…-field__label">…</span>        →      <span class="dk-component-switch__track"></span>
+  </label>                                       →      <span class="dk-component-switch__icon">…</span>
+                                                 →      <span class="dk-component-switch__text">…</span>
+                                                 →    </label>
+                                                 →  </div>
+  ```
+
+- **`role="switch"`, so it announces "switch, on" rather than "checkbox,
+  checked".** The element stays a native checkbox, which keeps the keyboard
+  handling, the form participation and the focus behaviour that a
+  `<div role="switch">` would have to reimplement.
+- **A filled neutral track with a white thumb when off**, and the choice
+  palette's fill when on. This is where a switch parts company with Checkbox and
+  Radio, whose unengaged state is an OUTLINED box flush with the page: a switch
+  cannot be, because the thumb sits on the track and is the only thing saying
+  which way the control points. `--dk-surface-choice-track` and
+  `--dk-icon-choice-track` are new. Light ships neutral-400 at **2.88:1**, which
+  is 0.12 under the 3:1 a graphical object carries, and that is a decision with
+  a mitigation rather than an oversight: neutral-500 clears the floor at 3.75
+  and reads too heavy for a control at rest, so the thumb's SHADOW draws its
+  edge instead, which is how a physical switch is legible too. Dark keeps
+  neutral-600 and clears both axes, because "lighter" means quieter in light and
+  louder in dark. Shipping: thumb against track 2.88:1 off and 4.25:1 on in
+  light, 5.00:1 and 2.82:1 in dark; track against page 2.88:1 and 3.21:1. The
+  old white-on-inset pair was **1.16:1** with nothing drawing the edge at all.
+- **The thumb is white in every state, theme and tone.** It read
+  `--dk-icon-choice-selected` when on, which is Checkbox's TICK colour and goes
+  primary-900 in dark, so the disc turned near-black wherever the dark palette
+  was in play: in dark mode, and equally on an inverse panel inside a light
+  page. A 2px stroke and a 14px disc with a shadow under it are not the same
+  object, so the switch stops sharing that token and reads
+  `--dk-icon-choice-track` in both states. One disc that slides is one colour.
+- **One disabled look for both states.** A disabled checkbox needs two, because
+  its tick is the only thing carrying the state; a switch has the thumb's
+  position, which survives being greyed out. Both states read the choice
+  palette's disabled pair at 2.59:1, where the enabled colours would have left a
+  disabled off switch showing a white thumb on a near-white track, 1.33:1.
+- **The track height IS Checkbox's box size**, 16 / 20 / 24, so the two line up
+  in one settings list. The width is the height times 1.75, one ratio rather
+  than three numbers chosen by hand, and the thumb and its travel are derived
+  from the height, so nothing is restated per rung.
+- **`data-align="end"` is presentation only.** The DOM order never changes; the
+  attribute reorders with `order`, so the reading order, the tab order and the
+  copyable markup are the same whichever way the row points. It is the only
+  layout attribute the component has, deliberately.
+- **The thumb shrinks under the finger**, 0.85, which is what Checkbox's glyph
+  does and for the same measured reason.
+- **FIXED, AND NOT ONLY IN SWITCH: a description was being read as part of the
+  control's name.** The root of all three choice components is a `<label>`, so
+  everything inside it joins the accessible NAME: a described checkbox announced
+  as "Email me product updates About once a month, and never your data." with no
+  description at all. `aria-describedby` alone makes it worse, the same words
+  then being announced twice. The `__desc` span now carries `aria-hidden="true"`
+  as well as the id the input points at, which hides it from the name traversal
+  while keeping it readable as the description, and keeps it on screen. Applied
+  to Switch, Checkbox and Radio, in the React components and in every documented
+  example. Forge's `check:contract` asserts the name and the description of a
+  described control, which is what caught it.
+- `migrations/15.0.0-switch-field-into-switch.json` maps every class.
+
+### Rename map: `migrations/15.0.0-switch-field-into-switch.json`
+
+```json
+{
+  "version": "15.0.0",
+  "summary": "Switch becomes a real component with Checkbox's grammar, and dk-component-switch-field is retired: its arrangement is data-align=\"end\" on the switch, and its recessed box is markup the page draws around it.",
+  "markup": {
+    "note": "The control keeps its shape: a <label> root, a visually hidden native checkbox, and a track beside it. What is new is role=\"switch\" on the input, the optional __icon and __text spans, and the attributes. Markup written before 15.0.0 still renders, because __input and __track are still adjacent siblings and a switch with no text is a supported shape; add role=\"switch\" to get the right announcement.",
+    "before": "<label class=\"dk-component-switch-field\">\n  <span class=\"dk-component-switch\">\n    <input type=\"checkbox\" class=\"dk-component-switch__input\">\n    <span class=\"dk-component-switch__track\"></span>\n  </span>\n  <span class=\"dk-component-switch-field__icon\">…</span>\n  <span class=\"dk-component-switch-field__label\">Use the Drift design system</span>\n</label>",
+    "after": "<div style=\"padding: 12px 16px; background: var(--dk-surface-nested-default); border: 1px solid var(--dk-border-nested-default); border-radius: var(--dk-border-radius-200);\">\n  <label class=\"dk-component-switch\" data-align=\"end\">\n    <input type=\"checkbox\" role=\"switch\" class=\"dk-component-switch__input\">\n    <span class=\"dk-component-switch__track\"></span>\n    <span class=\"dk-component-switch__icon\" aria-hidden=\"true\">…</span>\n    <span class=\"dk-component-switch__text\">\n      <span class=\"dk-component-switch__label\">Use the Drift design system</span>\n    </span>\n  </label>\n</div>"
+  },
+  "classes": {
+    "dk-component-switch-field": "dk-component-switch with data-align=\"end\" for the arrangement, plus a container of your own for the box. There is deliberately no data-row: a padded, bordered box is a layout decision a page makes, and the one that class made did not step with the surface level.",
+    "dk-component-switch-field__icon": "dk-component-switch__icon",
+    "dk-component-switch-field__label": "dk-component-switch__label, inside a dk-component-switch__text wrapper",
+    "the nested span.dk-component-switch": "gone: the input and the track are children of the root now, one element rather than two"
+  },
+  "added": {
+    "role=\"switch\"": "On the input. Without it the control announces as a checkbox. Required.",
+    "data-size": "small | medium | large. The track height is Checkbox's box size: 16 / 20 / 24 against 14 / 16 / 18 label text. The old track was 34x20 at every size, which is the new medium at 35x20.",
+    "data-align": "end. Presentation only, applied with `order`, so the markup does not change. The only layout attribute the component has.",
+    "dk-component-switch__text / __label / __desc": "The words. The description needs id + aria-hidden on the span and aria-describedby on the input, or it is read as part of the control's name.",
+    "dk-component-switch__icon": "A leading glyph for a settings row.",
+    "dk-component-switch-group / __legend / __desc": "Several settings under one heading, as a fieldset.",
+    "--dk-surface-choice-track / --dk-icon-choice-track": "New in the mapped choice palette: the unselected track and its thumb. Only a switch has an unselected FILL, since Checkbox and Radio paint their unengaged state as an outlined box from the field palette."
+  },
+  "rename": {
+    "--dk-component-switch-label-font-weight": "--dk-component-switch-label-font-weight (unchanged, and the only token this component had)"
+  },
+  "react": {
+    "note": "There was no Switch export before. There is now, plus SwitchGroup.",
+    "example": "<Switch label=\"Weekly summary\" description=\"A digest of everything that changed.\" defaultChecked />"
+  },
+  "alsoFixed": {
+    "descriptionInTheName": "Switch, Checkbox and Radio all render their description inside the <label> root, so it was being read as part of the control's accessible NAME and no description was exposed at all. The __desc span now carries aria-hidden=\"true\" alongside the id its input references, which takes it out of the name traversal while leaving it readable as the description and visible on screen. Fixed in the React components and in every documented example.",
+    "rowSurface": "The recessed row read --dk-surface-neutral-subtle and --dk-border-raised-subtle, neither of which steps with the surface level, so it was the same colour on the page, on a card and inside a nested panel. A page drawing its own box with --dk-surface-nested-default and --dk-border-nested-default gets that right by construction.",
+    "thumbContrast": "A white thumb on --dk-surface-inset-default measured 1.16:1 with nothing drawing its edge. The off track is a filled neutral now, --dk-surface-choice-track, with a white thumb from --dk-icon-choice-track and a 1px shadow under it: 2.88:1 in light and 5.00:1 in dark. The light pair sits 0.12 under the 3:1 graphical floor by decision, the rung that cleared it reading too heavy for a control at rest, and the shadow is what draws the disc's edge instead.",
+    "thumbColour": "The thumb is white in every state, theme and tone. It borrowed --dk-icon-choice-selected when on, which is Checkbox's tick colour and primary-900 in dark, so the disc went near-black in dark mode and on any inverse panel inside light. It reads --dk-icon-choice-track in both states now: one disc that slides is one colour."
+  }
+}
+```
+

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.
+