@cueplusplus/ui 0.18.2 → 0.19.0

package/manifest/components/chip.json

@@ -134,6 +134,7 @@
     "--cue-style-chip-radius",
     "--cue-style-chip-size",
     "--cue-style-chip-tracking",
+    "--cue-style-control-radius",
     "--cue-style-focus-width",
     "--cue-style-label-case",
     "--cue-style-label-face",

package/manifest/components/combobox.json

@@ -271,6 +271,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/command-palette.json

@@ -187,6 +187,7 @@
     "--cue-style-body-size",
     "--cue-style-body-weight",
     "--cue-style-control-face",
+    "--cue-style-control-radius",
     "--cue-style-control-step-size",
     "--cue-style-dialog-radius",
     "--cue-style-display-variation",

package/manifest/components/context-menu.json

@@ -92,7 +92,6 @@
     "--cue-control-sm",
     "--cue-fg",
     "--cue-fg-muted",
-    "--cue-fg-subtle",
     "--cue-font-mono",
     "--cue-leading-ui",
     "--cue-paint-rim-width",
@@ -119,6 +118,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/density.json

@@ -48,13 +48,14 @@
     },
     {
       "name": "styleSet",
-      "type": "\"console\" | \"editorial\" | \"marketing\" | \"graphite\" | \"tender\" | \"zine\" | \"kiln\" | \"porcelain\"",
+      "type": "\"command\" | \"console\" | \"editorial\" | \"marketing\" | \"graphite\" | \"tender\" | \"zine\" | \"kiln\" | \"porcelain\" | \"ledger\" | \"monolith\" | \"prism\"",
       "required": false,
       "defaultValue": null,
       "description": "A style set for this subtree: `console`, `editorial`, `marketing` or\n`graphite`.\n\nOptional, and **absent means inherit** — an island that names none stamps no\n`data-style` and passes the ambient set straight through, exactly as a bare\n`<Density>` does today. Naming one is what makes this the library's island\nform of the fourth axis, and there are two reasons to reach for it:\n\n- `console` inside a page that is not console. That is the whole job of the\n  default set: it restates the `:root` defaults, so a subtree stamped with\n  it renders the ordinary look inside a page under any other set.\n- Moving the band rhythm with the rung. `--cue-band-y` is\n  `calc(var(--cue-space-7) * 2)` declared on the `[data-style]` element, and\n  a custom property's `var()` references are substituted where they are\n  declared — so a nested density island moves `--cue-space-*` but inherits\n  the rhythm already resolved above it. Restating the set here re-resolves\n  it against this island's rung, which is how a denser island gets a\n  proportionally tighter band instead of the outer one's.\n\nThe library restates the set for you where an island changes what a set's\nvalues read besides the rung — the theme's inks, the pairing's faces: a\nnested `ThemeProvider` that names a theme or a mode, and a `Preview` stage\nwith a theme, a mode or a pairing, stamp the set and the pack in force\nbeside it. This island changes only the rung, so it does not, and the\nrhythm above stays the opt-in the second bullet describes.",
       "control": {
         "kind": "enum",
         "members": [
+          "command",
           "console",
           "editorial",
           "marketing",
@@ -62,7 +63,10 @@
           "tender",
           "zine",
           "kiln",
-          "porcelain"
+          "porcelain",
+          "ledger",
+          "monolith",
+          "prism"
         ]
       }
     },

package/manifest/components/dialog.json

@@ -166,7 +166,6 @@
     "--cue-control-sm",
     "--cue-fg",
     "--cue-fg-muted",
-    "--cue-fg-subtle",
     "--cue-font-mono",
     "--cue-leading-ui",
     "--cue-paint-rim-width",
@@ -195,6 +194,7 @@
     "--cue-style-body-size",
     "--cue-style-body-weight",
     "--cue-style-control-face",
+    "--cue-style-control-radius",
     "--cue-style-dialog-pad",
     "--cue-style-dialog-radius",
     "--cue-style-display-variation",

package/manifest/components/dmx-bar.json

@@ -64,7 +64,6 @@
     "--cue-data-ground",
     "--cue-fg",
     "--cue-fg-muted",
