npm - @cueplusplus/tokens - Versions diffs - 0.13.0 - Mend

@cueplusplus/tokens 0.13.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (12) hide show

package/CHANGELOG.md +1250 -0
package/LICENSE +21 -0
package/README.md +100 -0
package/dist/axes.css +324 -0
package/dist/base.json +364 -0
package/dist/primitives.tokens.json +27 -0
package/dist/registry/token-layer.json +340 -0
package/dist/tailwind.css +20 -0
package/dist/theme.css +12 -0
package/dist/tokens.d.ts +114 -0
package/dist/tokens.js +240 -0
package/package.json +51 -0

package/CHANGELOG.md ADDED Viewed

@@ -0,0 +1,1250 @@
+# @cueplusplus/tokens
+## 0.13.0
+### Minor Changes
+- 31a7567: Six new tokens on `:root`: `--cue-leading-prose` and `--cue-leading-ui` (both 1.625), and `--cue-measure-narrow` / `--cue-measure-wide` / `--cue-measure-broad` / `--cue-measure-prose` (42rem / 54rem / 84rem / 68ch). Line height and reading measure had no token at all until now — 186 `leading-*` call sites and 176 arbitrary `max-w-[…]` across this repository against nothing in the token layer to point them at.
+  They are declared once, on `:root`, and they are not part of the geometry contract: a measure is a property of a page rather than of how tightly its controls are packed, so it does not get a rung per density, and no theme package has to author one. Override them in your own `:root` or under your own block and every component that spends them follows.
+  The build's per-group token contract is now exact in both directions rather than a floor: a group whose sources emit a name its contract does not list fails the build, the same way a missing name already did. The style group needs it most — it is deliberately outside `dist/base.json` and outside the geometry contract, so nothing downstream would have noticed a seventh `--cue-measure-*` arriving from a source-file edit — and the geometry groups satisfy it as they stand, so it is one rule for both. No emitted CSS changes.
+  The build also discovers its style sources now, rather than opening `leading.tokens.json` and `measure.tokens.json` by name: every `src/style/*.tokens.json` on disk is read. A new style source is picked up the moment it lands, and the exact-contract rule above is what refuses a name that source was not planned to declare — the fail-closed shape every other source group on this branch already has. No emitted CSS changes here either: today's directory holds exactly the two files the build used to name.
+- 5b40f07: **A fourth composable axis: `data-style`, for page composition.**
+  Theme, density and font already answer "what colour", "how tight" and "which
+  typeface". `data-style` answers the question none of them could: how a _page_ is
+  composed — reading measure, prose line height, and the rhythm of a band. Three
+  sets ship. `console` is the current look made explicit and provably unchanged,
+  `editorial` widens the measure and opens the leading for long-form reading, and
+  `marketing` narrows the measure and spends the vertical space a landing page
+  wants.
+  Each set declares `--cue-measure-prose`, `--cue-leading-prose`, `--cue-band-y`,
+  `--cue-band-rule` and `--cue-band-ground`; `editorial` and `marketing` add
+  `--cue-style-display` for a display type scale. Only the display rung composes
+  with `--cue-font-scale`, and a name added to the set vocabulary without an
+  answer is a build error rather than a silent guess.
+  **Driving it.** `<ThemeProvider styleSet="editorial">` stamps the attribute on
+  its own element and on `<html>`, `useTheme().styleSet` and `setStyleSet()` read
+  and drive it, and it persists beside theme, density, font and mode under a
+  `style` key — written only when there is a set. A pre-paint script applies a
+  stored set before the first paint, so turning one on _or off_ lands on the first
+  frame rather than the first commit. The set is carried into overlay portals,
+  `<Density styleSet>` islands and `<Preview styleSet>` stages, so an overlay
+  follows the subtree it was opened from and three sets can be shown side by side
+  on one page.
+  `useTheme().styleSet` is **the set in force, not the set named here**. A
+  provider that names no set of its own reports the one stamped around it —
+  including a `<Density styleSet>` island sitting between it and an outer provider
+  — exactly as the DOM resolves it. That is deliberate: it makes the context value
+  and the set a portal or a stage carries out of that DOM one value rather than
+  two that can disagree. `null` means nothing anywhere has chosen a set, which is
+  not the same fact as `console`.
+  `setStyleSet(null)` is the same distinction from the writing side: it clears the
+  set this provider **names**, not the set that applies to it. A nested provider
+  that clears its own goes back to inheriting whatever is stamped around it, and
+  `styleSet` reports that inherited set, because it is what the cascade resolves
+  to. At the root the two coincide, which is why only a nested provider shows the
+  difference. To positively leave an inherited set, pass `DEFAULT_STYLE_SET`: it
+  stamps an attribute whose block restates the `:root` defaults token for token,
+  and an attribute is the only thing that out-specifies an ancestor's.
+  Restating a set on a `<Density>` island is what re-resolves its band rhythm at
+  that island's rung: `--cue-band-y` is built from `--cue-space-7`, and a custom
+  property's `var()` references are substituted where they are declared, so an
+  island that only changes density inherits the rhythm already resolved above it.
+  `STYLE_SETS`, `DEFAULT_STYLE_SET`, `STYLE_CONTRACT`, `STYLE_SET_CONTRACT` and
+  the `StyleSet` type are exported from `@cueplusplus/tokens`, so an application
+  can type a prop and validate a stored preference against the same closed list
+  the stylesheet was built from.
+  **What it costs.**
+  - **Every consumer carries 144 more bytes of blocking inline pre-paint script**,
+    whether or not the application uses the axis — a typical script grows from 995
+    bytes to 1139. It has to read the stored set and stamp or clear the attribute
+    before the first paint, and an application that never touches the axis cannot
+    opt out of the branch that decides there is nothing to stamp.
+  - **The attribute is the generic `data-style`, not `data-cue-style`.** An
+    application already using `data-style` on `<html>` for its own purposes will
+    have it overwritten while a `<ThemeProvider>` is mounted, and cleared when the
+    provider holds no set; the original value is restored on unmount. The generic
+    name was chosen for readability, and this collision is the price. If you use
+    `data-style` on `<html>` yourself, move it before upgrading.
+  **What is unchanged.** A page that names no set is untouched: no attribute is
+  stamped anywhere, no stored preference gains a key, and a stored `"style": null`
+  is refused and scrubbed on the next load like every other value nothing
+  declares. `console`'s declarations are asserted at build time to be exactly the
+  `:root` defaults, and a browser test compares every `--cue-*` on two identical
+  subtrees — one bare, one under `console` — and requires them to compute
+  identically. Switching to the default set changes nothing, as a checked fact
+  rather than a promise.
+  One note on `editorial`'s hairline: its 0.5px `--cue-band-rule` paints a
+  measured 1px on Chromium at either device pixel ratio and 0.5px only on retina
+  WebKit, so the separation it actually ships is the doubled `--cue-space-7`
+  rhythm with a hairline under it.
+### Patch Changes
+- b1c2f25: **Every package now ships the licence it declares.** All sixteen have said `"license": "MIT"` in
+  their manifest since they were first published, and none of them carried the text. Installing one
+  gave you a licence field and nothing to read; anyone auditing their dependency tree found a package
+  that claimed a licence it did not include. Each package root now holds the MIT notice, and npm packs
+  a root `LICENSE` whether or not `files` lists it, so it is in the tarball you install.
+  `@cueplusplus/ui` additionally ships `NOTICE.md`, the third-party notice for the assistant-ui code
+  vendored into its elements. That one is not automatic — `files` had to name it — and it is byte-for-byte
+  the notice that already sat beside the source it covers, because a notice that travels without the
+  bytes it describes is not a notice.
+  Nothing else about these packages changed: same exports, same versions of every dependency, same
+  registry. If you are upgrading only for this, the diff you receive is licence text.
+## 0.12.0
+## 0.11.1
+## 0.11.0
+## 0.10.0
+### Patch Changes
+- 64b4bab: Every package manifest's `repository` field now names `cueplusplus/cue-ui`, following the
+  repository's rename from an earlier working title.
+  **Nothing to do.** No code, no exports, no types, and no package name: the scope is the
+  organisation, not the repository, so every specifier you already import is the one you keep
+  importing. What moves is metadata — GitHub Packages matches a package to a repository through that
+  field, so from this release the "source" link on each package's registry page, and the repository
+  the next publish is attributed to, name `cue-ui`. The `directory` beside it is unchanged, so each
+  link still lands on that package rather than on the monorepo root.
+  If you have a bookmark or a script pointing at the old URL, GitHub's rename redirect answers it;
+  updating it to `https://github.com/cueplusplus/cue-ui` is tidiness rather than repair.
+- c2238cc: The README now states the removal window for `dist/theme.css`, the deprecated alias of
+  `axes.css`: it is kept through 0.10 and removed in the minor after. Nothing in the tarball
+  changes; if you still import `@cueplusplus/tokens/theme.css`, switch to `axes.css` before then.
+## 0.9.0
+### Minor Changes
+- 5eb0da2: The ten colour presets leave `@cueplusplus/tokens` and become packages of their
+  own. `@cueplusplus/ui/styles.css` now ships the blank base instead of a palette,
+  so a theme is something you install, import and register — the same way a
+  third-party theme always should have been, and now is.
+  `@cueplusplus/tokens` keeps the two axes it actually owns: the five density
+  rungs and the eight font pairings, plus the contracts, `base.json` and the
+  primitives a theme source aliases. It emits `axes.css` and no colour at all.
+  Each preset is `@cueplusplus/theme-<name>` — `cue`, `dusk`, `hivehub`, `luma`,
+  `quotamate`, `requestport`, `signal`, `snuffle`, `terminal`, `venu` — carrying
+  the stylesheet it always carried, byte for byte: nothing about any shipped
+  palette moved, and a frozen snapshot of what `tokens@0.8.0` emitted is committed
+  so that stays checkable rather than merely asserted.
+  ## Migrating
+  **The unattributed default stops being `cue`.** An app that imports
+  `@cueplusplus/ui/styles.css` and registers nothing now paints the blank base.
+  Nothing errors and nothing falls back: a `data-theme` value is styled by
+  whichever stylesheet declares it, and with no theme package imported, none does.
+  Ten custom properties move in dark and seven in light. Measured on a root
+  stamped `data-theme="cue"`, which is what every `ThemeProvider` stamped before
+  this release and still stamps, so this is the delta for an app that changes
+  nothing:
+  | token                                                | dark: `cue` → blank base                                                | light: `cue` → blank base      |
+  | ---------------------------------------------------- | ----------------------------------------------------------------------- | ------------------------------ |
+  | `--cue-accent`                                       | `#ffffff` → `#8a93a6`                                                   | `#0a0a0a` → `#3f4759`          |
+  | `--cue-accent-hover`                                 | `rgba(255,255,255,0.85)` → `#9aa3b6`                                    | `rgba(0,0,0,0.85)` → `#333a4a` |
+  | `--cue-accent-soft`                                  | follows `--cue-accent`: it is a 14% `color-mix` of it                   | same                           |
+  | `--cue-focus`                                        | `#ffffff` → `#8a93a6`                                                   | `#0a0a0a` → `#3f4759`          |
+  | `--cue-font-theme-mono`                              | JetBrains Mono → nothing; the base declares no theme mono               | same as dark                   |
+  | `--cue-font-mono`                                    | resolves through the line above, so JetBrains Mono → the platform stack | same as dark                   |
+  | `--cue-fg`                                           | `#f5f5f7` → `#f5f5f5`                                                   | unchanged                      |
+  | `--cue-hair`, `--cue-hair-strong`, `--cue-row-hover` | follow `--cue-fg`: each is a `color-mix` of it (6%, 12%, 3.5%)          | unchanged                      |
+  | `--cue-accent-fg`                                    | unchanged                                                               | `#fcfcfc` → `#ffffff`          |
+  The last four rows are the ones an eye catches and a list of "the accent and the
+  focus ring" would not have mentioned: four of the ten dark changes and the one
+  light change are tokens no theme file names directly, because they are mixes of
+  two that do.
+  To get `cue` back, exactly as it was:
+  ```bash
+  pnpm add @cueplusplus/theme-cue
+  ```
+  ```css
+  @import "@cueplusplus/ui/styles.css";
+  @import "@cueplusplus/theme-cue/theme.css";
+  ```
+  ```tsx
+  import cue from "@cueplusplus/theme-cue";
+  <ThemeProvider themes={[cue]} theme="cue">
+    {children}
+  </ThemeProvider>;
+  ```
+  The import order is load-bearing: a `[data-theme]` block and the base's bare
+  `:root` tie at (0,1,0), so the one declared later wins. Importing the theme
+  before `styles.css` paints the blank base over it. Importing the package from
+  its root, rather than the `manifest.json` subpath, also closes `ThemeName` to
+  the themes you installed, so a misspelt `theme=` is a type error.
+  Then the rest:
+  - **`@cueplusplus/tokens/theme.css` is a deprecated alias** of `axes.css` for
+    one minor. It still resolves and still delivers the geometry and type axes, so
+    a stylesheet naming it keeps building — it simply carries no palette. Change
+    the line to `@cueplusplus/tokens/axes.css`, or drop it: `ui/styles.css` already
+    brings the axes in through `@cueplusplus/theme-base/base.css`.
+  - **Gone from `@cueplusplus/tokens`:** the `themes/*.css` and
+    `registry/theme-*.json` subpaths, and the `THEMES`, `ThemeName`,
+    `THEME_SUPPORTS_LIGHT` and `DEFAULT_THEME` exports. `ThemeName` now comes from
+    `@cueplusplus/theme-base` (re-exported by `@cueplusplus/ui`) and widens with
+    each theme package installed, rather than naming the ten that happened to be
+    compiled in; whether a theme ships a light block is `supportsLight` on its own
+    `manifest.json`; and there is no default palette to name, because the library
+    contains none.
+  - **`@cueplusplus/tokens`' root entry is now `dist/tokens.js`**, with
+    `dist/tokens.d.ts` beside it, where it used to be the TypeScript source
+    `dist/tokens.ts`. The import specifier, the exported names and their values
+    are unchanged — `import { DENSITIES } from "@cueplusplus/tokens"` is the same
+    line it was — but the file behind it is one Node can execute. It could not
+    before: Node refuses to strip types for anything under `node_modules`, so the
+    package worked in a workspace and failed from a registry install, taking
+    `@cueplusplus/theme-base` and the `cue-theme` CLI with it. If you added
+    `@cueplusplus/tokens` to your bundler's transpile list to work around that
+    (Next.js' `transpilePackages`, or the equivalent), take it out.
+  - **`@cueplusplus/tokens` gains `base.json`'s `fonts.handshake`**: the three
+    literals of the monospace resolution (`font-pairing-mono`, `font-theme-mono`,
+    and the `var()` that resolves them), published as data so a theme built
+    anywhere spells them the same way this build does.
+  - **`@cueplusplus/ui`'s `THEME_NAME_PATTERN` and `RESOLVED_MONO` are now
+    re-exports** of `@cueplusplus/theme-base`'s. Same names, same values, one
+    definition instead of three.
+  - **`/r/tokens.json`'s `themes` are objects**, not strings:
+    `{ name, package, supportsLight, densities }`. A consumer reading the registry
+    for a theme list wants to know which package delivers it.
+  - **Every published tarball now carries a `README.md`.** On a registry the
+    package page _is_ the README, and `tokens`, `ui` and `brand-tokens` shipped
+    without one; `packages/release/test/publishable-packages.test.mjs` holds all
+    fifteen to it now, beside the same check for `CHANGELOG.md`.
+  - **`@cueplusplus/ui` depends on `@cueplusplus/theme-base@^1`**, a range rather
+    than a pin, deliberately: two copies of `theme-base` in one tree would break
+    the type registry, because a theme's `declare module` augments one copy while
+    `ui`'s re-exported `ThemeName` resolves against the other, and neither errors.
+- 2737aec: `@cueplusplus/tokens` exports the contracts and the axes as data, so a theme
+  built outside this repository can resolve over the same base: `COLOR_CONTRACT`,
+  `GEOMETRY_CONTRACT` and `FONT_TOKENS` as typed tuples, `base.json` (every
+  density's geometry, the pairings' stacks, the derived templates, the defaults),
+  `primitives.tokens.json` (the tier-1 file a theme source aliases), and
+  `axes.css` — `theme.css` with the theme axis removed. Nothing that exists today
+  moves; `theme.css` is unchanged.
+  `@cueplusplus/ui/theming` keeps every export it had. The contrast arithmetic now
+  lives in `@cueplusplus/theme-base` and is re-exported here; `ui` gains that
+  package as a dependency. No behaviour changes.
+### Patch Changes
+- cf80a87: No published behaviour changes. These packages gain a `lint` script and its two
+  dev dependencies, because `pnpm lint` now runs ESLint over every package that
+  holds source rather than resolving to an empty task graph, and a package with no
+  script is a package the gate is silently green about.
+## 0.8.0
+## 0.7.0
+## 0.6.0
+### Patch Changes
+- 778374d: The keyboard focus ring is now visible in the luma, venu and hivehub light
+  themes. Each set `--cue-focus` to its brand accent, and on paper that accent
+  read as low as 2.45:1 against the recessed fill a focused field paints it
+  over — under the 3:1 WCAG 1.4.11 asks of a focus indicator. Each light block
+  now carries its own focus colour: the same accent hue, stepped down in
+  lightness until it clears every surface a field can sit on. `--cue-accent` is
+  unchanged, so no button, chip or link moves.
+## 0.5.0
+### Minor Changes
+- 51e5046: ## The amber carries its own ink too
+  This is the amber half of the argument `the-red-carries-its-own-ink` already
+  made, and it is the same argument: the tone a control is _filled_ with decides
+  what can be read on it, and no other token in the palette knows that.
+  `TwoStepButton` is the one control in the library whose whole reason for
+  existing is that the press is consequential — arm, then confirm. Its `warn`
+  confirm painted `bg-warn text-black`. Black on an amber is a good guess, and on
+  the ten dark blocks it is right by a distance: 7.11:1 to 12.41:1. It is wrong on
+  the light ones, because a light theme darkens its amber to clear the paper and a
+  darkened amber wants paper back. **3.58:1** on requestport, **3.74:1** on dusk,
+  **4.22:1** on cue's own light block — three of the twenty preset x mode blocks
+  under AA, on the half of the control that does the thing.
+  It could not be closed before: there was no `--cue-warn-fg` to close it with,
+  and the queued note for the red said so in as many words. There is one now.
+  ### `--cue-warn-fg`
+  A new authored anchor, per preset, per mode, in the colour contract beside the
+  tone it is chosen against, with `text-warn-fg` / `bg-warn-fg` bridged into
+  Tailwind like every other colour token:
+  ```css
+  [data-theme="cue"] {
+    --cue-warn: oklch(0.8 0.17 75);
+    --cue-warn-fg: #000000;
+  }
+  [data-theme="cue"][data-mode="light"] {
+    --cue-warn: oklch(0.55 0.115 70);
+    --cue-warn-fg: #fcfcfc;
+  }
+  ```
+  Not one value is hand-picked. Each is the same `pickInk` `createTheme()` already
+  uses for `accent-fg` and `danger-fg`, run over the extremes the theme itself
+  owns — its page, its deepest well, its type — falling to pure black or white
+  only where none of the three reaches AA. Run over the reds instead, it
+  reproduces all twenty shipped `danger-fg` values exactly, spelling included,
+  which is the check that this is the same derivation rather than a second one
+  wearing its name.
+  The amber does not answer the way the red did, and that is the argument for
+  deriving against each tone instead of writing one rule about ink on a status
+  colour. All ten dark blocks take their deepest ground. The light ten split three
+  ways: cue, dusk and requestport take their paper; hivehub, luma, signal and
+  terminal take the theme's own type; quotamate, snuffle and venu take plain black
+  because nothing they own reaches AA on their amber. The worst amber pair in the
+  system is **4.77:1** (luma, light). The worst pair anywhere is still the red's
+  4.59:1.
+  `CONTRAST_REQUIREMENTS` gains an eleventh pair, `warn-fg/warn` at 4.5:1, so a
+  generated palette is judged on it too, and `createTheme()` derives it for one.
+  The configurator shows it beside the amber in the Status group. The assistant-ui
+  island declares its own, because that block re-tints `--cue-warn` and an ink
+  chosen against the app's amber is an ink chosen against a colour nobody is
+  looking at in there.
+  ### The sweep covers the amber now
+  `test/destructive-ink.test.ts` reads the source and measures what the components
+  _spend_ rather than what the palette _offers_. It swept the red and said in its
+  own prose that it did not sweep the amber, because sweeping a defect nobody
+  could fix turns a missing token into a red suite instead of into a decision. The
+  token exists, so the amber is in: every class string that makes `bg-warn` a
+  ground and puts an ink on it, every rule in the package's own stylesheets that
+  does the same, measured on all twenty blocks at 4.5:1, with the fills pinned by
+  name per tone so a new one has to choose its ink in the commit that paints it. A
+  tint keeps its exemption — `bg-warn/10 text-warn` and the search highlight's
+  `bg-warn/35 text-fg` are read against the page, and the report already owns
+  those pairs — and the file says out loud what that exemption does not cover.
+  One number beside it got more honest. Both that sweep and
+  `everywhere-the-red-is-spent` said the right ink "falls to 3.95:1 on quotamate's
+  dark" under `bg-danger/90` without naming the ground the alpha let through. It
+  is **3.94:1** over `--cue-sunken` and **3.97:1** over `--cue-bg`. That the two
+  grounds disagree at all is the reason an alpha is refused rather than measured.
+  ### And the amber's pair is swept on its own, the way the red's is
+  `destructive-ink.test.ts` covers `warn-fg` on `warn` across all twenty blocks
+  for exactly as long as `TwoStepButton` keeps painting that string, because it
+  measures the call site. The red does not depend on that: it has a second,
+  unconditional sweep of the token pair beside `RevertDock` in
+  `elements/canon.test.tsx`. The amber had no equivalent, and the gap is not
+  theoretical — with the confirm moved off the amber in the way a later refactor
+  legitimately might, and that file's pinned list updated to match, a `warn-fg`
+  re-tinted down to **1.62:1** passed every contrast guard in the package.
+  So `instruments/two-step-button.test.tsx` gains the sweep the red has, asking
+  nothing about what any component currently paints, plus the spot check that says
+  this confirm takes the amber at full strength in the amber's own ink rather than
+  the `text-black` it used to.
+  ### If you ship your own theme block
+  A hand-written `[data-theme="acme"]` block should declare `--cue-warn-fg`
+  alongside `--cue-warn`, the same way it now declares `--cue-danger-fg` alongside
+  `--cue-danger`. Without it, `text-warn-fg` resolves to nothing on your theme.
+  Themes generated by `createTheme()` and the configurator's exports already carry
+  it.
+- 06eb4ac: ## The flagship answers in colour
+  `cue` is a monochrome brand, and until this release it carried the monochrome
+  all the way through to the one vocabulary that exists to be told apart at a
+  glance. On the default theme `--cue-ok`, `--cue-busy`, `--cue-warn` and
+  `--cue-info` were all `#ffffff` on dark and all `#0a0a0a` on light: four
+  different meanings, one colour, distinguishable only by the glyph or the word
+  beside them. It read as restraint on a settings page. It reads as a defect on a
+  transcript where three tool calls are in three different states and the only
+  question is which of them is still moving.
+  They are chromatic now.
+  | token          | before (dark / light) | after (dark / light)                            |
+  | -------------- | --------------------- | ----------------------------------------------- |
+  | `--cue-ok`     | `#ffffff` / `#0a0a0a` | `oklch(0.72 0.17 149)` / `oklch(0.53 0.14 149)` |
+  | `--cue-busy`   | `#ffffff` / `#0a0a0a` | `oklch(0.78 0.13 220)` / `oklch(0.54 0.1 225)`  |
+  | `--cue-warn`   | `#ffffff` / `#0a0a0a` | `oklch(0.8 0.17 75)` / `oklch(0.55 0.115 70)`   |
+  | `--cue-info`   | `#ffffff` / `#0a0a0a` | `oklch(0.75 0.12 252)` / `oklch(0.55 0.16 258)` |
+  | `--cue-danger` | `#ff5f57` / `#d03030` | unchanged                                       |
+  `ok` and `warn` are assistant-ui's own semantic pair; `busy` is a console cyan
+  for in-flight and `info` a calmer blue for news. `danger` does not move — it was
+  the one tone already chromatic, and it is the one nobody should have to
+  re-learn.
+  The light row is darker than these hues usually run, and that is the point: a
+  tone is not only a dot here. `Chip`, `StatusDot`, `Toast` and the rest of the
+  tone family draw `text-<tone>` at 11px uppercase — text, judged at 4.5:1, not at
+  the 3:1 a signal is held to. Every light value above clears 4.5:1 on `--cue-bg`
+  (4.79 to 4.85, beside `danger`'s 4.94) and every one of them is inside sRGB, so
+  the measured ratio is the painted one. Dark was never in question: it runs 8.5
+  to 10.3:1.
+  The chrome is untouched. Ink, ground, surfaces, borders, `accent`, `focus` and
+  `selection` are the same monochrome they have always been, on both modes. This
+  change is the status vocabulary and the live hue below it, and nothing else.
+  The other nine presets do not move at all: `terminal`, `signal`, `venu`,
+  `hivehub`, `dusk`, `luma`, `snuffle`, `quotamate` and `requestport` were already
+  chromatic here, and an app on any of them sees nothing new in this section.
+  ### Migrating
+  **A console on the default theme that relied on monochrome statuses will now
+  see colour.** No API moved and nothing needs editing to keep working, but
+  pixels change, and they change in more places than a status pill: `Chip`,
+  `StatusDot`, `Meter`, `Toast`, `Stat`, `StatusBar`, `LogViewer`, `Sparkline`,
+  `GroupBar`, `TwoStepButton`, `Tree`, `TerminalFrame`, `AppWindowFrame`,
+  `UsageChart`, `FileUpload`, `EnvVarInput`, `AskBox`, `DelegationCard` and
+  `ToolCallCard` all spend these four tokens, along with the MIDI and DMX
+  instruments. Anywhere a `tone` prop was chosen and then quietly rendered white,
+  it now renders the tone. Screenshot tests on `data-theme="cue"` will need new
+  baselines; a design that used `tone="info"` as a way of saying "plain" will now
+  say "blue".
+  If a product deliberately wants the monochrome back, it is four declarations —
+  the soft fill and the rim derive from the base with `color-mix`, so overriding
+  the base moves the whole family with it:
+  ```css
+  @import "tailwindcss";
+  @import "@cueplusplus/ui/styles.css";
+  [data-theme="cue"] {
+    --cue-ok: #ffffff;
+    --cue-busy: #ffffff;
+    --cue-warn: #ffffff;
+    --cue-info: #ffffff;
+  }
+  [data-theme="cue"][data-mode="light"] {
+    --cue-ok: #0a0a0a;
+    --cue-busy: #0a0a0a;
+    --cue-warn: #0a0a0a;
+    --cue-info: #0a0a0a;
+  }
+  ```
+  Two selectors, not one, and the block goes _after_ the import — the preset's own
+  rules are `[data-theme="cue"]` and `[data-theme="cue"][data-mode="light"]`, so
+  an override has to match their specificity and win on source order. An app that
+  runs `mode="system"` mirrors these onto
+  `[data-theme="cue"][data-mode="system"]` inside the two `prefers-color-scheme`
+  queries, exactly as the generated sheet does.
+  ## `--cue-stream`, the live hue
+  The colour contract gains one token and its two derivations —
+  `--cue-stream`, `--cue-stream-soft` and `--cue-stream-border` — on all ten
+  presets, in both modes, at the same 12% and 35% mixes the statuses use. The
+  colour contract is 42 custom properties where it was 39.
+  It is the colour of something still arriving: a token mid-stream, a tool still
+  running, a cursor that has not stopped. It is deliberately **not** a sixth
+  status. A status is something a `Chip` or a `StatusDot` can be _told_ to be, and
+  "streaming" is not a tone a caller picks — it is a property of a surface while
+  the model is talking. There is no `tone="stream"` and there is not going to be
+  one. What it shares with the statuses is the shape of its family, which is why
+  it is derived beside them and bridged beside them:
+  ```
+  --color-stream   →  text-stream   bg-stream/15   border-stream/30
+  ```
+  The bridge carries the tone at full strength and lets Tailwind's alpha modifier
+  do the washes, the way `Chip` already writes `bg-busy/10`.
+  The flagship pair is assistant-ui's `--aui-live` — `blue-400` on ink verbatim,
+  and on paper `blue-500`'s hue taken down to `oklch(0.55 0.21 259.815)`, because
+  the elements draw the live hue as text and `blue-500` itself lands at 3.6:1
+  there. Every other preset answers in its own blue, except `terminal`, which
+  already owned a live hue and keeps it.
+  Three things that hold a second copy of the contract moved with it, so nothing
+  needs to be told about the new token twice: `createTheme()` resolves and derives
+  `stream` like any other tone and darkens an invented light one to the non-text
+  AA floor; the contrast report checks `stream/bg` against that same floor — every
+  preset clears it with room to spare, the tightest being `terminal`'s light block
+  at 4.89:1; and the configurator edits and exports it beside the statuses rather
+  than in the miscellany. A theme somebody generated before this release and pasted into their
+  own CSS keeps working: `stream` falls back through the same resolution order
+  every other invented token does.
+  ## `@cueplusplus/ui/elements`
+  A new group, and the largest one this library has added at once: the agent's own
+  surface. Fifteen elements, plus the island and the two label primitives the
+  family is built out of, at `/docs/components/elements`.
+  | element           | what it is                                                  |
+  | ----------------- | ----------------------------------------------------------- |
+  | `ToolCall`        | one invocation, request and result behind a disclosure      |
+  | `ToolGroup`       | calls that went out together, collapsed to one row          |
+  | `ToolError`       | one call failed, with the error legible                     |
+  | `TerminalBlock`   | output streaming line by line, ending in an exit status     |
+  | `CodeDiff`        | a unified diff, tinted, sized for a chat column             |
+  | `ReviewableDiff`  | the same diff where each hunk is a decision                 |
+  | `FileTree`        | everything a run touched, with the churn per file           |
+  | `ApprovalCard`    | the agent asking before it does something with side effects |
+  | `PermissionGrant` | granting a capability rather than approving an action       |
+  | `AgentPlan`       | a checklist the agent works through                         |
+  | `TodoList`        | the agent's working list, rewritten mid-run                 |
+  | `AgentStatus`     | one pill: what it is doing, and for how long                |
+  | `SubagentList`    | parallel workers, their models and their progress           |
+  | `TraceWaterfall`  | every span in a run on one nested time axis                 |
+  | `ChatPanel`       | the whole family working together, with its five parts      |
+  Beside them: `ShimmerLabel` and `SwapLabel`, the eighteen surface recipes the
+  family shares as plain class strings (`paper`, `floating`, `field`, `mono`,
+  `live`, `codeSurface`, `collapsePanel`, `pressable`, the swap pairs and the
+  rest), and `range`'s six functions — `at`, `clamp`, `indexIn`, `pct`,
+  `progressOf`, `take` — which are the arithmetic a replayed transcript is made
+  of.
+  Two conventions run through the group and both are worth knowing before you read
+  the source:
+  **State is a prop, and time is the caller's.** Nothing here holds a run.
+  `ToolCall` is _told_ `running` and `open`; `TerminalBlock` is told how many of
+  its lines are visible. Replaying a conversation is arithmetic on props, which is
+  what makes every one of these benchable at every state.
+  **These components are written upstream's way, not this library's.** Plain
+  exported functions with no `forwardRef`, a `data-slot` attribute on every root,
+  `className` merged last through `cn`. That is deliberate rather than sloppy: it
+  keeps a re-synced diff readable, and `data-slot` is what lets an app restyle a
+  part from the outside without a prop for it. `AgentSurface` — cue's own — is the
+  one component in the group written in the house style.
+  `lucide-react` is an **optional peer** of this entry, which is why the group is
+  its own subpath instead of part of the root barrel: the family draws its own
+  icons rather than taking them from a prop. Import nothing from `/elements` and
+  it costs nothing — no install, no bundle, no resolution error.
+  `@cueplusplus/ui/elements.css` ships beside it and is **optional even for this
+  subpath**, because the family is painted by the token layer already:
+  ```css
+  @import "tailwindcss";
+  @import "@cueplusplus/ui/styles.css";
+  @import "@cueplusplus/ui/elements.css"; /* motion, and the supersede island */
+  ```
+  It carries the two vocabularies upstream never shipped as anything but
+  dependencies — the shimmer sweep and the nine entrance utilities, both stilled
+  under `prefers-reduced-motion` — and the island values below. Skip it and the
+  elements still render in cue's palette; you lose the motion and `skin="aui"`
+  becomes a no-op.
+  **Every class it declares is namespaced `cue-elements-`**, and that is a
+  compatibility promise rather than a house style. The entrance utilities are
+  `tw-animate-css`'s by name — `animate-in`, `fade-in`, `slide-in-from-*` — and
+  `tw-animate-css` is what shadcn installs by default, so a stylesheet declaring
+  them again would give such an app two `.animate-in` rules with import order
+  picking the winner, silently. The vendoring codemod renames them at emit, the
+  lockfile records the table as `classRenames`, and a test fails on any class in
+  this stylesheet that a third-party utility package could also own.
+  ## The island: one DOM, two value-sets
+  ```tsx
+  import { AgentSurface, ToolCall } from "@cueplusplus/ui/elements";
+  <AgentSurface skin="aui" fidelity="upstream">
+    <ToolCall
+      label="Searched"
+      activeLabel="Searching"
+      query="composer"
+      request={request}
+      result={result}
+      running
+      open={open}
+      onOpenChange={setOpen}
+    />
+  </AgentSurface>;
+  ```
+  `AgentSurface` renders a plain `div` and stamps `data-cue-skin` and
+  `data-cue-fidelity` on it. `elements.css` re-declares, under those attributes,
+  the `--cue-*` tokens the family reads, and custom properties inherit — so the
+  whole subtree repaints with no prop threading and no branch inside any
+  component.
+  The two axes are independent, which is the switchable fidelity the spec asked
+  for:
+  - **`skin`** — `cue` (the default) or `aui`, which installs assistant-ui's four
+    shadcn variables and four literal hues as cue tokens, in light and dark.
+  - **`fidelity`** — `cue-metrics` (the default) keeps cue's type scale and
+    declares exactly one metric of its own:
+    `--spacing: calc(0.25rem * var(--cue-density, 1))`. That is the lever that
+    carries the density ladder into five hundred-odd vendored geometry utilities,
+    none of which names a `--cue-space-*` token. `upstream` pins assistant-ui's
+    radii, their 13.5/12/11px type and a flat `--spacing: 0.25rem` instead, so
+    **density stops at the island edge** and the subtree keeps upstream's
+    proportions whatever the console around it is set to.
+  It is not a theme. `data-theme`, `data-mode` and `data-density` are untouched,
+  and a light app gets a light island.
+  Overlays follow. The portal stamp gains both axes, so a popover or dialog opened
+  from inside an island — which mounts on `<body>`, far from the attributes —
+  paints like the transcript it came from rather than like the page. Outside an
+  island the two attributes are _absent_ rather than defaulted, so nothing that
+  does not use this pays for it.
+  ## Where this code came from
+  Elements are not a package. `@assistant-ui/ui` is private at `0.0.0` and never
+  published; the only channel is a shadcn registry whose index carries no version,
+  no date and no hash, rebuilt from upstream `main` on every deploy. Copy-in is
+  the intended use — so this release also ships the only thing that can answer
+  "which Elements do we have".
+  `scripts/elements-sync/` is pinned to upstream commit
+  `31a049fcfa846a76da7c8e2c0bcd62960825dbd4` (resolved 2026-08-22). It fetches
+  all 96 `elements-*` registry items, verifies every allowlisted file against
+  `raw.githubusercontent.com` at that pin, records every byte it read in
+  `elements-sync.lock.json`, and runs a committed codemod that rewrites the fetched
+  TSX before it lands: the ink ramp onto cue's four stops, the four literal
+  Tailwind hues onto `stream`/`ok`/`danger`/`warn` with their alphas intact,
+  literal pixel sizes onto the type scale, radii onto the three rungs, and every
+  `dark:` variant resolved away because cue's mode axis is `[data-mode]` rather
+  than `prefers-color-scheme`. Geometry is deliberately left alone: it all compiles
+  through `--spacing`, which is the island's lever. Upstream's own 679 documented
+  prop rows are merged into JSDoc on the way out, so the props table on each page
+  is upstream's description of upstream's prop.
+  What that buys a consumer: the elements arrive as source this library owns and
+  can fix, not as a dependency that can move underneath you; the "version" you have
+  is a SHA you can read in `NOTICE.md` and diff against; and the licence obligation
+  travels with the package. Upstream's MIT notice — Copyright (c) 2025 AgentbaseAI
+  Inc. — is preserved verbatim in `packages/ui/src/elements/NOTICE.md` and named in
+  the group's own documentation.
+  Two consequences worth stating plainly. **The directory is generated.** Every
+  file in `src/elements/` except `surfaces.tsx` and `agent-surface.tsx` is output;
+  a bug there is fixed by changing a codemod rule and re-running the sync, never by
+  editing the file, because the next re-sync deletes a hand edit without telling
+  anyone. And **six upstream export names are renamed at emit**, because docgen
+  slugs are globally unique and the `Chat` family stays authoritative:
+  `Composer → ElementsComposer`, `CommandPalette → ElementsCommandPalette`,
+  `DataTable → ElementsDataTable`, `EmptyState → ChatEmptyState`,
+  `Timeline → ElementsTimeline`, and `Source → CitationSource` (that one collides
+  inside upstream's own family). None of the six is in this release — they land
+  with the rest of the catalogue — but the table is generated by the sync, ships in
+  the group barrel, and is the answer to "why is the import name not the one on
+  assistant-ui's site".
+  ## What did not change
+  Outside the `cue` preset's four status values and its light `stream`, no colour
+  moved. No component's
+  props, structure or rendering changed, with two additions that are worth naming
+  because they are additions rather than nothing: the portal stamp — both
+  `useCuePortalProps` and `CuePortalFrame` — now carries `data-cue-skin` and
+  `data-cue-fidelity` alongside the four axes it already carried, and both are
+  _absent_ outside an island rather than defaulted; and the configurator's
+  `TokenEditor` lists `stream` in its Status group, so a generated theme edits it
+  where you would look for it.
+  The root barrel is untouched, so an app that never imports `/elements` gets no
+  new peer, no new stylesheet and no new bytes, and `tw-shimmer` and
+  `tw-animate-css` were reimplemented as CSS in this package rather than taken as
+  dependencies. The `Chat` group is unchanged and stays authoritative on every
+  name the two families both wanted.
+  Text is still text. Nothing in this group parses model output as markdown or
+  HTML; the elements render what they are given, for the same reason `Message`
+  does. Sanitized markdown is a documented, opt-in surface arriving later, with its
+  own peer and its own entry.
+  `schemaVersion` is still `1`.
+- 4e510e7: ## The red carries its own ink
+  `RevertDock`'s confirm is the one solid destructive fill in the elements family
+  and the one control in it that does something irreversible. It painted
+  `bg-danger/90 text-accent-fg`, and both halves of that were wrong.
+  `--cue-accent-fg` is the ink authored against `--cue-accent`. It has no
+  relationship to `--cue-danger`, and on the ten reds this system ships it lands
+  anywhere between **3.58:1** (venu, dark) and **6.67:1** (requestport, light).
+  The `/90` then let the paper through and took roughly another 0.65 off the
+  ratio. In cue's own light theme the label on that button measured **4.29:1** at
+  the 12px this row is set in — under AA, on the press that cannot be undone.
+  Inside an `<AgentSurface skin="aui">` in light mode it was **3.82:1**.
+  There is no existing token that fixes it. Every candidate the palette already
+  owns fails somewhere: `accent-fg` fails terminal and venu in dark, `bg` fails
+  terminal and hivehub in dark, the theme's own `fg` fails every light block. The
+  ink a red can carry is a property of _that red_, not of the mode — so the red
+  now has one.
+  ### `--cue-danger-fg`
+  A new authored anchor, per preset, per mode, in the colour contract beside the
+  tone it is chosen against:
+  ```css
+  [data-theme="cue"] {
+    --cue-danger: #ff5f57;
+    --cue-danger-fg: #000000;
+  }
+  [data-theme="cue"][data-mode="light"] {
+    --cue-danger: #d03030;
+    --cue-danger-fg: #fcfcfc;
+  }
+  ```
+  with `text-danger-fg` / `bg-danger-fg` bridged into Tailwind like every other
+  colour token. `ok`, `busy`, `info` and `stream` have no such ink, and that is
+  deliberate: they are read as signals — a dot, a rim, a 12% wash — and the text
+  near them sits on a surface. The red is a tone this system fills a control with,
+  which is what makes text on it text. (The amber turns out to be the other one —
+  _The amber carries its own ink too_, later in this same release.)
+  Each preset's value is the extreme it already owns, measured: every light block
+  takes its paper, seven dark blocks take their deepest ground, and the two whose
+  red sits in the middle of the range (terminal, hivehub) take white, because
+  nothing else reaches AA on it. The worst pair in the system is now **4.59:1**;
+  it was **3.58:1**.
+  `createTheme()` derives the same token for a generated theme the way it derives
+  `accent-fg` — best of the theme's ground, its deepest well and its ink, with
+  pure black or white only when none of the three can be read — and
+  `CONTRAST_REQUIREMENTS` gained a tenth pair, `danger-fg/danger` at 4.5:1, so a
+  generated palette is judged on it too. The configurator shows it next to the red
+  in the Status group.
+  A sweep in `@cueplusplus/ui`'s own suite now measures the shipped pairing across
+  all ten presets in both modes and fails under 4.5:1, and a second one measures
+  it inside the assistant-ui island, where the two halves legitimately disagree
+  about which ink their red wants.
+  ### If you ship your own theme block
+  A hand-written `[data-theme="acme"]` block should declare `--cue-danger-fg`
+  alongside `--cue-danger`. Without it, `text-danger-fg` resolves to nothing on
+  your theme. Themes generated by `createTheme()` and the configurator's exports
+  already carry it.
+## 0.4.0
+### Minor Changes
+- 85448d8: ## Three hairlines, derived from the foreground
+  A list is not a stack of boxes, and until now the token vocabulary had no way to
+  say the difference.
+  `--cue-border` is an authored anchor: every preset picks one, and what every
+  preset picks is a **box edge** — the line around a card, an input, a panel. It is
+  the right weight for exactly that. Repeat it down thirty rows of a table and the
+  page stops reading as a list and starts reading as thirty boxes stacked on each
+  other. The line _between_ things wants to be lighter than the line _around_ a
+  thing, and there was no token for it, so every surface that needed one either
+  borrowed `--cue-border` and looked heavy, or invented a `color-mix()` of its own
+  and stopped being themeable.
+  Three new tokens, in every preset, in both modes:
+  | Token               | Value                                                  | What it is                                                                                    |
+  | ------------------- | ------------------------------------------------------ | --------------------------------------------------------------------------------------------- |
+  | `--cue-hair`        | `color-mix(in oklch, var(--cue-fg) 6%, transparent)`   | **Hairline rule** — between rows, between sections, under a caption                           |
+  | `--cue-hair-strong` | `color-mix(in oklch, var(--cue-fg) 12%, transparent)`  | **Strong hairline** — the same line where it carries weight: a table head, a quiet tag's edge |
+  | `--cue-row-hover`   | `color-mix(in oklch, var(--cue-fg) 3.5%, transparent)` | **Row hover wash** — the faintest fill that still reads as one row picked out of a list       |
+  They are mixed from `--cue-fg`, not authored per preset, and that is the whole
+  point of them. A share of the foreground keeps its relationship to the type it
+  separates whatever the palette turned out to be — the rules lighten with the text
+  in a light block, they hold at `terminal`'s cyan-on-black and at `luma`'s warm
+  paper, and a preset added tomorrow gets all three for free without authoring a
+  thing. Asking ten presets to hand-pick a hairline would have produced ten
+  slightly different answers to a question nobody should have to answer.
+  They are emitted **inside** every theme block rather than once on `:root`, like
+  every other derived colour here: a custom property's `var()` references are
+  substituted at the element that declares it, so a `:root`-level mix would freeze
+  the default preset's foreground into every nested theme.
+  ## Spending them
+  They are not Tailwind utilities, on the same ruling as `--cue-accent-soft`'s
+  status siblings — arbitrary-property syntax reads the token directly:
+  ```tsx
+  <div className="border-t border-(--cue-hair) hover:bg-(--cue-row-hover)" />
+  ```
+  ## `--cue-row-hover` does not replace the surface ramp
+  Worth being exact, because there are now two answers to "how does a row show
+  hover" and only one of them is new. A row that sits **on a surface** still lifts
+  to the next rung — `hover:bg-surface-2` — and that is what this library's own
+  rows do: `Sidebar.Item`, `Tree`, `Pagination`, `Toggle`, `NumberField`. None of
+  them change, and none of them should.
+  `--cue-row-hover` is for rows drawn **directly on `--cue-bg`**, where the next
+  rung of the ramp is a step you can see from across the room and the row you are
+  pointing at ends up looking selected rather than hovered. If the ramp fits your
+  row, use the ramp.
+  ## `createTheme()` derives them too — and now it cannot forget to
+  `@cueplusplus/ui` carries its own copy of the derivation table, because
+  `createTheme()` runs in a browser over a palette somebody just typed while the
+  token build runs at publish time over DTCG files under Style Dictionary, and
+  neither package can import the other's. So a preset you generate gets the three
+  hairlines exactly as a shipped preset does.
+  The copy was the real hazard here, and it was already sitting in the tree: **no
+  test compared the two lists.** A derivation added to the build alone would have
+  been missing from every theme a consumer generated, and the only symptom would
+  have been an unstyled rule in somebody else's app weeks later. There is now a
+  test that compares `DERIVED_TOKEN_TEMPLATES` against the compiled stylesheet in
+  both directions, so a one-sided edit fails in this repository instead.
+  **Nothing changes for existing consumers.** Both packages gain tokens and neither
+  loses or moves one; no component's rendered output differs.
+## 0.3.0
+### Minor Changes
+- 31e3607: Ship the linked RequestPort preset release across tokens, UI, and brand tokens.
+  The release adds the typed RequestPort preset and its generated dark, light, and
+  system selectors; system SSR, prepaint, provider, and portal behavior; the
+  `persistPreferences={false}` and authoritative prepaint options contracts; the
+  typed `fontFamilies` provider/portal override; the deterministic package
+  manifest and companion checksums; and the accessible `TableScrollRegion`.
+  All three linked tarballs receive the same minor version and changelog entry.
+  The Version Packages path regenerates the package manifest after applying those
+  versions and rejects stale or nondeterministic output before publication.
+## 0.2.0
+### Minor Changes
+- 33a95c4: Typeface is a third axis, beside theme and density.
+  `data-font` selects one of eight font pairings — a sans and a monospace — the
+  same way `data-theme` selects a palette and `data-density` selects a geometry.
+  `<ThemeProvider font>`, `useTheme().font` / `setFont`, persistence beside the
+  other two, the pre-paint script, and every portal root carry it.
+  ```tsx
+  <ThemeProvider theme="cue" density="normal" font="plex">
+    <App />
+  </ThemeProvider>
+  ```
+  | id       | sans                   | mono                | what your app has to do            |
+  | -------- | ---------------------- | ------------------- | ---------------------------------- |
+  | `system` | the platform's UI sans | **the theme's own** | nothing — this is the default      |
+  | `geist`  | Geist                  | JetBrains Mono      | deliver two faces                  |
+  | `inter`  | Inter                  | IBM Plex Mono       | deliver two faces                  |
+  | `plex`   | IBM Plex Sans          | IBM Plex Mono       | deliver two faces                  |
+  | `roboto` | Roboto                 | Roboto Mono         | deliver two faces                  |
+  | `source` | Source Sans 3          | Source Code Pro     | deliver two faces                  |
+  | `apple`  | SF Pro Text            | SF Mono             | nothing — and nothing you _may_ do |
+  | `office` | Calibri (Carlito)      | Cascadia Mono       | nothing — and nothing you _may_ do |
+  New exports from `@cueplusplus/tokens`: `FONTS`, `FontName`, `DEFAULT_FONT`,
+  `FONT_PAIRINGS`, `FONT_FACES`, `FontDelivery`, `FontPairing`, `faceProperty`.
+  `prepaintScript()` takes a fourth argument, the default pairing.
+  ## You have to load the fonts. We will not.
+  **This package ships no font file and no `@font-face`, and that is deliberate.**
+  A library that injected one would be choosing your network requests, your
+  content-security policy and your font licensing, in a stylesheet you imported
+  for its colours. What a pairing emits instead is a hook with the family name as
+  its fallback:
+  ```css
+  [data-font="inter"] {
+    --cue-font-sans: var(--cue-face-inter, Inter), ui-sans-serif, system-ui, …;
+    --cue-font-mono:
+      var(--cue-face-ibm-plex-mono, "IBM Plex Mono"), ui-monospace, …;
+  }
+  ```
+  Assign nothing and the stack still resolves — a local install first, then the
+  platform — so no pairing ever renders as nothing. Assign the property and
+  everything painted from the token follows. With `next/font`, the property name
+  _is_ the option:
+  ```tsx
+  const inter = Inter({ subsets: ["latin"], display: "swap", preload: false, variable: "--cue-face-inter" });
+  <html className={inter.variable}>
+  ```
+  `preload: false` matters: with preloading on, a site offering five webfont
+  pairings makes every visitor download all of them to render in one.
+  `FONT_PAIRINGS[name].faces` is the list of properties one pairing needs;
+  `FONT_FACES` is every face at once, as `property → family`.
+  **`apple` and `office` are stacks and must stay stacks.** SF Pro and SF Mono are
+  Apple-licensed and may not be served as webfonts; Calibri is Microsoft's and
+  ships with Windows and Office rather than with anybody's site (Carlito is its
+  metric-compatible libre twin, and is in the stack). They light up where
+  installed and fall through cleanly where they are not. Do not bundle them.
+  ## A theme's monospace still applies — until somebody picks a pairing
+  Seven presets name a monospace of their own, and seven pairings name one, so
+  one token was claimed twice.
+  Neither axis writes it now: a theme publishes `--cue-font-theme-mono`, a pairing
+  publishes `--cue-font-pairing-mono`, and `--cue-font-mono` resolves the two,
+  pairing first. **A chosen pairing wins**, at whatever element each was stamped
+  on — a pairing is what a person picked out of a menu and a preset's mono is what
+  its author chose in the absence of a person. The default pairing, `system`,
+  declines the question, so an app that never touches the axis keeps exactly the
+  monospace it has today.
+  ## Two things that change without you asking
+  **The base sans no longer names `Geist`.** It named a font this package has
+  never delivered, so for almost every visitor it resolved to the next entry
+  anyway. `--cue-font-sans` and `--cue-font-display` are now the platform stack;
+  Geist is the head of the `geist` pairing, which your app can actually deliver.
+  If you want it back, deliver it: `font="geist"` plus the two `--cue-face-*`
+  assignments.
+  **A generated theme's mono moves with it.** `createTheme({ fonts: { mono } })`
+  now writes `--cue-font-theme-mono`. Nothing to change unless you read the
+  generated `tokens` map by key.
+  ## Migrating
+  Nothing is required. Two things are worth doing:
+  1. **Pass the pairing to the pre-paint script**, as its fourth argument, if your
+     app's default is not `system`:
+     `prepaintScript(DEFAULT_STORAGE_KEY, "cue", "normal", "geist")`. A theme that
+     arrives one frame late is a flash of the wrong colour; a _family_ that
+     arrives one frame late reflows every line under the reader.
+  2. **If your own CSS overrides `--cue-font-mono`** under a `[data-theme]` block
+     of your own, move it to `--cue-font-theme-mono` — otherwise your override
+     beats the typeface picker and yours is the one theme it cannot move.
+  `font` is a root-level prop: there is no font island, and a nested provider
+  forwards the axis (and `setFont`) to the root. A specimen that genuinely wants
+  one face beside another needs nothing from this library but `data-font` on a
+  `<div>`.
+- b86f482: The density ladder is five rungs, and the two names in the middle have moved.
+  `ultra-compact` · `normal` · `large` was never a ladder anyone could reason
+  about: the rung called `normal` is what every other design system calls
+  _compact_, the rung called `large` is what everyone else calls _normal_, and
+  above that there was nothing at all — no level for a touch panel, a stage
+  monitor, or a reader who needs the whole screen a size up. This renames the two
+  misnamed rungs to what they always were and adds the two that were missing.
+  **Minor rather than major because the package is pre-1.0** — 0.x's breaking rung
+  is the minor one, and this is breaking.
+  **Read the migration before you upgrade.** One of its four steps is a prop
+  rename a compiler catches. The other three are not: CSS of your own keyed on
+  `[data-density]`, a label map with one entry per level, and a persisted
+  preference all keep working after this release and quietly mean something else.
+  ## The mapping
+  | you wrote       | you now write     | geometry                                             |
+  | --------------- | ----------------- | ---------------------------------------------------- |
+  | `ultra-compact` | `ultra-compact`   | unchanged                                            |
+  | `normal`        | **`compact`**     | **unchanged** — the name moved, not a pixel          |
+  | `large`         | **`normal`**      | **unchanged** — the name moved, not a pixel          |
+  | —               | **`large`**       | new: a rung above what the ladder used to top out at |
+  | —               | **`ultra-large`** | new: the top, and the mirror of `ultra-compact`      |
+  Nothing that existed changed size. `<ThemeProvider density="normal">` used to
+  render 24px controls and now renders 32px ones — not because the geometry moved
+  but because `normal` now names the rung above the one it used to name.
+  ## Migrating
+  Four things move. Only the first and the last are visible to a compiler; the two
+  in the middle are the ones that ship a wrong-looking screen with a green build.
+  ### 1. Rename every level you name, one step down the ladder
+  Everywhere you write a density — the provider, a `<Density>` island, a prop you pass
+  through, a test:
+  ```diff
+  -<ThemeProvider theme="cue" density="normal">
+  +<ThemeProvider theme="cue" density="compact">
+  ```
+  ```diff
+  -<Density density="large">
+  +<Density density="normal">
+  ```
+  `ultra-compact` is unchanged and needs no edit. Do the two renames in that
+  order, or in one pass — `normal` → `compact` and `large` → `normal` — and your
+  screens render exactly as they did before.
+  **If you never passed a `density`, this step is a no-op.** The default moved
+  from `normal` to `compact`, which is the same geometry it always was: an app
+  that never chose a level renders identically before and after.
+  ### 2. Rename your own `[data-density]` CSS — and add blocks for the two new rungs
+  **This is the half that fails silently.** If your app keys any of its own CSS on
+  `data-density` — a per-rung scalar you multiply your lengths by, a per-rung
+  override, anything — those selectors still match a valid attribute value after
+  this release. They just match a _different rung_. Nothing throws, nothing logs,
+  no build fails: your rows simply stop matching the controls inside them.
+  ```diff
+   :root { --app-type: 1; --app-space: 1; }
+  -[data-density="normal"] { --app-type: 1;     --app-space: 1; }
+  -[data-density="large"]  { --app-type: 1.111; --app-space: 1.333; }
+  +[data-density="compact"] { --app-type: 1;     --app-space: 1; }
+  +[data-density="normal"]  { --app-type: 1.111; --app-space: 1.333; }
+  +/* and two blocks that did not exist before — continue your own step, or read
+  +   the ratio off the library's ladder: --cue-density is 0.85 / 1 / 1.3 / 1.6 / 1.9
+  +   and the spacing sequence shifts one place per rung. */
+  +[data-density="large"]       { --app-type: …; --app-space: …; }
+  +[data-density="ultra-large"] { --app-type: …; --app-space: …; }
+  ```
+  What each rung does if you rename the props and stop there:
+  | rung            | if you only renamed the props                   | what the reader sees                                                            |
+  | --------------- | ----------------------------------------------- | ------------------------------------------------------------------------------- |
+  | `ultra-compact` | your `ultra-compact` block still matches        | correct                                                                         |
+  | `compact`       | **no block matches** — falls through to `:root` | your scalars sit at their base values while the library's geometry is a rung up |
+  | `normal`        | your old `normal` block matches                 | your scalars are a rung behind the library's                                    |
+  | `large`         | your old `large` block matches                  | your scalars are two rungs behind                                               |
+  | `ultra-large`   | **no block matches** — falls through to `:root` | base scalars against the largest geometry the ladder has                        |
+  A rung with no block of yours does not fall back to the nearest one. It falls
+  through to whatever `:root` declares, which is almost always the smallest value
+  you own. Grep your stylesheets for `data-density` before you upgrade:
+  ```sh
+  rg 'data-density' --glob '!node_modules'
+  ```
+  ### 3. Fix anything that enumerates the ladder
+  A label map, a switcher, a segmented control, a settings screen, a persisted
+  preference — anything with one entry per density level is now missing two and
+  mis-naming two. A map keyed by the old three names does not error; it returns
+  `undefined`, and most switchers render the raw slug:
+  ```diff
+   const DENSITY_LABELS = {
+     "ultra-compact": "Ultra compact",
+  -  normal: "Normal",
+  -  large: "Large",
+  +  compact: "Compact",
+  +  normal: "Normal",
+  +  large: "Large",
+  +  "ultra-large": "Ultra large",
+   };
+  ```
+  `DENSITIES` from `@cueplusplus/tokens` is the list to derive from rather than
+  restate — it is five entries now and it will be right next time too. If your map
+  is typed `Record<Density, string>` TypeScript will fail the build for you; if it
+  is a plain object literal, nothing will.
+  **A persisted preference that says `"normal"` is now a bigger screen.** The
+  provider stores the level under `localStorage` and validates it against the
+  ladder, so `"normal"` is still a valid value — it just means a different rung.
+  Migrate the stored value the same way you migrate the code, or accept that
+  returning users move up one rung once.
+  ### 4. `density-ultra:` is now `density-ultra-compact:`
+  The stylesheet registers one Tailwind variant per rung, each named after the
+  rung it matches: `density-ultra-compact:`, `density-compact:`,
+  `density-normal:`, `density-large:`, `density-ultra-large:`. `density-ultra:` is
+  gone, because with an `ultra-large` rung on the ladder "ultra" names neither end
+  of it — and an unknown variant is a build error, so this one tells you.
+  `density-large:` keeps its name and changes meaning with its rung, which does
+  not.
+  ## The two new rungs
+  Every axis continues the step the three existing rungs already walk, rather than
+  scaling anything by a factor:
+  |                  | ultra-compact | compact | normal   | **large**    | **ultra-large** |
+  | ---------------- | ------------- | ------- | -------- | ------------ | --------------- |
+  | `control-md`     | 20px          | 24px    | 32px     | **40px**     | **48px**        |
+  | `chip-h`         | 16px          | 18px    | 22px     | **26px**     | **30px**        |
+  | `icon-md`        | 10px          | 12px    | 16px     | **20px**     | **24px**        |
+  | `text-body`      | 10px          | 11px    | 13px     | **15px**     | **17px**        |
+  | `pad-row`        | 2 × 6px       | 4 × 8px | 6 × 12px | **8 × 16px** | **10 × 20px**   |
+  | `chrome-toolbar` | 32px          | 36px    | 44px     | **52px**     | **60px**        |
+  | `--cue-density`  | 0.85          | 1       | 1.3      | **1.6**      | **1.9**         |
+  `large` is a touch and presentation rung: 40px controls clear the WCAG 2.2
+  SC 2.5.8 target floor with room to spare. `ultra-large` is for a wall display, a
+  kiosk, a stage monitor read from two metres, and for a low-vision reader who
+  wants the whole interface a size up rather than the browser's zoom.
+  The `@media (pointer: coarse)` re-raise still applies to `ultra-compact` alone,
+  and still raises it to exactly the same heights it always did — `compact`'s.
+  `compact` is the rung the raise lands on, so raising it too would mean promoting
+  it to `normal` and moving today's default geometry on every touch device.
+  ## The type ladder got a top
+  `text-title` and `text-emphasis` are bigger at every rung. `text-micro`,
+  `text-label`, `text-ui` and `text-body` are untouched — consoles are built out
+  of those four and none of them moves.
+  |                 | ultra-compact | compact       | normal        | large    | ultra-large |
+  | --------------- | ------------- | ------------- | ------------- | -------- | ----------- |
+  | `text-emphasis` | 11 → **13px** | 12 → **14px** | 14 → **17px** | **20px** | **23px**    |
+  | `text-title`    | 12 → **16px** | 13 → **18px** | 16 → **22px** | **26px** | **30px**    |
+  A page heading was 1.18× a paragraph, which is not a hierarchy — it is six sizes
+  within four points of each other, and every screen built on it came out flat. It
+  is now 1.6–1.76×, and the whole ladder spans 2× to 2.7× from `micro` to `title`
+  depending on the rung. If you set a page title in `text-title` it will look like
+  one now; if you were compensating with a hand-written size, delete the
+  compensation.
+  ## Also
+  `prepaintScript()` takes a third argument, `defaultDensity`, alongside
+  `defaultTheme`. An app whose provider names a level other than `compact` should
+  pass the same level here, or the first frame paints at one rung and every frame
+  after it at another:
+  ```tsx
+  prepaintScript(DEFAULT_STORAGE_KEY, "cue", "normal");
+  ```
+- a382b68: A ninth theme preset, `quotamate`, with a light pair.
+  `THEMES` gains `"quotamate"` and `ThemeName` widens with it, so a consumer can write
+  `theme="quotamate"` without a cast. `dist/themes/quotamate.css` is built alongside the other
+  eight, and `THEME_PRESETS.quotamate` is available to `createTheme()` and the configurator.
+  ```tsx
+  <ThemeProvider theme="quotamate" density="ultra-compact" mode="dark">
+  ```
+  A blue-black ramp at hue 240 under a cyan accent (`#00e5e5`). Not a new design — quotamate is
+  a shipping product whose palette was already fixed in a private stylesheet, so the values are
+  the same colours in hex that it authored in HSL. Adopting the preset is a no-op for the
+  running product rather than a restyle, which is the only reason it can be adopted at all.
+  **Its status hues are deliberately not the accent**, which is where this preset differs from
+  `cue`. quotamate's whole job is to say whether an account is usable right now, so `ok`, `warn`
+  and `danger` have to stay separable at a glance from the colour that means "interactive" — a
+  dashboard where "healthy" and "clickable" are the same green cannot be read quickly.
+  Light drops the accent to a deepened teal (`#0d7d7d`) rather than the near-black the product
+  itself used. `#00e5e5` on `#fcfcfc` fails contrast for text and for a hairline rim alike, so
+  the product's instinct was right; an accent that is merely dark, though, loses the brand.
+  Same hue, enough chroma to read as the product's colour, dark enough to carry white text on a
+  filled control.
+  Two tests encoded "eight presets" and were corrected rather than bumped:
+  - `build.test.mjs` listed the theme names, which is the point of that assertion.
+  - `disjoint.test.mjs` asserted `sources === 16` as a stand-in for "each preset has a dark and
+    a light source". A count is a poor proxy — eight darks and eight lights is 16, and so is
+    nine darks and seven lights — and it failed a geometry test for a reason unrelated to
+    geometry. It now asserts the pairing directly and will not go stale on the tenth preset.
+### Patch Changes
+- 6ce0c7d: The release notes now ship inside the package.
+  `files` was `dist` alone, so the `CHANGELOG.md` this repository writes on every
+  release stayed in a private git repository and reached nobody: `npm pack` left it
+  out, and the tarball a consumer installs from GitHub Packages carried the code
+  with no record of what had changed in it. Anyone asking "what moved between the
+  version I have and the version I am upgrading to" had to have access to the
+  source repository to find out.
+  `CHANGELOG.md` is now on the `files` allowlist of all three published packages,
+  so it lands in `node_modules/@cueplusplus/<package>/CHANGELOG.md` beside the code
+  it describes. `packages/release` has the test that keeps it there.
+  No code changes and no API changes — the same `dist`, plus one file.
+  The same notes are published, alongside the CUE++ agent skills' own, at
+  <https://skills.cueplusplus.com/releases>.
+## 0.1.0
+### Minor Changes
+- First release of the CUE++ design system.
+  `@cueplusplus/tokens` ships eight theme presets (`cue`, `terminal`, `signal`, `venu`, `hivehub`,
+  `dusk`, `luma`, `snuffle`) in dark and light, three density levels (`ultra-compact`, `normal`,
+  `large`), and the Tailwind v4 `@theme inline` mapping — colour scoped to `[data-theme]`, geometry to
+  `[data-density]`, never mixed.
+  `@cueplusplus/ui` ships 146 components on Base UI: the core entry plus the `/layout`, `/forms`,
+  `/overlays`, `/chrome`, `/instruments`, `/chat`, `/theming`, `/configurator`, `/color`, `/date`
+  subpaths and the four opt-in ones (`/charts`, `/dmx`, `/midi`, `/flow`) whose heavy dependencies stay
+  optional peers. `ThemeProvider`, the density islands, `createTheme()` with its contrast report and the
+  floating `ThemeConfigurator` come with it.
+  `@cueplusplus/brand-tokens` ships the CUE++ brand layer — the white-alpha ramp, the mono stack, the
+  eyebrow and motion treatments, and the wordmark and Plussie marks.