@cueplusplus/ui 0.18.2 → 0.19.0

package/dist/system/_style-label-ink.js

@@ -12,9 +12,16 @@
 * once, which is why the name exists.
 *
 * **Optional, so each reader keeps its own fallback** (spec §3.0, F-3): under
-* no set, `console` and every set that declines the name this resolves to
-* exactly what `text-fg-muted` or `text-fg-subtle` resolved to, at the label
-* itself — so a nested theme island still repaints it.
+* no set, `console` and every set that declines the name this resolves at the
+* label itself, so a nested theme island still repaints it.
+*
+* **Both fall back to `fg-muted`** (structural Looks, spec 2026-10-02 §4.1).
+* A label names what sits beside it, so it is held to 4.5:1 like body text,
+* and the quieter `fg-subtle` the second reader spent is a hint's ink, not a
+* label's: under Classic it drew stat labels, the logo strip's caption and a
+* sidebar section's label at 2.4:1 in dark and 3.1:1 in light, on the
+* rendered sweep. `LABEL_INK_SUBTLE` keeps its name so the readers that spent
+* `text-fg-subtle` stay findable.
 *
 * **Its own module**, for the reason `_style-control-face.ts` gives: one
 * token per file, so `@repo/docgen` credits exactly the components that read
@@ -23,7 +30,7 @@
 * @internal Not part of the public API.
 */
 const LABEL_INK = "text-[color:var(--cue-style-label-ink,var(--cue-fg-muted))]";
-/** @see LABEL_INK — for a reader that spent `text-fg-subtle` before this existed. */
-const LABEL_INK_SUBTLE = "text-[color:var(--cue-style-label-ink,var(--cue-fg-subtle))]";
+/** @see LABEL_INK — for a reader that spent `text-fg-subtle` before this existed; it falls back to `fg-muted` too. */
+const LABEL_INK_SUBTLE = LABEL_INK;
 //#endregion
 export { LABEL_INK, LABEL_INK_SUBTLE };

package/dist/system/_style-menu.js

@@ -25,7 +25,7 @@ const MENU_ITEM_INK = "text-[color:var(--cue-style-quiet-ink,var(--cue-fg-muted)
 * rows read the same name with a `0px` fallback (`_style-option.ts`), since
 * they drew no corner.
 */
-const MENU_ITEM_RADIUS = "rounded-[var(--cue-style-menu-item-radius,calc(var(--cue-radius-control)*var(--cue-radius-scale)))]";
+const MENU_ITEM_RADIUS = "rounded-[var(--cue-style-menu-item-radius,calc(var(--cue-style-control-radius,var(--cue-radius-control))*var(--cue-radius-scale)))]";
 /**
 * A menu popup's minimum width (round 6, spec §11, lane R6.P:
 * `style-menu-min-width`), falling back to the `10rem` it drew. coss.com/ui's

package/dist/system/_style-page-title.js

@@ -43,6 +43,6 @@
 *
 * @internal Not part of the public API.
 */
-const PAGE_TITLE_VOICE = "font-[family-name:var(--cue-style-page-title-face,var(--cue-font-mono))] text-[length:var(--cue-style-page-title-size,var(--cue-text-title))] font-[number:var(--cue-style-page-title-weight,500)] tracking-[var(--cue-style-page-title-tracking,normal)] leading-[var(--cue-style-page-title-leading,inherit)] [font-variation-settings:var(--cue-style-display-variation,normal)] text-[color:var(--cue-style-heading-ink,var(--cue-fg))] [overflow-wrap:anywhere]";
+const PAGE_TITLE_VOICE = "font-[family-name:var(--cue-style-page-title-face,var(--cue-font-mono))] text-[length:var(--cue-style-page-title-size,var(--cue-text-title))] font-[number:var(--cue-style-page-title-weight,500)] tracking-[var(--cue-style-page-title-tracking,normal)] leading-[var(--cue-style-page-title-leading,inherit)] [font-variation-settings:var(--cue-style-display-variation,normal)] text-[color:var(--cue-style-heading-ink,var(--cue-fg))] [text-transform:var(--cue-style-display-case,none)] [overflow-wrap:anywhere]";
 //#endregion
 export { PAGE_TITLE_VOICE };

package/dist/system/_style-segmented-control.js

@@ -72,7 +72,7 @@ const SEGMENTED_TRACK = "bg-[color:var(--cue-style-segment-track,var(--cue-surfa
 /** The overflow chevrons' ground: the track's colour over an opaque `surface-1`. */
 const SEGMENTED_CHEVRON_GROUND = "bg-surface-1 bg-[image:linear-gradient(var(--cue-style-segment-track,transparent),var(--cue-style-segment-track,transparent))]";
 /** A segment's corners, nested inside the track's inset. */