-    "--cue-fg-subtle",
     "--cue-font-mono",
     "--cue-leading-ui",
     "--cue-paint-rim-width",
@@ -91,6 +90,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/dmx-strip.json

@@ -74,7 +74,6 @@
     "--cue-data-ground",
     "--cue-fg",
     "--cue-fg-muted",
-    "--cue-fg-subtle",
     "--cue-font-mono",
     "--cue-leading-ui",
     "--cue-paint-rim-width",
@@ -101,6 +100,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/drawer.json

@@ -160,7 +160,6 @@
     "--cue-control-sm",
     "--cue-fg",
     "--cue-fg-muted",
-    "--cue-fg-subtle",
     "--cue-font-mono",
     "--cue-leading-ui",
     "--cue-paint-rim-width",
@@ -189,6 +188,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/dropdown-menu.json

@@ -248,6 +248,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/font-scope.json

@@ -0,0 +1,81 @@
+{
+  "name": "FontScope",
+  "slug": "font-scope",
+  "group": "system",
+  "importPath": "@cueplusplus/ui",
+  "peerDependencies": [],
+  "clientOnly": true,
+  "description": "A subtree set in another type pairing — and everything it opens with it.\n\n`ThemeProvider`'s `font` is root-level only: the pairing has no island, and a\nnested provider forwards it to the root. `data-font` on a `<div>` is enough\nfor the subtree's own tokens, and nothing more: a dialog or menu opened inside\nit mounts on `<body>`, stamped from the root's pairing, and unclassed text\nkeeps the family `<body>` computed, because a computed family does not follow\na token. `FontScope` does all three: it stamps `data-font`, asks for the\nfamily again on its own element, and republishes the pairing so every portal\nopened inside it is stamped with it and asks for the family too. It is what\n`Preview` does for a stage that names a pairing, as a component of its own.\n\nIt never calls `setFont`, so the root's pairing — and the visitor's stored\none — never moves. A gallery frame that draws a page in a Look of its own is\nthe case it exists for (structural Looks, spec 2026-10-02 §6.2).\n\nThe set and pack in force around it are restated beside `data-font`, once it\nmay restate, because their names read the pairing and a custom property's\n`var()`s are substituted where it is declared.",
+  "props": [
+    {
+      "name": "font",
+      "type": "\"source\" | \"system\" | \"geist\" | \"geist-mono\" | \"inter\" | \"plex\" | \"roboto\" | \"apple\" | \"office\" | \"inter-source\" | \"dm\" | \"calsans\" | \"fraunces-mono\"",
+      "required": true,
+      "defaultValue": null,
+      "description": "The pairing this subtree is set in.",
+      "control": {
+        "kind": "enum",
+        "members": [
+          "source",
+          "system",
+          "geist",
+          "geist-mono",
+          "inter",
+          "plex",
+          "roboto",
+          "apple",
+          "office",
+          "inter-source",
+          "dm",
+          "calsans",
+          "fraunces-mono"
+        ]
+      }
+    },
+    {
+      "name": "children",
+      "type": "ReactNode",
+      "required": true,
+      "defaultValue": null,
+      "description": "What is set in it. Every overlay opened inside it is set in it too.",
+      "control": {
+        "kind": "node",
+        "fixture": "children.text"
+      }
+    }
+  ],
+  "typeReferences": [
+    "Omit<React.ComponentPropsWithoutRef<\"div\">, \"children\">"
+  ],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-font-sans"
+  ],
+  "summary": "A subtree set in another type pairing, and every dialog or menu it opens with it, without moving the root's.",
+  "examples": [
+    {
+      "title": "Usage",
+      "code": "<FontScope font=\"inter-source\">\n  <Dialog.Root>…</Dialog.Root>\n</FontScope>",
+      "language": "tsx"
+    }
+  ],
+  "status": "stable",
+  "url": "/docs/components/font-scope",
+  "mdUrl": "/docs/components/font-scope.md",
+  "jsonUrl": "/r/components/font-scope.json",
+  "whenToUse": [
+    "A frame or specimen that draws a page in a Look of its own, where the pairing has to reach its overlays too.",
+    "A picker row or a comparison that shows one pairing beside the page's."
+  ],
+  "whenNotToUse": [
+    "Changing the page's own pairing. That is `ThemeProvider`'s `font`, at the root, or its `setFont`.",
+    "A heading in another face. A class on the element is enough; a scope re-sets everything under it."
+  ],
+  "commonMistakes": [
+    "Stamping `data-font` on a `<div>` and expecting a dialog opened inside it to follow. The dialog mounts on `<body>`; only the scope carries the pairing to it.",
+    "Passing `font` to a nested `ThemeProvider`. The pairing is root-level there, and a nested provider forwards it to the root."
+  ]
+}

