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

package/manifest/migrations/1.0.0.md

@@ -0,0 +1,50 @@
+## 1.0.0 — 2026-08-18
+
+The source is reorganised by token collection and by component, and the package
+now has exactly one CSS entry point.
+
+### Breaking
+
+- Per-layer exports removed. `./core.css`, `./tokens.css`,
+  `./components-tokens.css` and `./components.css` are gone; everything is
+  `./drift-kit.css`. A layered interface let a consumer assemble an incoherent
+  subset — component CSS without its tokens — which is a silent-failure class,
+  not a feature.
+- Core Drift is no longer a vendored CDN snapshot. The upstream token layers are
+  generated from component-library's own SCSS partials (`refresh:tokens`
+  replaces `refresh:core`), which drops 193 declarations that the CDN snapshot
+  carried and the SCSS source does not: 95 legacy `--ui-*` palette
+  declarations, 68 declared solely inside component-library's hashed React
+  CSS-module selectors, and 30 more in hashed `@keyframes`/`@property`/
+  `@supports` blocks and two `.pretty-scrollbar` rules (1,264 CSS-module rules
+  removed in total). All 193 are accounted for — 0 unexplained. Migrating the
+  `--ui-*` palette and the extracted CSS-module rules into the three Forge
+  prototypes that use them is a later project stage, not yet done. The bundle
+  falls from 519,815 to 334,060 bytes (507.6 KB → 326.2 KB, a 181 KB / 35.7%
+  reduction).
+
+#### Structure
+
+- `src/tokens/**` mirrors component-library's collection layout — brand,
+  responsive, dynamic, alias, mapped — so an upstream diff maps 1:1 onto our
+  files. Our extensions live below an `UPSTREAM … END UPSTREAM` fence in the
+  same group file; `refresh:tokens` rewrites only the fenced bytes.
+- `src/components/<name>/` holds each component's `tokens.css`, `styles.css` and
+  `behaviour.js` together, replacing two files that held eleven components
+  between them.
+- `src/manifest.js` is the only place cascade order is encoded: 87 CSS entries
+  and 7 JS entries, matching the 87 `.css` files on disk one-for-one.
+- The bundle ships 6 self-hosted `@font-face` rules (Inter and Syne, 6
+  `.woff2` files) — unchanged from the retired snapshot.
+
+##### Gates
+
+- The build fails on: a CSS file absent from the manifest, a manifest entry that
+  does not exist, a surviving `@import`/`@use`, component styles ordered before
+  component tokens, a malformed fence, or a Karmo token shadowed by a later
+  upstream fence (`check:placement`).
+- `npm test` (11 tests) proves the restructure lost nothing: canonical-form
+  equality against a frozen pre-restructure bundle, and (selector, property,
+  value) parity between the converted upstream tokens and the retired
+  snapshot.
+

package/manifest/migrations/10.0.0.md