-const SEGMENT_RADIUS = "rounded-[calc(var(--cue-radius-control)*var(--cue-radius-scale)-var(--cue-style-segment-inset,0px))]";
+const SEGMENT_RADIUS = "rounded-[calc(var(--cue-style-control-radius,var(--cue-radius-control))*var(--cue-radius-scale)-var(--cue-style-segment-inset,0px))]";
 /** `SegmentedControl`'s pressed segment. */
 const SEGMENT_PRESSED = "data-[pressed]:bg-[color:var(--cue-style-segment-ground,var(--cue-accent-soft))] data-[pressed]:text-[color:var(--cue-style-segment-ink,var(--cue-accent))] [:where(&[data-pressed])]:font-[number:var(--cue-style-segment-weight,400)] [:where(&[data-pressed])]:shadow-[inset_0_0_0_var(--cue-border-width)_var(--cue-style-segment-edge,transparent),0_calc(2px*var(--cue-paint-shadow-scale))_calc(4px*var(--cue-paint-shadow-scale))_var(--cue-paint-rest-shade,transparent)]";
 /**

package/dist/system/_style-skeleton.js

@@ -10,6 +10,6 @@
 *
 * @internal Not part of the public API.
 */
-const SKELETON_RADIUS = "rounded-[var(--cue-style-skeleton-radius,calc(var(--cue-radius-control)*var(--cue-radius-scale)))]";
+const SKELETON_RADIUS = "rounded-[var(--cue-style-skeleton-radius,calc(var(--cue-style-control-radius,var(--cue-radius-control))*var(--cue-radius-scale)))]";
 //#endregion
 export { SKELETON_RADIUS };

package/dist/system/_style-tab.js

@@ -60,7 +60,7 @@ const TAB_TRACK = "bg-[color:var(--cue-style-segment-track,transparent)] p-[var(
 * Porcelain's idle tabs are 500 too — falling back to 400. A caller's
 * `font-*` class on a tab replaces it through `tailwind-merge`.
 */
-const TAB_SHAPE = "rounded-t-[calc(var(--cue-style-tab-radius,calc(var(--cue-radius-control)*var(--cue-radius-scale)+var(--cue-style-segment-inset,0px)))-var(--cue-style-segment-inset,0px))] rounded-b-[calc(var(--cue-style-tab-radius,var(--cue-style-segment-inset,0px))-var(--cue-style-segment-inset,0px))] font-[number:var(--cue-style-segment-weight,400)]";
+const TAB_SHAPE = "rounded-t-[calc(var(--cue-style-tab-radius,calc(var(--cue-style-control-radius,var(--cue-radius-control))*var(--cue-radius-scale)+var(--cue-style-segment-inset,0px)))-var(--cue-style-segment-inset,0px))] rounded-b-[calc(var(--cue-style-tab-radius,var(--cue-style-segment-inset,0px))-var(--cue-style-segment-inset,0px))] font-[number:var(--cue-style-segment-weight,400)]";
 /** The list's bottom rule, as a width. */
 const TAB_RULE = "border-b-[length:var(--cue-style-tab-rule,1px)]";
 /** The active tab's underline ink, on its `::after`. */

package/dist/system/font-scope.d.ts

@@ -0,0 +1,38 @@
+import * as React from "react";
+import { FontName } from "@cueplusplus/theme-base";
+//#region src/system/font-scope.d.ts
+interface FontScopeProps extends Omit<React.ComponentPropsWithoutRef<"div">, "children"> {
+  /** The pairing this subtree is set in. */
+  font: FontName;
+  /** What is set in it. Every overlay opened inside it is set in it too. */
+  children: React.ReactNode;
+}
+/**
+ * A subtree set in another type pairing — and everything it opens with it.
+ *
+ * `ThemeProvider`'s `font` is root-level only: the pairing has no island, and a
+ * nested provider forwards it to the root. `data-font` on a `<div>` is enough
+ * for the subtree's own tokens, and nothing more: a dialog or menu opened inside
+ * it mounts on `<body>`, stamped from the root's pairing, and unclassed text
+ * keeps the family `<body>` computed, because a computed family does not follow
+ * a token. `FontScope` does all three: it stamps `data-font`, asks for the
+ * family again on its own element, and republishes the pairing so every portal
+ * opened inside it is stamped with it and asks for the family too. It is what
+ * `Preview` does for a stage that names a pairing, as a component of its own.
+ *
+ * It never calls `setFont`, so the root's pairing — and the visitor's stored
+ * one — never moves. A gallery frame that draws a page in a Look of its own is
+ * the case it exists for (structural Looks, spec 2026-10-02 §6.2).
+ *
+ * The set and pack in force around it are restated beside `data-font`, once it
+ * may restate, because their names read the pairing and a custom property's
+ * `var()`s are substituted where it is declared.
+ *
+ * @example
+ * <FontScope font="inter-source">
+ *   <Dialog.Root>…</Dialog.Root>
+ * </FontScope>
+ */
+declare const FontScope: React.ForwardRefExoticComponent<FontScopeProps & React.RefAttributes<HTMLDivElement>>;
+//#endregion
+export { FontScope, FontScopeProps };

