@cueplusplus/ui 0.2.0 → 0.5.0

package/dist/theming/contrast.js

@@ -1,7 +1,7 @@
 import { converter, parse } from "culori";
 //#region src/theming/contrast.ts
 /**
-* WCAG contrast, and the eight pairs a theme is judged on.
+* WCAG contrast, and the eleven pairs a theme is judged on.
 *
 * A generator that only derived colours would be a colour toy: the reason to
 * compute a palette instead of picking one is that the computer can then *check*
@@ -82,13 +82,25 @@ function contrastRatio(foreground, background) {
 	return (high + .05) / (low + .05);
 }
 /**
-* The eight pairs that decide whether a theme is usable.
+* The eleven pairs that decide whether a theme is usable.
 *
 * Not every pair in the palette: the ones a reader's comprehension actually
 * depends on. Primary ink is held to AAA because it carries the prose; secondary
-* ink and accent ink to AA because they carry labels; the five status colours to
-* the non-text AA floor because they are read as *signals* — a dot, a rim, a bar
-* — never as body copy.
+* ink and accent ink to AA because they carry labels; the five status colours
+* and the live hue to the non-text AA floor because they are read as *signals*
+* — a dot, a rim, a bar — never as body copy.
+*
+* `danger` and `warn` each appear twice, and they are the only tones that do.
+* `ok`, `busy`, `info` and `stream` are *only* ever signals, so the non-text
+* floor is the whole truth about them. The red and the amber are also grounds:
+* they are the two tones this system fills a control with, and what they fill is
+* the confirm on something irreversible and the confirm on something merely
+* consequential. Text on either fill is text, so its ink is held to the text
+* floor against the tone it sits on rather than against the page.
+*
+* `stream` is measured for the same reason `ok` is: `createTheme()` darkens it
+* to this floor when it has to invent a light block, and a report that did not
+* check what the derivation targets would be checking the wrong thing.
 */
 const CONTRAST_REQUIREMENTS = [
 	{
@@ -112,12 +124,27 @@ const CONTRAST_REQUIREMENTS = [
 		minimum: WCAG_AA_TEXT,
 		reason: "The label on a solid accent button has to be readable."
 	},
+	{
+		id: "danger-fg/danger",
+		foreground: "danger-fg",
+		background: "danger",
+		minimum: WCAG_AA_TEXT,
+		reason: "The label on a solid destructive fill is read before something irreversible happens."
+	},
+	{
+		id: "warn-fg/warn",
+		foreground: "warn-fg",
+		background: "warn",
+		minimum: WCAG_AA_TEXT,
+		reason: "The label on a solid warning fill is read before a consequential press lands."
+	},
 	...[
 		"ok",
 		"busy",
 		"warn",
 		"danger",
-		"info"
+		"info",
+		"stream"
 	].map((status) => ({
 		id: `${status}/bg`,
 		foreground: status,

package/dist/theming/create-theme.d.ts

@@ -30,7 +30,7 @@ declare const DEFAULT_THEME_BASE: ThemeName;
 /**
  * How far the sunken ground sits below the page, in oklch lightness.
  *
- * Small on purpose: sunken is a well, not a second theme. Across the eight
+ * Small on purpose: sunken is a well, not a second theme. Across the ten
  * shipped presets the authored gap runs −0.011 to −0.031.
  */
 declare const SUNKEN_LIGHTNESS_STEP = -0.02;
@@ -75,7 +75,7 @@ declare const ACCENT_FG_MINIMUM = 4.5;
  * extreme rather than to the arithmetic mirror: `1 − L` of a 0.16 near-black is a
  * 0.84 mid-grey, which is not a page. Compressing instead maps the ladder of
  * dark grounds onto a narrow paper band — a deeper dark theme gets a cleaner
- * white page — and lands within 0.01 of all eight authored light presets.
+ * white page — and lands within 0.01 of all ten authored light presets.
  */
 declare const LIGHT_GROUND_COMPRESSION = 0.1;
 interface ThemeAnchors {
@@ -103,8 +103,12 @@ interface ThemeAnchors {
   accent?: string;
   /** Individual rungs of the surface ladder, overriding whatever would be derived. */
   surfaces?: Partial<Record<"sunken" | "surface-1" | "surface-2" | "surface-3", string>>;
-  /** Individual status tones. Never derived — a signal colour is a decision. */
-  status?: Partial<Record<"ok" | "busy" | "warn" | "danger" | "info", string>>;
+  /**
+   * Individual status tones, plus `stream` — the live hue an agent surface
+   * paints a token still arriving with. Never derived: a signal colour is a
+   * decision.
+   */
+  status?: Partial<Record<"ok" | "busy" | "warn" | "danger" | "info" | "stream", string>>;
   /**
    * Font stacks. `mono` is the one the presets themselves override; `sans` and
    * `display` are emitted only when given. Values pass through verbatim, so they

package/dist/theming/create-theme.js

@@ -1,7 +1,7 @@
 import { formatColorString } from "../color/_convert.js";
 import { BASE_FONT_STACKS, DEFAULT_DENSITY_LEVEL, DENSITY_RADIUS_SCALE, RESOLVED_MONO, THEME_COLOR_TOKENS, THEME_PRESETS } from "./_presets.js";
 import { WCAG_AA_TEXT, contrastRatio, contrastReport } from "./contrast.js";
-import { assertCssValue, assertThemeName, derivedTokens, serializeThemeCss, themeSelector, tokenProperty } from "./serialize.js";
+import { assertCssValue, assertThemeName, derivedTokens, serializeSystemModeAliases, serializeThemeCss, themeSelector, tokenProperty } from "./serialize.js";
 import { clampChroma, converter, formatHex, inGamut, parse } from "culori";
 //#region src/theming/create-theme.ts
 /**
@@ -32,7 +32,7 @@ const DEFAULT_THEME_BASE = "cue";
 /**
 * How far the sunken ground sits below the page, in oklch lightness.
 *
-* Small on purpose: sunken is a well, not a second theme. Across the eight
+* Small on purpose: sunken is a well, not a second theme. Across the ten
 * shipped presets the authored gap runs −0.011 to −0.031.
 */
 const SUNKEN_LIGHTNESS_STEP = -.02;
@@ -81,7 +81,7 @@ const ACCENT_FG_MINIMUM = WCAG_AA_TEXT;
 * extreme rather than to the arithmetic mirror: `1 − L` of a 0.16 near-black is a
 * 0.84 mid-grey, which is not a page. Compressing instead maps the ladder of
 * dark grounds onto a narrow paper band — a deeper dark theme gets a cleaner
-* white page — and lands within 0.01 of all eight authored light presets.
+* white page — and lands within 0.01 of all ten authored light presets.
 */
 const LIGHT_GROUND_COMPRESSION = .1;
 /** Lightness a derived light colour steps down by while hunting for contrast. */
@@ -178,14 +178,31 @@ function lookup(map, token) {
 * and stays correct if a consumer overrides the accent in tier 1 later.
 */
 const SELECTION_WASH = `color-mix(in oklch, var(--cue-accent) 22%, transparent)`;
-/** The five status tones, in the order every theme block declares them. */
-const STATUSES = [
+/**
+* The five tones plus the live hue, in the order the colour contract lists them.
+*
+* `stream` resolves exactly like a status — authored, never derived from the
+* accent, and darkened to the non-text floor when a light block has to be
+* invented — but it is not a `tone` any component takes. See
+* `ThemeAnchors.status`.
+*/
+const TINTED = [...[
 	"ok",
 	"busy",
 	"warn",
 	"danger",
 	"info"
-];
+], "stream"];
+/**
+* The tones that are also *grounds*, in contract order.
+*
+* Every other status colour is only ever a signal — a dot, a rim, a wash — and
+* whatever text sits near it sits on a surface. These two get filled: the amber
+* carries the confirm on a consequential press and the red the confirm on an
+* irreversible one, and text on a fill is text. So each gets an ink derived
+* against itself, `warn-fg` and `danger-fg`.
+*/
+const INKED = ["warn", "danger"];
 /** The three raised surfaces, in ladder order. */
 const SURFACES = [
 	"surface-1",
@@ -243,7 +260,12 @@ function resolveDark(anchors, preset) {
 	const accent = colors["accent"];
 	define("accent-hover", void 0, accentMoved, () => shift(readColor(accent, "accent"), ACCENT_HOVER_LIGHTNESS_STEP));
 	define("accent-fg", void 0, accentMoved, () => pickInk(accent, [colors["bg"], colors["fg"]]));
-	for (const tone of STATUSES) define(tone, status[tone], false);
+	for (const tone of TINTED) define(tone, status[tone], false);
+	for (const tone of INKED) define(`${tone}-fg`, void 0, status[tone] !== void 0, () => pickInk(colors[tone], [
+		colors["bg"],
+		colors["sunken"],
+		colors["fg"]
+	]));
 	define("selection", void 0, accentMoved, () => SELECTION_WASH);
 	define("focus", void 0, accentMoved, () => accent);
 	define("data-ground", void 0, false);
@@ -311,7 +333,12 @@ function resolveLight(dark, preset) {
 	const accent = colors["accent"];
 	define("accent-hover", () => shift(readColor(accent, "accent"), ACCENT_HOVER_LIGHTNESS_STEP));
 	define("accent-fg", () => pickInk(accent, [colors["bg"], colors["fg"]]));
-	for (const tone of STATUSES) define(tone, () => darkenToContrast(dark.colors[tone], paperGround, 3, tone));
+	for (const tone of TINTED) define(tone, () => darkenToContrast(dark.colors[tone], paperGround, 3, tone));
+	for (const tone of INKED) define(`${tone}-fg`, () => pickInk(colors[tone], [
+		colors["bg"],
+		colors["sunken"],
+		colors["fg"]
+	]));
 	define("selection", () => SELECTION_WASH);
 	define("focus", () => accent);
 	define("data-ground", () => dark.colors["data-ground"]);
@@ -400,7 +427,7 @@ function createTheme(anchors) {
 	const derived = Object.entries(derivedTokens());
 	const fonts = resolveFonts(anchors, preset.fonts);
 	const radius = anchors.radiusScale === void 0 ? null : radiusBlocks(name, anchors.radiusScale);
-	const darkSections = [
+	const darkPaletteSections = [
 		{ declarations: colorDeclarations(dark.colors) },
 		{
 			comment: DERIVED_COMMENT,
@@ -409,25 +436,26 @@ function createTheme(anchors) {
 		{
 			comment: FONT_COMMENT,
 			declarations: fonts
-		},
-		...radius === null ? [] : [{
-			comment: SHAPE_COMMENT,
-			declarations: radius.base
-		}]
+		}
 	];
+	const darkSections = [...darkPaletteSections, ...radius === null ? [] : [{
+		comment: SHAPE_COMMENT,
+		declarations: radius.base
+	}]];
+	const lightSections = light === null ? null : [{ declarations: colorDeclarations(light.colors) }, {
+		comment: DERIVED_COMMENT,
+		declarations: derived
+	}];
 	const blocks = [
 		{
 			selector: themeSelector(name),
 			colorScheme: "dark",
 			sections: darkSections
 		},
-		...light === null ? [] : [{
+		...lightSections === null ? [] : [{
 			selector: themeSelector(name, { mode: "light" }),
 			colorScheme: "light",
-			sections: [{ declarations: colorDeclarations(light.colors) }, {
-				comment: DERIVED_COMMENT,
-				declarations: derived
-			}]
+			sections: lightSections
 		}],
 		...radius?.blocks ?? []
 	];
@@ -441,7 +469,15 @@ function createTheme(anchors) {
 	}]];
 	return {
 		name,
-		css: serializeThemeCss(blocks, { banner: `@cueplusplus/ui — theme "${name}"` }),
+		css: `${serializeThemeCss(blocks, { banner: `@cueplusplus/ui — theme "${name}"` }).trimEnd()}\n\n${serializeSystemModeAliases(name, [{
+			mode: "dark",
+			colorScheme: "light dark",
+			sections: darkPaletteSections
+		}, {
+			mode: "light",
+			colorScheme: "light dark",
+			sections: lightSections ?? darkPaletteSections
+		}])}\n`,
 		tokens: Object.fromEntries(darkSections.flatMap((section) => section.declarations)),
 		light: light === null ? null : Object.fromEntries([...colorDeclarations(light.colors), ...derived]),
 		report: contrastReport(inputs)

package/dist/theming/serialize.d.ts

@@ -88,12 +88,21 @@ declare function themeSelector(name: string, options?: ThemeSelectorOptions): st
  * `:root`, for the same reason the build does it: a custom property's `var()`
  * references are substituted at the element that declares it, so a `:root`-level
  * mix would freeze the default theme's accent into every nested theme.
+ *
+ * This is deliberately a second copy of the `DERIVED` table in
+ * `packages/tokens/build.mjs`. It has to be one: that table runs at publish time
+ * over DTCG files under Style Dictionary, this one runs in a browser over a
+ * palette somebody just typed, and neither package can import the other's. What
+ * keeps a copy from drifting is not discipline but
+ * `test/theming/serialize.test.ts`, which compares this list against the
+ * compiled stylesheet in both directions — a derivation added to one side alone
+ * fails there rather than in a consumer's app six weeks later.
  */
 declare const DERIVED_TOKEN_TEMPLATES: ReadonlyArray<readonly [string, string]>;
 /**
  * {@link DERIVED_TOKEN_TEMPLATES} as a property → value map.
  *
- * @returns The eleven derived declarations, keyed by custom property.
+ * @returns The sixteen derived declarations, keyed by custom property.
  * @example
  * derivedTokens()["--cue-accent-soft"];
  */
@@ -110,7 +119,7 @@ interface ThemeBlock {
   /** The selector the rule declares under. */
   selector: string;
   /** Emitted as `color-scheme`, ahead of the custom properties. Omit to skip it. */
-  colorScheme?: "dark" | "light";
+  colorScheme?: "dark" | "light" | "light dark";
   /** The declarations, grouped into commented sections. */
   sections: readonly ThemeBlockSection[];
 }

package/dist/theming/serialize.js

@@ -97,6 +97,53 @@ function themeSelector(name, options = {}) {
 		density === void 0 ? "" : `[data-density="${density}"]`
 	].join("");
 }
+/** The tone vocabulary that gets a soft fill and a soft border in every theme. */
+const STATUSES = [
+	"ok",
+	"busy",
+	"warn",
+	"danger",
+	"info"
+];
+/**
+* The live hue — a token still arriving, a tool still running, a cursor that
+* has not stopped.
+*
+* Not a member of {@link STATUSES}, because 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. What it shares with
+* the statuses is the shape of its family — a full-strength ink, a soft fill and
+* a rim — so it derives alongside them. `packages/tokens/build.mjs` carries the
+* same pair of constants for the same reason; see the note on
+* {@link DERIVED_TOKEN_TEMPLATES}.
+*/
+const STREAM = "stream";
+/** Every tone that earns a derived soft fill and a derived rim. */
+const TINTED = [...STATUSES, STREAM];
+/**
+* The three shares of the foreground the list idioms are ruled with.
+*
+* `--cue-border` is an authored anchor, and what a preset authors is a *box
+* edge* — the line around a card, an input, a panel. Repeated down thirty rows a
+* box edge reads as a stack of boxes rather than as a list, so a rule between
+* things is drawn lighter than the edge around a thing.
+*
+* Mixed from `--cue-fg` rather than authored, which is what makes them hold for
+* a preset `createTheme()` produced from a palette nobody vetted: the rules keep
+* their relationship to the type they separate whatever the palette turned out
+* to be, in both modes, with nothing to get wrong.
+*
+* `row-hover` is the same measurement from the other side — the faintest wash
+* that still reads as one row picked out of a list. It does not replace the
+* surface ramp: a row sitting *on* a surface still lifts to the next rung
+* (`hover:bg-surface-2`), which is what this library's own rows do. This is for
+* rows drawn directly on `--cue-bg`, where the next rung is a visible step.
+*/
+const HAIRLINE_TEMPLATES = [
+	["hair", "color-mix(in oklch, var(--cue-fg) 6%, transparent)"],
+	["hair-strong", "color-mix(in oklch, var(--cue-fg) 12%, transparent)"],
+	["row-hover", "color-mix(in oklch, var(--cue-fg) 3.5%, transparent)"]
+];
 /**
 * The derived colours every theme block carries, as `[token, value]` pairs.
 *
@@ -105,18 +152,25 @@ function themeSelector(name, options = {}) {
 * `:root`, for the same reason the build does it: a custom property's `var()`
 * references are substituted at the element that declares it, so a `:root`-level
 * mix would freeze the default theme's accent into every nested theme.
+*
+* This is deliberately a second copy of the `DERIVED` table in
+* `packages/tokens/build.mjs`. It has to be one: that table runs at publish time
+* over DTCG files under Style Dictionary, this one runs in a browser over a
+* palette somebody just typed, and neither package can import the other's. What
+* keeps a copy from drifting is not discipline but
+* `test/theming/serialize.test.ts`, which compares this list against the
+* compiled stylesheet in both directions — a derivation added to one side alone
+* fails there rather than in a consumer's app six weeks later.
 */
-const DERIVED_TOKEN_TEMPLATES = [["accent-soft", "color-mix(in oklch, var(--cue-accent) 14%, transparent)"], ...[
-	"ok",
-	"busy",
-	"warn",
-	"danger",
-	"info"
-].flatMap((status) => [[`${status}-soft`, `color-mix(in oklch, var(--cue-${status}) 12%, transparent)`], [`${status}-border`, `color-mix(in oklch, var(--cue-${status}) 35%, transparent)`]])];
+const DERIVED_TOKEN_TEMPLATES = [
+	["accent-soft", "color-mix(in oklch, var(--cue-accent) 14%, transparent)"],
+	...TINTED.flatMap((tone) => [[`${tone}-soft`, `color-mix(in oklch, var(--cue-${tone}) 12%, transparent)`], [`${tone}-border`, `color-mix(in oklch, var(--cue-${tone}) 35%, transparent)`]]),
+	...HAIRLINE_TEMPLATES
+];
 /**
 * {@link DERIVED_TOKEN_TEMPLATES} as a property → value map.
 *
-* @returns The eleven derived declarations, keyed by custom property.
+* @returns The sixteen derived declarations, keyed by custom property.
 * @example
 * derivedTokens()["--cue-accent-soft"];
 */
@@ -148,6 +202,30 @@ function serializeThemeBlock(block) {
 	}
 	return `${block.selector} {\n${lines.join("\n")}\n}`;
 }
+/** Indent a complete rule once so it can live inside an at-rule. */
+function indentRule(rule) {
+	return rule.split("\n").map((line) => `  ${line}`).join("\n");
+}
+/**
+* Alias resolved dark/light palettes onto the preserved logical `system` mode.
+*
+* Both `createTheme()` and the configurator call this function. Keeping the
+* selector and media-query spelling here prevents exported overrides from
+* drifting away from generated custom themes.
+*
+* @internal Used by package-owned theme serializers; not part of the public
+* `@cueplusplus/ui/theming` barrel.
+*/
+function serializeSystemModeAliases(theme, aliases) {
+	const name = assertThemeName(theme);
+	return aliases.map(({ mode, colorScheme, sections }) => {
+		return `@media (prefers-color-scheme: ${mode}) {\n${indentRule(serializeThemeBlock({
+			selector: `[data-theme="${name}"][data-mode="system"]`,
+			colorScheme,
+			sections
+		}))}\n}`;
+	}).join("\n\n");
+}
 /**
 * A whole generated stylesheet: banner, then one rule per block.
 *
@@ -162,4 +240,4 @@ function serializeThemeCss(blocks, options = {}) {
 	return `${[...options.banner === void 0 ? [] : [`/*! ${options.banner}\n * Generated by createTheme(). Do not edit by hand.\n */`], ...rules].join("\n\n")}\n`;
 }
 //#endregion
-export { CUE_TOKEN_PREFIX, DERIVED_TOKEN_TEMPLATES, THEME_NAME_PATTERN, assertCssValue, assertThemeName, derivedTokens, serializeThemeBlock, serializeThemeCss, themeSelector, tokenProperty };
+export { CUE_TOKEN_PREFIX, DERIVED_TOKEN_TEMPLATES, THEME_NAME_PATTERN, assertCssValue, assertThemeName, derivedTokens, serializeSystemModeAliases, serializeThemeBlock, serializeThemeCss, themeSelector, tokenProperty };

package/manifest/components/accordion.json

@@ -0,0 +1,154 @@
+{
+  "name": "Accordion",
+  "slug": "accordion",
+  "group": "layout",
+  "importPath": "@cueplusplus/ui",
+  "peerDependencies": [],
+  "clientOnly": true,
+  "description": "A stack of sections, one (or several) open at a time.\n\nWraps Base UI's `Accordion`, so the disclosure ARIA, keyboard handling and\nopen-state bookkeeping are the primitive's. This layer adds the console skin:\nhairline separation, mono summary rows on the control ladder, and a height\ntransition that respects `prefers-reduced-motion`.",
+  "props": [],
+  "typeReferences": [],
+  "subcomponents": [
+    "Root",
+    "Item",
+    "Header",
+    "Trigger",
+    "Panel"
+  ],
+  "parts": [
+    {
+      "name": "Root",
+      "usage": "Accordion.Root",
+      "description": "Groups the sections and owns which of them are open.",
+      "props": [
+        {
+          "name": "className",
+          "type": "string",
+          "required": false,
+          "defaultValue": null,
+          "description": "Extra classes for the accordion frame."
+        }
+      ],
+      "typeReferences": [
+        "Omit<BaseAccordion.Root.Props, \"className\">"
+      ]
+    },
+    {
+      "name": "Item",
+      "usage": "Accordion.Item",
+      "description": "One section.\n\nSeparation is a hairline the section draws above itself, dropped on the first\none — so a stack shows rules *between* sections and none against the rim of\nwhatever contains them. Same rule as `Row`, for the same reason.",
+      "props": [
+        {
+          "name": "className",
+          "type": "string",
+          "required": false,
+          "defaultValue": null,
+          "description": "Extra classes for the section."
+        }
+      ],
+      "typeReferences": [
+        "Omit<BaseAccordion.Item.Props, \"className\">"
+      ]
+    },
+    {
+      "name": "Header",
+      "usage": "Accordion.Header",
+      "description": "The heading that labels a section's panel. An `<h3>` with no type of its own.",
+      "props": [
+        {
+          "name": "className",
+          "type": "string",
+          "required": false,
+          "defaultValue": null,
+          "description": "Extra classes for the heading."
+        }
+      ],
+      "typeReferences": [
+        "Omit<BaseAccordion.Header.Props, \"className\">"
+      ]
+    },
+    {
+      "name": "Trigger",
+      "usage": "Accordion.Trigger",
+      "description": "The summary row that opens a section.\n\nA mono row on the control ladder, padded to the same gutters as a `Row`, with\na caret that rotates off the trigger's own `data-panel-open` — nothing in\nReact has to know the section is open for the arrow to turn.",
+      "props": [
+        {
+          "name": "className",
+          "type": "string",
+          "required": false,
+          "defaultValue": null,
+          "description": "Extra classes for the summary row."
+        }
+      ],
+      "typeReferences": [
+        "Omit<BaseAccordion.Trigger.Props, \"className\">"
+      ]
+    },
+    {
+      "name": "Panel",
+      "usage": "Accordion.Panel",
+      "description": "A section's body.\n\nHeight is animated from `--accordion-panel-height`, which Base UI measures.\nThe animating element carries no padding — padding is part of the box height,\nso it would be counted into the `0 → measured` transition and make the panel\njump at both ends — hence the inner body element.",
+      "props": [
+        {
+          "name": "className",
+          "type": "string",
+          "required": false,
+          "defaultValue": null,
+          "description": "Extra classes for the animating box. Padding belongs on `bodyClassName`."
+        },
+        {
+          "name": "bodyClassName",
+          "type": "string",
+          "required": false,
+          "defaultValue": null,
+          "description": "Extra classes for the padded body inside it."
+        }
+      ],
+      "typeReferences": [
+        "Omit<BaseAccordion.Panel.Props, \"className\">"
+      ]
+    }
+  ],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-accent",
+    "--cue-border",
+    "--cue-control-md",
+    "--cue-fg",
+    "--cue-fg-muted",
+    "--cue-fg-subtle",
+    "--cue-font-mono",
+    "--cue-icon-sm",
+    "--cue-pad-row-x",
+    "--cue-space-1",
+    "--cue-space-3",
+    "--cue-space-4",
+    "--cue-text-ui"
+  ],
+  "summary": "A stack of sections, one (or several) open at a time.",
+  "examples": [
+    {
+      "title": "Usage",
+      "code": "<Accordion.Root>\n  <Accordion.Item value=\"routing\">\n    <Accordion.Header><Accordion.Trigger>routing</Accordion.Trigger></Accordion.Header>\n    <Accordion.Panel>…</Accordion.Panel>\n  </Accordion.Item>\n</Accordion.Root>\n<Accordion.Root multiple defaultValue={[\"routing\"]}>…</Accordion.Root>",
+      "language": "tsx"
+    }
+  ],
+  "status": "todo-docs",
+  "url": "/docs/components/accordion",
+  "mdUrl": "/docs/components/accordion.md",
+  "jsonUrl": "/r/components/accordion.json",
+  "specimens": [
+    {
+      "title": "Accordion",
+      "group": "layout",
+      "components": [
+        "Accordion"
+      ],
+      "code": "<Accordion.Root className=\"w-full max-w-[36rem]\" defaultValue={[\"patch\"]}>\n  <Accordion.Item value=\"patch\">\n    <Accordion.Header>\n      <Accordion.Trigger>Patch</Accordion.Trigger>\n    </Accordion.Header>\n    <Accordion.Panel>48 fixtures across 4 universes.</Accordion.Panel>\n  </Accordion.Item>\n  <Accordion.Item value=\"cues\">\n    <Accordion.Header>\n      <Accordion.Trigger>Cues</Accordion.Trigger>\n    </Accordion.Header>\n    <Accordion.Panel>12 cues, last edited 4 minutes ago.</Accordion.Panel>\n  </Accordion.Item>\n  <Accordion.Item value=\"network\" disabled>\n    <Accordion.Header>\n      <Accordion.Trigger>Network</Accordion.Trigger>\n    </Accordion.Header>\n    <Accordion.Panel>Art-Net on 10.0.0.42.</Accordion.Panel>\n  </Accordion.Item>\n</Accordion.Root>",
+      "note": "Hairline-separated items with mono summary rows. Several can be open at once.",
+      "interaction": "the whole header row is the trigger; the panel animates its height and stills under prefers-reduced-motion."
+    }
+  ],
+  "todo": true
+}

package/manifest/components/activity-graph.json

@@ -0,0 +1,88 @@
+{
+  "name": "ActivityGraph",
+  "slug": "activity-graph",
+  "group": "elements",
+  "importPath": "@cueplusplus/ui/elements",
+  "peerDependencies": [
+    "heat-graph"
+  ],
+  "clientOnly": true,
+  "description": "A half-year of runs as a calendar of cells, dense where the work was.",
+  "props": [
+    {
+      "name": "data",
+      "type": "readonly DataPoint[]",
+      "required": true,
+      "defaultValue": null,
+      "description": "Date and count pairs from the heat-graph package. Levels are classified for you;\ngaps are filled as empty cells."
+    },
+    {
+      "name": "start",
+      "type": "string | Date",
+      "required": true,
+      "defaultValue": null,
+      "description": "First day of the window. Pass it explicitly: left unset, heat-graph draws a full\nyear ending today, which will not match your data."
+    },
+    {
+      "name": "end",
+      "type": "string | Date",
+      "required": true,
+      "defaultValue": null,
+      "description": "Last day of the window. Cells are fixed-size, so a long window scrolls\nhorizontally rather than shrinking."
+    },
+    {
+      "name": "title",
+      "type": "string",
+      "required": true,
+      "defaultValue": null,
+      "description": "What is being counted."
+    },
+    {
+      "name": "total",
+      "type": "string",
+      "required": true,
+      "defaultValue": null,
+      "description": "Pre-formatted summary shown opposite the title."
+    }
+  ],
+  "typeReferences": [
+    "Omit<\n  ComponentProps<\"div\">,\n  \"children\" | \"data\" | \"start\" | \"end\" | \"title\" | \"total\"\n> & {\n  /**\n   * Date and count pairs from the heat-graph package. Levels are classified for you;\n   * gaps are filled as empty cells.\n   */\n  data: readonly HeatGraph.DataPoint[];\n  /**\n   * First day of the window. Pass it explicitly: left unset, heat-graph draws a full\n   * year ending today, which will not match your data.\n   */\n  start: string | Date;\n  /**\n   * Last day of the window. Cells are fixed-size, so a long window scrolls\n   * horizontally rather than shrinking.\n   */\n  end: string | Date;\n  /** What is being counted. */\n  title: string;\n  /** Pre-formatted summary shown opposite the title. */\n  total: string;\n}"
+  ],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-fg-subtle",
+    "--cue-radius-control",
+    "--cue-radius-overlay",
+    "--cue-stream",
+    "--cue-surface-2",
+    "--cue-text-body"
+  ],
+  "summary": "A half-year of runs as a calendar of cells, dense where the work was.",
+  "examples": [
+    {
+      "title": "Usage",
+      "code": "import { ActivityGraph } from \"@cueplusplus/ui/elements\";\n\n<ActivityGraph\n  data={data}\n  start={start}\n  end={end}\n  title=\"Agent runs\"\n  total=\"1,204 in 6 months\"\n/>",
+      "language": "tsx"
+    }
+  ],
+  "status": "todo-docs",
+  "url": "/docs/components/activity-graph",
+  "mdUrl": "/docs/components/activity-graph.md",
+  "jsonUrl": "/r/components/activity-graph.json",
+  "specimens": [
+    {
+      "title": "ActivityGraph",
+      "group": "elements-agents",
+      "components": [
+        "ActivityGraph"
+      ],
+      "code": "<Specimens>\n  <Specimen label=\"six months\" wide>\n    <ActivityGraph\n      data={RUN_DAYS}\n      start=\"2026-02-01\"\n      end=\"2026-08-21\"\n      title=\"Agent runs\"\n      total=\"1,204 in 6 months\"\n    />\n  </Specimen>\n  <Specimen label=\"a fortnight\" wide>\n    <ActivityGraph\n      data={RECENT_DAYS}\n      start={RECENT_DAYS[0]!.date}\n      end={RECENT_DAYS[RECENT_DAYS.length - 1]!.date}\n      title=\"Agent runs\"\n      total=\"63 in 14 days\"\n    />\n  </Specimen>\n</Specimens>",
+      "note": "Half a year of runs as a calendar of cells, dense where the work was. It is the one element in the family with a runtime dependency of its own — `heat-graph`, an optional peer — which does the calendar arithmetic and the levelling; everything you can see here is cue's, from the five-step ramp in the streaming hue down to the legend. Cells are a fixed size, so a long window scrolls sideways rather than shrinking into a smudge.",
+      "interaction": "none. The five legend swatches are `aria-hidden` and sit between the words less and more, which is what carries the scale."
+    }
+  ],
+  "todo": true
+}