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

package/manifest/migrations/20.0.0.md

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

package/manifest/migrations/21.0.0.md

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

package/manifest/migrations/22.0.0.md

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

package/manifest/migrations/23.0.0.md

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

package/manifest/migrations/3.0.0.md

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

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