package/dist/system/font-scope.js

@@ -0,0 +1,69 @@
+"use client";
+import { cn } from "../lib/cn.js";
+import { useRead } from "./published.js";
+import { DensityContext, PaintContext, StyleSetContext, useFollowedAxes, useRestateReady } from "./density.js";
+import { ThemeContext } from "./theme-provider.js";
+import { StageScope, stageAttributes } from "./_stage-scope.js";
+import * as React from "react";
+import { jsx } from "react/jsx-runtime";
+//#region src/system/font-scope.tsx
+/**
+* A subtree set in another type pairing — and everything it opens with it.
+*
+* `ThemeProvider`'s `font` is root-level only: the pairing has no island, and a
+* nested provider forwards it to the root. `data-font` on a `<div>` is enough
+* for the subtree's own tokens, and nothing more: a dialog or menu opened inside
+* it mounts on `<body>`, stamped from the root's pairing, and unclassed text
+* keeps the family `<body>` computed, because a computed family does not follow
+* a token. `FontScope` does all three: it stamps `data-font`, asks for the
+* family again on its own element, and republishes the pairing so every portal
+* opened inside it is stamped with it and asks for the family too. It is what
+* `Preview` does for a stage that names a pairing, as a component of its own.
+*
+* It never calls `setFont`, so the root's pairing — and the visitor's stored
+* one — never moves. A gallery frame that draws a page in a Look of its own is
+* the case it exists for (structural Looks, spec 2026-10-02 §6.2).
+*
+* The set and pack in force around it are restated beside `data-font`, once it
+* may restate, because their names read the pairing and a custom property's
+* `var()`s are substituted where it is declared.
+*
+* @example
+* <FontScope font="inter-source">
+*   <Dialog.Root>…</Dialog.Root>
+* </FontScope>
+*/
+const FontScope = React.forwardRef(function FontScope({ font, className, children, ...elementProps }, ref) {
+	const outer = useRead(ThemeContext);
+	const aroundStyleSet = useRead(StyleSetContext);
+	const aroundPaint = useRead(PaintContext);
+	const aroundDensity = useRead(DensityContext);
+	const restateReady = useRestateReady(aroundStyleSet !== null || aroundPaint !== null);
+	const followed = useFollowedAxes({
+		theme: false,
+		mode: false,
+		density: false
+	});
+	const attributes = stageAttributes({ font }, outer, restateReady ? {
+		styleSet: aroundStyleSet,
+		paint: aroundPaint
+	} : null, aroundDensity, followed);
+	return /* @__PURE__ */ jsx("div", {
+		ref,
+		"data-slot": "font-scope",
+		...elementProps,
+		...attributes,
+		className: cn("font-sans", className),
+		children: /* @__PURE__ */ jsx(StageScope, {
+			theme: void 0,
+			mode: void 0,
+			density: void 0,
+			font,
+			styleSet: void 0,
+			paint: void 0,
+			children
+		})
+	});
+});
+//#endregion
+export { FontScope };

package/dist/system/index.d.ts

@@ -7,6 +7,8 @@ import { ThemeRegistry } from "./vocabulary.js";
 import { useDensities, useFonts, useThemes } from "./theme-registry.js";
 import { ControlSize, useControlHeight, useDensity } from "./use-density.js";
 import { useTheme } from "./use-theme.js";
+import { StillProvider, StillProviderProps, useStill } from "./still.js";
+import { FontScope, FontScopeProps } from "./font-scope.js";
 import { DEFAULT_PAINT, DEFAULT_STYLE_SET, PAINTS, Paint, STYLE_SETS, StyleSet } from "@cueplusplus/tokens";
 import { Density as DensityLevel, DensityEntry, FontEntry, FontName, Mode, ThemeManifest, ThemeName } from "@cueplusplus/theme-base";
