@sableui/react 0.1.1 → 0.3.0

package/AGENTS.md

@@ -12,6 +12,7 @@ How to **build with** Sable. This is the whole consumer contract an agent needs;
 |---|---|
 | Which component, and its props/examples | `npx sable search "<need>"` → `npx sable component <Name> --detail full` |
 | A page composition to start from | `npx sable pattern --list` → `npx sable pattern <Name> --skeleton` |
+| A card, form or list to start from (a block) | `npx sable block --list` → `npx sable block <Name> --code` |
 | The rules for type, motion, spacing, shape, surfaces, a11y | `npx sable docs typography` (also `motion`, `spacing`, `shape`, `surfaces`, `accessibility`) |
 | Which token to reach for | `npx sable token <name>` · `npx sable docs token-intent` |
 | A task walkthrough | `npx sable docs --list --kind tasks` |
@@ -61,7 +62,7 @@ The machine-readable version of this section is the `consume` block in `registry
    `styles.css` carries **Base only** — the default theme, and the layout floor every other theme inherits (`--page-inset`, `--region-*`, `--rhythm-unit` on a bare `:root`). The bundled **alternates are opt-in**, because they are `[data-sable-theme]`-scoped and an app that never sets the attribute ships CSS that can never match: 5.5 KB gzip of permanently-dead weight, which is exactly how a real app's build audit found this. Using one? `@import "@sableui/react/theme/prism.css";`. Offering the whole set through a `<ThemeSelector>`? `@import "@sableui/react/themes.css";`. **Symptom of forgetting:** `data-sable-theme` is set, nothing matches, and the page silently renders as Base — no error, just the wrong theme.
 4. **Fonts:** load Figtree (sans) + DM Mono (mono) — the theme declares the stacks, the host provides the files. Apply `antialiased` (`-webkit-font-smoothing: antialiased` / `-moz-osx-font-smoothing: grayscale`) **once on the app root**: Sable's type scale was drawn against smoothed text, and without it macOS renders every weight heavier than designed. The package deliberately doesn't set it — a library has no business styling the host's whole page — so it has to happen here.
 5. **Providers (all optional):** components render with **Reicon** by default, so `<IconProvider set={…}>` is only needed to replace it with another icon package or extend it using `composeIconSets(appExtras, reiconIconSet)`; `<MotionProvider>` is optional too. Use `<SableThemeProvider>` + `useSableTheme()` when the app should expose user-selectable themes; pair `themeId` / `setThemeId` with `<ThemeSelector>` and `preference` / `setPreference` with `<ThemeSwitcher>`. The provider stores `light` / `dark` / `system`, toggles the `dark` class on `<html>`, stores the active design theme, and writes `data-sable-theme` for non-default themes. Apps with their own state layer can call `applySableColorMode()` / `applySableTheme()` instead. You only need a Tailwind `@custom-variant dark` if **your** app code uses `dark:` utilities (Sable ships none).
-6. Import from the root barrel: `import { Button } from "@sableui/react"`. Page shells live on the `patterns` subpath (`import { SettingsPage } from "@sableui/react/patterns"`) — preview one, then copy its source from `registry.json → patterns` when the route needs to diverge.
+6. Import from the root barrel: `import { Button } from "@sableui/react"`. Page shells live on the `patterns` subpath (`import { SettingsPage } from "@sableui/react/patterns"`) — preview one, then copy its source from `registry.json → patterns` when the route needs to diverge. Blocks — section-sized compositions such as a sign-in card or a pricing card — live on the `blocks` subpath (`import { SignInBlock } from "@sableui/react/blocks"`) and ship the same way (`registry.json → blocks`); copy one and edit its content constants. A block's props are only `className`, `framed` and its primary action's callback, never content.
 
 7. **Check the wiring:** `npx sable doctor`. Every check it runs corresponds to a way Sable fails *silently* — a second React (blank page, "invalid hook call"), a missing `@source` (Tailwind emits none of the package's classes, everything renders unstyled), or `data-sable-theme` set with no theme CSS imported (every theme renders as Base and the switcher looks broken). Exits 1 on any failure; `--json` for the structured report.
 
@@ -70,6 +71,7 @@ The machine-readable version of this section is the `consume` block in `registry
    ```bash
    npx sable pattern --list                      # the eight page shells
    npx sable pattern SettingsPage --skeleton     # composition tree, fixtures stripped
+   npx sable block --list                        # section-sized blocks: cards, forms, lists
    npx sable component DataTable --props
    npx sable search "empty state"                # across components, patterns, layout, tokens, docs
    npx sable docs converting-an-app              # the task walkthroughs

package/CHANGELOG.md

@@ -1,5 +1,125 @@
 # What's new
 
+## 0.3.0
+
+Blocks, charts, and the components they needed.
+
+### Breaking
+
+- **`DotsMenu` is now `OverflowMenu`** (`overflowMenuMeta`, same props). The
+  name says what it is for — the "more actions" menu — rather than how its
+  trigger is drawn.
+
+### New
+
+- **Blocks** — section-sized compositions on a new `@sableui/react/blocks`
+  subpath and in `registry.json → blocks`: 40 of them across Auth, Settings &
+  team, Commerce, Dashboard, Marketing, Social & messaging, Media & files,
+  Navigation and System (sign-in, pricing table, team members, invoice
+  history, FAQ, 404, chart cards…). Copy one and edit its content constants;
+  props are only `className`, `framed` and the primary action's callbacks.
+  `sable block --list`, `--family`, `--skeleton` and `--code` retrieve them,
+  and the docs have a Blocks page with live previews and copyable code.
+- **Charts** — `AreaChart`, `BarChart`, `LineChart`, `PieChart`,
+  `RadarChart`, `RadialChart` and `Sparkline`, in SVG with no dependency, for
+  dashboards, landing pages and decks. Stacked and 100% stacked, grouped,
+  horizontal and diverging bars, smooth/linear/step curves, gradients, dots and
+  labels, donuts with a centre value, gauges, legends with icons, and tooltips
+  with dot/line/dashed indicators, formatters and totals. Lines draw on, bars
+  rise and slices sweep in as a chart scrolls into view, and new data eases
+  from the old shape — all on the motion tokens. Every chart carries its data
+  as a table for assistive tech and steps through it from the keyboard.
+- **Chart palette** — `--chart-1` … `--chart-8`, eight series colours
+  validated for colour-blind separation, a normal-vision floor, a lightness
+  band and a chroma floor, in light and dark. Every theme inherits them; a
+  theme may override the set. `chartColor(i)` hands the same colours to a
+  charting library.
+- **`DateTile`** — a calendar-page date (month band over the day), with
+  lining figures so a display face never drops the day below centre.
+- **`SegmentedBar`** — one bar split into the parts of a whole, read aloud as a
+  single labelled image.
+- `CardTitle` takes `render`, so a card's name can be a heading
+  (`render={<h2 />}`).
+- `Entity` takes `selected` for the current row of a selectable list.
+- Icons: `stop`, `key`, `wallet`, `thumbs-up`, `thumbs-down`.
+- `sable-lint` lints a single file as well as a folder.
+
+### Components
+
+- **Sidebar:** components placed in the rail ink with the rail's own tokens, so
+  a dark rail on a light page keeps its account row legible.
+- **Entity:** hover and selected fills step off whatever surface the row sits
+  on.
+- **ChatComposer:** the stop control is a filled square, not an ✕.
+- **CommandMenu:** a long detail no longer squeezes the label.
+
+### Fixes
+
+- The registry's derived imports for patterns and blocks include hooks called
+  with a type argument (`useRef<…>(`) — `ListDetailPage`'s copied source was
+  missing its `useRef` import.
+
+## 0.2.0
+
+A design and polish pass across the library, its page patterns, and the site.
+
+### Breaking
+
+- **`Description` is removed.** Label/value lists are now typography on the
+  native element: `<dl className="sable-list-dl">` with `<dt>`/`<dd>` children,
+  and `sable-list-dl-2` for two pairs a row inside an `@container`. Colour a
+  status value with a `text-*` utility on its `<dd>`. `DescriptionItem`,
+  `DescriptionTerm`, `DescriptionDetail`, `descriptionVariants` and
+  `descriptionMeta` go with it.
+
+### New
+
+- List utilities for semantic HTML: `sable-list` (bullets),
+  `sable-list-numbered`, `sable-list-dl` and `sable-list-dl-2`, documented under
+  Typography → Lists.
+- `sable-frame-tool`: a frame for edge-to-edge tool chrome that keeps the
+  theme's radius and passes concentric geometry to what's inside. PanelSection
+  rows grow their inset with the corner and compact fields curve parallel to
+  it; unframed, panels keep their 8px inset.
+- `KbdGroup` for keyboard combinations.
+
+### Components
+
+- **Bubble:** the tail is a drawn ear on every corner style, flat through fully
+  pilled, with a softened tip and a filleted inner corner; square themes keep it
+  sharp. Bubbles reserve the tail's space so grouped runs line up.
+- **Checkbox / CheckboxCard:** the check and dash read at a consistent ~1.6px
+  weight on the filled box.
+- **EmptyState:** the glyph stands on its own, with no disc, and can be an image
+  or illustration.
+- **Skeleton:** one eased sheen passes through every skeleton on screen as a
+  single wave, a highlight in light and dark, and rests off-screen under reduced
+  motion.
+- **Stepper:** indicators no longer rise above sticky headers or navigation bars.
+- **BottomNav / Button:** badge dots sit on the icon's corner.
+- **Toast:** enters from the edge it is anchored to, and portals to `<body>` so a
+  transformed ancestor can't trap it.
+- Refinements to Card (concentric inner radius, footer seams), Table and
+  DataTable, Avatar, Badge, Pill, Kbd, Combobox, Select, NumberField, SideNav,
+  ThemeSelector, ChatComposer and more.
+
+### Presets
+
+- Verdant and Meridian lift cards and popovers above the page in light mode, so
+  fields read as boxes to type in. A theme test now holds every preset to it.
+
+### iOS
+
+- `IosSheet` follows iOS 26: Liquid Glass at the medium detent, floating and
+  concentric with the screen; opaque at the large detent; a glass close button
+  and a centred title.
+
+### Page patterns
+
+- All eight rebuilt as fuller examples. Dashboard, Settings, Auth, List–detail
+  and Feed now tell one product story; Landing shows the library working;
+  Brand landing and Chat are polished.
+
 ## 0.1.1
 
 - Published with npm trusted publishing: releases come from `sableui/sable`'s

package/CONTRIBUTING.md

@@ -195,6 +195,14 @@ not. The brief determines the result, not resemblance to an existing shell.
 
 The **source is the contract**: each pattern is real TSX (typechecked, design-linted, rendered live by the docs app), split as `<name>.meta.ts` (a `PatternMeta`: name/summary/intent/notes/a11y) + `<name>.tsx` whose code after the `// ---pattern-code---` marker is emitted verbatim into the registry by `build-registry.mjs` — so the shipped recipe can never drift from code that compiles. Keep patterns hook-free and self-contained (inline sample data, `<a href>` for links); the generator auto-derives the consumer import block. To add one: write the pair, export both from `src/patterns/index.ts`, regenerate the registry, and add it to the docs `PatternPreview` map.
 
+## Blocks (section-sized compositions)
+
+`src/blocks/` holds compositions smaller than a page — a sign-in card, a pricing card, an order tracker — built from components with sample content and no behaviour of their own. They ship exactly like patterns (`@sableui/react/blocks` previews + `registry.json → blocks` source, `sable block <Name>`), from the same `<name>.meta.ts` (a `BlockMeta`) + `<name>.tsx` pair split by a `// ---block-code---` marker. The docs canvas and the Blocks page render them, so the scenes a theme is judged on are the source a consumer copies.
+
+**Component or block?** If it owns behaviour, state or an a11y contract that should arrive on upgrade, it is a component. If it is an arrangement of components plus copy, it is a block. A block that needs something the library lacks is a library gap: add the component first (`DateTile` and `SegmentedBar` arrived this way), then compose it.
+
+**The block contract** (checked by `build-registry`): the name ends in `Block`; the meta declares a `family`, a `kind` (`card` | `section`) and, for cards, the designed `width` ({ min, max }); the root takes `className` and renders `w-full` capped at the designed max; a card block built on Card takes `framed` (Card `default` / `flat`); the only other props are the primary action's callbacks. Content is never a prop — it is the constant at the top of the file, edited after copying. Variants are separate blocks, not a `variant` prop. To add one: write the pair, export both from `src/blocks/index.ts`, and regenerate the registry; the Blocks docs page picks it up from the catalog.
+
 ## Promoting from an app (and the drift back down)
 
 The system grows **out of the apps**, not ahead of them. A component earns its way in by being built in a consuming app first, measured in place, and only then lifted here — which is how the workspace register (v0.31.1, out of Glitch's tool chrome) and `Tree` (v0.32.0, out of Glitch's layers list) landed. Both deleted more app code than they added: Glitch's `globals.css` went 229 → 49 lines and its local `components/workspace/` disappeared. That deletion is the signal you're promoting something real rather than relocating it.

package/README.md

@@ -122,6 +122,7 @@ Two binaries ship with the package, both zero-dependency and both reading the co
 ```bash
 npx sable pattern --list                     # the eight canonical page shells
 npx sable pattern DashboardPage --skeleton   # its composition tree — 127 lines of source, 45 of structure
+npx sable block PricingCardBlock --code      # a section-sized block's source, imports included
 npx sable component Button --props
 npx sable search "date range"                # one ranked set across components, patterns, layout, tokens, docs
 npx sable doctor                             # is this project wired correctly? exits 1 if not

package/bin/sable.mjs

@@ -4,6 +4,7 @@
  *
  *   npx sable pattern --list              # the eight page shells, one line each
  *   npx sable pattern DashboardPage --skeleton
+ *   npx sable block --list                # section-sized blocks: cards, forms, lists
  *   npx sable component Button --props
  *   npx sable search "date range"
  *   npx sable doctor
@@ -109,10 +110,10 @@ const COMMANDS = [
 	},
 	{
 		name: "search",
-		summary: "One ranked result set across components, patterns, layout primitives, utilities, tokens, and docs.",
+		summary: "One ranked result set across components, patterns, blocks, layout primitives, utilities, tokens, and docs.",
 		arg: { name: "query", required: true },
 		flags: [
-			{ name: "--type", value: "component|pattern|layout|utility|token|doc", describe: "Restrict to one kind." },
+			{ name: "--type", value: "component|pattern|block|layout|utility|token|doc", describe: "Restrict to one kind." },
 			{ name: "--limit", value: "n", describe: "Cap results. Default 20." },
 		],
 		returns: ["search"],
@@ -142,6 +143,18 @@ const COMMANDS = [
 		],
 		returns: ["pattern.list", "pattern.detail", "pattern.skeleton", "pattern.code"],
 	},
+	{
+		name: "block",
+		summary: "Section-sized compositions — a sign-in card, a pricing card. Smaller than a page shell; copy the code and edit its content.",
+		arg: { name: "Name", required: false },
+		flags: [
+			{ name: "--list", value: null, describe: "List the blocks instead." },
+			{ name: "--family", value: "family", describe: "With --list: one family only (e.g. \"Commerce\")." },
+			{ name: "--skeleton", value: null, describe: "Composition tree only — no fixtures, no copy." },
+			{ name: "--code", value: null, describe: "Full source with its import line." },
+		],
+		returns: ["block.list", "block.detail", "block.skeleton", "block.code"],
+	},
 	{
 		name: "layout",
 		summary: "Layout primitives and the layout doctrine.",
@@ -175,7 +188,7 @@ const COMMANDS = [
 		arg: { name: "slug", required: false },
 		flags: [
 			{ name: "--list", value: null, describe: "List every doc slug." },
-			{ name: "--kind", value: "components|layout|patterns|reference|tasks|taste", describe: "With --list: one kind." },
+			{ name: "--kind", value: "components|layout|patterns|blocks|reference|tasks|taste", describe: "With --list: one kind." },
 		],
 		returns: ["docs.list", "docs.detail"],
 	},
@@ -271,6 +284,7 @@ const ERROR_CODES = [
 	{ code: "ERR_MISSING_ARGUMENT", when: "A command that requires an argument got none." },
 	{ code: "ERR_UNKNOWN_COMPONENT", when: "No component by that name. `suggestions` carries near matches." },
 	{ code: "ERR_UNKNOWN_PATTERN", when: "No pattern by that name." },
+	{ code: "ERR_UNKNOWN_BLOCK", when: "No block by that name." },
 	{ code: "ERR_UNKNOWN_LAYOUT", when: "No layout primitive by that name." },
 	{ code: "ERR_UNKNOWN_TOKEN_GROUP", when: "No token group by that name." },
 	{ code: "ERR_UNKNOWN_UTILITY", when: "No utility or variant by that name. `suggestions` carries near matches." },
@@ -413,6 +427,7 @@ const section = (title, lines) => (lines.length ? `\n${DENSE ? title : `${title}
 
 const COMPONENTS = R.components ?? []
 const PATTERNS = R.patterns?.items ?? []
+const BLOCKS = R.blocks?.items ?? []
 const PRIMITIVES = R.layoutPrimitives?.primitives ?? []
 const TOKEN_GROUPS = Object.keys(R.tokens ?? {})
 const UTILITIES = R.utilities?.items ?? []
@@ -440,7 +455,7 @@ function cmdManifest() {
 		name: "sable",
 		version: R.version,
 		package: R.name,
-		describes: { components: COMPONENTS.length, patterns: PATTERNS.length, layoutPrimitives: PRIMITIVES.length },
+		describes: { components: COMPONENTS.length, patterns: PATTERNS.length, blocks: BLOCKS.length, layoutPrimitives: PRIMITIVES.length },
 		envelope: { success: "{ type, data }", error: "{ type: 'error', code, message, suggestions }" },
 		globalFlags: GLOBAL_FLAGS,
 		commands: COMMANDS,
@@ -448,7 +463,7 @@ function cmdManifest() {
 	}
 	ok("manifest", data, () =>
 		[
-			`sable ${R.version} — ${COMPONENTS.length} components, ${PATTERNS.length} patterns, ${PRIMITIVES.length} layout primitives.`,
+			`sable ${R.version} — ${COMPONENTS.length} components, ${PATTERNS.length} patterns, ${BLOCKS.length} blocks, ${PRIMITIVES.length} layout primitives.`,
 			"",
 			"Commands:",
 			...COMMANDS.map((c) => `  ${(c.name + (c.arg ? ` <${c.arg.name}>` : "")).padEnd(22)}${c.summary}`),
@@ -502,6 +517,9 @@ function cmdSearch() {
 	if (!type || type === "pattern")
 		for (const p of PATTERNS)
 			pool.push({ kind: "pattern", name: p.name, summary: p.summary, _s: score({ name: p.name, text: `${p.summary} ${p.intent ?? ""}` }) })
+	if (!type || type === "block")
+		for (const b of BLOCKS)
+			pool.push({ kind: "block", name: b.name, summary: b.summary, family: b.family, _s: score({ name: b.name, keywords: [b.family.toLowerCase()], text: `${b.summary} ${b.intent ?? ""}` }) })
 	if (!type || type === "layout")
 		for (const m of PRIMITIVES)
 			pool.push({ kind: "layout", name: m.name, summary: m.summary, _s: score({ name: m.name, keywords: m.keywords, text: m.summary }) })
@@ -518,7 +536,7 @@ function cmdSearch() {
 	// Ties resolve in the order AGENTS.md tells an agent to resolve a need:
 	// a component first, then a pattern or primitive, then a utility, then a
 	// token. "segmented" should land on ToggleGroup before the well behind it.
-	const KIND_ORDER = ["component", "pattern", "layout", "utility", "token", "doc"]
+	const KIND_ORDER = ["component", "pattern", "block", "layout", "utility", "token", "doc"]
 	const hits = pool
 		.filter((h) => h._s > 0)
 		.sort((a, b) => b._s - a._s || KIND_ORDER.indexOf(a.kind) - KIND_ORDER.indexOf(b.kind))
@@ -679,25 +697,38 @@ function docSlugFor(name) {
 	const entry =
 		COMPONENTS.find((c) => c.name.toLowerCase() === name.toLowerCase()) ??
 		PRIMITIVES.find((m) => m.name.toLowerCase() === name.toLowerCase()) ??
-		PATTERNS.find((p) => p.name.toLowerCase() === name.toLowerCase())
+		PATTERNS.find((p) => p.name.toLowerCase() === name.toLowerCase()) ??
+		BLOCKS.find((b) => b.name.toLowerCase() === name.toLowerCase())
 	if (!entry?.path) return slugify(name)
 	return entry.path.split("/").pop().replace(/\.tsx$/, "")
 }
 
-/* ── pattern ────────────────────────────────────────────────────────────────── */
+/* ── pattern / block ────────────────────────────────────────────────────────── */
 
-function cmdPattern() {
+/**
+ * The copy-in tiers share one retrieval shape: list, detail, skeleton, code.
+ * Patterns are page shells; blocks are section-sized (a card, a form) and add
+ * a family and a designed width.
+ */
+function cmdComposition({ kind, items, about, noun, errorCode }) {
 	if (flags.has("list") || !rest[0]) {
-		const data = PATTERNS.map((p) => ({ name: p.name, summary: p.summary, intent: p.intent }))
-		return ok("pattern.list", { count: data.length, about: R.patterns?.about, patterns: data }, () =>
+		const family = flags.get("family")
+		const list = family ? items.filter((x) => x.family?.toLowerCase() === String(family).toLowerCase()) : items
+		const data = list.map((x) => ({
+			name: x.name,
+			...(x.family ? { family: x.family } : {}),
+			summary: x.summary,
+			intent: x.intent,
+		}))
+		return ok(`${kind}.list`, { count: data.length, about, [`${kind}s`]: data }, () =>
 			[
-				DENSE ? "" : `${data.length} canonical page shells. Read a skeleton before composing anything:\n`,
-				...data.map((p) =>
+				DENSE ? "" : `${data.length} ${noun}${family ? ` in ${family}` : ""}. Read a skeleton before composing anything:\n`,
+				...data.map((x) =>
 					DENSE
-						? `${p.name} ${firstSentence(p.summary)}`
-						: `  ${p.name.padEnd(20)}${firstSentence(p.intent ?? p.summary)}`,
+						? `${x.name} ${firstSentence(x.summary)}`
+						: `  ${x.name.padEnd(kind === "block" ? 28 : 20)}${x.family ? x.family.padEnd(20) : ""}${firstSentence(x.intent ?? x.summary)}`,
 				),
-				DENSE ? "" : "\n  sable pattern <Name> --skeleton   the composition tree, ~25 lines",
+				DENSE ? "" : `\n  sable ${kind} <Name> --skeleton   the composition tree, ~25 lines`,
 			]
 				.filter(Boolean)
 				.join("\n"),
@@ -705,30 +736,31 @@ function cmdPattern() {
 	}
 
 	const name = rest[0]
-	const p = PATTERNS.find((x) => x.name.toLowerCase() === name.toLowerCase())
+	const p = items.find((x) => x.name.toLowerCase() === name.toLowerCase())
 	if (!p)
-		fail("ERR_UNKNOWN_PATTERN", `No pattern named "${name}".`, [
-			...nearest(name, PATTERNS.map((x) => x.name)).map((n) => `Did you mean ${n}?`),
-			"sable pattern --list",
+		fail(errorCode, `No ${kind} named "${name}".`, [
+			...nearest(name, items.map((x) => x.name)).map((n) => `Did you mean ${n}?`),
+			`sable ${kind} --list`,
 		])
 
 	if (flags.has("skeleton")) {
 		const { tree, elided } = skeletonize(p.code)
-		return ok("pattern.skeleton", { name: p.name, tree, elidedFixtures: elided }, () =>
+		return ok(`${kind}.skeleton`, { name: p.name, tree, elidedFixtures: elided }, () =>
 			[
 				DENSE ? "" : `${p.name} — composition tree${elided ? ` (${elided} demo fixtures elided)` : ""}\n`,
 				tree,
-				DENSE ? "" : `\nFull source: sable pattern ${p.name} --code`,
+				DENSE ? "" : `\nFull source: sable ${kind} ${p.name} --code`,
 			]
 				.filter(Boolean)
 				.join("\n"),
 		)
 	}
 	if (flags.has("code"))
-		return ok("pattern.code", { name: p.name, imports: p.imports, code: p.code }, () => `${p.imports}\n\n${p.code}`)
+		return ok(`${kind}.code`, { name: p.name, imports: p.imports, code: p.code }, () => `${p.imports}\n\n${p.code}`)
 
 	const level = detailLevel("compact")
 	const data = { name: p.name, path: p.path, summary: p.summary, intent: p.intent }
+	if (p.family) Object.assign(data, { family: p.family, kind: p.kind, ...(p.width ? { width: p.width } : {}) })
 	if (level !== "brief") {
 		data.notes = p.notes ?? []
 		data.a11y = p.a11y ?? []
@@ -738,21 +770,30 @@ function cmdPattern() {
 		data.imports = p.imports
 		data.code = p.code
 	}
-	ok("pattern.detail", data, () =>
+	const shape = p.family ? `  ${p.family} · ${p.kind}${p.width ? ` · ${p.width.min}–${p.width.max}` : ""}` : ""
+	ok(`${kind}.detail`, data, () =>
 		[
-			`${p.name}  (${p.path})`,
+			`${p.name}  (${p.path})${shape}`,
 			p.summary,
 			p.intent ? `\nReach for it when:\n  ${p.intent}` : "",
 			level === "brief" ? "" : section("notes", (p.notes ?? []).map(bullet)),
 			level === "brief" ? "" : section("a11y", (p.a11y ?? []).map(bullet)),
 			level === "brief" ? "" : `\nComposition:\n${data.skeleton}`,
-			level === "full" ? `\n${p.imports}\n\n${p.code}` : `\nFull source: sable pattern ${p.name} --code`,
+			level === "full" ? `\n${p.imports}\n\n${p.code}` : `\nFull source: sable ${kind} ${p.name} --code`,
 		]
 			.filter(Boolean)
 			.join("\n"),
 	)
 }
 
+function cmdPattern() {
+	cmdComposition({ kind: "pattern", items: PATTERNS, about: R.patterns?.about, noun: "canonical page shells", errorCode: "ERR_UNKNOWN_PATTERN" })
+}
+
+function cmdBlock() {
+	cmdComposition({ kind: "block", items: BLOCKS, about: R.blocks?.about, noun: "blocks", errorCode: "ERR_UNKNOWN_BLOCK" })
+}
+
 /* ── layout ─────────────────────────────────────────────────────────────────── */
 
 function cmdLayout() {
@@ -1183,6 +1224,7 @@ const HANDLERS = {
 	search: cmdSearch,
 	component: cmdComponent,
 	pattern: cmdPattern,
+	block: cmdBlock,
 	layout: cmdLayout,
 	token: cmdToken,
 	utility: cmdUtility,

package/dist/{_contract-CYScOdf5.d.ts → _contract-o3tUc8Ig.d.ts}

@@ -7,7 +7,7 @@
  * To author a new theme: copy `themes/base/`, keep these token names, and
  * supply your own palette + values. See CONTRIBUTING.md → "Theme contract".
  */
-declare const SEMANTIC_TOKENS: readonly ["background", "foreground", "card", "card-foreground", "popover", "popover-foreground", "muted", "muted-foreground", "border", "border-strong", "input", "ring", "primary", "primary-foreground", "secondary", "secondary-foreground", "accent", "accent-foreground", "destructive", "destructive-foreground", "success", "success-foreground", "tone-standard", "tone-collectible", "tone-edition", "tone-info", "tone-warning", "highlight", "tone-standard-foreground", "tone-collectible-foreground", "tone-edition-foreground", "tone-info-foreground", "tone-warning-foreground", "highlight-foreground", "overlay", "overlay-foreground", "sidebar", "sidebar-foreground", "sidebar-primary", "sidebar-primary-foreground", "sidebar-accent", "sidebar-accent-foreground", "sidebar-border", "sidebar-ring"];
+declare const SEMANTIC_TOKENS: readonly ["background", "foreground", "card", "card-foreground", "popover", "popover-foreground", "muted", "muted-foreground", "border", "border-strong", "input", "control-border", "ring", "primary", "primary-foreground", "secondary", "secondary-foreground", "accent", "accent-foreground", "destructive", "destructive-foreground", "success", "success-foreground", "tone-standard", "tone-collectible", "tone-edition", "tone-info", "tone-warning", "highlight", "tone-standard-foreground", "tone-collectible-foreground", "tone-edition-foreground", "tone-info-foreground", "tone-warning-foreground", "highlight-foreground", "overlay", "overlay-foreground", "sidebar", "sidebar-foreground", "sidebar-primary", "sidebar-primary-foreground", "sidebar-accent", "sidebar-accent-foreground", "sidebar-border", "sidebar-ring"];
 type SemanticToken = (typeof SEMANTIC_TOKENS)[number];
 /**
  * Motion tokens (mode-independent). A theme MAY override these to retune its