@sableui/react 0.6.2 → 0.7.1

package/AGENTS.md

@@ -32,7 +32,7 @@ library gap to report, not a reason for a native control.
 
 These are short on purpose. Each links to a foundations doc with the full vocabulary, the reasoning, and before/after examples; `sable-lint` catches most violations.
 
-0. **Compose from Sable components; never rebuild one.** Before writing any interactive or recognisable element — a button, a field, a toggle, tabs, a menu, a badge, a card, a search box, a dialog — run `npx sable search "<what you need>"` and use what it returns. A raw `<button>`, `<input>` or `<div>` dressed in a component's classes is a reinvention, and it is a bug even when every class is a semantic token: it misses the component's states, density, focus and keyboard contract, and drifts the moment the component changes. A link that looks like a button is `<Button render={<a href=… />}>`. If nothing fits, compose from the nearest component's parts; if it genuinely does not exist, say so in your summary — that is a library gap to report, not a license to invent. The rules below are for styling what you compose *around* components, not for re-creating them. `sable-lint` flags the common cases (`hand-rolled-control`, `lookalike-control`).
+0. **Compose from Sable components; never rebuild one.** Before writing any interactive or recognisable element — a button, a field, a toggle, tabs, a menu, a badge, a card, a search box, a dialog — run `npx sable search "<what you need>"` and use what it returns. A raw `<button>`, `<input>` or `<div>` dressed in a component's classes is a reinvention, and it is a bug even when every class is a semantic token: it misses the component's states, density, focus and keyboard contract, and drifts the moment the component changes. A link that looks like a button is `<Button render={<a href=… />}>`. If nothing fits, compose from the nearest component's parts; if it genuinely does not exist, say so in your summary — that is a library gap to report, not a license to invent. The rules below are for styling what you compose *around* components, not for re-creating them. `sable-lint` flags the common cases (`hand-rolled-control`, `lookalike-control`), and the bigger assemblies built from utilities and tokens: a raw `grid` of mapped items is `<Grid cols minItemWidth>` (`lookalike-grid`), a link or button wearing a card's radius, surface and padding is `<Card render={<Link … />}>` (`lookalike-card`), a round fixed-size box holding a picture, GradientArt or initials is `<Avatar>` (`lookalike-avatar`), and an `aspect-*` + `overflow-hidden` frame around media is `<AspectBox ratio>` (`lookalike-media-frame`). `sable check` also lists every app-owned surface (a card fill, a bordered padded box, a media frame, a fixed-size circle) for your reuse inventory: each one composes the component named beside it, or the inventory says why the app owns it.
 
    **The same goes for everything below a component. Resolve in this order, and stop at the first that fits:** (1) a **component** → (2) a Sable **utility or recipe** — relative surfaces (`sable-surface*`, `sable-well`, `sable-surface-interactive`), state variants (`sable-selected:`, `sable-highlighted:`…), geometry (`rounded-concentric-*`, `popup-inset`, `rounded-popup-item`, `popup-bleed`), scroll policies, `motion-*` recipes → (3) a **semantic token** → (4) hand-written CSS, last, and reported as a gap. `npx sable search "<what you need>"` searches all of these; `registry.json → utilities` lists the utilities with intent and what each replaces. Mixing ink into a surface by hand (`color-mix(… var(--foreground) …)`) is the tell that you skipped step 2 — that is what the relative-surface utilities compute, in every theme and mode.
 
@@ -61,7 +61,7 @@ The machine-readable version of this section is the `consume` block in `registry
 
    `styles.css` carries **Sable 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 the Sable theme — 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)` (list the added names in `.sable/icons.json` as `{ "names": [...] }` so `sable grade` accepts them); `<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).
+5. **Providers:** `<IconProvider>` is **required** — wrap the app once in `<IconProvider set={reiconIconSet}>` with `import { reiconIconSet } from "@sableui/react/icons/reicon"` (without it every `<Icon>` renders nothing; development builds warn once). Pass another icon package's set instead to replace Reicon, or extend it using `composeIconSets(appExtras, reiconIconSet)` (list the added names in `.sable/icons.json` as `{ "names": [...] }` so `sable grade` accepts them); `<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. 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 the Sable theme and the switcher looks broken). Exits 1 on any failure; `--json` for the structured report.

package/CHANGELOG.md

@@ -1,5 +1,320 @@
 # What's new
 