-export { type ControlSize, CuePortalFrame, type CuePortalFrameProps, DEFAULT_PAINT, DEFAULT_STORAGE_KEY, DEFAULT_STYLE_SET, Density, type DensityEntry, type DensityLevel, type DensityProps, type FontEntry, type FontFamilies, type FontName, type Mode, PAINTS, type Paint, type PersistedPreferences, type PrepaintDefaults, type PrepaintOptions, type ResolvedMode, STYLE_SETS, type StyleSet, type ThemeContextValue, type ThemeManifest, type ThemeName, ThemeProvider, type ThemeProviderProps, type ThemeRegistry, type TokenOverrides, isSafeTokenValue, prepaintScript, useControlHeight, useCuePortalProps, useDensities, useDensity, useFonts, useTheme, useThemes };
+export { type ControlSize, CuePortalFrame, type CuePortalFrameProps, DEFAULT_PAINT, DEFAULT_STORAGE_KEY, DEFAULT_STYLE_SET, Density, type DensityEntry, type DensityLevel, type DensityProps, type FontEntry, type FontFamilies, type FontName, FontScope, type FontScopeProps, type Mode, PAINTS, type Paint, type PersistedPreferences, type PrepaintDefaults, type PrepaintOptions, type ResolvedMode, STYLE_SETS, StillProvider, type StillProviderProps, type StyleSet, type ThemeContextValue, type ThemeManifest, type ThemeName, ThemeProvider, type ThemeProviderProps, type ThemeRegistry, type TokenOverrides, isSafeTokenValue, prepaintScript, useControlHeight, useCuePortalProps, useDensities, useDensity, useFonts, useStill, useTheme, useThemes };

package/dist/system/index.js

@@ -1,3 +1,4 @@
+import { StillProvider, useStill } from "./still.js";
 import { Density } from "./density.js";
 import { isSafeTokenValue } from "./overrides.js";
 import { DEFAULT_STORAGE_KEY, prepaintScript } from "./prepaint.js";
@@ -6,5 +7,6 @@ import { ThemeProvider } from "./theme-provider.js";
 import { CuePortalFrame, useCuePortalProps } from "./portal.js";
 import { useControlHeight, useDensity } from "./use-density.js";
 import { useTheme } from "./use-theme.js";
+import { FontScope } from "./font-scope.js";
 import { DEFAULT_PAINT, DEFAULT_STYLE_SET, PAINTS, STYLE_SETS } from "@cueplusplus/tokens";
-export { CuePortalFrame, DEFAULT_PAINT, DEFAULT_STORAGE_KEY, DEFAULT_STYLE_SET, Density, PAINTS, STYLE_SETS, ThemeProvider, isSafeTokenValue, prepaintScript, useControlHeight, useCuePortalProps, useDensities, useDensity, useFonts, useTheme, useThemes };
+export { CuePortalFrame, DEFAULT_PAINT, DEFAULT_STORAGE_KEY, DEFAULT_STYLE_SET, Density, FontScope, PAINTS, STYLE_SETS, StillProvider, ThemeProvider, isSafeTokenValue, prepaintScript, useControlHeight, useCuePortalProps, useDensities, useDensity, useFonts, useStill, useTheme, useThemes };

package/dist/system/portal.js

@@ -4,6 +4,7 @@ import { AgentSkinContext } from "./agent-skin.js";
 import { useRead } from "./published.js";
 import { DensityContext, PaintContext, StyleSetContext } from "./density.js";
 import { OverridesContext } from "./overrides.js";
+import { ScopedPairingContext } from "./_scoped-pairing.js";
 import { FontFamiliesContext, FontScaleContext, PairingSeedContext, ThemeContext } from "./theme-provider.js";
 import * as React from "react";
 import { jsx } from "react/jsx-runtime";