package/manifest/components/footer.json

@@ -69,7 +69,6 @@
     "--cue-band-y",
     "--cue-border",
     "--cue-fg-muted",
-    "--cue-fg-subtle",
     "--cue-font-mono",
     "--cue-space-3",
     "--cue-space-5",

package/manifest/components/gloss-object.json

@@ -0,0 +1,81 @@
+{
+  "name": "GlossObject",
+  "slug": "gloss-object",
+  "group": "brand",
+  "importPath": "@cueplusplus/ui",
+  "peerDependencies": [],
+  "clientOnly": false,
+  "description": "A glossy, iridescent object for a marketing hero — the chrome-ring and gloss\nlettermark look (spec 2026-10-02 §3.4). Drawn with layered radial and linear\ngradients of the theme's accent against the foreground's mix, plus a specular\nhighlight in the accent's own ink (`--cue-accent-fg`), so it is the Look's own colour and never a copied render.\nDecorative: hidden from assistive technology.\n\nStatic markup — no `\"use client\"`.",
+  "props": [
+    {
+      "name": "shape",
+      "type": "\"mark\" | \"torus\" | \"knot\"",
+      "required": false,
+      "defaultValue": "torus",
+      "description": "The object: a ring, a knot of two rings, or a rounded mark. Defaults to `\"torus\"`.",
+      "control": {
+        "kind": "enum",
+        "members": [
+          "mark",
+          "torus",
+          "knot"
+        ]
+      }
+    },
+    {
+      "name": "seed",
+      "type": "number",
+      "required": false,
+      "defaultValue": "1",
+      "description": "Tilts the highlight. Defaults to `1`.",
+      "control": {
+        "kind": "number"
+      }
+    }
+  ],
+  "typeReferences": [
+    "React.SVGProps<SVGSVGElement>"
+  ],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-accent",
+    "--cue-accent-fg",
+    "--cue-fg"
+  ],
+  "summary": "A glossy, iridescent object — a ring, two rings or a rounded mark — in the theme's accent.",
+  "examples": [
+    {
+      "title": "Usage",
+      "code": "<GlossObject shape=\"knot\" className=\"h-48 w-48\" />",
+      "language": "tsx"
+    }
+  ],
+  "status": "stable",
+  "url": "/docs/components/gloss-object",
+  "mdUrl": "/docs/components/gloss-object.md",
+  "jsonUrl": "/r/components/gloss-object.json",
+  "whenToUse": [
+    "A marketing hero's centrepiece, or art between sections."
+  ],
+  "whenNotToUse": [
+    "Icons or small UI marks. It is a hero-scale decoration."
+  ],
+  "commonMistakes": [
+    "Expecting a 3D render. It is layered gradients, drawn in the Look's own colour."
+  ],
+  "specimens": [
+    {
+      "title": "GlossObject",
+      "group": "brand",
+      "components": [
+        "GlossObject"
+      ],
+      "code": "<Specimens>\n  {([\"torus\", \"knot\", \"mark\"] as const).map((shape) => (\n    <Specimen key={shape} label={shape}>\n      <GlossObject shape={shape} className=\"size-40\" />\n    </Specimen>\n  ))}\n</Specimens>",
+      "note": "A glossy object of layered gradients over an authored outline, lit in the accent.",
+      "interaction": "none."
+    }
+  ]
+}

package/manifest/components/grid.json

