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

package/manifest/index.json

@@ -0,0 +1,402 @@
+{
+  "schema": 1,
+  "version": "23.4.0",
+  "built": "2026-10-22",
+  "components": [
+    {
+      "id": "accordion",
+      "name": "Accordion",
+      "purpose": "A list of things you can open: FAQs, settings, details on demand. Built on <details>, so it works before the script does, with motion that turns round mid-way."
+    },
+    {
+      "id": "action-bar",
+      "name": "Action bar",
+      "purpose": "A flow's controls along the bottom: Back, Next, what the step costs and how far along it is."
+    },
+    {
+      "id": "alert",
+      "name": "Alert",
+      "purpose": "An inline, persistent message in the page: a status colour, an optional icon, title, body, actions and a dismiss button."
+    },
+    {
+      "id": "app-shell",
+      "name": "App shell",
+      "purpose": "The layout that places a Sidebar, a Top bar, the page and an Action bar, in the viewport or in a box."
+    },
+    {
+      "id": "avatar",
+      "name": "Avatar",
+      "purpose": "A person, as their photo or their initials: the photo fades in once it has loaded, and the initials stay if it never does."
+    },
+    {
+      "id": "body",
+      "name": "Body",
+      "purpose": "The body-copy primitive: one element, eleven colours, two emphasis rungs, four sizes, eight weights, and, unlike the component- library original, aware of the surface it sits on."
+    },
+    {
+      "id": "box",
+      "name": "Box",
+      "purpose": "A grouped surface: a panel that separates what is in it from what is around it, optionally laid out as a responsive grid of facts."
+    },
+    {
+      "id": "breadcrumb",
+      "name": "Breadcrumb",
+      "purpose": "Where this page sits, and the way back up: the pages above it as quiet pills, its own name last."
+    },
+    {
+      "id": "button",
+      "name": "Button",
+      "purpose": "Two families: four semantic variants (default / accent / outline / subtle) across primary and error statuses, and a four-rung neutral emphasis ladder: ghost (no chrome until you touch it), subtle (a filled tint), plain (flat on its surface with an edge), raised (that edge lifted above it), plus inverse (maximum contrast, opposite-theme fill)."
+    },
+    {
+      "id": "calendar",
+      "name": "Calendar",
+      "purpose": "A month grid for choosing a date or a range: the engine behind Date picker, also usable on its own."
+    },
+    {
+      "id": "card",
+      "name": "Card",
+      "purpose": "A surface that goes somewhere: media over or beside a title, a subtitle and a row of meta, the whole card the target."
+    },
+    {
+      "id": "checkbox",
+      "name": "Checkbox",
+      "purpose": "Any number of these, or none. A native input, a painted box, three sizes, and a mixed state for a parent row."
+    },
+    {
+      "id": "choice-card",
+      "name": "Choice card",
+      "purpose": "A radio or checkbox drawn as a card, for a choice that needs room to explain itself: a payment frequency and its price, a saved card."
+    },
+    {
+      "id": "code-input",
+      "name": "Code input",
+      "purpose": "A verification code, a PIN, a voucher. N characters, one per box, with one real input underneath them."
+    },
+    {
+      "id": "date-picker",
+      "name": "Date picker",
+      "purpose": "A date field you can type into or pick from a calendar: one date (a date of birth among them) or a start and an end."
+    },
+    {
+      "id": "day-of-month",
+      "name": "Day of month",
+      "purpose": "A day of the month, 1 to 31, chosen from a grid: the day a bill is paid."
+    },
+    {
+      "id": "detail-list",
+      "name": "Detail list",
+      "purpose": "Rows of a glyph, a title and a line, with a value at the end, on a hairline between rows."
+    },
+    {
+      "id": "divider",
+      "name": "Divider",
+      "purpose": "A rule between things. An <hr> that follows the border palette, mostly steps with the surface level, and turns vertical without a wrapper."
+    },
+    {
+      "id": "dropdown",
+      "name": "Dropdown",
+      "purpose": "A menu of commands hanging off a trigger. Select's surface, a menu's semantics: real focus, no value."
+    },
+    {
+      "id": "dropzone",
+      "name": "Dropzone",
+      "purpose": "A place to drop or browse for files: one file or a list, with the type, size and count checked on the way in and a plain message when something is refused."
+    },
+    {
+      "id": "eyebrow",
+      "name": "Eyebrow",
+      "purpose": "Uppercase labels, the component-library's Overline, renamed. Three fixed sizes (12 / 11 / 10 px) with tracking that widens as the size shrinks, bold by default, the Body colour grammar."
+    },
+    {
+      "id": "feedback-badge",
+      "name": "Feedback badge",
+      "purpose": "A status's circle inside its own soft ring, with a white glyph. The big mark at the top of a success screen or an empty state."
+    },
+    {
+      "id": "glider",
+      "name": "Glider",
+      "purpose": "One value from a few options side by side, or several: a raised frame with a primary pill that slides to the choice."
+    },
+    {
+      "id": "heading",
+      "name": "Heading",
+      "purpose": "The outline tier: Inter, six responsive sizes, nine weights, the Body colour grammar."
+    },
+    {
+      "id": "hero",
+      "name": "Hero",
+      "purpose": "The display tier: Syne on the heading ramp, five responsive sizes, four weights, the Body colour grammar."
+    },
+    {
+      "id": "icon",
+      "name": "Icon",
+      "purpose": "The icon primitive, built to behave like text: the same colour grammar, sizes named and fixed like the body rungs, weight as stroke width, and 1em when unsized."
+    },
+    {
+      "id": "icon-button",
+      "name": "Icon button",
+      "purpose": "A button whose whole label is its icon. Same rungs as Button, so the two line up in a row, plus one rung below Button's smallest because compact chrome is where most icon buttons actually live."
+    },
+    {
+      "id": "icon-tile",
+      "name": "Icon tile",
+      "purpose": "A glyph on a small coloured square, subtle or solid, with one corner at every size."
+    },
+    {
+      "id": "input",
+      "name": "Text input",
+      "purpose": "Label, field and caption, with leading and trailing slots, three sizes, and error, disabled and read-only states."
+    },
+    {
+      "id": "link",
+      "name": "Link",
+      "purpose": "A way to go somewhere. Inline, it is the sentence it sits in; standalone, it has its own size and room for an icon."
+    },
+    {
+      "id": "loading-spinner",
+      "name": "Loading spinner",
+      "purpose": "The brand symbol inside a sweeping arc. It spins for at least half a second, so a fast load does not flash, and tells you when it has gone."
+    },
+    {
+      "id": "logo",
+      "name": "Logo",
+      "purpose": "The brand mark, as a symbol or with its wordmark, in three colourways."
+    },
+    {
+      "id": "modal",
+      "name": "Modal",
+      "purpose": "A dialog on a backdrop, and a bottom sheet on a phone. Focus trap, Escape, scroll lock and focus return included."
+    },
+    {
+      "id": "pagination",
+      "name": "Pagination",
+      "purpose": "Where a long list is in pages, and the way to the others: a page list between two arrows, with an optional count of what is showing and a rows select."
+    },
+    {
+      "id": "payment-form",
+      "name": "Payment form",
+      "purpose": "Stripe's Payment Element on the kit's tokens: its fields, labels, tabs and errors follow the theme, the surface and the tone around them, like any kit field."
+    },
+    {
+      "id": "price-summary",
+      "name": "Price summary",
+      "purpose": "Labelled amounts on hairlines, then their total with a note under it. Credits in the brand tone."
+    },
+    {
+      "id": "radio",
+      "name": "Radio",
+      "purpose": "One of these, and only one. Checkbox's twin, with a circular box, a drawn dot and a group that is not optional."
+    },
+    {
+      "id": "section-heading",
+      "name": "Section heading",
+      "purpose": "A glyph beside a title and a line under it, heading a list or a card from outside."
+    },
+    {
+      "id": "select",
+      "name": "Select",
+      "purpose": "One value from a list. A field-shaped trigger, a floating listbox, and the keyboard that drives both."
+    },
+    {
+      "id": "shield",
+      "name": "Shield",
+      "purpose": "A shield that scales in, shakes when a code is wrong and pulses a tick in when it is right."
+    },
+    {
+      "id": "sidebar",
+      "name": "Sidebar",
+      "purpose": "An app's main navigation. A rail on a desktop that collapses to its glyphs, and on a phone a bottom tab bar or a drawer, from one set of markup."
+    },
+    {
+      "id": "stepper",
+      "name": "Stepper",
+      "purpose": "Where someone is in a process with a known number of steps, and what is left."
+    },
+    {
+      "id": "switch",
+      "name": "Switch",
+      "purpose": "An on/off setting that takes effect immediately. Checkbox's label, description, sizes and states on a track and a thumb, with a settings-row treatment of its own."
+    },
+    {
+      "id": "table",
+      "name": "Table",
+      "purpose": "Rows and columns, as a real <table>. Sorting, selection, sticky edges and the two rows that stand in for rows."
+    },
+    {
+      "id": "tabs",
+      "name": "Tabs",
+      "purpose": "A strip of tabs that switch between panels of one page, on a hairline with a bar that slides to the selected tab."
+    },
+    {
+      "id": "tag",
+      "name": "Tag",
+      "purpose": "A label, a category, a status. Six statuses, three variants, and a dot for the column where the word is already there."
+    },
+    {
+      "id": "textarea",
+      "name": "Text area",
+      "purpose": "Several lines of text: notes, messages, comments. Input's field, sized in rows, with auto-grow, a character counter and a submit shortcut."
+    },
+    {
+      "id": "toast",
+      "name": "Toast",
+      "purpose": "A message that arrives, says one thing and goes: a card with a badge, a title and a description, or a compact one-liner."
+    },
+    {
+      "id": "tooltip",
+      "name": "Tooltip",
+      "purpose": "A floating label for an element that needs one word more than it can show."
+    },
+    {
+      "id": "top-bar",
+      "name": "Top bar",
+      "purpose": "The page's banner: the brand, an optional row of links, and what the page puts at the end, from a help line to the account."
+    },
+    {
+      "id": "vehicle",
+      "name": "Vehicle",
+      "purpose": "A photo of a vehicle, from the car-line photo catalogue trimmed to the car: on its own at any size, or stood on a panel the car overflows. 304 models ship with the kit."
+    }
+  ],
+  "tokenGroups": [
+    {
+      "id": "surface",
+      "title": "Surfaces"
+    },
+    {
+      "id": "border",
+      "title": "Borders and edges"
+    },
+    {
+      "id": "text",
+      "title": "Text colours"
+    },
+    {
+      "id": "icon",
+      "title": "Icon colours"
+    },
+    {
+      "id": "interactive",
+      "title": "Interaction"
+    },
+    {
+      "id": "font",
+      "title": "Type"
+    },
+    {
+      "id": "motion",
+      "title": "Motion"
+    },
+    {
+      "id": "spacing",
+      "title": "Spacing"
+    },
+    {
+      "id": "radius",
+      "title": "Radius"
+    },
+    {
+      "id": "border-width",
+      "title": "Border width"
+    },
+    {
+      "id": "shadow",
+      "title": "Shadows"
+    }
+  ],
+  "migrations": [
+    {
+      "major": "23.0.0",
+      "title": "23.0.0 - 2026-10-17"
+    },
+    {
+      "major": "22.0.0",
+      "title": "22.0.0 - 2026-10-15"
+    },
+    {
+      "major": "21.0.0",
+      "title": "21.0.0 - 2026-10-14"
+    },
+    {
+      "major": "20.0.0",
+      "title": "20.0.0 - 2026-10-12"
+    },
+    {
+      "major": "19.0.0",
+      "title": "19.0.0 - 2026-10-06"
+    },
+    {
+      "major": "18.0.0",
+      "title": "18.0.0 - 2026-10-01"
+    },
+    {
+      "major": "17.0.0",
+      "title": "17.0.0 - 2026-09-24"
+    },
+    {
+      "major": "16.0.0",
+      "title": "16.0.0 - 2026-09-22"
+    },
+    {
+      "major": "15.0.0",
+      "title": "15.0.0 - 2026-09-22"
+    },
+    {
+      "major": "14.0.0",
+      "title": "14.0.0 - 2026-09-22"
+    },
+    {
+      "major": "13.0.0",
+      "title": "13.0.0 - 2026-09-19"
+    },
+    {
+      "major": "12.0.0",
+      "title": "12.0.0 - 2026-09-18"
+    },
+    {
+      "major": "11.0.0",
+      "title": "11.0.0 - 2026-09-18"
+    },
+    {
+      "major": "10.0.0",
+      "title": "10.0.0 - 2026-09-17"
+    },
+    {
+      "major": "9.0.0",
+      "title": "9.0.0 - 2026-09-14"
+    },
+    {
+      "major": "8.0.0",
+      "title": "8.0.0 - 2026-09-12"
+    },
+    {
+      "major": "7.0.0",
+      "title": "7.0.0 — 2026-09-12"
+    },
+    {
+      "major": "6.0.0",
+      "title": "6.0.0 — 2026-09-11"
+    },
+    {
+      "major": "5.0.0",
+      "title": "5.0.0 — 2026-09-10"
+    },
+    {
+      "major": "4.0.0",
+      "title": "4.0.0 — 2026-09-10"
+    },
+    {
+      "major": "3.0.0",
+      "title": "3.0.0 — 2026-09-09"
+    },
+    {
+      "major": "2.0.0",
+      "title": "2.0.0 — 2026-09-09"
+    },
+    {
+      "major": "1.0.0",
+      "title": "1.0.0 — 2026-08-18"
+    }
+  ]
+}

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