@@ -0,0 +1,154 @@
+## 10.0.0 - 2026-09-17
+
+Breaking change to Input's markup. Anything that hand-wrote
+`dk-component-input` markup needs the new shape below.
+
+- **The wrapping `<label>` doubled as the accessible name and silently
+  absorbed the caption.** Measured with the new contract gate (see below)
+  before any fix: a field labelled "Full name" with a "Helper text goes
+  here." caption announced as one string, `"FULL NAME Helper text goes
+  here."`, and had no separate accessible description at all (empty string).
+  The all-caps portion is the label's own `text-transform: uppercase`
+  bleeding into the accessible-name computation, not a second defect.
+- **Fixed by giving the label and the field their own elements.** The root
+  is now `<div class="dk-component-input">`, optionally carrying
+  `data-size="small"`, `"medium"` or `"large"`. The label is a real
+  `<label class="dk-component-input__label" for="ID">`. The field wrapper is
+  `<div class="dk-component-input__field">` (a `<span>` still renders
+  correctly, `<div>` is what the docs now teach). Measured after the fix:
+  the accessible name is the label alone, `"Full name"`, and the caption is
+  wired in as the accessible description through
+  `<p class="dk-component-input__caption" id="ID-caption">` plus
+  `aria-describedby="ID-caption"` on the control. `check:contract` now
+  passes for Input.
+- **Migrated Forge's `model-approval` prototype to the new shape: 24
+  instances, 12 in `index.html` and 12 in `v2.html`.** Every one already had
+  a control `id`, so the migration reused it rather than inventing one.
+  `grep -c` for the old `<label class="dk-component-input">` shape returns 0
+  in both files. Input's own docs entry in `design-system/registry.js`
+  carried one further instance, migrated separately while that entry was
+  rebuilt, and Modal's own Preview and Trigger
+  examples in the same file carried two more, migrated in the final review
+  fix wave so the docs no longer teach the retired shape anywhere on the
+  Modal page. A handful of other embedded Input snippets outside Input's
+  own docs, `model-approval`, and Modal, Forge's root `index.html` and
+  `assets/forge-cards.js`, still use the old wrapping-label shape. They
+  render fine (the class names carry the CSS regardless of tag), but they
+  are out of scope for this change and were left alone.
+- **Fix: `outline: none` on the control silently removed the focus ring
+  from a `<textarea>` or `<select>` field, and the disabled border with
+  it.** Both the resting focus ring and the disabled-border hook were
+  narrowed to `:has(input:focus-visible)` and `:has(input:disabled)` while
+  `outline: none` stayed on all three control types, `input`, `textarea`
+  and `select`. A textarea or select inside a field therefore lost its
+  native outline and matched no rule that restored one: no focus indicator
+  at all, and no border change when disabled. Both selectors now read
+  `:has(:is(input, textarea, select):focus-visible)` and
+  `:has(:is(input, textarea, select):disabled)`. Verified with a keyboard
+  probe on a textarea field: before the fix the field's border and
+  box-shadow stayed at their resting values on real focus; after, the
+  border switches to the primary ring colour and the box-shadow shows the
+  usual 4px focus ring, matching an `<input>` field exactly.
+- **The error state is `aria-invalid="true"` on the control, not a modifier
+  class.** `.dk-component-input--error` and `.dk-component-input--disabled`
+  are both gone; the CSS now keys off `:has(input[aria-invalid="true"])` and
+  `:has(input:disabled)`. The visual state and what a screen reader
+  announces read off the same attribute, so they cannot drift apart the way
+  a class and an ARIA attribute set separately could.
+- **Three field heights, 38 / 44 / 52px for small / medium / large, all
+  `border-box`, each moving the box and the type together at 14 / 16 /
+  18px.** None is written as a literal: each is `calc()`'d from the
+  primitive scale, padding doubled plus the line box. Small and medium land
+  on Button's first two rungs so a field and a button share a row cleanly,
+  and Forge's `check:contract` measures a rendered field against a rendered
+  button to keep them there. Large deliberately does not match Button's
+  56px: a 52px field is the proportion a form wants, and a large field
+  usually stands alone.
+- **`medium` is a real value.** It was `small | large` with the middle rung
+  unnamed. Omitting the attribute still lands on the same rule, but Button
+  names its middle rung and one component spelling the middle size while
+  another leaves a hole is not something anyone should have to discover.
+- **That same derivation fixes the 46px these three heights replace.** The
+  old field was `min-height: 44px` under `box-sizing: content-box` with a
+  1px border, which rendered at 46px, two pixels proud of Button's 44px
+  medium in the same row. The field is `border-box` now, so it lines up
+  exactly.
+- **Two new slots, leading and trailing**, `.dk-component-input__leading`
+  and `__trailing`, sizing a child `svg` or `i` to 20px, stepping to 16px
+  at `data-size="small"` so they match the action buttons beside them. For
+  a currency prefix, a unit, or a search glyph.
+- **The field is flush with its surface and defined by its border.**
+  Background is `--dk-surface-current`, so the field tracks
+  `data-surface` at every level instead of holding one colour. The border
+  and the placeholder read three new mapped tokens,
+  `--dk-border-field-default`, `--dk-border-field-hover` and
+  `--dk-text-field-placeholder`, declared per theme because the neutral
+  ramp is not mirrored between light and dark and every borrowed token
+  therefore reads wrong in one of them. Hover moves the border and the
+  fill together.
+- **Two in-field actions**, `.dk-component-input__action` with
+  `data-input-reveal` or `data-input-clear`, wired by a new
+  `components/input/behaviour.js` (`dk.component.input.init()`, auto-run
+  on `DOMContentLoaded`). The reveal toggle flips `type` between
+  `password` and `text`, moves `aria-pressed`, and swaps its accessible
+  name; both glyphs live in the markup and CSS shows one, so the picture
+  cannot drift from the announced state. The clear button empties the
+  control, fires a bubbling native `input` event, and hides itself while
+  the field is empty. These are real buttons in the tab order with their
+  own names and focus rings, which is why the field's own ring keys off
+  `:has(input:focus-visible)` rather than `:focus-within`.
+- **Autofill no longer looks autofilled.** Chrome and Safari paint their
+  own fill at a level `background-color` cannot beat; the control now
+  stays genuinely transparent so it keeps following the field behind it,
+  including on hover.
+- **The required asterisk is warning, not error.** An unfilled required
+  field is a prompt, not a failure, and a form of ten of them should not
+  open entirely in red.
+- **The error message has its own colour token**,
+  `--dk-component-input-error-color`. It read `--dk-text-error-default`,
+  which is the status fill and glyph rung and measures 3.48:1 on a white
+  page, below AA for body text.
+- **A React component**: `Input`, `InputProps`, `InputSize`, exported from
+  `src/react/index.ts`. Falls back to `useId()` when the caller passes no
+  `id`, wires `aria-describedby` to caption then error (caption first) when
+  both are present, and sets `aria-invalid` only when an `error` prop is
+  given, never a class. `revealable` and `clearable` give the two in-field
+  actions; clearing goes through the prototype's value setter so it works
+  for a controlled and an uncontrolled field alike.
+- **A new gate: `check:contract`, added to Forge.** A stylesheet cannot
+  assert what a screen reader announces or what height a control renders
+  at, so this gate loads each documented component's live page, takes an
+  accessibility snapshot, and measures `getBoundingClientRect()`, against a
+  `contract` block declared in that component's registry entry. Input is
+  the first component to carry one. It also checks cross-component height
+  cohorts, which is what replaced Input reading Button's padding tokens
+  directly: an agreement between two components is a thing to assert, not
+  to implement by coupling.
+
+**Kit-wide, not Input.** Two files that affect every component:
+
+- **`kit/reset.css`** zeroes the browser's own margin on anything carrying
+  a `dk-component-` class, and gives form controls `font: inherit`. Every
+  text-bearing component was doing this by hand and Input forgot, which
+  put its caption 14px out of place. Scoped to kit classes and written at
+  zero specificity with `:where()`, so a consumer's markup is untouched
+  and any component rule wanting a margin still wins. A new Forge gate,
+  `check:ua-defaults`, proves nothing else is falling through.
+- **`kit/selection.css`** paints selected text in the brand primary with
+  white on top, the same in both themes. Scoped to `[data-brand]`, the
+  attribute a page sets to opt into the kit, because selection is
+  document-wide and this stylesheet loads into applications whose markup
+  the kit does not own.
+
+**Migration.** Replace `<label class="dk-component-input">...</label>` with
+`<div class="dk-component-input">...</div>`. Turn
+`<span class="dk-component-input__label">Text</span>` into
+`<label class="dk-component-input__label" for="ID">Text</label>`, where `ID`
+is the control's own `id`. Turn
+`<span class="dk-component-input__field">` into
+`<div class="dk-component-input__field">` (optional, a span still works).
+If there is a caption, give it `id="ID-caption"` and add
+`aria-describedby="ID-caption"` to the control. Replace any reliance on
+`.dk-component-input--error` or `.dk-component-input--disabled` with
+`aria-invalid="true"` or the native `disabled` attribute.
+

