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

package/manifest/migrations/4.0.0.md

@@ -0,0 +1,147 @@
+## 4.0.0 — 2026-09-10
+
+### Breaking
+
+- **The type scale is rebuilt, and sizes leave the h1…h6 vocabulary.** Hero,
+  Heading and Body now read one Karmo-owned scale
+  (`alias/karmo/font/type-scale.css`) and name their rungs from one shared
+  t-shirt vocabulary, `xxlarge` … `xxsmall` — the words Body and Eyebrow already
+  used. The audit that prompted this found three faults: Hero read the HEADING
+  ramp, so the display tier topped out at the same 48px as an H1 and ran down to
+  24px; the heading ramp had a 36% gap at the top and three rungs inside 4px at
+  the bottom (28 · 26 · 24); and Body jumped 16 → 20 with no reading rung
+  between. Every value is now a `--dk-primitive-scale-*` step (one noted
+  exception, 26px) and every ramp is monotonic in size and in leading ratio.
+    - Hero — its own DISPLAY ramp, 72 · 64 · 56 · 48 · 40 desktop, scaling over
+      three breakpoints, never below 40px.
+    - Heading — seven rungs, 48 · 40 · 36 · 32 · 28 · 24 · 20 desktop, every step
+      at least 11%.
+    - Body — five rungs, 20 · 18 · 16 · 14 · 12, fixed at every breakpoint.
+      **`large` changed VALUE, not just name**: it was 20px, it is now the new
+      18px rung, and the old 20px is `xlarge`. This is the only silent change in
+      the release — a stale `data-size="large"` still renders, 2px smaller.
+    - Eyebrow — unchanged.
+  Why not h1…h6: the size axis exists to decouple the visual size from the
+  element, and naming its values after the HTML outline invites exactly the
+  coupling it was built to break — an author who needs an `<h2>` reaches for
+  `data-size="h2"` and lets the look pick the semantics. The element is still
+  yours; the size is now named in a vocabulary that cannot be mistaken for it.
+- **`disabled` is a state, not a colour.** `data-color="disabled"` is gone from
+  body, heading, hero, eyebrow and icon; the state is `[data-disabled]` or
+  `[aria-disabled="true"]`, the pair Button already accepts. It composes with
+  `data-color` instead of replacing it, so a disabled error label is finally
+  expressible. Not `data-status` — that axis is the five semantic statuses, and
+  disabled is an interaction state, which is how every other component models it.
+- **`data-dc-tooltip` → `data-dk-tooltip`.** The last public name still carrying
+  the pre-2.0.0 prefix.
+
+#### Added
+
+- `data-style="italic"` on Heading. Inter ships a drawn italic at every weight,
+  so this selects a real face. Hero deliberately does NOT get one: Syne ships
+  `normal` only, and a browser-synthesised oblique is not a typeface decision.
+
+##### Fixed
+
+- Stale `--dc-*` collection names and retired `window.dc*` globals in source
+  comments, which had named tokens and functions that no longer exist since
+  2.0.0. Prose only.
+
+Migration map: `migrations/4.0.0-type-scale.json`. Design note: forge
+`docs/superpowers/specs/2026-09-10-drift-type-scale-design.md`.
+
+### Rename map: `migrations/4.0.0-type-scale.json`
+
+```json
+{
+  "version": "4.0.0",
+  "date": "2026-09-10",
+  "note": "The type scale rebuild. Four breaking changes: (1) Hero and Heading size values move from the h1…h6 outline vocabulary to the shared t-shirt rungs, and Hero moves onto its own display ramp; (2) Body gains an 18px rung, which means `large` CHANGES VALUE — see sizes.body.warning; (3) disabled stops being a data-color value and becomes a state; (4) the tooltip markup attribute takes the dk prefix. Every entry below is a mechanical find-and-replace except the one flagged warning.",
+
+  "sizes": {
+    "note": "data-size values, per component. Old px are desktop values.",
+
+    "hero": {
+      "note": "Hero now reads the DISPLAY ramp (72 · 64 · 56 · 48 · 40 desktop) instead of the heading ramp, so it is bigger at every rung and stops below 40px on purpose. h1 keeps its exact size under a new name; h2 rounds up 2px. h3/h4/h5 have NO display equivalent — 28/26/24px in Syne was a heading wearing the display face, and the right migration is to change the element to a Heading, not to pick the nearest Hero rung.",
+      "h1": "medium",
+      "h2": "small",
+      "h3": "→ use .dk-component-heading[data-size=\"small\"]",
+      "h4": "→ use .dk-component-heading[data-size=\"xsmall\"]",
+      "h5": "→ use .dk-component-heading[data-size=\"xsmall\"]"
+    },
+
+    "heading": {
+      "note": "Seven rungs, 48 → 20 desktop. h1, h3, h5 and h6 keep their exact px; h2 rounds up 2px (38 → 40); h4 rounds down 2px (26 → 24) and lands on the same rung as h5, which is the point — 28/26/24 were three rungs inside 4px.",
+      "h1": "xxlarge",
+      "h2": "xlarge",
+      "h3": "small",
+      "h4": "xsmall",
+      "h5": "xsmall",
+      "h6": "xxsmall"
+    },
+
+    "body": {
+      "warning": "`large` is the one name in 4.0.0 whose VALUE changed rather than its name: it was 20px and is now 18px, the new reading rung. Anything that wants the old 20px must move to `xlarge`. A stale data-size=\"large\" keeps rendering — 2px smaller — so this one cannot be caught by a missing-token check. Search for it explicitly.",
+      "large": "xlarge",
+      "medium": "medium",
+      "small": "small",
+      "extra-small": "xsmall"
+    },
+
+    "eyebrow": {
+      "note": "Unchanged — large/medium/small at 12/11/10 were already on the shared vocabulary."
+    }
+  },
+
+  "states": {
+    "note": "disabled is a state now, not a palette value, so it composes with data-color instead of replacing it. Applies to body, heading, hero, eyebrow and icon. Use aria-disabled=\"true\" when the thing really is announced as disabled; data-disabled when it is purely presentational.",
+    "data-color=\"disabled\"": "data-disabled",
+    "data-color=\"disabled\" data-emphasis=\"subtle\"": "data-disabled data-emphasis=\"subtle\""
+  },
+
+  "attributes": {
+    "note": "The last public name still on the pre-2.0.0 prefix.",
+    "data-dc-tooltip": "data-dk-tooltip"
+  },
+
+  "tokens": {
+    "--dk-component-hero-h1-font-size": "--dk-component-hero-medium-font-size",
+    "--dk-component-hero-h1-line-height": "--dk-component-hero-medium-line-height",
+    "--dk-component-hero-h2-font-size": "--dk-component-hero-small-font-size",
+    "--dk-component-hero-h2-line-height": "--dk-component-hero-small-line-height",
+    "--dk-component-hero-h3-font-size": "--dk-component-heading-small-font-size",
+    "--dk-component-hero-h3-line-height": "--dk-component-heading-small-line-height",
+    "--dk-component-hero-h4-font-size": "--dk-component-heading-xsmall-font-size",
+    "--dk-component-hero-h4-line-height": "--dk-component-heading-xsmall-line-height",
+    "--dk-component-hero-h5-font-size": "--dk-component-heading-xsmall-font-size",
+    "--dk-component-hero-h5-line-height": "--dk-component-heading-xsmall-line-height",
+
+    "--dk-component-heading-h1-font-size": "--dk-component-heading-xxlarge-font-size",
+    "--dk-component-heading-h1-line-height": "--dk-component-heading-xxlarge-line-height",
+    "--dk-component-heading-h2-font-size": "--dk-component-heading-xlarge-font-size",
+    "--dk-component-heading-h2-line-height": "--dk-component-heading-xlarge-line-height",
+    "--dk-component-heading-h3-font-size": "--dk-component-heading-small-font-size",
+    "--dk-component-heading-h3-line-height": "--dk-component-heading-small-line-height",
+    "--dk-component-heading-h4-font-size": "--dk-component-heading-xsmall-font-size",
+    "--dk-component-heading-h4-line-height": "--dk-component-heading-xsmall-line-height",
+    "--dk-component-heading-h5-font-size": "--dk-component-heading-xsmall-font-size",
+    "--dk-component-heading-h5-line-height": "--dk-component-heading-xsmall-line-height",
+    "--dk-component-heading-h6-font-size": "--dk-component-heading-xxsmall-font-size",
+    "--dk-component-heading-h6-line-height": "--dk-component-heading-xxsmall-line-height",
+
+    "--dk-component-body-large-font-size": "--dk-component-body-xlarge-font-size",
+    "--dk-component-body-large-line-height": "--dk-component-body-xlarge-line-height",
+    "--dk-component-body-extra-small-font-size": "--dk-component-body-xsmall-font-size",
+    "--dk-component-body-extra-small-line-height": "--dk-component-body-xsmall-line-height"
+  },
+
+  "new-names": {
+    "note": "Added, with nothing to migrate from.",
+    "--dk-font-scale-display-{xxlarge|xlarge|large|medium|small}-{text-size|line-height}": "the display ramp, responsive",
+    "--dk-font-scale-heading-{xxlarge…xxsmall}-{text-size|line-height}": "the heading ramp, responsive",
+    "--dk-font-scale-body-{xlarge…xsmall}-{text-size|line-height}": "the body ramp, fixed",
+    "--dk-component-heading-italic-font-style": "data-style=\"italic\" on Heading — Inter has a drawn italic; Hero has no equivalent because Syne ships none"
+  }
+}
+```
+