+## 0.7.1
+
+Fixes from building a customer-support app on 0.7.0 with an app-owned preset,
+plus guidance for choosing a page width. Nothing to migrate.
+
+- **A table in a flush card keeps the card's corners.** `Card` now clips to its
+  rounded corners when it holds a `CardContent flush`, as it already did for a
+  `CardList`. The hover fill of an edge-to-edge `Table` or `DataTable` row and a
+  `TableFooter`'s tint no longer poke square corners out past the card's.
+- **Only body rows hover.** `TableRow` lifts on hover inside `TableBody`; header
+  and footer rows stay still, since nothing there responds to a click.
+- **SideNav and Sidebar icons stay level with their labels at any spacing
+  step.** The icon box was sized in spacing steps around an icon sized in type,
+  so a theme with a step other than 4px shrank the box and dropped every icon
+  about 2px below its label. The box is now sized in the icon's own unit and
+  centred with flex.
+- **A donut's number holds the centre.** In `PieChart` and a full-ring
+  `RadialChart`, `centerLabel`'s value sits on the centre and its caption hangs
+  below, instead of the pair splitting the centre between them.
+- **`centerLabel.value` takes a number.** It is written in full up to 9,999 and
+  shortened from 10,000 on (`10.2K`, `102.1K`, `1.2M`), in the chart's
+  `locale`. A string still shows as written, for units.
+- **Presets can set page widths.** `page-inset` and the role caps
+  (`region-form`, `-feed`, `-content`, `-wide`, `-full`) are preset tokens, so a
+  product's widths live in its preset rather than app CSS. They are opt-in:
+  `sable preset --template` and Canvas exports leave them out, so a preset never
+  overrides widths an app already sets. `PAGE_WIDTH_TOKENS` lists them.
+- **Guidance for choosing a page width.** `sable docs building-a-page` has a
+  table of which `max` to use by what the person does on the page, and when to
+  go fluid. The Region docs say `full` is the largest cap (edge to edge is
+  `bleed`) and show a fluid workspace; the old "Fluid dashboard" example was
+  capped and is retitled. `reviewing-a-design` asks for a 1920px capture of a
+  capped or fluid route, where the choice shows, and the skill's brief records
+  each route's width.
+- **A pasted preset gets applied.** Canvas's "Copy for agent" message now asks
+  the agent to apply the preset and build the app, not only save it. The skill
+  treats a preset supplied for an existing app as a restyle, `sable docs
+  using-presets` has an "Apply to an existing app" section, and a passing
+  `sable preset --check` lists the steps that make an app use the preset.
+- **`TrafficTrendBlock` fits a narrow card.** Below 24rem its range toggles
+  move under the title instead of squeezing it.
+
+## 0.7.0
+
+A dogfooding release. An agent built a music streaming app on Sable with
+Sable's own skill, and this release closes the gaps it hit:
+- media tiles, an image fallback and a persistent player dock;
+- section headers, portrait avatars and in-place pickers;
+- labelled sliders and focusable text links.
+The package is also much smaller per import, `sable check` runs the whole
+finish check in one command, and lint now catches hand-assembled lookalikes of
+Sable components.
+
+### Upgrading from 0.6
+
+- **Icons are opt-in.** Wrap the app once in `<IconProvider set={reiconIconSet}>`,
+  with `reiconIconSet` from `@sableui/react/icons/reicon`. Without it, every
+  `<Icon>` (including those inside Sable components) renders nothing, and
+  `sable doctor` reports it.
+- **`SableThemeProvider` defaults to `"system"`.** Pass
+  `defaultPreference="dark"` to keep the old first-visit mode.
+- **`Grid minItemWidth` keeps its empty columns (`auto-fill`).** Pass
+  `track="fit"` where a fixed set should stretch across the row.
+- **Button's side padding is a variable.** A `px-*` className on a Button no
+  longer matches its optical alignment (`bleed`). Set `--button-px` instead.
+
+### Everything in this release
+
+- **`SableThemeProvider` follows the visitor's OS on a first visit.**
+  `defaultPreference` now defaults to `"system"` instead of `"dark"`. A stored
+  choice still wins. **Behaviour change:** an app that relied on the implicit
+  dark default should pass `defaultPreference="dark"` (or its preset's
+  `defaultMode`).
+- **`Slider` names the slider, not its wrapper.** `aria-label` used to land on
+  the Root's `role="group"`, so screen readers announced an unnamed slider. It
+  now goes to each thumb's input. New `getAriaLabel` (per thumb, for ranges)
+  and `getAriaValueText` (e.g. a seek bar's "1:23 of 3:45").
+- **AppShell `dock` slot** for persistent chrome such as a now-playing or call
+  bar. It is full width and sticky to the bottom, above `bottomNav` on mobile,
+  and the app Sidebar shortens to clear it.
+- **`link-underline` carries a focus-visible outline** in `--ring`, so plain
+  text links meet the focus floor without app CSS.
+- **Media icons:** `shuffle`, `repeat`, `repeat-one`, `volume`, `volume-low`,
+  `volume-off`, `queue`, `music`.
+- **`--theme-art-brand` hook.** Ember's and Prism's art (and the default art
+  ground) key off it, falling back to `--primary`. Set it wherever the primary
+  action stops being the brand, such as a neutral black/white primary, so the
+  art keeps the brand colour.
+- **`sable lint`'s `static-interactive` rule reads variants, not substrings.**
+  A capability query like `[@media(hover:none)]:opacity-100` is no longer
+  mistaken for a hover style.
+- **Breaking: icons are opt-in.** `<Icon>` no longer falls back to Reicon, so
+  an app that brings its own set ships none of Reicon's artwork (about 190 KB
+  minified). Without an `IconProvider`, icons render nothing and a development
+  build warns once. `reiconIconSet`, `reiconIconNames` and the deprecated
+  `fallbackIconSet` moved off the root (and `/icons`) barrel to
+  `@sableui/react/icons/reicon`. **Migrate:** wrap the app once in
+  `<IconProvider set={reiconIconSet}>` with
+  `import { reiconIconSet } from "@sableui/react/icons/reicon"`.
+- **Smaller bundles: the package ships one module per source file.** `dist`
+  keeps the `src` layout instead of a few large bundles, so a bundler drops
+  every component an app does not import. Importing only `Button` used to pull
+  in about 70% of the library under esbuild; the import paths and exports are
+  unchanged. Each module also keeps its `"use client"` directive.
+- **GradientArt loads its WebGL renderer on first paint.** The shader code
+  (about 43 KB minified) is a separate chunk, so a plain `Avatar` no longer
+  ships it, and art still shows its CSS stand-in until the shader fades in.
+- **`OtpField` resolves Base UI's OTP parts when it first renders**, so apps
+  that never use it no longer carry Base UI's OTP Field.
+- **`sable check`: one command to run before calling a build done.** It runs
+  `sable doctor`, `sable lint` and `sable grade` on the given paths (default
+  `src`), prints one pass/fail summary, exits 1 if any fails, and then lists the
+  review steps no tool can verify (rendered design, journey, motion, reduced
+  motion, reuse inventory, lessons). `--json` returns `{ type: "check", data }`.
+  The skill's finish checklist now opens the skill and starts with it.
+- **`sable setup --agent` offers a Claude Code Stop hook** that runs
+  `sable check --stop-hook` before Claude can end a task: on failure it exits 2
+  with the findings on stderr, so Claude keeps working (once; a second
+  consecutive block lets it stop). Setup prints the exact `.claude/settings.json`
+  entry and writes it only with `--hook`, merging into existing settings. The
+  command is one plain invocation with no `cd`, `&&` or `${…}`, so it runs under
+  Git Bash and PowerShell 5.1 alike; `sable check --stop-hook` locates the
+  project from `CLAUDE_PROJECT_DIR` (plus `--root <dir>` for a workspace
+  package, reached with the package manager's workspace flag).
+- **`sable grade` judges each import against the subpath it came from.** It
+  checked every `@sableui/react/*` import against the root barrel, so correct
+  imports from `/blocks`, `/presets` or `/icons/reicon` read as hallucinations
+  (25 in Sable's own docs app). Each subpath's surface is now read from the
+  package `exports`, an unpublished subpath is reported as such, and
+  `reiconIconSet` imported from the root is caught. Props and icon names are
+  judged only on components imported from Sable (aliases followed), not on an
+  app's own `PageHeader` or `Icon`, and not on JSX inside template-literal code
+  samples. Media attributes such as `autoPlay` are accepted.
+- **`sable doctor` checks icons.** An app that imports Sable with no
+  `<IconProvider>` fails with the fix, since every icon would render nothing.
+- **Global flags work on every command.** `sable learn --search "…" --dense`
+  failed with "Unknown flag: --dense"; `--dense` and `--detail` are now taken out
+  before a command hands off to its script, and `--json --dense` prints that
+  script's JSON on one line. A switch no longer swallows the next word
+  (`sable component --dense Button`), and a bad `--detail` value is an error on
+  every command.
+- **Every utility in styles.css is retrievable.** `sable utility
+  motion-icon-swap` answered ERR_UNKNOWN_UTILITY: the 24 `motion-*`/`animate-*`
+  recipes were only names in `tokens.motion.recipes`. They now have full entries
+  (family `motion`), and `sable utility text-heading-1` resolves the paired type
+  tiers. A test asks the CLI for every `@utility` and `@custom-variant`, with an
+  explicit `INTERNAL_UTILITIES` list for deliberate exceptions.
+- **Providers are in the catalog.** New `sable provider [Name]` and
+  `registry.json → providers` cover SableThemeProvider, IconProvider,
+  MotionProvider, ToastProvider, TooltipProvider, CodeHighlightProvider,
+  DensityProvider and PresentationProvider: whether each is required, where it
+  goes, props and examples. `sable component SableThemeProvider` answers with the
+  provider, and search finds them. The build fails on an exported `*Provider`
+  documented nowhere.
+- **`sable docs AGENTS` serves the package's AGENTS.md** (also README,
+  CONTRIBUTING, DESIGN, CHANGELOG and llms), the file llms.txt points agents to
+  first. An unknown doc now lists the package and task guide names.
+- **`sable lint --json`** returns `{ type: "lint", data: { violations, … } }`.
+  The skill already told agents to pass `--json`; it printed text.
+- **`sable preset --check` warns when a preset is newer than the installed
+  Sable.** A preset authored with a later `sableVersion` used to validate
+  silently. It still validates, but now prints both versions and the upgrade
+  command for the project's package manager; `--json` carries it as
+  `warnings: [{ code: "WARN_PRESET_NEWER_SABLE", authoredWith, installed,
+  suggestion }]`. `--css` reports the same warning.
+- **`sable grade --template` shows what an artifact looks like.** It now starts
+  with one example screenshot and one example report artifact (they fail
+  validation until replaced with real captures), and `sable docs
+  reviewing-a-design` lists every artifact field with its meaning.
+- **`SheetList`**: edge-to-edge rows in a Sheet (a queue, notifications, a
+  picker), the Sheet equivalent of `CardList`. Entity rows line up with
+  `SheetHeader` instead of sitting 12px in, with no `--entity-px` override. The
+  Sheet's padding is now the `--sheet-p` variable.
+- **`SidebarBrand`**: the brand row on the same grid as `SidebarItem`, with the
+  mark in the icon slot and the name on the label column. It collapses to the
+  mark. The dashboard and settings patterns use it.
+- **GradientArt gives each seed its own variant of the palette.** The palette
+  turns by up to ±20° of hue and ±0.04 lightness, so presets whose art is one
+  colour family (Ember, brand-derived palettes) still tell artists and covers
+  apart. The same seed still paints the same art.
+- **Selected table rows paint their fill on the cells**, each overlapping the
+  next by 1px, to rule out hairline seams at fractional column widths.
+- **`MediaPlayerBlock`'s seek bar runs in seconds.** The readouts follow the
+  drag, and the slider announces "1:24 of 3:40".
+- **`static-interactive` explains display-only hovers.** When a hover only
+  flips `display`, visibility or an underline, the hint points at an opacity
+  swap or `motion-icon-swap` instead of `motion-interactive`.
+- **ThemeSelector draws each theme as a miniature of itself.** Each tile is
+  the theme's background, "Aa" in its display face, a card, and a primary
+  button whose corners scale from the theme's real radii, so it shows shape as
+  well as colour. Four of six themes used to come out as the same
+  white-and-black strip. Names sit in the app's face, so every option is the
+  same height. The selected tile takes an outline in the app's own ink, and
+  list rows carry a small tile. A light preview is now pinned with `.light`, so
+  a dark page no longer paints it dark. The docs' Customize panel uses this
+  component instead of its own preset tiles.
+- **Segmented controls follow the theme's control shape.** ThemeSwitcher and
+  ToggleGroup `appearance="segmented"` take `--button-radius`, the same corners
+  as Button: square in Meridian, 12px in Poppy, a capsule in Sable.
+- **`sable lint` catches assemblies, not just controls.** Four new
+  consumer rules (new in 0.7.0, so `sable-lint --since 0.6.2` lists them) find
+  pieces built from Sable's utilities and tokens, which every token rule passes:
+  `lookalike-grid` (a raw `grid` over mapped or repeated items, or an
+  auto-fill `minmax()` track → `Grid`, with the `cols` map spelled out),
+  `lookalike-card` (an `<a>`, `<button>` or router `<Link>` with a card's
+  radius, surface and padding → `Card render={…}`), `lookalike-avatar` (a
+  round fixed-size box holding an image, GradientArt or initials → `Avatar`)
+  and `lookalike-media-frame` (`aspect-*` + `overflow-hidden` around media →
+  `AspectBox`). Each needs a signal beyond the classes, so a form grid, a text
+  link, a status dot or an empty ratio box is left alone. The docs site's own
+  item grids now compose `Grid`.
+- **`sable grade` and `sable check` list app-owned surfaces.** Elements with a
+  card fill, a bordered padded box, a media frame or a fixed-size circle are
+  listed with the component to consider (`inventory` in `--json`). The list is
+  never scored and never fails a check; it is the starting point for the reuse
+  inventory.
+- **`MediaTile`: a cover-first tile** for albums, videos, podcasts, galleries
+  and shelves. Square, `video` or `poster` cover, a title and subtitle that
+  can each be links (`href` / `render={<Link />}`, `subtitleHref` /
+  `subtitleRender`), an `action` over the cover's corner and a `badge` on it.
+  The whole tile follows the title's link without wrapping anything in an
+  `<a>`, so the artist link and the play button stay separate controls; Tab
+  goes title → subtitle → action.
+- **`MediaImage`: an image with a fallback.** It fills its box, rests on a
+  muted surface while loading, fades the image in, and paints GradientArt
+  seeded by the item when there is no `src` or it fails to load. It uses
+  Base UI's image-load tracking, the same Avatar uses, so a failure before
+  hydration is still caught. `MediaPlayerBlock` and `ProductCardBlock` use it
+  for their artwork; add the image URL to their content constant.
+- **`reveal-on-hover` utility** for row and tile actions that wait for hover.
+  It hides the action only on devices that can hover, shows it on hover or
+  focus within the nearest `group` (or `data-reveal-scope`) and while its menu
+  is open, and fades on the motion tokens. The action stays in the tab order
+  and the accessibility tree, and touch devices always show it. `sable lint`'s
+  `static-interactive` rule accepts it as a recipe and now suggests it for a
+  hand-written `group-hover:opacity-*` reveal.
+- **`stretched-link` utility.** One link covers its whole item while the
+  item's other controls stay clickable, and its focus ring goes around the
+  item (`--stretched-link-radius`).
+- **`SectionHeader`** heads each section below the page title: an h2 by
+  default (`titleAs` for h3/h4), an optional description, and actions on the
+  title row, such as a "View all" link or two small buttons. The actions drop
+  beneath the title only when the row runs out of room. `size` sets the look
+  apart from the level (`md` text-heading-3, `sm` text-heading-4), and the
+  title always carries an id (`titleId`, or a generated one) for
+  `<section aria-labelledby>`. It shares PageHeader's title row and has no outer
+  spacing, so the section's gap sets the rhythm. PageHeader's docs now point a
+  second heading to it.
+- **Avatar `xl` (96px) and `2xl` (160px)** for portraits: profile headers,
+  artist heroes and roster tiles. The initials move to `text-heading-2` /
+  `text-display-lg`, about a third of the circle as at row sizes. A `status`
+  indicator and its cut-out ring scale with the portrait, and the photo fades
+  in over the resting surface. AvatarGroup stays at `sm`–`lg`.
+- **Breaking: `Grid minItemWidth` keeps empty columns (`auto-fill`).** With one
+  or two items, `auto-fit` collapsed the empty tracks and stretched each item
+  across the row, so a single search result rendered as a full-width cover.
+  New `track` prop: `"fill"` (default) keeps items at their size whatever their
+  count; `"fit"` restores the old stretch for a fixed set designed to span the
+  row. **Migrate:** add `track="fit"` to a grid of a known, fixed number of
+  cards that should share the row (a KPI row, plan tiers).
+- **New `DisclosurePicker`:** a property row that names the current value and
+  opens its list in place, beneath the row, instead of in a popup, for a tool
+  panel where the choice is made while looking at what it changes. Parts:
+  `DisclosurePickerTrigger` (optional `label` caption and `media`, the value,
+  a chevron that flips), `DisclosurePickerPanel`, `DisclosurePickerList` (a
+  listbox: arrows move, Enter/Space/click pick and close),
+  `DisclosurePickerOption` (optional `media` and `note`) and
+  `DisclosurePickerEmpty`, plus `useDisclosurePicker()` for a list it does not
+  own, such as a Tree.
+  Search is opt-in (`search` on the panel), for lists past about a dozen
+  options. Keyboard opens move focus to the search field or the chosen option;
+  Escape and picks return it to the row. `size="xs"` sits on the
+  property-grid rung.
+- **New `FontPicker`,** built on DisclosurePicker: the row names the family in
+  its own face, and the list draws each family in itself. Fonts and loading
+  come from the app (`fonts`, `loadFont(font, "preview" | "use")`); Sable
+  bundles no catalog. Search is on by default; pass `searchable={false}` for a
+  short list.
+- **Button `bleed` — optical alignment for borderless buttons.** A ghost or
+  link button carries padding you can't see, so at the start or end of a row
+  its label sat ~12px inside the edge the row shares. `bleed="start" | "end" |
+  "both"` pulls the box out by exactly its own padding (the size's new
+  `--button-px`, which the padding now reads; the icon side's optical padding
+  when an icon sits there; an icon-only size's inset to its glyph), so the
+  label lands on the edge while the hit area and hover fill keep their full
+  size. Logical sides, so RTL mirrors. A no-op on variants with a visible edge
+  (primary, secondary, outline, destructive, floating, field, on-color,
+  on-color-outline). SectionHeader and PageHeader actions, PageHeader's back
+  control and CardAction now align their outermost ghost/link Button
+  automatically (it renders `data-bleed="auto"`; `bleed="none"` opts out);
+  when a header's actions wrap beneath the title, the first one aligns to the
+  start edge. Applied in the dashboard, feed and list-detail patterns and the
+  task-list and verify-code blocks (the feed's hand-set `-ms-3` is gone).
+  **Migrate:** replace `-ms-3` / `-me-3` nudges on ghost buttons with `bleed`;
+  to retune a button's padding set `[--button-px:…]` rather than `px-*`.
+- **`DisclosurePicker` commits on Enter, not on every arrow key.** Its list
+  was a radio group, whose checked state follows focus, so each arrow press
+  called `onValueChange`: in the docs Customize panel the first ArrowDown on
+  the preset row switched presets (or opened "discard changes?"), and on a font
+  row loaded every family passed. The list is now a `role="listbox"` of
+  `role="option"` rows: ArrowUp/ArrowDown, Home/End and type-ahead move focus
+  (roving tabindex) and apply nothing; Enter, Space or a click picks, applies
+  and closes; Escape closes with the value untouched. `aria-selected` marks the
+  committed value. `onValueChange` fires once per pick, and not when the pick
+  is the current value. ArrowUp from the first option returns to the search
+  field. New on `DisclosurePickerOption`: `media` (a leading tile),
+  `disabled`, `textValue` (what type-ahead matches). Changed from the
+  unreleased radio version: the list takes div props instead of RadioGroup
+  props, options are no longer
+  `role="radio"`, and `DisclosurePickerEmpty` belongs in place of the list,
+  not inside it. **FontPicker** inherits it: arrows walk the families, Enter
+  picks and loads one. ThemeSelector's `layout="list"` stays a radio group
+  (instant switching is standard there); its guidance now says to use a
+  DisclosurePicker list with `ThemePreview` media when a switch has a cost.
+
 ## 0.6.2
 
 - **`llms.txt` names the default theme correctly.** Its summary still called

package/CONTRIBUTING.md

@@ -11,7 +11,7 @@ The checks are the specification. Every rule below names the gate that enforces
 1. **Components reference semantic tokens only.** Use `bg-card`, `text-muted-foreground`, `bg-tone-edition`, `text-primary`, etc. — never raw palette steps (`--purple-heart-700`) and never inline `oklch()`/hex. For text/icons on a tone fill use the theme-adaptive `text-tone-*-foreground` ink (no `dark:` variant); for scrims, media letterbox, and pills on imagery use `bg-overlay`/`text-overlay-foreground`. Palette names are theme-internal; a component that names a palette breaks themeability — and `design-lint`'s `palette-ref` rule now has **zero** sanctioned exceptions.
 2. **Paired typography utilities, never decomposed.** Use `text-heading-1`, `text-body-md`, `text-label-lg`, … Each bundles size + weight + line-height + tracking. Do **not** combine `text-{size}` + `font-{weight}` + `tracking-{x}` by hand. (Icons are the exception — size them with `text-{size}` scales, never type utilities.)
 3. **Base UI is behavior; `components/` is the public API.** Each component wraps `@base-ui/react` directly inside its own folder (use the **`render` prop** for composition; read state from `data-[state=…]` attributes) and owns 100% of the styling. There is no separate primitives tier. Consumers import only from the package root barrel.
-4. **Semantic icons in components.** Use `<Icon name="…">`; Reicon is the default. Concrete icon-package imports belong only in `src/icon-sets/`. Apps may override or extend the set through `<IconProvider>`.
+4. **Semantic icons in components.** Use `<Icon name="…">`. Concrete icon-package imports belong only in `src/icon-sets/`, which nothing in the core graph imports. Apps supply the set through `<IconProvider>` (Reicon from `@sableui/react/icons/reicon`, or their own).
 5. **Every scroll container declares a scrollbar policy.** An `overflow-*-auto|scroll` utility must be paired with `scrollbar-quiet` (a 4px thumb, invisible at rest, fading in while the region scrolls) or `scrollbar-hidden` (no bar — only when something else carries the affordance, and you should be able to name it). Left bare, the platform draws its own: on Windows that means stepper arrows hard against the padding edge, poking out of any rounded corner. Vertical scrolling takes a bar; **horizontal takes none** — an edge fade says "there is more this way" better than a rail does, which is why `Scroller` splits by axis. New scroll container? Reach for `useScrollActivity` so the bar appears on touch drags and programmatic scrolls, which hover cannot see. Enforced by `design-lint`'s `unmanaged-overflow` **and** by `build-registry` over every registry example. Full rationale: `DESIGN.md → Scrolling`.
 6. **Tailwind v4 packaging discipline.** `src/styles.css` must **not** `@import "tailwindcss"` (the consumer owns that). It carries only token blocks, `@theme inline` mappings, `@utility` typography, layout vars, and `@source`. `@source` points at `src` (never the gitignored `dist`).
 
@@ -139,19 +139,25 @@ The manifest's `fonts` field is `{ sans: string; mono: string; display?: string
 ## Icon contract
 
 Components reference semantic names through `<Icon name="…" />`. Reicon (MIT)
-is the default, installed as a runtime dependency and kept external to the build.
-Concrete icon imports belong only in `src/icon-sets/`; components never import
-an icon package or duplicate its SVG artwork.
-
-- **Use the default:** render components without an icon provider.
+is the bundled set, installed as a runtime dependency and kept external to the
+build. It is opt-in: `<Icon>` has no fallback, so an app that brings its own set
+ships none of Reicon's artwork. Concrete icon imports belong only in
+`src/icon-sets/`; components never import an icon package or duplicate its SVG
+artwork, and nothing in the core graph imports `src/icon-sets/`.
+
+- **Use Reicon:** `import { reiconIconSet } from "@sableui/react/icons/reicon"` and
+  mount `<IconProvider set={reiconIconSet}>` once at the app root. Without a
+  provider, icons render nothing and a development build warns once.
 - **Replace the package:** pass your own `IconSet` to `<IconProvider set={mySet}>`.
   Map semantic names to that package's components; preserve className, variant,
   spin and accessible labels. Return `null` for unknown names.
-- **Extend Reicon:** import `composeIconSets` and `reiconIconSet` from Sable and
-  use `<IconProvider set={composeIconSets(appExtras, reiconIconSet)}>`.
+- **Extend Reicon:** import `composeIconSets` from Sable and `reiconIconSet` from
+  `@sableui/react/icons/reicon`, then use
+  `<IconProvider set={composeIconSets(appExtras, reiconIconSet)}>`.
   The first set returning a non-null node wins.
-- `@sableui/react/icons/reicon` remains an alternative import for the same adapter.
-  `fallbackIconSet` is a deprecated alias of Reicon, with no separate artwork.
+- `@sableui/react/icons/reicon` is the only import path for the adapter; the root
+  barrel does not re-export it. `fallbackIconSet` is a deprecated alias of Reicon
+  on the same subpath, with no separate artwork.
 - Brand marks are a separate additive set at `@sableui/react/icons/brands`.
   The 23 marks are generated from licensed `reicon-brands` npm artwork by
   `pnpm icons:brands`, normalized to the 24-unit grid, and inherit currentColor.

package/DESIGN.md

@@ -329,7 +329,7 @@ The same 4px scale governs **sizes**, so controls, icons, and avatars all land o
 
 - **Controls** — `sm` h-8 (32, compact / chips) · **`md` h-10 (40) — the default** (Input, Button, Select, the field row) · `lg` h-12 (48, prominent / touch-first) · `xl` h-14 (56, hero / mobile CTA).
 - **Icons** — `xs` 14 · `sm` 16 · **`md` 20 — default UI glyph** · `lg` 24 · `xl` 32. Icons are em-sized with `text-{size}` (never type utilities) and inherit text color.
-- **Avatars / media** — `sm` 24 · `md` 32 · `lg` 40 · `xl` 48, then up the scale (`size-16`, `size-24`).
+- **Avatars** — `sm` 32 · **`md` 40 — default** · `lg` 48 (rows with a title and subtitle) · `xl` 96 (a profile header beside a name) · `2xl` 160 (an artist or profile hero, a roster portrait). `xl` doubles `lg` and `2xl` is ×1.67 again — steps far enough apart that two neighbours never read as the same size. Media beyond that is an `AspectBox`, not an avatar.
 - **Touch targets** — interactive elements clear **44×44px** (`size-11`, WCAG 2.5.5). A visually smaller control (a 32px icon button) keeps the 44px *hit* area via padding or hit-slop, not a bigger glyph. The `hit-target` utility is the sanctioned implementation: a centered 44px `::after`, so the hit area grows without the layout moving. Never on an `<input>` — replaced elements don't render pseudo-elements reliably; wrap it in a label instead.
 
 **Borderless controls need roughly twice the clearance of bordered ones.** A bordered control declares where it ends; a borderless one has nothing but the gap to say so, and two ghost buttons 12px apart read as one wide target. Budget around 24px between adjacent borderless controls where 12px would be right for bordered ones.
@@ -369,7 +369,7 @@ Sable's layout foundation is deliberately fluid: **edge-to-edge, with a fluid pa
 
 (`--region-ultrawide` 1800 is legacy; prefer `full`.)
 
-**Primitives** (in `src/layout/`): `Region` (fluid page region: `inset`, opt-in `max` as a named region *or any CSS length*, per-edge `safeArea`) · `Page` (route shell — `Region` + a vertically-rhythmic `Stack`) · `Grid` (CSS Grid; explicit `cols` or `auto-fit minmax` so cells breathe) · `Columns`/`Col` (track + spans) · `Bleed` (escapes a capped/inset ancestor to the **content-area** edge, via container-query units, so it stops at a fixed sidebar) · `SplitPane` (responsive two-pane, side-by-side above a breakpoint, stacked below) · `Stack` (vertical rhythm) · `Row` (horizontal flex) · `Spacer` · `Center` (optional prose cap) · `AspectBox` (reserves space, no layout shift) · `SafeArea` · `GridOverlay` (structure visualizer for docs/dev).
+**Primitives** (in `src/layout/`): `Region` (fluid page region: `inset`, opt-in `max` as a named region *or any CSS length*, per-edge `safeArea`) · `Page` (route shell — `Region` + a vertically-rhythmic `Stack`) · `Grid` (CSS Grid; explicit `cols` or `minItemWidth` cells that breathe — `auto-fill` by default, so a sparse row keeps its empty columns and one result stays one cell wide; `track="fit"` stretches a fixed set across the row) · `Columns`/`Col` (track + spans) · `Bleed` (escapes a capped/inset ancestor to the **content-area** edge, via container-query units, so it stops at a fixed sidebar) · `SplitPane` (responsive two-pane, side-by-side above a breakpoint, stacked below) · `Stack` (vertical rhythm) · `Row` (horizontal flex) · `Spacer` · `Center` (optional prose cap) · `AspectBox` (reserves space, no layout shift) · `SafeArea` · `GridOverlay` (structure visualizer for docs/dev).
 
 `Columns count`, `Col span`/`start`, and `Grid cols` accept either a number **or a responsive breakpoint map** (`{ base, sm, md, lg, xl, "2xl" }`) — resolved mobile-first by the stylesheet, so a grid can thin to fewer columns on small screens without the consumer's Tailwind scanning a class.
 
@@ -528,7 +528,7 @@ Not every removal is a regression; check for an **equivalent replacement** befor
 - Pure `#000`/`#fff` (use `zinc-950`/`zinc-50`, or `overlay`/`overlay-foreground` for scrims). *(CI-enforced: `raw-black-white`.)*
 - In the Sable theme, purple/brand for primary CTAs (brand = editions + selection only). A different theme chooses its action palette through the semantic pair.
 - Gradient text, side-stripe borders, nested cards, mixed radii.
-- Concrete icon-package imports scattered through components. Reicon supplies the default through the shared adapter; IconProvider allows replacement.
+- Concrete icon-package imports scattered through components. Reicon is an opt-in set behind the shared adapter; the app's IconProvider supplies it or a replacement.
 - A global page max-width (use opt-in region caps).
 - Off-scale spacing or sizing (`p-[15px]`, `h-[37px]`) — snap to the 4px scale. In a component, a fixed `rem`/`px` padding or gap also escapes the density control. *(CI-enforced in the package: `fixed-spacing`.)*
 - Restyling a library component with override classes to get a look it lacks (`<Button className="rounded-full bg-…">`, `<MenuItem className="text-destructive">`, `pl-6` on a table cell). Use or add a real variant. *(CI-enforced: `component-restyle`, `destructive-item-ink`, `table-edge-padding`.)*

package/README.md

@@ -21,7 +21,7 @@ in Sable.
 
 - **Behavior:** [Base UI](https://base-ui.com) (`@base-ui/react`) — accessible primitives, isolated behind our own component APIs.
 - **Styling:** Tailwind CSS v4 + semantic CSS-variable tokens; variants via `class-variance-authority`.
-- **Icons:** Reicon by default, with a pluggable adapter for any icon package.
+- **Icons:** opt-in through `IconProvider` — Reicon's set ships ready to mount, or plug in any icon package. Apps pay only for the set they choose.
 - **Motion:** a token-driven, zero-dependency motion layer (recipes, policy, browser-native primitives).
 - **Themeable:** components reference semantic tokens only; a theme is a CSS variable set.
 
@@ -98,7 +98,7 @@ function ThemeControls() {
   )
 }
 
-<IconProvider set={reiconIconSet}>       {/* optional — omit for Reicon, or pass another icon set */}
+<IconProvider set={reiconIconSet}>       {/* required — Reicon, or pass another icon set */}
   <MotionProvider>                    {/* optional — enables the motion on/off toggle */}
     <SableThemeProvider>              {/* optional, recommended when users can switch themes */}
       <App />
@@ -107,7 +107,7 @@ function ThemeControls() {
 </IconProvider>
 ```
 
-Components render Reicon icons out of the box. To replace Reicon, mount `<IconProvider set={yourIconSet}>`; to add domain icons, use `composeIconSets(appExtras, reiconIconSet)`. Both helpers and the `IconSet` type are exported from Sable. A set returns `null` for names it does not handle. List the names your extras add in `.sable/icons.json` (`{ "names": [...] }`) so `sable grade` counts them as icons the app supplies, not off-contract ones. `fallbackIconSet` remains a deprecated alias of Reicon for compatibility. `SableThemeProvider` is the preferred route for user-facing theme switching: it stores the user's color preference (`light` / `dark` / `system`), toggles the **`.dark` class**, stores the active design theme, and writes **`data-sable-theme`** for non-default themes. If your app already owns this state, use `applySableColorMode()` / `applySableTheme()` or the exported `SABLE_THEME_ATTRIBUTE` constant directly. You do **not** need a Tailwind `@custom-variant dark` for Sable itself — add one (`@custom-variant dark (&:where(.dark, .dark *));`) only if **your own** app code uses `dark:` utilities (Sable ships none).
+Icons are opt-in: mount `<IconProvider set={reiconIconSet}>` once at the app root, with `reiconIconSet` from `@sableui/react/icons/reicon` (its only import path). Without a provider every `<Icon>` renders nothing, and a development build warns once. An app that passes its own set ships none of Reicon's artwork. To add domain icons, use `composeIconSets(appExtras, reiconIconSet)`; `composeIconSets` and the `IconSet` type are exported from the root. A set returns `null` for names it does not handle. List the names your extras add in `.sable/icons.json` (`{ "names": [...] }`) so `sable grade` counts them as icons the app supplies, not off-contract ones. `fallbackIconSet` remains a deprecated alias of Reicon, exported from `@sableui/react/icons/reicon`. `SableThemeProvider` is the preferred route for user-facing theme switching: it stores the user's color preference (`light` / `dark` / `system`), toggles the **`.dark` class**, stores the active design theme, and writes **`data-sable-theme`** for non-default themes. If your app already owns this state, use `applySableColorMode()` / `applySableTheme()` or the exported `SABLE_THEME_ATTRIBUTE` constant directly. You do **not** need a Tailwind `@custom-variant dark` for Sable itself — add one (`@custom-variant dark (&:where(.dark, .dark *));`) only if **your own** app code uses `dark:` utilities (Sable ships none).
 
 **6. Use it:**
 

package/bin/sable-lint.mjs

@@ -58,6 +58,10 @@ const rules = makeRules({ semanticTokens, motionTokens, labelContrast: await lab
 
 /* ── Args. ─────────────────────────────────────────────────────────────────── */
 const args = process.argv.slice(2)
+/* --json: agents and `sable check` read the result instead of scraping the
+   report. The skill told agents to run `sable lint <paths> --json` while this
+   printed the text report regardless. */
+const JSON_OUT = args.includes("--json")
 if (args.includes("--help") || args.includes("-h")) {
 	console.log(
 		[
@@ -67,6 +71,7 @@ if (args.includes("--help") || args.includes("-h")) {
 			"  sable-lint --ignore <glob> skip matching paths (repeatable)",
 			"  sable-lint --rules         list the rules",
 			"  sable-lint --since <ver>   what the contract added since that version",
+			'  sable-lint --json          print { type: "lint", data } instead of the report',
 			"",
 			`Contract: @sableui/react ${REGISTRY.version} (${semanticTokens.size} semantic tokens)`,
 			"",
@@ -131,6 +136,13 @@ const targets = args.filter((a, i) => !a.startsWith("-") && args[i - 1] !== "--i
 const dirs = (targets.length ? targets : ["src"]).map((d) => resolve(CWD, d))
 const missing = dirs.filter((d) => !existsSync(d))
 if (missing.length) {
+	if (JSON_OUT) {
+		const message = `Not found: ${missing.map((d) => relative(CWD, d)).join(", ")}`
+		process.stdout.write(
+			`${JSON.stringify({ type: "error", code: "ERR_LINT_INPUT", message, suggestions: ["Pass the directories to lint, e.g. sable lint app components"] })}\n`,
+		)
+		process.exit(1)
+	}
 	console.error(
 		`[sable-lint] Not found: ${missing.map((d) => relative(CWD, d)).join(", ")}\n` +
 			"Pass the directories to lint, e.g. `sable-lint app components`.",
@@ -191,6 +203,12 @@ for (const dir of dirs) {
 	}
 }
 
+if (JSON_OUT) {
+	const data = { version: REGISTRY.version, filesScanned, failed: violations.length > 0, violations }
+	process.stdout.write(`${JSON.stringify({ type: "lint", data }, null, 1)}\n`)
+	process.exit(violations.length ? 1 : 0)
+}
+
 process.exit(
 	report(
 		"sable-lint",