@@ -33,6 +34,7 @@ function usePortalStamp() {
 	const skin = React.useContext(AgentSkinContext);
 	const styleSet = useRead(StyleSetContext);
 	const paint = useRead(PaintContext);
+	const scopedPairing = React.useContext(ScopedPairingContext);
 	return {
 		theme: theme?.theme ?? DEFAULT_THEME,
 		density: island ?? theme?.density ?? "compact",
@@ -44,7 +46,8 @@ function usePortalStamp() {
 		skin: skin?.skin ?? null,
 		fidelity: skin?.fidelity ?? null,
 		styleSet,
-		paint
+		paint,
+		scopedPairing
 	};
 }
 /**
@@ -155,6 +158,8 @@ function applyStamp(element, stamp) {
 	else element.setAttribute("data-cue-fidelity", stamp.fidelity);
 	const overrides = stamp.overrides ?? {};
 	for (const property of stampedOverrides.get(element) ?? []) if (!(property in overrides)) element.style.removeProperty(property);
+	if (stamp.scopedPairing) element.style.setProperty("font-family", "var(--cue-font-sans)");
+	else element.style.removeProperty("font-family");
 	if (stamp.fontScale === null) element.style.removeProperty(FONT_SCALE_PROPERTY);
 	else element.style.setProperty(FONT_SCALE_PROPERTY, String(stamp.fontScale));
 	setOptionalProperty(element, FONT_SANS_PROPERTY, stamp.fontFamilies?.sans);
@@ -186,6 +191,7 @@ function CuePortalFrame({ children, className, style }) {
 	const stamp = usePortalStamp();
 	const frameStyle = {
 		display: "contents",
+		...stamp.scopedPairing ? { fontFamily: "var(--cue-font-sans)" } : null,
 		...stamp.fontScale === null ? null : { [FONT_SCALE_PROPERTY]: stamp.fontScale },
 		...stamp.fontFamilies?.sans === void 0 ? null : { [FONT_SANS_PROPERTY]: stamp.fontFamilies.sans },
 		...stamp.fontFamilies?.mono === void 0 ? null : { [FONT_MONO_PROPERTY]: stamp.fontFamilies.mono },

package/dist/system/still.d.ts

@@ -0,0 +1,32 @@
+import * as React from "react";
+//#region src/system/still.d.ts
+interface StillProviderProps {
+  /** `true` holds everything under it still. Nested providers can only add stillness, never remove it. */
+  still: boolean;
+  /** What it holds still. Optional, as `ThemeProvider`'s is: an empty provider renders nothing. */
+  children?: React.ReactNode;
+}
+/**
+ * Hold a subtree still (see {@link useStill}). A gallery frame mounts one with
+ * `still` when it is a thumbnail.
+ *
+ * @example
+ * <StillProvider still><Page /></StillProvider>
+ */
+declare function StillProvider({ still, children }: StillProviderProps): React.JSX.Element;
+/**
+ * `true` under a still {@link StillProvider}, or while the reader prefers reduced
+ * motion. Live: it changes when the preference does. `false` on the server, where
+ * nothing animates anyway.
+ *
+ * @example
+ * const still = useStill();
+ * React.useEffect(() => {
+ *   if (still) return;
+ *   const frame = requestAnimationFrame(step);
+ *   return () => cancelAnimationFrame(frame);
+ * }, [still]);
+ */
+declare function useStill(): boolean;
+//#endregion
+export { StillProvider, StillProviderProps, useStill };

package/dist/system/still.js

@@ -0,0 +1,47 @@
+"use client";
+import { usePrefersReducedMotion } from "../instruments/_motion.js";
+import * as React from "react";
+import { jsx } from "react/jsx-runtime";
+//#region src/system/still.tsx
+/**
+* Whether this subtree must hold still: no motif animates, no replay plays, no
+* live readout loops. A gallery thumbnail is the case it exists for (spec
+* 2026-10-02 §6.2) — a scrolled gallery of twenty live pages must cost nothing at
+* rest — and a reader's `prefers-reduced-motion` is folded in, so a consumer asks
+* one question.
+*/
+const StillContext = React.createContext(false);
+/**
+* Hold a subtree still (see {@link useStill}). A gallery frame mounts one with
+* `still` when it is a thumbnail.
+*
+* @example
+* <StillProvider still><Page /></StillProvider>
+*/
+function StillProvider({ still, children }) {
+	const outer = React.useContext(StillContext);
+	return /* @__PURE__ */ jsx(StillContext.Provider, {
+		value: outer || still,
+		children
+	});
+}
+/**
+* `true` under a still {@link StillProvider}, or while the reader prefers reduced
+* motion. Live: it changes when the preference does. `false` on the server, where
+* nothing animates anyway.
+*
+* @example
+* const still = useStill();
+* React.useEffect(() => {
+*   if (still) return;
+*   const frame = requestAnimationFrame(step);
+*   return () => cancelAnimationFrame(frame);
+* }, [still]);
+*/
+function useStill() {
+	const still = React.useContext(StillContext);
+	const reduced = usePrefersReducedMotion();
+	return still || reduced;
+}
+//#endregion
+export { StillProvider, useStill };

package/manifest/components/alert-dialog.json

@@ -171,7 +171,6 @@
     "--cue-control-sm",
     "--cue-fg",
     "--cue-fg-muted",
-    "--cue-fg-subtle",
     "--cue-font-mono",
     "--cue-leading-ui",
     "--cue-paint-rim-width",
@@ -200,6 +199,7 @@
     "--cue-style-body-size",
     "--cue-style-body-weight",
     "--cue-style-control-face",
+    "--cue-style-control-radius",
     "--cue-style-dialog-radius",
     "--cue-style-display-variation",
     "--cue-style-group-label-ink",