package/manifest/migrations/11.0.0.md

@@ -0,0 +1,24 @@
+## 11.0.0 - 2026-09-18
+
+- **Search input is now called Search bar**, and its source directory moves
+  with it. Input takes `type="search"` and gets a suggested magnifier and a
+  clear button with it, so there are genuinely two things, and one name for both
+  gave nobody a way to say which they meant. This is the prominent one: the
+  large rung, an elevation no other field has, one per page, no visible label.
+  A form field sits in the page; a search bar sits on top of it.
+- **BREAKING: the class and token names follow.** `.dk-component-search`
+  becomes `.dk-component-search-bar`, and the parts go from a hyphen to the
+  `__` every other component in the kit uses:
+  `.dk-component-search-icon` and `.dk-component-search-input` become
+  `.dk-component-search-bar__icon` and `.dk-component-search-bar__input`. Search
+  bar was the only component naming its parts with a hyphen, so fixing the name
+  and leaving the convention broken would have been half a job. The token prefix
+  moves with them, `--dk-component-search-*` to `--dk-component-search-bar-*`,
+  a clean 1:1 rename of six names.
+
+**Migration.** Search and replace, longest first so the root does not eat the
+parts: `dk-component-search-input` to `dk-component-search-bar__input`, then
+`dk-component-search-icon` to `dk-component-search-bar__icon`, then the bare
+`dk-component-search` to `dk-component-search-bar`, then
+`--dk-component-search-` to `--dk-component-search-bar-`.
+

