@sableui/react 0.3.1 → 0.4.0

package/AGENTS.md

@@ -4,7 +4,7 @@ How to **build with** Sable. This is the whole consumer contract an agent needs;
 
 ## What this is
 
-**Sable** is an owned, themeable React component system: about 100 components (`npx sable manifest` has the live count), 13 layout primitives, 8 page shells, on [Base UI](https://base-ui.com) behavior with Tailwind v4 + semantic CSS-variable tokens. The default theme is **Base**; the other featured presets are Meridian, Prism, Verdant, Ember, and Poppy.
+**Sable** is an owned, themeable React component system: about 100 components (`npx sable manifest` has the live count), 13 layout primitives, 8 page shells, on [Base UI](https://base-ui.com) behavior with Tailwind v4 + semantic CSS-variable tokens. The default theme is **Sable**; the other featured presets are Meridian, Prism, Verdant, Ember, and Poppy.
 
 **Where things are**
 
@@ -59,12 +59,12 @@ The machine-readable version of this section is the `consume` block in `registry
 2. **Dedupe React** in the bundler (`resolve.dedupe: ["react","react-dom"]`) — Base UI must not resolve a second React, or you get an "invalid hook call" blank page.
 3. **CSS, in order:** `@import "tailwindcss";` → `@import "@sableui/react/styles.css";` → `@source "<node_modules>/@sableui/react/dist/**/*.{js,mjs}";` so Tailwind scans the package's classes.
 
-   `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.
+   `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)`; `<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 (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).
 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.
+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.
 
 8. **Read the catalog through the CLI, not the file.** `registry.json` is about 1 MB and `llms-full.txt` about 800 KB — complete and unreadable in a working context. `npx sable` serves the same generated contract in pieces, offline, at your installed version:
 
@@ -144,6 +144,10 @@ Base UI wires `aria-invalid`/`aria-describedby` when you use `Field`; the behavi
 After installing Sable, run `pnpm exec sable setup --agent` in the target
 project. It installs discoverable entry files in `.agents/skills/sable` for
 Codex/Cursor and `.claude/skills/sable` for Claude Code; `--target` selects a host.
+In a monorepo where Sable belongs to one workspace package, run setup in that
+package with `--root` naming the repository root (for example
+`pnpm --filter web exec sable setup --agent --root ../..`); the entries go
+there and resolve Sable through the package.
 Each entry resolves `skills/sable/SKILL.md` from the installed package, so package
 upgrades also update the workflow. Other agents can read that file directly.
 Use `$sable build <idea>`, `inspire <references>`, `audit <target>`, or

package/CHANGELOG.md

@@ -1,5 +1,65 @@
 # What's new
 
+## 0.4.0
+
+### The default theme is now called Sable
+
+The default theme was called Base, which read too close to Base UI, the
+library Sable's components are built on. It is now **Sable**. It looks the same.
+
+- Theme id `base` → `sable` (`data-sable-theme="sable"`, `setThemeId("sable")`).
+- `@sableui/react/theme/base` and `theme/base.css` → `theme/sable` and
+  `theme/sable.css`. `styles.css` still includes it, so most apps import nothing new.
+- `baseTheme` → `sableTheme`.
+- A stored `base` choice is no longer a known id, so `SableThemeProvider`
+  falls back to the default, which is Sable.
+
+### Themes
+
+- **Panel fields read in dark mode.** `panel-field` was the canvas tone, 3% ink
+  off the panel, which measured 1.04:1 on a dark panel. It is now mixed from the
+  panel at 9% ink (1.15:1 dark, 1.25:1 light), with hover a step further at 12%.
+- **Ember's dark-mode primary button has white text.** The fill is now Ember's
+  light-mode orange-red. On the old, brighter fill the dark label passed WCAG
+  but read muddy (APCA Lc 42); white now clears both (4.8:1, Lc 76). The
+  sidebar's active item follows.
+
+### Agent tools
+
+- `sable-lint` no longer reports `hand-derived-surface` on the value of a
+  `--theme-*` hook, such as `--theme-panel-field: color-mix(…)`. Tuning a
+  derived token is what the hooks are for.
+- `sable grade --ignore <glob>` skips the same paths `sable-lint --ignore`
+  does, so a data layer of document colours is not counted as contract
+  violations. Ignored files are still fingerprinted.
+
+## 0.3.2
+
+### Workspace panels
+
+- **`panel-field` and `panel-field-hover` tokens.** The fill of a compact
+  control docked in a panel, and its hover step. They default to the canvas
+  tone and the raised panel step, so nothing changes visually. The `xs` field
+  rung (Input, SelectTrigger, Combobox, ScrubField) now wears them, and a panel
+  control of your own can too, without a lint exception.
+- **`<Button variant="field">`.** A button that sits among `xs` fields in a
+  panel row, such as a font picker or an add action: the inset field fill and
+  the field's corner instead of a pill. Use it with `size="xs"` or `"icon-xs"`.
+
+### Agent tools
+
+- `sable grade` checks props against each component's real type, so props a
+  component forwards to Base UI (`Toggle`'s `pressed`, `Combobox`'s `filter`)
+  are no longer reported as hallucinated. `registry.json` carries the result as
+  `propSurface`.
+- `sable grade` reads the icon names your app adds with `composeIconSets` from
+  `.sable/icons.json` (`{ "names": [...] }`), or from `--icons <file>`, and stops
+  counting them as off-contract.
+- `sable setup --agent --root <dir>` writes the skill entries in an ancestor
+  directory. In a monorepo, run it in the workspace package that depends on
+  Sable with `--root` at the repository root. The entries resolve Sable through
+  that package.
+
 ## 0.3.1
 
 ### Charts

package/CONTRIBUTING.md

@@ -117,7 +117,7 @@ deliberately reverses: `DESIGN.md → Registers`. What a contributor needs to kn
 
 ## Theme contract
 
-A theme is a CSS file that defines every token in `themes/_contract.ts` for `:root` (light) and `.dark` (dark), plus an optional TS manifest. Components depend on the **semantic** layer; each theme supplies its own palette underneath. Alternate themes activate through the root `data-sable-theme` attribute; consuming apps should usually let `<SableThemeProvider>` own that wiring and read/update it through `useSableTheme()`. To make a new theme: copy `themes/base/`, swap the palette + semantic values, keep the token names identical, add the manifest to `themes/registry.ts`, import its CSS from `src/themes.css`, add `./theme/<id>` + `./theme/<id>.css` to both `exports` and `publishConfig.exports`, and cover it in `themes.test.ts`. `build-registry` fails on a theme missing from any of those, and generates `registry.json → themes.available` from the manifests — never hand-edit that list. Re-skinning never touches component code.
+A theme is a CSS file that defines every token in `themes/_contract.ts` for `:root` (light) and `.dark` (dark), plus an optional TS manifest. Components depend on the **semantic** layer; each theme supplies its own palette underneath. Alternate themes activate through the root `data-sable-theme` attribute; consuming apps should usually let `<SableThemeProvider>` own that wiring and read/update it through `useSableTheme()`. To make a new theme: copy `themes/sable/`, swap the palette + semantic values, keep the token names identical, add the manifest to `themes/registry.ts`, import its CSS from `src/themes.css`, add `./theme/<id>` + `./theme/<id>.css` to both `exports` and `publishConfig.exports`, and cover it in `themes.test.ts`. `build-registry` fails on a theme missing from any of those, and generates `registry.json → themes.available` from the manifests — never hand-edit that list. Re-skinning never touches component code.
 
 **Themes are presets, not the unit of customization.** Every token a theme sets can also be set by an app (or by the docs customizer) on `:root` after the theme loads. A theme is the starting point a consumer picks; the customizer exports the deltas on top of it. Keep that working: a theme must not set a token with `!important` or under a selector more specific than `[data-sable-theme="<id>"]`, or a consumer override cannot win.
 
@@ -130,7 +130,7 @@ while allowing a consumer to tune the whole type system, rather than making only
 headings reflect its art direction. Existing defaults remain the fallback; themes
 do not need to declare every optional hook.
 
-`SEMANTIC_TOKENS` includes `border-strong` alongside `border` — a visually-stronger structural divider (grid lines, table rules, section separators) distinct from `border`, which stays tuned for subtle chrome (badge/input outlines). Both need light + dark values, derived from the same neutral ramp as `border` but pulled from a higher-contrast step (e.g. Base: `border` = `--zinc-200` light / low-alpha `--zinc-700` dark → `border-strong` = `--zinc-300` light / higher-alpha `--zinc-500` dark). `styles.css`'s `@theme inline` block maps it to `--color-border-strong`, so components/consumers use it via the `border-strong` Tailwind color utility, same pattern as `border`.
+`SEMANTIC_TOKENS` includes `border-strong` alongside `border` — a visually-stronger structural divider (grid lines, table rules, section separators) distinct from `border`, which stays tuned for subtle chrome (badge/input outlines). Both need light + dark values, derived from the same neutral ramp as `border` but pulled from a higher-contrast step (e.g. the Sable theme: `border` = `--zinc-200` light / low-alpha `--zinc-700` dark → `border-strong` = `--zinc-300` light / higher-alpha `--zinc-500` dark). `styles.css`'s `@theme inline` block maps it to `--color-border-strong`, so components/consumers use it via the `border-strong` Tailwind color utility, same pattern as `border`.
 
 `TYPE_OVERLINE_TOKENS` (`type-overline-size/weight/leading/tracking/transform`) back the `text-overline` utility — the eyebrow/badge-label/stat-caption text role with no home in `TYPE_SCALE_TOKENS`'s display/heading/title ramp. `type-overline-transform` is themeable rather than a hardcoded `uppercase`, so a quieter reference (e.g. Cove) can opt into sentence case. Like the other type tiers, every built-in theme declares explicit values rather than relying on styles.css's fallback defaults (`0.75rem` / weight `600` / leading `1.2` / tracking `0.08em` / `uppercase`).
 

package/DESIGN.md

@@ -1,6 +1,6 @@
 # Sable — Design System Spec
 
-The system-level design spec for **Sable**, an owned, themeable component system. This document is **theme-agnostic**: it describes the structure, tokens, and rules that every theme inherits. The **default theme is "Base"** (a dark-by-default, content-first, fluid product aesthetic); its concrete values live in `src/themes/base/`. Other themes supply their own values for the same token contract.
+The system-level design spec for **Sable**, an owned, themeable component system. This document is **theme-agnostic**: it describes the structure, tokens, and rules that every theme inherits. The **default theme is "Sable"** (a dark-by-default, content-first, fluid product aesthetic); its concrete values live in `src/themes/sable/`. Other themes supply their own values for the same token contract.
 
 For building with Sable see `AGENTS.md`; for changing the package see `CONTRIBUTING.md`. For the machine-readable catalog see `registry.json` / `llms.txt`.
 
@@ -9,7 +9,7 @@ For building with Sable see `AGENTS.md`; for changing the package see `CONTRIBUT
 1. **Own the surface, theme the values.** Components reference semantic roles, not colors. Swapping a theme re-skins everything without touching a component.
 2. **Content over chrome.** The UI recedes so content advances. Restraint over decoration.
 3. **Constraint is generative.** A small set of tokens, tiers, and primitives yields a large space of good UIs. Reach for what exists before inventing.
-4. **A deliberate visual world.** Base starts dark. A consuming product chooses its modes, typography, shape, and art direction from its brief; the token contract travels across those choices.
+4. **A deliberate visual world.** The Sable theme starts dark. A consuming product chooses its modes, typography, shape, and art direction from its brief; the token contract travels across those choices.
 5. **Accessible by construction.** Base UI carries behavior/ARIA; semantic token pairs are pre-checked to WCAG AA.
 6. **AI-native.** The system is documented for machines as well as people (`registry.json`, per-component `*.meta.ts`).
 
@@ -26,7 +26,7 @@ evidence contract. A reviewer still has to see and operate the result. Read
 
 The semantic contract protects meaning, behavior, and consistency. It does not
 choose the story, visual hierarchy, imagery, or composition for every product.
-Statements about Base's accent, shape, and dark-first identity describe the
+Statements about the Sable theme's accent, shape, and dark-first identity describe the
 default theme; consumers can choose a different art direction while preserving
 semantic roles and accessibility. A palette change alone is not a new design.
 
@@ -57,7 +57,7 @@ Three layers, outermost is what components use:
 | **Semantic** (the contract) | `--primary`, `--card`, `--muted-foreground`, `--tone-edition`, `--ring` | **Components** (via `bg-*`/`text-*` utilities). |
 | **Component** (local) | a cva variant string | Inside one component. |
 
-`themes/_contract.ts` enumerates the semantic tokens every theme must define. The default (Base) palette is authored in **OKLCH** for perceptually-uniform ramps, locked hue, gamut-safe chroma, and dark-mode vibrancy.
+`themes/_contract.ts` enumerates the semantic tokens every theme must define. The default (Sable) palette is authored in **OKLCH** for perceptually-uniform ramps, locked hue, gamut-safe chroma, and dark-mode vibrancy.
 
 ### Semantic tokens (the contract)
 
@@ -68,7 +68,7 @@ Tone ink (legible text/icon on a tone fill, theme-adaptive): `tone-standard-fore
 Overlay (fixed dark surface over content — scrims, media letterbox, pills on imagery): `overlay`, `overlay-foreground`.
 Sidebar set: `sidebar`, `sidebar-foreground`, `sidebar-primary(-foreground)`, `sidebar-accent(-foreground)`, `sidebar-border`, `sidebar-ring`.
 
-**Base inversion rule:** in dark mode `primary` is light (a near-white pill); in light mode it is near-black. Other themes may use a different action palette. Never call `primary` "black" or `primary-foreground` "white" — use the semantic pair, whose values belong to the theme.
+**Sable theme inversion rule:** in dark mode `primary` is light (a near-white pill); in light mode it is near-black. Other themes may use a different action palette. Never call `primary` "black" or `primary-foreground` "white" — use the semantic pair, whose values belong to the theme.
 
 ### Tone system
 
@@ -442,7 +442,7 @@ Motion is a first-class token layer, not an afterthought. **Subtle by default, w
 
 **Three parts:**
 
-1. **Tokens** (`themes/base/base.css` → Motion tokens; contract in `themes/_contract.ts` → `MOTION_TOKENS`).
+1. **Tokens** (`themes/sable/sable.css` → Motion tokens; contract in `themes/_contract.ts` → `MOTION_TOKENS`).
    - **Durations:** `instant` 75 · `fast` 150 · `base` 200 · `slow` 300 · `slower` 500, plus semantic `enter`/`exit`. Every duration is multiplied by `--motion-scale`.
    - **Easings:** `standard` (≈ease-in-out, default) · `decelerate` (≈ease-out, entrances) · `emphasized` (large surfaces) · `linear` (indeterminate loaders) · **`spring`** (gentle ~+4% single overshoot — the default for delightful pops) · **`bounce`** (~+10%, opt-in playful accents). Springs apply on **enter only**; exits stay overshoot-free.
    - Consume easings via the `ease-*` utilities; durations via `duration-(--motion-duration-*)` (so the kill-switch always applies).
@@ -526,7 +526,7 @@ Not every removal is a regression; check for an **equivalent replacement** befor
 - Inline `oklch()`/hex or raw palette steps in components. *(CI-enforced: `inline-color`, `palette-ref`.)*
 - Decomposing paired typography utilities. *(CI-enforced: `decomposed-type`.)*
 - Pure `#000`/`#fff` (use `zinc-950`/`zinc-50`, or `overlay`/`overlay-foreground` for scrims). *(CI-enforced: `raw-black-white`.)*
-- In Base, purple/brand for primary CTAs (brand = editions + selection only). A different theme chooses its action palette through the semantic pair.
+- 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.
 - A global page max-width (use opt-in region caps).

package/README.md

@@ -1,6 +1,6 @@
 # Sable
 
-**Sable** — a themeable React component system with layout patterns, semantic tokens and tools for coding agents. Default theme: **Base**. On npm as `@sableui/react`; docs and the live catalog at [sableui.com](https://www.sableui.com).
+**Sable** — a themeable React component system with layout patterns, semantic tokens and tools for coding agents. Default theme: **Sable**. On npm as `@sableui/react`; docs and the live catalog at [sableui.com](https://www.sableui.com).
 
 For a clickable iOS prototype (demos and presentations, not production), ask the
 Sable skill to build with the iOS target. Every screen is Sable components in your
@@ -13,7 +13,7 @@ Frame it with `PhoneFrame` from `@sableui/react/ios/preview`. See
 
 Original Sable code is [MIT licensed](./LICENSE).
 
-The featured presets are Base (neutral), Meridian (square), Prism (compact technical),
+The featured presets are Sable (neutral), Meridian (square), Prism (compact technical),
 Verdant (serif), Ember (warm), and Poppy (playful). Every preset supports light and
 dark modes. Load its declared fonts and use `ThemeSelector` to offer preset choices.
 [Third-party notices](./THIRD_PARTY_NOTICES.md) list the software and fonts used
@@ -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. `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).
+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).
 
 **6. Use it:**
 
@@ -181,6 +181,10 @@ pnpm --filter @sableui/react build   # regenerates registry.json from the metas
 After installing Sable, run `pnpm exec sable setup --agent` in the target
 project. It installs discoverable entry files in `.agents/skills/sable` for
 Codex/Cursor and `.claude/skills/sable` for Claude Code; `--target` selects a host.
+In a monorepo where Sable belongs to one workspace package, run setup in that
+package with `--root` naming the repository root (for example
+`pnpm --filter web exec sable setup --agent --root ../..`); the entries go
+there and resolve Sable through the package.
 Each entry resolves `skills/sable/SKILL.md` from the installed package, so package
 upgrades also update the workflow. Other agents can read that file directly.
 Use `$sable build <idea>`, `inspire <references>`, `audit <target>`, or

package/bin/sable.mjs

@@ -83,7 +83,7 @@ const COMMANDS = [
 		summary: "Create, validate, or compile a portable Sable preset used by Canvas and builds.",
 		arg: null,
 		flags: [
-			{ name: "--template", value: null, describe: "Print a complete editable Base preset JSON record." },
+			{ name: "--template", value: null, describe: "Print a complete editable Sable preset JSON record." },
 			{ name: "--check", value: "file.json", describe: "Validate the schema and Sable token contract." },
 			{ name: "--css", value: "file.json", describe: "Generate scoped theme CSS from a validated preset." },
 		],
@@ -96,6 +96,7 @@ const COMMANDS = [
 		flags: [
 			{ name: "--agent", value: null, describe: "Install skill entry files. Required." },
 			{ name: "--target", value: "all|codex|claude|cursor", describe: "Host discovery directories. Default all; Codex and Cursor share .agents." },
+			{ name: "--root", value: "dir", describe: "Write the entries in this ancestor instead, e.g. the repository root when Sable belongs to one workspace package. Run setup in that package." },
 			{ name: "--update", value: null, describe: "Refresh unchanged managed entries after a package upgrade." },
 			{ name: "--dry-run", value: null, describe: "Check and report the destination without writing files." },
 		],
@@ -208,6 +209,8 @@ const COMMANDS = [
 			{ name: "--review", value: "review.json", describe: "Check captures, observations, iterations, and the source fingerprint." },
 			{ name: "--strict", value: null, describe: "Exit 1 for contract findings or missing/incomplete/unresolved review evidence." },
 			{ name: "--cli-log", value: "file.jsonl", describe: "Include retrieval usage from a SABLE_CLI_LOG file." },
+			{ name: "--icons", value: "icons.json", describe: 'Icon names the app adds with composeIconSets, as { "names": [...] }. Default: .sable/icons.json when present.' },
+			{ name: "--ignore", value: "glob", describe: "Skip matching paths in the checks, with the same globs as sable-lint --ignore. Repeatable." },
 		],
 		returns: ["grade.score", "grade.template"],
 	},
@@ -1076,7 +1079,7 @@ function cmdDoctor() {
 	/* The theme trap: opting into theme switching without importing theme CSS. */
 	const src = collectSources(/\.(tsx?|jsx?)$/)
 	const srcText = src.map((f) => f.text).join("\n")
-	// A provider used only for light/dark mode needs Base, not alternate themes.
+	// A provider used only for light/dark mode needs only the Sable theme, not alternate themes.
 	const usesThemes = /ThemeSelector|data-sable-theme|applySableTheme|setThemeId|defaultThemeId/.test(srcText)
 	if (usesThemes) {
 		const themeCss = /@import\s+["'](?:@sableui\/react\/|[^"']*packages\/sable\/(?:src|dist)\/)(themes\.css|theme\/[a-z-]+\.css|themes\/[a-z-]+\/[a-z-]+\.css)["']/.test(cssText)
@@ -1086,7 +1089,7 @@ function cmdDoctor() {
 			add(
 				"fail",
 				"themes",
-				"This app selects a design theme but has no alternate or app-owned scoped theme CSS — the selected theme may silently render as Base.",
+				"This app selects a design theme but has no alternate or app-owned scoped theme CSS — the selected theme may silently render as the Sable theme.",
 				'Import themes.css, one theme/<id>.css, or the scoped CSS generated by sable preset --css.',
 			)
 	}
@@ -1215,9 +1218,11 @@ const HANDLERS = {
 	preset: () => cmdDesignTool("design-presets.mjs"),
 	setup: () => {
 		if (!flags.has("agent") || rest.length) fail("ERR_BAD_ARGUMENT", "Use sable setup --agent from your project root.", ["sable setup --agent --dry-run"])
+		const root = flags.get("root")
+		if (root === true) fail("ERR_BAD_ARGUMENT", "--root needs a directory.", ["pnpm --filter <package> exec sable setup --agent --root ../.."])
 		try {
-			const data = installAgentSkill({ root: CWD, packageRoot: PKG_ROOT, target: flags.get("target") ?? "all", update: flags.has("update"), dryRun: flags.has("dry-run") })
-			ok("setup.agent", data, `${data.dryRun ? "Would install" : "Installed"} Sable skill entries at ${data.destinations.join(", ")}.\nNext: ${data.next}`)
+			const data = installAgentSkill({ root: root ? resolve(CWD, root) : CWD, project: CWD, packageRoot: PKG_ROOT, target: flags.get("target") ?? "all", update: flags.has("update"), dryRun: flags.has("dry-run") })
+			ok("setup.agent", data, `${data.dryRun ? "Would install" : "Installed"} Sable skill entries at ${data.destinations.map((d) => relative(CWD, join(data.root, d)).replaceAll("\\", "/")).join(", ")}.\nNext: ${data.next}`)
 		} catch (error) { fail("ERR_AGENT_SETUP", error.message, ["sable setup --agent --dry-run"]) }
 	},
 	manifest: cmdManifest,

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

@@ -4,14 +4,14 @@
  * never a theme's internal palette steps — which is what makes the system
  * re-themeable without touching component code.
  *
- * To author a new theme: copy `themes/base/`, keep these token names, and
+ * To author a new theme: copy `themes/sable/`, 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", "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
- * motion feel; if omitted, the Base defaults apply. Components reference
+ * motion feel; if omitted, the Sable theme's defaults apply. Components reference
  * them via `duration-(--motion-duration-*)` + the `ease-*` utilities, or — far
  * more often — via the named motion recipes (`motion-pop`, `motion-press`, …)
  * defined in styles.css. Every duration is multiplied by `--motion-scale`, the
@@ -23,7 +23,7 @@ type MotionToken = (typeof MOTION_TOKENS)[number];
 /**
  * Radius tokens (mode-independent). A theme MAY override these to retune its
  * shape language (soft-square, rectilinear, full-pill, …); if omitted, the
- * Base defaults apply (see styles.css → `@theme inline`, which bridges
+ * Sable defaults apply (see styles.css → `@theme inline`, which bridges
  * each `--theme-radius-*` var to the `radius-*` Tailwind scale). Components
  * never reference these directly — they use the derived `rounded-*`
  * utilities.
@@ -33,7 +33,7 @@ type RadiusToken = (typeof RADIUS_TOKENS)[number];
 /**
  * Type-scale tokens (mode-independent). A theme MAY override these to retune
  * its typographic voice (weight, leading, tracking, and — for heading/display
- * tiers — size); if omitted, the Base defaults baked into styles.css's
+ * tiers — size); if omitted, the Sable theme's defaults baked into styles.css's
  * paired `text-*` utilities apply. Additional body/label/caption/mono and size
  * hooks are advertised separately in TYPE_REFINEMENT_TOKENS: they are optional,
  * so a theme can retune its reading voice without duplicating every default.
@@ -95,11 +95,16 @@ type DensityToken = (typeof DENSITY_TOKENS)[number];
  *   COMPRESSED tonal band — Paper's whole ladder spans 249→242→238, about 3-7
  *   RGB units, with a low-contrast hairline doing the structural work. `card` is
  *   tuned for the opposite job (lifting content off a page).
+ * - `panel-field` / `panel-field-hover` are the inset fill of a compact control
+ *   docked in a panel (the `size="xs"` field rung, a field-style button) and its
+ *   hover step, mixed from the panel they sit in. Named so a consumer's own panel
+ *   control can wear them without borrowing the work surface's token or a fixed
+ *   hover the surface-hover rule rightly rejects.
  * - `hairline` / `hairline-strong` are that structural edge. In this register
  *   hairlines carry structure INSTEAD of tonal steps — a deliberate reversal of
  *   the page register's "prefer a tonal step or space over a divider line".
  */
-declare const WORKSPACE_SURFACE_TOKENS: readonly ["canvas", "canvas-foreground", "panel", "panel-foreground", "panel-raised", "hairline", "hairline-strong"];
+declare const WORKSPACE_SURFACE_TOKENS: readonly ["canvas", "canvas-foreground", "panel", "panel-foreground", "panel-raised", "panel-field", "panel-field-hover", "hairline", "hairline-strong"];
 type WorkspaceSurfaceToken = (typeof WORKSPACE_SURFACE_TOKENS)[number];
 /**
  * UI type tiers (mode-independent) — the chrome typography register.

package/dist/blocks/index.js

@@ -1,5 +1,5 @@
-import { Kbd, CommandMenuPanel, ToggleGroup, Toggle, BarChart, DateTile, Accordion, AccordionItem, AccordionTrigger, AccordionPanel, RadialChart, Sparkline, Slider, Stepper, StepperItem, SegmentedBar, Checkbox, PieChart, AreaChart, OtpField } from '../chunk-WCFLQVK5.js';
-import { Card, CardHeader, CardTitle, CardDescription, CardAction, Button, CardList, Entity, OverflowMenu, MenuItem, MenuSeparator, Code, CardContent, Message, Bubble, CardFooter, DestructiveActionModal, Badge, AvatarGroup, Avatar, Textarea, CodeBlock, Input, Table, TableHeader, TableRow, TableHead, TableBody, TableCell, StatusDot, Switch, Form, Field, Select, SelectTrigger, SelectContent, SelectItem, Separator, Label, Attachment } from '../chunk-CKNM7KSB.js';
+import { Kbd, CommandMenuPanel, ToggleGroup, Toggle, BarChart, DateTile, Accordion, AccordionItem, AccordionTrigger, AccordionPanel, RadialChart, Sparkline, Slider, Stepper, StepperItem, SegmentedBar, Checkbox, PieChart, AreaChart, OtpField } from '../chunk-FBSL2LZQ.js';
+import { Card, CardHeader, CardTitle, CardDescription, CardAction, Button, CardList, Entity, OverflowMenu, MenuItem, MenuSeparator, Code, CardContent, Message, Bubble, CardFooter, DestructiveActionModal, Badge, AvatarGroup, Avatar, Textarea, CodeBlock, Input, Table, TableHeader, TableRow, TableHead, TableBody, TableCell, StatusDot, Switch, Form, Field, Select, SelectTrigger, SelectContent, SelectItem, Separator, Label, Attachment } from '../chunk-CCUDFLU3.js';
 import { Region, Stack, Row, Grid } from '../chunk-3IWZYBGH.js';
 import { cn } from '../chunk-SRQWQUTW.js';
 import { Icon } from '../chunk-NGBDP3BM.js';

package/dist/{chunk-YXBOYWBN.js → chunk-C4Z3CF54.js}

@@ -2,7 +2,7 @@
 var atelierTheme = {
   id: "atelier",
   label: "Atelier",
-  deprecated: { replacement: "base" },
+  deprecated: { replacement: "sable" },
   modes: ["light", "dark"],
   defaultMode: "light",
   fonts: {

package/dist/{chunk-CKNM7KSB.js → chunk-CCUDFLU3.js}

@@ -339,6 +339,15 @@ var buttonVariants = cva(
          * restyling secondary/ghost three different ways was the alternative.
          */
         floating: "border border-border-floating bg-popover/90 text-popover-foreground shadow-md backdrop-blur hover:bg-popover",
+        /*
+         * A button docked in a panel among compact fields — a picker that
+         * opens a popover, "Add fill", a swatch's trigger. It wears the xs
+         * field rung's shell (lib/field-shell → FIELD_SHELL_XS): the inset
+         * `panel-field` fill, no border, the field's corner rather than the
+         * button's pill, so it reads as one of the row's controls. Secondary
+         * or ghost there read as page buttons dropped into tool chrome.
+         */
+        field: "rounded-[var(--panel-field-radius,var(--radius-xs))] bg-panel-field text-panel-foreground hover:bg-panel-field-hover",
         /*
          * On-colour tiers — for a button sitting ON a coloured fill (a tone
          * band, a solid Banner, a brand panel, a dark section in a light
@@ -587,9 +596,9 @@ var buttonMeta = {
   props: [
     {
       name: "variant",
-      type: '"primary" | "secondary" | "ghost" | "outline" | "destructive" | "link" | "floating" | "on-color" | "on-color-outline" | "on-color-ghost"',
+      type: '"primary" | "secondary" | "ghost" | "outline" | "destructive" | "link" | "floating" | "field" | "on-color" | "on-color-outline" | "on-color-ghost"',
       default: '"primary"',
-      description: "Visual emphasis tier. One primary per screen. The on-color tiers are for buttons ON a coloured fill: they paint with the inherited text colour (the fill's ink) \u2014 on-color is solid (ink background, fill-coloured label via the optional --on-color-fill var, else black/white), on-color-outline and on-color-ghost are transparent with an ink label. Never use them on page or card surfaces. floating is for a control that sits OVER content (carousel arrows, a marquee pause, a jump-to-latest over a conversation): its own edge, lift and translucent popover fill, so it reads on arbitrary content beneath."
+      description: "Visual emphasis tier. One primary per screen. The on-color tiers are for buttons ON a coloured fill: they paint with the inherited text colour (the fill's ink) \u2014 on-color is solid (ink background, fill-coloured label via the optional --on-color-fill var, else black/white), on-color-outline and on-color-ghost are transparent with an ink label. Never use them on page or card surfaces. floating is for a control that sits OVER content (carousel arrows, a marquee pause, a jump-to-latest over a conversation): its own edge, lift and translucent popover fill, so it reads on arbitrary content beneath. field is for a button docked in a workspace panel among xs fields: the inset panel-field fill and the field's corner, so a picker trigger or an add action reads as one of the row's controls; pair it with size xs or icon-xs."
     },
     {
       name: "size",
@@ -638,6 +647,7 @@ var buttonMeta = {
       "destructive",
       "link",
       "floating",
+      "field",
       "on-color",
       "on-color-outline",
       "on-color-ghost"
@@ -654,7 +664,10 @@ var buttonMeta = {
     "input",
     "destructive",
     "destructive-foreground",
-    "ring"
+    "ring",
+    "panel-field",
+    "panel-field-hover",
+    "panel-foreground"
   ],
   motion: [
     {
@@ -746,6 +759,10 @@ var buttonMeta = {
       label: "Icon button with an unread badge",
       code: '<Button size="icon" variant="ghost" aria-label="Notifications" badge={<NotificationBadge dot />}><Icon name="bell" /></Button>'
     },
+    {
+      label: "Field button in a panel row",
+      code: '<PanelSection title="Text">\n  <PropertyRow label="Font">\n    <Button variant="field" size="xs" className="w-full justify-between" iconEnd={<Icon name="chevron-down" />}>Figtree</Button>\n  </PropertyRow>\n</PanelSection>'
+    },
     {
       label: "On a coloured band",
       code: '<div className="flex gap-3 bg-tone-info p-6 text-tone-info-foreground [--on-color-fill:var(--tone-info)]"><Button variant="on-color">Join the beta</Button><Button variant="on-color-outline">Read the notes</Button></div>'
@@ -2183,7 +2200,7 @@ var separatorMeta = {
 var FIELD_SHELL = "rounded-sm border border-input bg-card motion-interactive placeholder:text-muted-foreground focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring disabled:cursor-not-allowed disabled:opacity-50";
 var MOBILE_FIELD_TIER = "max-sm:text-body-lg";
 var FIELD_INVALID = "aria-[invalid=true]:border-destructive aria-[invalid=true]:ring-destructive/30";
-var FIELD_SHELL_XS = "rounded-[var(--panel-field-radius,var(--radius-xs))] border-transparent bg-canvas hover:bg-panel-raised";
+var FIELD_SHELL_XS = "rounded-[var(--panel-field-radius,var(--radius-xs))] border-transparent bg-panel-field hover:bg-panel-field-hover";
 function Input({ className, type, size = "md", ref, ...props }) {
   const tier = useTypeTier();
   const density = useDensity();
@@ -2289,7 +2306,7 @@ var inputMeta = {
       name: "size",
       type: '"md" | "xs"',
       default: '"md"',
-      description: "md is the form field. xs is the dense inset field of a tool panel (an inset canvas fill, no outline, tight padding) \u2014 the same ladder as Select and Combobox. Use it instead of overriding the height with className."
+      description: "md is the form field. xs is the dense inset field of a tool panel (an inset panel-field fill, no outline, tight padding) \u2014 the same ladder as Select and Combobox. Use it instead of overriding the height with className."
     },
     {
       name: "type",
@@ -3969,7 +3986,7 @@ var selectMeta = {
     {
       name: "SelectTrigger",
       type: 'Base UI Trigger props + placeholder?: ReactNode + size?: "md" | "xs" + className',
-      description: 'The button. Composes Trigger + Value + a chevron Icon that flips on open (data-[popup-open]). `size="xs"` is the property-grid rung \u2014 height, padding, radius AND surface move together, which is why it is a prop and not a className: the xs trigger is an inset `bg-canvas` field with no border, matching ScrubField on the same row. A consumer overriding only the height gets an md-register 8px radius on a 24px box and a raised card sitting among inset fields; one inspector panel had eleven of those, and both tells are visible at a glance.'
+      description: 'The button. Composes Trigger + Value + a chevron Icon that flips on open (data-[popup-open]). `size="xs"` is the property-grid rung \u2014 height, padding, radius AND surface move together, which is why it is a prop and not a className: the xs trigger is an inset `bg-panel-field` field with no border, matching ScrubField on the same row. A consumer overriding only the height gets an md-register 8px radius on a 24px box and a raised card sitting among inset fields; one inspector panel had eleven of those, and both tells are visible at a glance.'
     },
     {
       name: "SelectContent",

package/dist/{chunk-6LCIBMMG.js → chunk-D2ETQBHV.js}

@@ -1,4 +1,4 @@
-import { useMotion, useIsomorphicLayoutEffect, mergeRefs, trimLabel, useTypeTier, buttonVariants, Input, Table, TableCaption, TableHeader, TableRow, TableHead, Button, TableBody, TableCell, Card, SimpleTooltip, useDensity, FIELD_SHELL, FIELD_INVALID, MOBILE_FIELD_TIER, Tooltip, TooltipTrigger, TooltipContent, useScrollActivity, setRef, Textarea, Menu, MenuTrigger, MenuContent, MenuSubmenu, MenuSubmenuTrigger, Separator } from './chunk-CKNM7KSB.js';
+import { useMotion, useIsomorphicLayoutEffect, mergeRefs, trimLabel, useTypeTier, buttonVariants, Input, Table, TableCaption, TableHeader, TableRow, TableHead, Button, TableBody, TableCell, Card, SimpleTooltip, useDensity, FIELD_SHELL, FIELD_INVALID, MOBILE_FIELD_TIER, Tooltip, TooltipTrigger, TooltipContent, useScrollActivity, setRef, Textarea, Menu, MenuTrigger, MenuContent, MenuSubmenu, MenuSubmenuTrigger, Separator } from './chunk-CCUDFLU3.js';
 import { cn } from './chunk-SRQWQUTW.js';
 import { Icon } from './chunk-NGBDP3BM.js';
 import { createContext, useRef, useState, useEffect, isValidElement, cloneElement, useContext, useMemo, useCallback, useImperativeHandle } from 'react';

package/dist/{chunk-MXJX3NZI.js → chunk-EFLC4NA3.js}

@@ -1,19 +1,19 @@
 import { prismTheme } from './chunk-7MG4SHYX.js';
 import { verdantTheme } from './chunk-KO3NAEBF.js';
 import { emberTheme } from './chunk-L4IEIQQA.js';
-import { baseTheme } from './chunk-EP55KSYA.js';
+import { sableTheme } from './chunk-EHH4MHO6.js';
 import { poppyTheme } from './chunk-ADLLDWLW.js';
 import { meridianTheme } from './chunk-K7RUHUGC.js';
-import { atelierTheme } from './chunk-YXBOYWBN.js';
+import { atelierTheme } from './chunk-C4Z3CF54.js';
 import { createContext, useMemo, useState, useEffect, useCallback, useContext } from 'react';
 import { jsx } from 'react/jsx-runtime';
 
 // src/themes/registry.ts
 var SABLE_THEME_ATTRIBUTE = "data-sable-theme";
-var DEFAULT_THEME_ID = baseTheme.id;
+var DEFAULT_THEME_ID = sableTheme.id;
 var defaultThemeId = DEFAULT_THEME_ID;
 var themeManifests = [
-  baseTheme,
+  sableTheme,
   meridianTheme,
   prismTheme,
   verdantTheme,

package/dist/{chunk-EP55KSYA.js → chunk-EHH4MHO6.js}

@@ -1,7 +1,7 @@
-// src/themes/base/index.ts
-var baseTheme = {
-  id: "base",
-  label: "Base",
+// src/themes/sable/index.ts
+var sableTheme = {
+  id: "sable",
+  label: "Sable",
   modes: ["dark", "light"],
   defaultMode: "dark",
   fonts: {
@@ -9,6 +9,6 @@ var baseTheme = {
     mono: '"DM Mono", ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, "Courier New", monospace'
   }
 };
-var base_default = baseTheme;
+var sable_default = sableTheme;
 
-export { baseTheme, base_default };
+export { sableTheme, sable_default };

package/dist/{chunk-WCFLQVK5.js → chunk-FBSL2LZQ.js}

@@ -1,4 +1,4 @@
-import { FIELD_SHELL, FIELD_INVALID, useMotion, useTypeTier, useScrollActivity, setRef, useAnchoredDensity, Dialog, DialogContent, DialogTitle, DialogDescription, useIsomorphicLayoutEffect } from './chunk-CKNM7KSB.js';
+import { FIELD_SHELL, FIELD_INVALID, useMotion, useTypeTier, useScrollActivity, setRef, useAnchoredDensity, Dialog, DialogContent, DialogTitle, DialogDescription, useIsomorphicLayoutEffect } from './chunk-CCUDFLU3.js';
 import { cn } from './chunk-SRQWQUTW.js';
 import { Icon } from './chunk-NGBDP3BM.js';
 import * as OtpParts from '@base-ui/react/otp-field';

package/dist/{chunk-X276MF2W.js → chunk-OQACYT2D.js}

@@ -273,6 +273,8 @@ var WORKSPACE_SURFACE_TOKENS = [
   "panel",
   "panel-foreground",
   "panel-raised",
+  "panel-field",
+  "panel-field-hover",
   "hairline",
   "hairline-strong"
 ];