package/manifest/migrations/5.0.0.md

@@ -0,0 +1,73 @@
+## 5.0.0 — 2026-09-10
+
+### Breaking
+
+- **Disabled loses its emphasis axis on the type primitives.** `data-emphasis="subtle"`
+  no longer does anything alongside the disabled state on body, heading, hero,
+  eyebrow or icon, and the five `--dk-component-{x}-disabled-subtle-color`
+  tokens are removed. The surviving token drops the segment it no longer varies
+  on: `--dk-component-{x}-disabled-default-color` → `--dk-component-{x}-disabled-color`.
+
+  The two rungs were never two strengths of one idea. Measured against the page
+  surface, `-default` is **2.88:1** in light and **5.57:1** in dark; `-subtle` is
+  **1.80:1** and **2.33:1**. Below 2:1 is not a quieter label, it is text nobody
+  can read — so on prose the axis offered a choice between "dim" and "invisible"
+  with no rule for picking one. The kit itself never had to pick: every disabled
+  CONTROL label (Button's six variants, Checkbox's description) takes `-subtle`,
+  and `-default` was referenced exactly once outside the type primitives, by the
+  accent Button's text-*shadow*. Prose keeps the readable rung; controls keep
+  theirs.
+
+#### Unchanged, deliberately
+
+- `--dk-text-disabled-subtle` / `--dk-icon-disabled-subtle` stay — Button and
+  Checkbox still read them, and a disabled control is conventionally near-
+  invisible in a way a paragraph is not.
+- `data-emphasis="subtle"` still works with `data-color="neutral"`, whose subtle
+  rung is a real, legible de-emphasis.
+
+Migration map: `migrations/5.0.0-disabled-one-rung.json`.
+
+### Rename map: `migrations/5.0.0-disabled-one-rung.json`
+
+```json
+{
+  "version": "5.0.0",
+  "date": "2026-09-10",
+  "note": "Disabled loses its emphasis axis on the type primitives. One breaking change, and the mechanical part of it is a token rename; the behavioural part is that `data-emphasis=\"subtle\"` no longer does anything alongside the disabled state. Nothing else moves — data-emphasis still works for data-color=\"neutral\", and the Mapped --dk-text-disabled-subtle / --dk-icon-disabled-subtle tokens are untouched because Button and Checkbox still read them.",
+
+  "why": "The two rungs were never two strengths of one idea. Measured against the page surface: -default is 2.88:1 in light and 5.57:1 in dark; -subtle is 1.80:1 and 2.33:1. Below 2:1 is not a quieter label, it is text nobody can read, so on prose the axis offered a choice between 'dim' and 'invisible' with no rule for picking. The kit never had to pick either: every disabled CONTROL label (Button's six variants, Checkbox's description) takes -subtle, and -default was referenced exactly once outside the type primitives (the accent Button's text-shadow). Prose keeps the readable rung; controls keep theirs.",
+
+  "attributes": {
+    "note": "Applies to body, heading, hero, eyebrow and icon. Drop the emphasis attribute; the disabled state alone is now the whole answer. If it was the ONLY reason data-emphasis was on the element, remove the attribute entirely.",
+    "data-disabled data-emphasis=\"subtle\"": "data-disabled",
+    "aria-disabled=\"true\" data-emphasis=\"subtle\"": "aria-disabled=\"true\""
+  },
+
+  "tokens": {
+    "note": "The `-default` segment goes with the axis: the collection grammar omits any segment a token no longer varies on. The -subtle component tokens are REMOVED, not renamed — a var() to one now resolves to nothing, which is the intended loud failure.",
+    "--dk-component-body-disabled-default-color": "--dk-component-body-disabled-color",
+    "--dk-component-heading-disabled-default-color": "--dk-component-heading-disabled-color",
+    "--dk-component-hero-disabled-default-color": "--dk-component-hero-disabled-color",
+    "--dk-component-eyebrow-disabled-default-color": "--dk-component-eyebrow-disabled-color",
+    "--dk-component-icon-disabled-default-color": "--dk-component-icon-disabled-color"
+  },
+
+  "removed": {
+    "note": "No replacement. If a design genuinely needs 1.8:1 text, it is not a disabled label and should say what it actually is.",
+    "--dk-component-body-disabled-subtle-color": null,
+    "--dk-component-heading-disabled-subtle-color": null,
+    "--dk-component-hero-disabled-subtle-color": null,
+    "--dk-component-eyebrow-disabled-subtle-color": null,
+    "--dk-component-icon-disabled-subtle-color": null
+  },
+
+  "unchanged": {
+    "note": "Called out because they look like they should have moved and did not.",
+    "--dk-text-disabled-subtle": "still the Mapped token every disabled control label reads",
+    "--dk-icon-disabled-subtle": "same, for icons inside disabled controls",
+    "data-emphasis=\"subtle\" with data-color=\"neutral\"": "unaffected — neutral's subtle rung is a real, legible de-emphasis"
+  }
+}
+```
+

package/manifest/migrations/6.0.0.md

@@ -0,0 +1,67 @@
+## 6.0.0 — 2026-09-11
+
+- **BREAKING: icon sizes are the pixel number, not a t-shirt.** Five rungs become
+  nine: 12, 14, 16, 20, 24, 28, 32, 40, 48. Every old name maps to the pixel value
+  it already resolved to, so nothing renders differently:
+  `extra-small`→`12`, `small`→`16`, `medium`→`20`, `large`→`24`,
+  `extra-large`→`32`. Map in `migrations/6.0.0-icon-numeric-sizes.json`.
+- **Why numbers.** Figma has always called these 12 and 24, so every handoff
+  carried a translation step that existed only because the kit disagreed with the
+  design tool. Numbers also let a rung slot in without renaming its neighbours:
+  adding 14 between 12 and 16 meant inventing a name between extra-small and
+  small, and 40 and 48 meant extra-extra-large and worse.
+- **Four genuinely new rungs**: 14 for dense chrome, 28 between 24 and 32, and 40
+  and 48 for display sizes the old scale could not reach. Every value is an
+  existing scale primitive; nothing new was invented.
+- **The old names are removed, not aliased.** A `var()` to one now resolves to
+  nothing, which is the loud failure this kit prefers over a silent fallback to
+  some default size.
+- **data-weight is unchanged at three rungs**, and that is a decision rather than
+  an omission. The stroke scales with the icon, so `bold` at 12px already renders
+  around 1.25px; splitting that into five or seven steps would be differences
+  nobody can see at the sizes icons are actually used, and every extra rung is
+  another cell in the token matrix.
+
+### Rename map: `migrations/6.0.0-icon-numeric-sizes.json`
+
+```json
+{
+  "version": "6.0.0",
+  "date": "2026-09-11",
+  "note": "Icon sizes stop being t-shirts and become the pixel number. Five rungs become nine: 12, 14, 16, 20, 24, 28, 32, 40, 48. The four existing values keep their pixel sizes exactly, so this is a rename and not a resize, except that `medium` was 20px and anyone who assumed it meant 24 will now have to say which they meant.",
+
+  "why": "Figma has always called these 12 and 24, so every handoff carried a translation step that existed only because the kit disagreed with the design tool. Numbers also let a rung slot in without renaming its neighbours: adding 14 between 12 and 16 under the old scheme meant inventing a name between extra-small and small, and adding 40 and 48 meant extra-extra-large and worse. More sizes were asked for because five did not cover the range; nine do, and the scheme no longer fights the next addition.",
+
+  "attributes": {
+    "note": "Applies to any element with class dk-component-icon. The pixel value each old name resolved to is the new name, so rendering is unchanged.",
+    "data-size=\"extra-small\"": "data-size=\"12\"",
+    "data-size=\"small\"": "data-size=\"16\"",
+    "data-size=\"medium\"": "data-size=\"20\"",
+    "data-size=\"large\"": "data-size=\"24\"",
+    "data-size=\"extra-large\"": "data-size=\"32\""
+  },
+
+  "tokens": {
+    "note": "Same mapping at the token level. The five old names are REMOVED, not aliased: a var() to one resolves to nothing, which is the loud failure this kit prefers over a silent fallback to some default size.",
+    "--dk-component-icon-extra-small-size": "--dk-component-icon-12-size",
+    "--dk-component-icon-small-size": "--dk-component-icon-16-size",
+    "--dk-component-icon-medium-size": "--dk-component-icon-20-size",
+    "--dk-component-icon-large-size": "--dk-component-icon-24-size",
+    "--dk-component-icon-extra-large-size": "--dk-component-icon-32-size"
+  },
+
+  "added": {
+    "note": "Four new rungs with no predecessor. 14 for dense table chrome, 28 between 24 and 32, and 40 and 48 for the display sizes the old scale simply could not reach.",
+    "--dk-component-icon-14-size": "var(--dk-primitive-scale-3-5)",
+    "--dk-component-icon-28-size": "var(--dk-primitive-scale-7)",
+    "--dk-component-icon-40-size": "var(--dk-primitive-scale-10)",
+    "--dk-component-icon-48-size": "var(--dk-primitive-scale-12)"
+  },
+
+  "unchanged": {
+    "note": "data-weight stays at three rungs. The stroke scales with the icon, so bold at 12px already renders around 1.25px; splitting that further would be differences nobody can see at the sizes icons are actually used.",
+    "data-weight": ["light", "regular", "bold"]
+  }
+}
+```
+

package/manifest/migrations/7.0.0.md

@@ -0,0 +1,71 @@
+## 7.0.0 — 2026-09-12
+
+- **Shadows are one ramp, named for the job.** `raised` (a thing resting on the
+  page), `lifted` (the same thing picked up), `floating` (a layer above the
+  page), `overlay` (a layer above everything), `on-color` (any of those on a
+  coloured fill). A token called `card` was already doing the work for toasts,
+  menus and a search field, which is the tell that it was named for the wrong
+  thing. Light values are unchanged, so the rename alone repaints nothing.
+- **Thirteen of the nineteen shadow tokens had never been used anywhere.** The
+  upstream `drop-*` and `inner-*` families are COLOURS, not shadows:
+  `color-mix` with no offset or blur, unusable without writing the geometry
+  yourself, and only one thing in the kit ever did. They still resolve, since
+  upstream owns the block above the fence and a refresh would restore them, but
+  they are no longer part of the system and the Shadows page no longer presents
+  them as shadows. Markup composing them by hand keeps working.
+- **The modal had no shadow token at all.** It hardcoded
+  `0 4px 8px -2px rgba(0,0,0,.1), 0 2px 4px -2px rgba(0,0,0,.06)`, which never
+  themed and was lighter than a card on hover, leaving the most elevated thing
+  in the system with the least considered elevation. It uses `overlay` now.
+- **Dark is not light with more alpha.** Black falling on a dark surface has
+  almost no range, which is why the old dark values read as nothing. Alpha
+  roughly doubles again (raised 0.16 to 0.36, lifted 0.20 to 0.44), and the two
+  genuinely floating rungs gain a hairline of light along the top edge, which is
+  how a raised surface catches light in a dark room. The lower rungs skip it: a
+  tab is not floating, and a bright line across its top reads as a seam.
+- **`--dk-shadow-focus-ring`** for the `0 0 0 4px` primary ring that card,
+  checkbox, switch and select each wrote out raw. Button keeps its own, whose
+  width and colour are already component tokens that vary by variant.
+- Migration map in `migrations/7.0.0-shadow-roles.json`.
+
+### Rename map: `migrations/7.0.0-shadow-roles.json`
+
+```json
+{
+  "version": "7.0.0",
+  "summary": "Shadows become one ramp named for the job. Light values are unchanged; dark is deeper, and the two floating rungs gain a hairline top edge.",
+  "rename": {
+    "--dk-shadow-card-faint": "--dk-shadow-raised",
+    "--dk-shadow-card-subtle": "--dk-shadow-lifted",
+    "--dk-shadow-card-default": "--dk-shadow-floating",
+    "--dk-shadow-card-on-color": "--dk-shadow-on-color",
+    "--dk-shadow-popover": "--dk-shadow-overlay"
+  },
+  "added": {
+    "--dk-shadow-focus-ring": "The 0 0 0 4px primary-300 ring that card, checkbox, switch and select each wrote out raw. Button keeps its own, whose width and colour are already component tokens."
+  },
+  "removedFromTheSystem": {
+    "note": "The upstream drop-* and inner-* families are colours, not shadows: color-mix with no offset or blur, unusable without writing the geometry yourself. Thirteen of the fourteen had never been used anywhere, and the one that was (drop-lg, in the select menu) now uses --dk-shadow-floating. They still resolve, because upstream owns the block above the fence in tokens/mapped/shadow.css and a refresh would restore them, but they are no longer part of the shadow system and the Shadows page no longer lists them. Markup that composes them by hand keeps working.",
+    "tokens": [
+      "--dk-shadow-drop-xs",
+      "--dk-shadow-drop-sm-1",
+      "--dk-shadow-drop-sm-2",
+      "--dk-shadow-drop-md-1",
+      "--dk-shadow-drop-md-2",
+      "--dk-shadow-drop-lg-1",
+      "--dk-shadow-drop-lg-2",
+      "--dk-shadow-drop-xl-1",
+      "--dk-shadow-drop-xl-2",
+      "--dk-shadow-drop-2xl",
+      "--dk-shadow-drop-3xl",
+      "--dk-shadow-inner-sm",
+      "--dk-shadow-inner-md",
+      "--dk-shadow-inner-lg"
+    ]
+  },
+  "alsoFixed": {
+    "modal": "dk-component-modal hardcoded 0 4px 8px -2px rgba(0,0,0,.1), 0 2px 4px -2px rgba(0,0,0,.06): it never themed, and it was lighter than a card on hover. It now uses --dk-shadow-overlay."
+  }
+}
+```
+

package/manifest/migrations/8.0.0.md

@@ -0,0 +1,16 @@
+## 8.0.0 - 2026-09-12
+
+- **drift-kit is importable from React.** New `@karmo-co/drift-kit/react` covering
+  Body, Heading, Hero, Eyebrow, Divider and Button, and `@karmo-co/drift-kit/icons/<set>`
+  covering all eight icon sets. Props are the data attributes with `data-` dropped,
+  so a prototype and an app use the same words in the same order.
+- Components are thin: class names and attributes, no styling runtime, no state.
+  All of them render on the server and none carries a `'use client'` directive.
+- Icons are per-icon named exports annotated `/*#__PURE__*/`, so an app ships only
+  what it imports rather than all 2,090 lucide glyphs.
+- One prop had to be renamed: `data-style` is `textStyle`, because React owns `style`.
+- Button's variant and status pairs are a union, so a combination the CSS does not
+  style fails to compile.
+- The repo gains its first dependencies, all of them dev only. The published package
+  still declares no runtime dependencies; react is a peer.
+

package/manifest/migrations/9.0.0.md

@@ -0,0 +1,107 @@
+## 9.0.0 - 2026-09-14
+
+Three changes to Alert, all of them breaking, all of them asked for together.
+
+- **The status tint on the words is now opt-in, via `data-text="tinted"`.**
+  8.3.0 made every status paint its own title and body on `subtle`, `outline`
+  and `plain`. By default they are back to the flat pair the base rule always
+  carried: default-coloured title, grey body. The **icon stays status-coloured
+  either way**, so turning the tint off never costs the reader the signal, it
+  just stops the message carrying it twice.
+- Mechanically the five status rules no longer write `--_alert-title` and
+  `--_alert-body` at all. They write one new private slot,
+  `--_alert-tint-text`, and only the `[data-text="tinted"]` rule spends it.
+  That rule and `[data-variant="solid"]` are the only two writers of the text
+  slots and they have identical specificity, so **source order alone** decides
+  which wins and solid has to stay last: tinted words on a solid status fill
+  would be that colour on itself. `test/order.test.js` now asserts both the
+  writer list and the order, and fails if a third rule appears or the two swap.
+- **`neutral` is a named status.** `data-status="neutral"` renders exactly what
+  omitting the attribute always did, so nothing changes visually; what changes
+  is that you can now say it. A sixth component token,
+  `--dk-component-alert-neutral-color`, completes the per-status text family,
+  so a tinted neutral alert has a colour of its own rather than falling back to
+  nothing. React's `AlertStatus` gains `'neutral'`.
+- **Width follows Button: content width by default, `data-full-width="true"`
+  to fill.** This reverses 8.1.0, which shipped `width: 100%`. Two width
+  vocabularies pointing opposite ways across one kit is worse than either
+  default on its own. `fit-content` is less narrow than it sounds: it resolves
+  to `min(max-content, max(min-content, available))`, so a long body still
+  fills the column and only a short one hugs. React gains `fullWidth`.
+- **Content width gained a trailing-padding rule**, found by looking at the new
+  default on the docs page. A leading icon with no trailing dismiss button is
+  the one configuration whose two insets do not match: measured at the default
+  size, the words start 48px in (padding, icon column, gap) and stop 18px from
+  the other edge. Its `padding-inline-end` becomes `padding + gap`, the same
+  step that separates the icon from the words, mirrored, so it tracks both the
+  size axis and the responsive spacing scale with no second number to keep in
+  sync. Content width only, since full width has slack there and widening it
+  would buy nothing but a narrower column. The other two configurations are
+  already even (48/48 with a dismiss button in the mirror column, 18/18 with no
+  icon) and are excluded, as is `plain`, whose whole job is to have no padding.
+- **The icon and the dismiss button now centre correctly when there is no
+  title.** Both align to `--_alert-title-line`, so with title omitted they were
+  centring on a line that is not there: the body is a size step smaller
+  (body-small 20px against body-medium 24px), which left both 2px low. With no
+  title the slot now resolves to the body's line height instead. Only visible at
+  the default size, since `data-size="small"` steps the title down to
+  body-small too and the two already coincided. Measured across all 26
+  icon-bearing alerts on the docs page: every one centres within 0.6px.
+- **The dismiss button now has hover and press states**, borrowed from Icon
+  button and recoloured by the status: a background that appears on hover, one
+  rung further on press, the glyph stepping `-hover` then `-focus` alongside it,
+  and a `scale(0.9)`. Two deliberate differences from `.dk-component-icon-btn`:
+  it is transparent at rest, since it already sits on a tinted panel and a
+  resting fill would read as a second panel inside the first, and its colours
+  come from the status rather than from neutral.
+- Its box is now the glyph plus a padding ring (`28px` around a `20px` glyph at
+  the default size, `24px` around `16px` at small), which is what gives the
+  hover background a body instead of a smudge hugging the X, and it sits
+  `--dk-component-alert-dismiss-offset` further from the words: the gap from the
+  text to the button goes from 12px to 20px, and to the glyph itself 24px.
+- **`solid` needed a scrim rather than a rung.** Measured before building it:
+  `--dk-surface-<status>-focus` is byte-identical to `--dk-surface-<status>-solid`
+  in light for all five statuses, and `--dk-surface-error-default` collides with
+  it the same way in dark, so no existing ladder gives two distinct steps above
+  a solid fill in both themes. Two new primitives,
+  `--dk-primitive-opacity-scrim-{hover,active}` (0.14 and 0.24), are laid over
+  the fill in the on-solid colour, which self-adapts: white over a status fill,
+  black over the neutral one. The glyph stays on-solid, since dimming the one
+  white thing on a saturated fill would cost contrast to signal a hover.
+- `kit/reduced-motion.css` gains the dismiss button in both its lists, so the
+  new press does not move the element for a reader who asked for less motion.
+  That file exists precisely to stop new motion shipping unguarded.
+- **Padding is even on all sides**, `--dk-component-alert-padding` (16px, 12px
+  at small), replacing the 12px-vertical against 16px-horizontal pair. That is
+  the shape a control has, not a panel, and Toast, the component Alert is the
+  persistent half of, already sets a flat `padding: var(--dk-spacing-4)`. ONE
+  token per size rather than two holding the same value, so the two edges
+  cannot drift apart again: `--dk-component-alert-padding-block` and
+  `-padding-inline` are gone, at both sizes.
+- **An alert with no dismiss button gets a bit more room on its trailing
+  edge**, 24px against 16px (16px against 12px at small). With the button
+  there the right side already holds something and the words stop well short
+  of the edge; take it away and they run up against the padding alone. The
+  extra is its own token, `--dk-component-alert-trailing-extra`. It was the
+  dismiss offset until that offset was raised: the two had been equal only
+  because they arrived at the same size, and reusing one for the other meant
+  widening the gap before the button silently widened the padding of every
+  alert that has no button. This replaces the narrower rule that only fired at
+  content width and only with a leading icon: with even padding it is the
+  missing control that makes the difference, not the icon, and it is missing
+  at any width. `plain` stays excluded.
+- **More room between the words and the dismiss button**, 28px rather than
+  20px at the default size and 20px rather than 12px at small.
+  `--dk-component-alert-dismiss-offset` is now the panel's own padding, so the
+  control stands as far from the words as the words stand from the edge, and
+  it tracks the size axis with them rather than being a number of its own.
+- **Migrating.** An alert that wants its 8.3.0 look adds `data-text="tinted"`;
+  one that wants its 8.1.0 width adds `data-full-width="true"`. Neither has a
+  silent failure mode: leave them off and you get the new defaults, which
+  render correctly, just differently.
+- Contrast moves the right way. Neutral words on the status tints clear AA in
+  29 of 30 theme and surface-level combinations, against 12 below-AA readings
+  of 288 for the tinted path. The single miss is error body text in dark at
+  ambient `data-surface="2"`, 3.95:1, and it only applies to an alert that has
+  opted out of the tint on a level-2 surface.
+

package/manifest/rules.md

@@ -0,0 +1,37 @@
+# The kit's own guard tests
+
+Every rule below is a test in drift-kit. A component the kit ships passes all of them.
+
+## motion-guard
+
+- components read motion patterns only
+- behaviours read motion through dk.motion, never their own parser
+
+## invariant
+
+- bundle canonical form matches the pre-restructure fixture
+- no component transition writes a literal duration
+- comment delimiters in the built bundle are balanced
+- no declaration in the built bundle has unbalanced parentheses
+- every component with a size axis sets those properties without one too
+
+## tone-boundary
+
+- the audit's self-surfaced components are boundaries
+- the element that paints is reset, not the component around it
+- a variant that paints nothing at rest is excluded
+- parts that paint only under the pointer, and disabled or control fills, are not boundaries
+- Box is never a boundary: it is a toned surface by design
+- Card is never a boundary either: rebuilt on the kit surface, 16 Oct
+- a fill that stays put (a selected row) is a boundary; one that comes and goes (hover) is not
+- status tints count as a component's own surface, followed through a private variable
+- a fill no tone remaps is the component's own surface (Choice card, by name)
+- a state set on an ancestor that repaints a part with a tone-following fill excludes it (an inset Input)
+- an ancestor tone treatment that repaints a part excludes it (Icon tile on a solid)
+- review: variants are also judged in pairs (a status solid Tag is a mark rule C inverts, not a surface)
+- the derivation follows --dk-interactive-* to the surface it reads
+
+## anatomy
+
+- every component stylesheet opens with an Anatomy block rooted at its own class
+- every component stylesheet says what the component is for, in a Purpose line

package/manifest/setup.md

@@ -0,0 +1,70 @@
+# The package
+
+Installed as `@karmo-co/drift-kit` from GitHub Packages.
+
+## Entry points
+
+| Import | File |
+|---|---|
+| `@karmo-co/drift-kit/drift-kit.css` | `./dist/drift-kit.css` |
+| `@karmo-co/drift-kit/drift-kit.min.css` | `./dist/drift-kit.min.css` |
+| `@karmo-co/drift-kit/components.js` | `./dist/components.js` |
+| `@karmo-co/drift-kit/fonts/*` | `./dist/fonts/*` |
+| `@karmo-co/drift-kit/vehicles/*` | `./dist/vehicles/*` |
+| `@karmo-co/drift-kit/manifest/*` | `./dist/manifest/*` |
+| `@karmo-co/drift-kit/package.json` | `./package.json` |
+| `@karmo-co/drift-kit/react` | `./dist/react/index.js` |
+| `@karmo-co/drift-kit/behaviours/*` | `./dist/react/behaviours/*.js` |
+| `@karmo-co/drift-kit/icons/*` | `./dist/icons/*.js` |
+
+## Root attributes the stylesheet reads
+
+| Attribute | Values |
+|---|---|
+| `data-brand` | `karmo`, `volvo` |
+| `data-theme` | `dark`, `light` |
+| `data-border-radius` | `bubbly`, `normal`, `sharp` |
+| `data-border-width` | `medium`, `thick`, `thin` |
+| `data-density` | `normal`, `spacious`, `tight` |
+
+## Container attributes
+
+Set on a panel, not the root: everything inside follows. A container that sets a level or a tone paints `background: var(--dk-surface-current)`, the colour of the place it is in.
+
+| Attribute | Values |
+|---|---|
+| `data-surface` | `0`, `1`, `2`, `raised` |
+| `data-tone` | `credit`, `error`, `information`, `inverse`, `muted`, `neutral`, `none`, `primary`, `success`, `warning` |
+| `data-tone-fill` | `solid` |
+
+## Verify
+
+1. **The tokens resolve:** `getComputedStyle(document.body).getPropertyValue('--dk-surface-current')` is non-empty. Probe on `document.body`, never `document.documentElement`: the tokens live on the attribute scopes. Empty means the root attributes are missing or miscased.
+2. **The components are styled:** add a temporary main-action Button, `<button class="dk-component-button" data-variant="default" data-status="primary">`, to the body, read its computed `padding-inline-start`, then remove it. Zero means the stylesheet is missing, truncated or from another major.
+
+A component token resolves only on its own component's element, so never probe one on `body`: it is empty on a healthy install.
+
+## The public kit
+
+A page with no npm install (a plain HTML prototype, a slide deck) links this version from the public kit. Every address carries the version, and a version's files never change, so never write a link without one. Link the stylesheet in the head (`drift-kit.min.css` when shipping), `components.js` only when a component on the page has behaviour, and one icon script, only for the set the page's icons come from. Fonts load from the same folder, relative to the stylesheet.
+
+Both scripts are deferred, and an icon script goes after `components.js`, which replaces the icon registry when it runs: an icon script that runs first loses its set. Every tag carries its file's `integrity` from the table below and `crossorigin="anonymous"`, so a file whose bytes changed never loads. In this order:
+
+```html
+<link rel="stylesheet" href="https://storage.googleapis.com/drift-kit-public/23.5.0/drift-kit.css" integrity="sha384-QFAunRFb04Unk6O2tsutrhpLKyCKeEZldwHPxXbbx26XezTwo15nej6qBMcQQE2O" crossorigin="anonymous" />
+<script src="https://storage.googleapis.com/drift-kit-public/23.5.0/components.js" integrity="sha384-2YLDzdQXhMM10gupcoaZoir9HCk4EILtF7OdDjFoMUhPNkLbre117mISxLLOTojA" crossorigin="anonymous" defer></script>
+<script src="https://storage.googleapis.com/drift-kit-public/23.5.0/drift-icons-<set>.js" integrity="<its integrity>" crossorigin="anonymous" defer></script>
+```
+
+| File | Address | Integrity |
+|---|---|---|
+| `drift-kit.css` | `https://storage.googleapis.com/drift-kit-public/23.5.0/drift-kit.css` | `sha384-QFAunRFb04Unk6O2tsutrhpLKyCKeEZldwHPxXbbx26XezTwo15nej6qBMcQQE2O` |
+| `drift-kit.min.css` | `https://storage.googleapis.com/drift-kit-public/23.5.0/drift-kit.min.css` | `sha384-1XaZo6zP9LN6tnGxlT7VlqgL3SV7MkmSiUZxNho5joChtDA27cxjK4bEOI71HYya` |
+| `components.js` | `https://storage.googleapis.com/drift-kit-public/23.5.0/components.js` | `sha384-2YLDzdQXhMM10gupcoaZoir9HCk4EILtF7OdDjFoMUhPNkLbre117mISxLLOTojA` |
+| `drift-icons-card.js` | `https://storage.googleapis.com/drift-kit-public/23.5.0/drift-icons-card.js` | `sha384-Dl18Pw11QQ+/KtbAzbjt1DdP6fJwFNn4kCykxtFsF+uEZtUfMIseQJ7s14OmqEmg` |
+| `drift-icons-coolicon.js` | `https://storage.googleapis.com/drift-kit-public/23.5.0/drift-icons-coolicon.js` | `sha384-8WaBw9LZuhj/u7G2Jf1aiVo8HBhMj1fBsmpSWJnYi5Xdi2ANXB3BLBZxz2NLQGYl` |
+| `drift-icons-feather.js` | `https://storage.googleapis.com/drift-kit-public/23.5.0/drift-icons-feather.js` | `sha384-MFEltFi3gRSwgNdAMXGCYo+6Ri9iXLLWp4Gq3AeayzeliWAo3czd+pTTLAFHHU6s` |
+| `drift-icons-flag-circle.js` | `https://storage.googleapis.com/drift-kit-public/23.5.0/drift-icons-flag-circle.js` | `sha384-gtU89vOz98Fbn0KZWzkHVQA4+kFhOFYoT/Dr43ljTskqkyGDMw1ihH1I7Zn25dzZ` |
+| `drift-icons-flag.js` | `https://storage.googleapis.com/drift-kit-public/23.5.0/drift-icons-flag.js` | `sha384-VtM24IDkwASIVzD5hI+ijQYRXufYQbveKM0+wqaFSGZbrYZlodFlnvZOexhCpiH9` |
+| `drift-icons-lucide.js` | `https://storage.googleapis.com/drift-kit-public/23.5.0/drift-icons-lucide.js` | `sha384-yEy9LdLbPCXUy577fmNq4loJ2G9AQ1InAW54iozwnVfe8KIK6gVe2227eaNmxFi1` |
+| `drift-icons-social.js` | `https://storage.googleapis.com/drift-kit-public/23.5.0/drift-icons-social.js` | `sha384-+hPy5fFjIqfIAmDN+WOwekTLu7NIFZvyzOwXUTAiBEQqnZ0/kXgd4frbSGOr/c8c` |

package/manifest/tokens/border-width.md

@@ -0,0 +1,12 @@
+# Border width tokens
+
+Declared values, light and dark. Reference a token by name; never copy its value.
+
+| Token | Light | Dark |
+|---|---|---|
+| `--dk-border-width-0` | `var(--dk-dynamic-border-width-0)` | `var(--dk-dynamic-border-width-0)` |
+| `--dk-border-width-25` | `var(--dk-dynamic-border-width-25)` | `var(--dk-dynamic-border-width-25)` |
+| `--dk-border-width-50` | `var(--dk-dynamic-border-width-50)` | `var(--dk-dynamic-border-width-50)` |
+| `--dk-border-width-100` | `var(--dk-dynamic-border-width-100)` | `var(--dk-dynamic-border-width-100)` |
+| `--dk-border-width-150` | `var(--dk-dynamic-border-width-150)` | `var(--dk-dynamic-border-width-150)` |
+| `--dk-border-width-200` | `var(--dk-dynamic-border-width-200)` | `var(--dk-dynamic-border-width-200)` |