package/manifest/components/announcement-bar.json

@@ -0,0 +1,82 @@
+{
+  "name": "AnnouncementBar",
+  "slug": "announcement-bar",
+  "group": "chrome",
+  "importPath": "@cueplusplus/ui",
+  "peerDependencies": [],
+  "clientOnly": false,
+  "description": "One line across the top of a page, and one link: a launch, a change, a date.\n\nFilled in the accent, centred, and as short as its line. It is not a\nnotification: it says the same thing to every reader and cannot be dismissed,\nso use `Toast` or `Alert` for anything that is about the reader.\n\nStatic markup — no `\"use client\"`.",
+  "props": [
+    {
+      "name": "children",
+      "type": "ReactNode",
+      "required": true,
+      "defaultValue": null,
+      "description": "The one line.",
+      "control": {
+        "kind": "node",
+        "fixture": "children.text"
+      }
+    },
+    {
+      "name": "action",
+      "type": "AnnouncementBarAction",
+      "required": false,
+      "defaultValue": null,
+      "description": "One link, read as the bar's action.",
+      "control": {
+        "kind": "opaque"
+      }
+    }
+  ],
+  "typeReferences": [
+    "React.ComponentPropsWithoutRef<\"div\">"
+  ],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-accent-fill",
+    "--cue-accent-fill-fg",
+    "--cue-space-2",
+    "--cue-space-3",
+    "--cue-space-5",
+    "--cue-text-ui"
+  ],
+  "summary": "One line across the top of a page, and one link: a launch, a change, a date.",
+  "examples": [
+    {
+      "title": "Usage",
+      "code": "<AnnouncementBar action={{ label: \"Learn more\", href: \"/changelog\" }}>Plans for teams are here.</AnnouncementBar>",
+      "language": "tsx"
+    }
+  ],
+  "status": "stable",
+  "url": "/docs/components/announcement-bar",
+  "mdUrl": "/docs/components/announcement-bar.md",
+  "jsonUrl": "/r/components/announcement-bar.json",
+  "whenToUse": [
+    "A product page's launch or pricing news, shown to every reader.",
+    "Above a `SiteNav`-style `AppBar` on a marketing page."
+  ],
+  "whenNotToUse": [
+    "Anything about the reader or their account. Use `Alert` or `Toast`.",
+    "Something the reader must dismiss or act on. This bar cannot be dismissed."
+  ],
+  "commonMistakes": [
+    "Putting more than one link in it. It is one line and one action."
+  ],
+  "specimens": [
+    {
+      "title": "AnnouncementBar",
+      "group": "chrome",
+      "components": [
+        "AnnouncementBar"
+      ],
+      "code": "<AnnouncementBar action={{ label: \"Read the release notes\", href: \"#\" }}>\n  The structural Looks are here.\n</AnnouncementBar>",
+      "note": "One line and one link, above the page's own chrome.",
+      "interaction": "the link is an ordinary anchor."
+    }
+  ]
+}

package/manifest/components/app-bar.json

@@ -87,8 +87,8 @@
           "name": "align",
           "type": "\"center\" | \"end\" | \"start\"",
           "required": false,