@@ -9,17 +9,17 @@
   "props": [
     {
       "name": "cols",
-      "type": "4 | 1 | 2 | 3 | 5 | 6",
+      "type": "1 | 4 | 2 | 3 | 5 | 6",
       "required": false,
       "defaultValue": "1",
       "description": "How many equal columns. Defaults to `1`. Ignored when `minItemWidth` is set.",
       "control": {
         "kind": "enum",
         "members": [
-          4,
           1,
           2,
           3,
+          4,
           5,
           6
         ],
@@ -29,7 +29,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 cells. Defaults to `4`.",
@@ -37,14 +37,14 @@
         "kind": "enum",
         "members": [
           0,
-          4,
-          8,
           1,
           2,
           3,
+          4,
           5,
           6,
-          7
+          7,
+          8
         ],
         "min": 0,
         "max": 8

package/manifest/components/halftone.json

@@ -0,0 +1,79 @@
+{
+  "name": "Halftone",
+  "slug": "halftone",
+  "group": "brand",
+  "importPath": "@cueplusplus/ui",
+  "peerDependencies": [],
+  "clientOnly": false,
+  "description": "A halftone dot screen over a generated form — the engraved, printed look of a\ndeveloper-tool landing page (spec 2026-10-02 §3.4). Every dot's size is the\nform's density at that cell, so the picture is drawn by the screen itself\nrather than filtered from an image, and nothing is fetched. Dots are the\nforeground ink. Decorative: hidden from assistive technology.\n\nStatic markup — no `\"use client\"`.",
+  "props": [
+    {
+      "name": "shape",
+      "type": "\"wave\" | \"orb\" | \"ridge\"",
+      "required": false,
+      "defaultValue": "ridge",
+      "description": "The generated form the dots describe. Defaults to `\"ridge\"`.",
+      "control": {
+        "kind": "enum",
+        "members": [
+          "wave",
+          "orb",
+          "ridge"
+        ]
+      }
+    },
+    {
+      "name": "seed",
+      "type": "number",
+      "required": false,
+      "defaultValue": "1",
+      "description": "Which variant of the form. Defaults to `1`.",
+      "control": {
+        "kind": "number"
+      }
+    }
+  ],
+  "typeReferences": [
+    "React.SVGProps<SVGSVGElement>"
+  ],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-fg"
+  ],
+  "summary": "A halftone dot screen over a generated form: the engraved, printed developer-tool motif.",
+  "examples": [
+    {
+      "title": "Usage",
+      "code": "<Halftone shape=\"orb\" className=\"h-72 w-72\" />",
+      "language": "tsx"
+    }
+  ],
+  "status": "stable",
+  "url": "/docs/components/halftone",
+  "mdUrl": "/docs/components/halftone.md",
+  "jsonUrl": "/r/components/halftone.json",
+  "whenToUse": [
+    "Hero art on a developer-tool or documentation landing page."
+  ],
+  "whenNotToUse": [
+    "Turning a photograph into halftone. It draws only its generated forms and fetches nothing."
+  ],
+  "commonMistakes": [
+    "Using it at a few pixels. The dot screen needs room; below ~120px the form is lost."
+  ],
+  "specimens": [
+    {
+      "title": "Halftone",
+      "group": "brand",
+      "components": [
+        "Halftone"
+      ],
+      "code": "<Specimens>\n  {([\"ridge\", \"wave\", \"orb\"] as const).map((shape) => (\n    <Specimen key={shape} label={shape}>\n      <Halftone shape={shape} className=\"size-40\" />\n    </Specimen>\n  ))}\n</Specimens>",
+      "note": "A dot screen over a generated form, drawn by the screen itself rather than filtered from an image. Nothing is fetched.",
+      "interaction": "none."
+    }
+  ]
+}

package/manifest/components/hero.json

@@ -0,0 +1,204 @@
+{
+  "name": "Hero",
+  "slug": "hero",
+  "group": "chrome",
+  "importPath": "@cueplusplus/ui",
+  "peerDependencies": [],
+  "clientOnly": false,
+  "description": "The opening of a page: a title, the line under it, what to do next, and art.\n\n**The Look decides the arrangement, not this component.** The grid reads the\nstyle set's hero recipe — `style-hero-columns`, `style-hero-align` and\n`style-hero-media-order` — so the same hero opens centred under one Look, with\nits art beside the words under another, and with the art first under a third,\nwith no prop changed. Unset, it is one column, start-aligned, art after the\nwords.\n\n**No media, one column**, whatever the recipe says: two columns with nothing in\nthe second is half a page of nothing.\n\n`surface=\"inverse\"` is a theme island in dark mode, so every ink inside it —\nthe title, the lede, a button's fill and its focus ring — is the dark palette's,\nand an overlay opened from it inherits that. The island carries\n`data-cue-rescope`, where the token build re-declares the active set's and\npack's inks, so the card is right in the first frame, before hydration.\n\nStatic markup — no `\"use client\"`.",
+  "props": [
+    {
+      "name": "eyebrow",
+      "type": "ReactNode",
+      "required": false,
+      "defaultValue": null,
+      "description": "A short line above the title, usually an `Eyebrow`.",
+      "control": {
+        "kind": "node",
+        "fixture": "children.text"
+      }
+    },
+    {
+      "name": "title",
+      "type": "ReactNode",
+      "required": true,
+      "defaultValue": null,
+      "description": "The title's first line. A hero without a title is a band; use `Band`.",
+      "control": {
+        "kind": "node",
+        "fixture": "children.text"
+      }
+    },
+    {
+      "name": "titleSecond",
+      "type": "ReactNode",
+      "required": false,
+      "defaultValue": null,
+      "description": "The title's second line, drawn in the style set's second ink: the accent, a\nmuted ink or the keyword gradient, by the Look. Omit it for a one-line title.",
+      "control": {
+        "kind": "node",
+        "fixture": "children.text"
+      }
+    },
+    {
+      "name": "level",
+      "type": "1 | 2 | 3",
+      "required": false,
+      "defaultValue": "1",
+      "description": "The title's heading level. `1`, the default, is a page's opening; `2` or `3`\nis a hero that opens a section under the page's own `<h1>`, or a preview of\none on a page about something else.",
+      "control": {
+        "kind": "enum",
+        "members": [
+          1,
+          2,
+          3
+        ],
+        "min": 1,
+        "max": 3
+      }
+    },
+    {
+      "name": "lede",
+      "type": "ReactNode",
+      "required": false,
+      "defaultValue": null,
+      "description": "The sentence under the title.",
+      "control": {
+        "kind": "node",
+        "fixture": "children.text"
+      }
+    },
+    {
+      "name": "actions",
+      "type": "ReactNode",
+      "required": false,
+      "defaultValue": null,
+      "description": "The calls to action, usually a primary and a secondary `Button`.",
+      "control": {
+        "kind": "node",
+        "fixture": "children.text"
+      }
+    },
+    {
+      "name": "media",
+      "type": "ReactNode",
+      "required": false,
+      "defaultValue": null,
+      "description": "Art beside or behind the words: a `Motif`, an image, a product shot.",
+      "control": {
+        "kind": "node",
+        "fixture": "children.text"
+      }
+    },
+    {
+      "name": "stats",
+      "type": "ReactNode",
+      "required": false,
+      "defaultValue": null,
+      "description": "A row of figures under the lede, usually a `StatBand`.",
+      "control": {
+        "kind": "node",
+        "fixture": "children.text"
+      }
+    },
+    {
+      "name": "surface",
+      "type": "\"page\" | \"inverse\"",
+      "required": false,
+      "defaultValue": "page",
+      "description": "`page` draws the hero on the page's own ground. `inverse` draws it as a dark\ncard on any page — its whole colour scope flipped, controls and focus included —\nwhich is how a report opens on a light page. Defaults to `\"page\"`.",
+      "control": {
+        "kind": "enum",
+        "members": [
+          "page",
+          "inverse"
+        ]
+      }
+    }
+  ],
+  "typeReferences": [
+    "Omit<React.ComponentPropsWithoutRef<\"section\">, \"title\">"
+  ],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-bg",
+    "--cue-fg",
+    "--cue-fg-muted",
+    "--cue-font-mono",
+    "--cue-leading-ui",
+    "--cue-radius-surface",
+    "--cue-space-3",
+    "--cue-space-5",
+    "--cue-space-7",
+    "--cue-style-body-face",
+    "--cue-style-body-weight",
+    "--cue-style-display",
+    "--cue-style-display-case",
+    "--cue-style-display-face",
+    "--cue-style-display-variation",
+    "--cue-style-display-weight",
+    "--cue-style-heading-ink",
+    "--cue-style-hero-align",
+    "--cue-style-hero-columns",
+    "--cue-style-hero-media-order",
+    "--cue-style-hero-title-clip-2",
+    "--cue-style-hero-title-fill-2",
+    "--cue-style-hero-title-ink-2",
+    "--cue-style-hero-title-size",
+    "--cue-style-hero-title-text-2",
+    "--cue-style-leading-display",
+    "--cue-style-lede-ink",
+    "--cue-style-lede-leading",
+    "--cue-style-lede-size",
+    "--cue-style-page-title-face",
+    "--cue-style-page-title-leading",
+    "--cue-style-page-title-size",
+    "--cue-style-page-title-tracking",
+    "--cue-style-page-title-weight",
+    "--cue-style-prose-ink",
+    "--cue-style-prose-tracking",
+    "--cue-style-tracking-display",
+    "--cue-text-title",
+    "--cue-text-ui"
+  ],
+  "summary": "The opening of a page: a title, its second line, what to do next, and art — arranged by the Look.",
+  "examples": [
+    {
+      "title": "Usage",
+      "code": "<Hero eyebrow={<Eyebrow>Category report</Eyebrow>} title=\"Snacks & nuts\" titleSecond=\"Range review\"\n  lede=\"Every recommendation has a boundary.\" actions={<Button>Open the report</Button>} />",
+      "language": "tsx"
+    }
+  ],
+  "status": "stable",
+  "url": "/docs/components/hero",
+  "mdUrl": "/docs/components/hero.md",
+  "jsonUrl": "/r/components/hero.json",
+  "whenToUse": [
+    "The top of a landing, product or report page, where one statement and one action lead.",
+    "A report's opening card: `surface='inverse'` with `stats` draws the dark KPI hero on a light page."
+  ],
+  "whenNotToUse": [
+    "A section further down the page. Use `Band` with a `SectionHeader`; a page has one hero.",
+    "An app screen. Apps open on their work, not a statement; use `AppShell` and `PageShell`."
+  ],
+  "commonMistakes": [
+    "Passing layout props to make it centred or two-column. The Look decides that through its style set; a hero that hard-codes it cannot be re-skinned.",
+    "Two columns with no `media`: the hero falls back to one column, by design, so supply the art or let it be one column.",
+    "Leaving the default `level={1}` on a hero drawn inside a page that already has its own `<h1>` — a preview, a tile, an embedded page. Pass `level={2}`."
+  ],
+  "specimens": [
+    {
+      "title": "Hero",
+      "group": "chrome",
+      "components": [
+        "Hero"
+      ],
+      "code": "<div className=\"grid w-full gap-(--cue-space-7)\">\n  <Hero\n    eyebrow={<Eyebrow>Category report</Eyebrow>}\n    title=\"Snacks and nuts\"\n    titleSecond=\"Range review, week 32\"\n    lede=\"Every recommendation has a boundary, and every boundary has a reason you can read.\"\n    actions={\n      <>\n        <Button variant=\"primary\">Open the report</Button>\n        <Button>Download the deck</Button>\n      </>\n    }\n    media={<div className=\"aspect-[4/3] w-full rounded-(--radius-surface) bg-surface-2\" />}\n  />\n  <Hero\n    surface=\"inverse\"\n    eyebrow={<Eyebrow>This week</Eyebrow>}\n    title=\"Availability held at 97.4%\"\n    lede=\"The dark card is the page's choice, not the Look's: an island in dark mode, drawn in the Look's own dark palette.\"\n    stats={\n      <StatBand\n        stats={[\n          { label: \"Lines\", value: \"1,091\" },\n          { label: \"Brands\", value: \"148\" },\n          { label: \"Delisted\", value: \"37\", note: \"of 1,128\" },\n        ]}\n      />\n    }\n  />\n</div>",
+      "note": "The opening of a page. The style set decides the arrangement — one column or two, centred or start-aligned, art first or after — so this hero changes shape with the Look while its props stay put. With no media it is one column whatever the set says.",
+      "interaction": "none of its own; the actions are ordinary Buttons."
+    }
+  ]
+}