package/manifest/migrations/12.0.0.md

@@ -0,0 +1,38 @@
+## 12.0.0 - 2026-09-18
+
+**Icon button, rebuilt.** It was a 34-line port with no token collection, the
+only component in the kit without one.
+
+- **BREAKING: `.dk-component-icon-btn` becomes `.dk-component-icon-button`**,
+  matching its own directory and the kit's no-abbreviation convention. Every
+  consumer is migrated in this release: 23 tags in Forge and five inside the kit
+  (Toast's close button, Dropzone's clear, three comments).
+- **BREAKING: it now lines up with Button.** Measured before: 28 / 32 / 40 / 48
+  against Button's 40 / 46 / 58 / 66 at the same size names, so an icon button
+  beside a text one was 12 to 18px short at every rung but the smallest. Height
+  is now derived the way Button's is, from the same padding and line-height
+  primitives, NOT from Button's own tokens, which would be a
+  component-to-component dependency. Three `check:contract` cohorts assert the
+  pairs so it cannot drift back.
+- **BREAKING: four rungs, `extra-small` to `large`.** small, medium and large
+  are Button's exactly; `extra-small` sits below Button's ladder because a text
+  button that small stops being pressable and an icon one does not. Measured
+  across Forge, every icon button in the product sat at 28, 32 or 40px, all at
+  or below Button's smallest, and nothing used the old top two rungs. Forge's
+  usages are remapped to the nearest new rung, so rendered sizes move by at most
+  2px.
+- **BREAKING: `.dk-component-icon-btn--subtle` retires into `data-variant`.**
+  It was documented as "the transparent-at-rest variant" and set
+  `background-color: var(--dk-surface-default-body)`: an opaque white square on
+  any surface that was not white. `data-variant="plain"` is the real thing.
+  Three variants now, `subtle` (the default, and the look this already had),
+  `plain`, and `raised`, which pairs with Button's raised.
+- **The accessible name is asserted, not assumed.** With no text, `aria-label`
+  is the only thing between this control and "button" being all a screen reader
+  can say about it, so `check:contract` now checks it.
+- Gone with the rewrite: five hardcoded icon sizes, a hardcoded 4px focus ring, a
+  `scale(0.9)` press that pressed harder than every other control in the kit, and
+  an alias colour read straight into a component rule.
+- Full docs: api table, three examples including one proving the row alignment,
+  and a playground.
+

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."
+  }
+}
+```
+