-          "defaultValue": "end",
-          "description": "Where the links sit when they are narrower than the space. Defaults to `\"end\"`.",
+          "defaultValue": null,
+          "description": "Where the links sit when they are narrower than the space. Omitted, the style\nset's `style-nav-align` decides, and without one it is `\"end\"`.",
           "control": {
             "kind": "enum",
             "members": [
@@ -290,6 +290,7 @@
     "--cue-style-chrome-rule-style",
     "--cue-style-focus-width",
     "--cue-style-hover-ink",
+    "--cue-style-nav-align",
     "--cue-style-nav-case",
     "--cue-style-nav-face",
     "--cue-style-nav-hover-ground",

package/manifest/components/app-shell.json

@@ -425,6 +425,9 @@
     "--cue-space-3",
     "--cue-space-4",
     "--cue-space-5",
+    "--cue-style-page-ground-image",
+    "--cue-style-page-ground-repeat",
+    "--cue-style-page-ground-tile",
     "--cue-surface-1",
     "--cue-text-label"
   ],

package/manifest/components/autocomplete.json

@@ -268,6 +268,7 @@
     "--cue-style-chip-size",
     "--cue-style-chip-tracking",
     "--cue-style-control-face",
+    "--cue-style-control-radius",
     "--cue-style-control-step-size",
     "--cue-style-disabled-edge",
     "--cue-style-disabled-fill",

package/manifest/components/band.json

@@ -5,7 +5,7 @@
   "importPath": "@cueplusplus/ui",
   "peerDependencies": [],
   "clientOnly": false,
-  "description": "A full-bleed horizontal section: the page's rhythm, its separation, and a\ncolumn at the measure.\n\nThis is `Footer`'s recipe with the footer taken out of it — a `w-full`\nelement, a rule running edge to edge, and a centred `Container` inside so the\nline reaches the window while the words stop at the measure. `Footer` is\nbuilt on this rather than beside it; the recipe exists once.\n\nEvery dimension it spends belongs to the style axis, so the same markup\ncomposes differently under `[data-style]` without a prop changing: the\nvertical rhythm is `--cue-band-y` (one `--cue-space-7` with no set, doubled\nunder `editorial`, trebled under `marketing` and `graphite`), the column is\n`--cue-measure-prose` unless `width` names a fixed rung, and the rule and the\nground are `--cue-band-rule` and `--cue-band-ground`. Read `separation`'s own\ndocumentation before choosing one, because two of the four can come out to\nnothing and they do not vanish symmetrically: `--cue-band-ground` is\n`transparent` on `:root` and on every set but `marketing` and `kiln`, so a\n`\"ground\"` paints nothing on most pages, while `--cue-band-rule` is `0px`\nunder those two alone. Both are deliberate and nothing warns.\n\n**Two substitution boundaries, because `--cue-band-y` is a `calc()` resolved\nat the element that declares it.** A `<Density>` island nested inside a\nstyled page moves every `--cue-space-*` and the band rhythm does **not**\nfollow it — the island inherits the rhythm already resolved above. Restate\nthe set on the island (`<Density density=\"compact\" styleSet=\"editorial\">`) to\nre-resolve it against that island's rung. Likewise a hand-stamped\n`[data-theme]` element under a marketing page paints the **outer** theme's\n`--cue-surface-1` through an already-resolved `--cue-band-ground`, and its\nrule in the outer theme's border. The library's own theme islands do not: a\nnested `ThemeProvider` that names a theme or a mode, and a `Preview` stage\nwith a theme, a mode or a pairing, restate the set in force beside it, so a\nband inside one paints that island's ground and rule.\n\nIt renders a `<section>`, which is not a landmark until it has an accessible\nname — so a band with a heading should carry `aria-labelledby` pointing at\nit, and a band without one costs the document nothing.\n\nStatic markup — no `\"use client\"`.",
+  "description": "A full-bleed horizontal section: the page's rhythm, its separation, and a\ncolumn at the measure.\n\nThis is `Footer`'s recipe with the footer taken out of it — a `w-full`\nelement, a rule running edge to edge, and a centred `Container` inside so the\nline reaches the window while the words stop at the measure. `Footer` is\nbuilt on this rather than beside it; the recipe exists once.\n\nEvery dimension it spends belongs to the style axis, so the same markup\ncomposes differently under `[data-style]` without a prop changing: the\nvertical rhythm is `--cue-band-y` (one `--cue-space-7` with no set, doubled\nunder `editorial`, trebled under `marketing` and `graphite`), the column is\n`--cue-measure-prose` unless `width` names a fixed rung, and the rule and the\nground are `--cue-band-rule` and `--cue-band-ground`. Read `separation`'s own\ndocumentation before choosing one, because two of the four can come out to\nnothing and they do not vanish symmetrically: `--cue-band-ground` is\n`transparent` on `:root` and on every set but `marketing` and `kiln`, so a\n`\"ground\"` paints nothing on most pages, while `--cue-band-rule` is `0px`\nunder those two and under `ledger` and `prism`, which separate bands by\nrhythm alone (and `prism`'s by a ground image, `style-band-ground-image`).\nBoth are deliberate and nothing warns.\n\n**Two substitution boundaries, because `--cue-band-y` is a `calc()` resolved\nat the element that declares it.** A `<Density>` island nested inside a\nstyled page moves every `--cue-space-*` and the band rhythm does **not**\nfollow it — the island inherits the rhythm already resolved above. Restate\nthe set on the island (`<Density density=\"compact\" styleSet=\"editorial\">`) to\nre-resolve it against that island's rung. Likewise a hand-stamped\n`[data-theme]` element under a marketing page paints the **outer** theme's\n`--cue-surface-1` through an already-resolved `--cue-band-ground`, and its\nrule in the outer theme's border. The library's own theme islands do not: a\nnested `ThemeProvider` that names a theme or a mode, and a `Preview` stage\nwith a theme, a mode or a pairing, restate the set in force beside it, so a\nband inside one paints that island's ground and rule.\n\nIt renders a `<section>`, which is not a landmark until it has an accessible\nname — so a band with a heading should carry `aria-labelledby` pointing at\nit, and a band without one costs the document nothing.\n\nStatic markup — no `\"use client\"`.",
   "props": [
     {
       "name": "separation",
@@ -85,6 +85,7 @@
     "--cue-paint-texture-blend",
     "--cue-paint-texture-opacity",
     "--cue-paint-texture-size",
+    "--cue-style-band-ground-image",
     "--cue-style-band-width"
   ],
   "summary": "A full-bleed horizontal section: a rule to the window's edge, a column at the measure.",

package/manifest/components/bento.json

@@ -27,9 +27,9 @@
           "control": {
             "kind": "enum",
             "members": [
-              4,
               2,
-              3
+              3,
+              4
             ],
             "min": 2,
             "max": 4
@@ -37,17 +37,17 @@
         },
         {
           "name": "rows",
-          "type": "4 | 1 | 2 | 3",
+          "type": "1 | 4 | 2 | 3",
           "required": false,
           "defaultValue": null,
           "description": "How many rows to declare from `sm` up.\n\nOnly worth setting where a tile spans rows: a `rowSpan` over implicit\ntracks sizes itself to the tile's own content, which is not a span.",
           "control": {
             "kind": "enum",
             "members": [
-              4,
               1,
               2,
-              3
+              3,
+              4
             ],
             "min": 1,
             "max": 4
@@ -65,7 +65,7 @@
         },
         {
           "name": "gap",
-          "type": "0 | 4 | 8 | 1 | 2 | 3 | 5 | 6 | 7",
+          "type": "0 | 1 | 4 | 8 | 2 | 3 | 5 | 6 | 7",
           "required": false,
           "defaultValue": "4",
           "description": "Which rung of the density space ladder to spend between tiles. Defaults to `4`.",
@@ -73,14 +73,14 @@
             "kind": "enum",
             "members": [
               0,
-              4,
-              8,
               1,
               2,
               3,
+              4,
               5,
               6,
-              7
+              7,
+              8
             ],
             "min": 0,
             "max": 8
@@ -109,17 +109,17 @@
       "props": [
         {
           "name": "span",
-          "type": "4 | 1 | 2 | 3",
+          "type": "1 | 4 | 2 | 3",
           "required": false,
           "defaultValue": null,
           "description": "How many columns to cover. Clamped by the container to its own `cols`.",
           "control": {
             "kind": "enum",
             "members": [
-              4,
               1,
               2,
-              3
+              3,
+              4
             ],
             "min": 1,
             "max": 4

package/manifest/components/button.json

@@ -150,6 +150,7 @@
     "--cue-style-outline-edge",
     "--cue-style-outline-hover-edge",
     "--cue-style-outline-hover-ground",
+    "--cue-style-primary-fill",
     "--cue-style-quiet-ink",
     "--cue-style-secondary-edge",
     "--cue-style-secondary-ground",

package/manifest/components/channel-matrix.json

@@ -224,6 +224,7 @@
     "--cue-style-body-size",
     "--cue-style-body-weight",
     "--cue-style-control-face",
+    "--cue-style-control-radius",
     "--cue-style-display-variation",
     "--cue-style-focus-width",
     "--cue-style-group-label-ink",

package/manifest/components/chart-tooltip-content.json

@@ -125,6 +125,7 @@
     "--cue-style-body-size",
     "--cue-style-body-weight",
     "--cue-style-control-face",
+    "--cue-style-control-radius",
     "--cue-style-display-variation",
     "--cue-style-group-label-ink",
     "--cue-style-group-label-pad",

package/manifest/components/checkbox-group.json

@@ -36,7 +36,6 @@
     "--cue-danger-fg",
     "--cue-fg",
     "--cue-fg-muted",
-    "--cue-fg-subtle",
     "--cue-focus",
     "--cue-focus-ring",
     "--cue-font-mono",
@@ -60,6 +59,7 @@
     "--cue-style-choice-gap",
     "--cue-style-control-face",
     "--cue-style-control-label-leading",
+    "--cue-style-control-radius",
     "--cue-style-disabled-edge",
     "--cue-style-disabled-fill",
     "--cue-style-disabled-ink",

package/manifest/components/checkbox.json

@@ -61,7 +61,6 @@
     "--cue-danger-fg",
     "--cue-fg",
     "--cue-fg-muted",
-    "--cue-fg-subtle",
     "--cue-focus",
     "--cue-focus-ring",
     "--cue-font-mono",
@@ -85,6 +84,7 @@
     "--cue-style-choice-gap",
     "--cue-style-control-face",
     "--cue-style-control-label-leading",
+    "--cue-style-control-radius",
     "--cue-style-disabled-edge",
     "--cue-style-disabled-fill",
     "--cue-style-disabled-ink",