@sableui/react 0.8.2 → 0.9.1

package/registry.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://sable.design/registry.schema.json",
   "name": "@sableui/react",
-  "version": "0.8.2",
+  "version": "0.9.1",
   "description": "Themeable React components, semantic tokens, layout patterns, presets, and package-owned agent skills. Default theme: Sable.",
   "engine": {
     "behavior": "@base-ui/react",
@@ -2957,6 +2957,13 @@
           "description": "Floating overlays — a message launcher, FAB, or modal mount points."
         }
       ],
+      "subcomponents": [
+        {
+          "name": "SkipLink",
+          "type": "ComponentProps<\"a\">",
+          "description": "AppShell's skip link on its own, for a layout that is not an AppShell (a storefront with a top header). Put it first in the body and give the page's <main> the matching id: `<SkipLink />` then `<main id=\"main-content\" tabIndex={-1}>`. `href` defaults to #main-content, the label to \"Skip to content\"."
+        }
+      ],
       "tokensUsed": [
         "background",
         "foreground",
@@ -2975,6 +2982,11 @@
           "code": "<AppShell\n  banners={<Banner tone=\"warning\">Network congested — mints may be slow.</Banner>}\n  header={<AppHeader title=\"Studio\" />}\n  sidebar={\n    <Sidebar>\n      <SidebarNav>\n        <SidebarItem icon={<Icon name=\"home\" />} label=\"Home\" active render={<Link to=\"/\" />} />\n        <SidebarItem icon={<Icon name=\"bell\" />} label=\"Notifications\" render={<Link to=\"/notifications\" />} />\n        <SidebarItem icon={<Icon name=\"gear\" />} label=\"Settings\" render={<Link to=\"/settings\" />} />\n      </SidebarNav>\n    </Sidebar>\n  }\n  bottomNav={\n    <BottomNav>\n      <BottomNavItem icon={<Icon name=\"home\" />} label=\"Home\" active render={<Link to=\"/\" />} />\n      <BottomNavItem icon={<Icon name=\"bell\" />} label=\"Alerts\" render={<Link to=\"/notifications\" />} />\n    </BottomNav>\n  }\n>\n  <Region max=\"feed\">\n    <PageHeader title=\"Home\" description=\"Latest posts from artists you follow.\" />\n  </Region>\n</AppShell>",
           "imports": "import { AppHeader, AppShell, Banner, BottomNav, BottomNavItem, Icon, PageHeader, Region, Sidebar, SidebarItem, SidebarNav } from \"@sableui/react\"\n// <Link> = your router's link (react-router, next/link, @tanstack/router, …)"
         },
+        {
+          "label": "SkipLink in a layout of your own",
+          "code": "<>\n  <SkipLink />\n  <header className=\"flex items-center justify-between px-(--page-inset) py-4\">\n    <Link to=\"/\">Alder & Lune</Link>\n    <Button variant=\"ghost\" size=\"icon\" aria-label=\"Search\"><Icon name=\"search\" /></Button>\n  </header>\n  <main id=\"main-content\" tabIndex={-1}>\n    <Region max=\"wide\">\n      <PageHeader title=\"Lighting\" />\n    </Region>\n  </main>\n</>",
+          "imports": "import { Button, Icon, PageHeader, Region, SkipLink } from \"@sableui/react\"\n// <Link> = your router's link (react-router, next/link, @tanstack/router, …)"
+        },
         {
           "label": "Minimal (sidebar + content only)",
           "code": "<AppShell\n  sidebar={\n    <Sidebar>\n      <SidebarNav>\n        <SidebarItem icon={<Icon name=\"home\" />} label=\"Dashboard\" active render={<Link to=\"/\" />} />\n      </SidebarNav>\n    </Sidebar>\n  }\n>\n  <Region max=\"wide\">\n    <PageHeader title=\"Dashboard\" />\n  </Region>\n</AppShell>",
@@ -4922,7 +4934,12 @@
           "name": "loading",
           "type": "boolean",
           "default": "false",
-          "description": "Disable the button and show a leading Spinner while an action is in flight. Sets aria-busy; a native button is disabled, a render element (e.g. an <a>) gets aria-disabled."
+          "description": "Show a leading Spinner while an action is in flight and refuse presses. Sets aria-busy and aria-disabled, never the native disabled: disabling the focused button sent focus to <body>, so a sheet the action opened had nowhere to return it."
+        },
+        {
+          "name": "onClick",
+          "type": "(event: MouseEvent<HTMLButtonElement>) => unknown",
+          "description": "May return a promise: the button shows `loading` until it settles and ignores further presses meanwhile, from the first click on. Prefer it to a `busy` flag in state, which takes effect a render late (three fast clicks ran three times)."
         },
         {
           "name": "badge",
@@ -5354,7 +5371,7 @@
           "name": "variant",
           "type": "\"default\" | \"flat\"",
           "default": "\"default\"",
-          "description": "\"default\" raises with bg-card + border + soft shadow; \"flat\" is transparent."
+          "description": "\"default\" raises with bg-card + border + soft shadow; \"flat\" is transparent, for a card inside a section that already frames it. A flat card made a link or button shows its shape only on hover (the muted fill), so over a photo with square bottom corners it reads as a cropped image at rest: give a linked media card the default variant."
         },
         {
           "name": "density",
@@ -7800,6 +7817,7 @@
     {
       "name": "DateTile",
       "status": "stable",
+      "composition": "a <time> element with the type tiers, on a surface utility",
       "group": "Data display",
       "register": "page",
       "path": "components/date-tile",
@@ -8859,6 +8877,7 @@
     {
       "name": "Feedback",
       "status": "stable",
+      "composition": "Popover, Textarea, ToggleGroup, Button",
       "group": "Overlays",
       "register": "page",
       "path": "components/feedback",
@@ -8972,7 +8991,7 @@
       "group": "Forms",
       "register": "either",
       "path": "components/fieldset",
-      "summary": "Form section panel (Card-like bordered surface) over Base UI Fieldset, with Legend/Description/Content/Footer parts.",
+      "summary": "Form section panel (Card-like bordered surface) over Base UI Fieldset, with Legend/Description/Content/Footer parts; `variant=\"plain\"` is the bare group, for a radio group's shared name.",
       "keywords": [
         "fieldset",
         "form group",
@@ -8994,6 +9013,10 @@
             "guidance": "dont",
             "description": "Do not use Fieldset as a generic spacing wrapper outside forms."
           },
+          {
+            "guidance": "do",
+            "description": "Use `variant=\"plain\"` to name a radio group or a run of checkboxes inside a form or card that is already framed: the legend reads as a field label and nothing draws a second box. Do not strip the card variant with classes instead."
+          },
           {
             "guidance": "dont",
             "description": "Do not use a Legend that is really a heading. A legend names the group's question for assistive technology; using it as a section title puts a question mark where the outline should be."
@@ -9034,6 +9057,12 @@
         ]
       },
       "props": [
+        {
+          "name": "variant",
+          "type": "\"card\" | \"plain\"",
+          "default": "\"card\"",
+          "description": "`card` is a bordered, raised section with padded parts. `plain` is the grouping alone (no border, surface or inset) with the legend in the field-label style: the shared name a radio group needs, inside a form that is already framed."
+        },
         {
           "name": "disabled",
           "type": "boolean",
@@ -9095,6 +9124,11 @@
           "label": "Why a fieldset, and when it is wrong",
           "code": "// Fieldset groups inputs that are ONE question with multiple parts, and gives\n// the group a single accessible name — which is the part you cannot do with a\n// div and a heading.\n\n<Fieldset>\n  <FieldsetLegend>Digest frequency</FieldsetLegend>\n  <FieldsetContent>\n    <RadioGroup defaultValue=\"weekly\">\n      <Field label=\"Daily\" orientation=\"horizontal\"><Radio value=\"daily\" /></Field>\n      <Field label=\"Weekly\" orientation=\"horizontal\"><Radio value=\"weekly\" /></Field>\n    </RadioGroup>\n  </FieldsetContent>\n</Fieldset>\n\n// ✓ Required for radio groups: without a fieldset the options have no shared\n//   name, so a screen reader announces \"Weekly, radio\" with no question.\n// ✗ Not for visual grouping of unrelated fields. Use PanelSection on a panel or\n//   a Card section on a page; a legend that is really a heading lies to\n//   assistive technology about the form's structure.",
           "imports": "import { Field, Fieldset, FieldsetContent, FieldsetLegend, Radio, RadioGroup } from \"@sableui/react\""
+        },
+        {
+          "label": "A radio group's name, without a second box",
+          "code": "<Card>\n  <CardContent>\n    <Fieldset variant=\"plain\">\n      <FieldsetLegend>Delivery</FieldsetLegend>\n      <RadioGroup defaultValue=\"standard\">\n        <RadioCard value=\"standard\" title=\"Standard\" description=\"3–5 working days\" trailing=\"Free\" />\n        <RadioCard value=\"express\" title=\"Express\" description=\"Next working day\" trailing=\"$12.00\" />\n      </RadioGroup>\n    </Fieldset>\n  </CardContent>\n</Card>",
+          "imports": "import { Card, CardContent, Fieldset, FieldsetLegend, RadioCard, RadioGroup } from \"@sableui/react\""
         }
       ]
     },
@@ -9575,7 +9609,12 @@
         {
           "name": "Form",
           "type": "{ validationMode?: \"onSubmit\" | \"onBlur\" | \"onChange\"; errors?: Record<string, string | string[]>; onFormSubmit?: (values, details) => void; actionsRef?: RefObject<Form.Actions> } + ComponentPropsWithRef<\"form\">",
-          "description": "A <form> laid out as a vertical column with comfortable field spacing (override with className, e.g. gap-4). On submit it validates every Field (native constraints plus Field validate), shows each message under its field, focuses the first invalid control, and only then calls onSubmit. validationMode defaults to \"onSubmit\" (then live re-validation on change). errors shows external (e.g. server) messages keyed by Field name and clears one when its field is edited. onFormSubmit receives the named Field values and prevents the native submit. A control outside any Field is still checked by the browser before onSubmit runs. Validating in your own code (react-hook-form, a schema, state)? Pass noValidate: onSubmit always runs and each Field shows the error you set; without it an empty required Field stops the submit before your handler can set that error."
+          "description": "A <form> laid out as a vertical column with comfortable field spacing (override with className, e.g. gap-4). On submit it validates every Field (native constraints plus Field validate), shows each message under its field, focuses the first invalid control, and only then calls onSubmit. validationMode defaults to \"onSubmit\" (then live re-validation on change). errors shows external (e.g. server) messages keyed by Field name and clears one when its field is edited. onFormSubmit receives the named Field values and prevents the native submit. A control outside any Field is still checked by the browser before onSubmit runs. Validating in your own code (react-hook-form, a schema, state)? Pass noValidate: onSubmit always runs and each Field shows the error you set; without it an empty required Field stops the submit before your handler can set that error. Either way, once onSubmit returns (or the promise it returns settles), the first control a Field marks invalid takes focus."
+        },
+        {
+          "name": "onSubmit",
+          "type": "(event: FormEvent<HTMLFormElement>) => unknown",
+          "description": "The native submit handler. It may return a promise. When it returns, or its promise settles, the first control a Field marks invalid takes focus, so errors your own code sets get the same treatment as Sable's validation."
         },
         {
           "name": "validationMode",
@@ -9608,8 +9647,8 @@
       "subcomponents": [
         {
           "name": "Field",
-          "type": "{ label?: ReactNode; description?: ReactNode; error?: ReactNode; required?: boolean; messages?: Partial<Record<\"valueMissing\" | \"typeMismatch\" | \"patternMismatch\" | \"tooShort\" | \"tooLong\" | \"rangeUnderflow\" | \"rangeOverflow\" | \"stepMismatch\" | \"badInput\", ReactNode>>; disabled?: boolean; name?: string; validate?: (value, formValues) => string | string[] | null | Promise<…>; validationMode?: \"onSubmit\" | \"onBlur\" | \"onChange\"; validationDebounceTime?: number; orientation?: \"vertical\" | \"horizontal\"; className?: string; children: ReactElement }",
-          "description": "Wraps a single control element (e.g. <Input />) on Base UI Field and wires label (htmlFor + aria-labelledby), helper text and error (aria-describedby), aria-invalid, and required onto it automatically. Base UI-backed controls (Input, Textarea, Select, Combobox, NumberField, Checkbox, Switch, Slider, OtpField…) register through context; the child is also cloned so plain elements keep the same wiring. error renders a destructive message and takes precedence; without it the slot shows the field's messages entry for the native constraint that failed (messages={{ valueMissing: \"Enter a subject.\" }}), else Base UI's validation message (the browser's wording for a native constraint, validate, or Form errors). required adds the native attribute plus a visual asterisk (defaults to false). disabled disables the control and dims the label. name keys the field in Form errors / onFormSubmit. validationMode overrides the Form's. orientation defaults to \"vertical\" (label → control); \"horizontal\" places control then label inline for a single checkbox / switch / radio — the control centres on the label's first line (it stays there when the label wraps) and description/error sit in the label's column. The root, label, description, error and control carry data-invalid / data-valid, data-touched, data-dirty, data-filled, data-focused and data-disabled for state styling."
+          "type": "{ label?: ReactNode; description?: ReactNode; error?: ReactNode; required?: boolean; messages?: Partial<Record<\"valueMissing\" | \"typeMismatch\" | \"patternMismatch\" | \"tooShort\" | \"tooLong\" | \"rangeUnderflow\" | \"rangeOverflow\" | \"stepMismatch\" | \"badInput\", ReactNode>>; disabled?: boolean; name?: string; validate?: (value, formValues) => string | string[] | null | Promise<…>; validationMode?: \"onSubmit\" | \"onBlur\" | \"onChange\"; validationDebounceTime?: number; orientation?: \"vertical\" | \"horizontal\"; trailing?: ReactNode; className?: string; children: ReactElement } + other div props on the root",
+          "description": "Wraps a single control element (e.g. <Input />) on Base UI Field and wires label (htmlFor + aria-labelledby), helper text and error (aria-describedby), aria-invalid, and required onto it automatically. Base UI-backed controls (Input, Textarea, Select, Combobox, NumberField, Checkbox, Switch, Slider, OtpField…) register through context; the child is also cloned so plain elements keep the same wiring. error renders a destructive message and takes precedence; without it the slot shows the field's messages entry for the native constraint that failed (messages={{ valueMissing: \"Enter a subject.\" }}), else Base UI's validation message (the browser's wording for a native constraint, validate, or Form errors). required adds the native attribute plus a visual asterisk (defaults to false). disabled disables the control and dims the label. name keys the field in Form errors / onFormSubmit. validationMode overrides the Form's. orientation defaults to \"vertical\" (label → control); \"horizontal\" places control then label inline for a single checkbox / switch / radio — the control centres on the label's first line (it stays there when the label wraps) and description/error sit in the label's column. trailing puts something at the end of the control's row: vertically, beside the control (a promo code's Apply button, the control taking the rest); horizontally, at the end of the label's first line (a facet count). Other props (data-*, id, aria-*) land on the root. The root, label, description, error and control carry data-invalid / data-valid, data-touched, data-dirty, data-filled, data-focused and data-disabled for state styling."
         }
       ],
       "tokensUsed": [
@@ -9633,6 +9672,11 @@
           "code": "<Field label=\"Password\" error=\"Must be at least 8 characters.\"><Input type=\"password\" /></Field>",
           "imports": "import { Field, Input } from \"@sableui/react\""
         },
+        {
+          "label": "An input with its action",
+          "code": "<Field label=\"Promo code\" error={promoError} trailing={<Button variant=\"secondary\" onClick={applyPromo}>Apply</Button>}><Input name=\"promo\" autoCapitalize=\"characters\" /></Field>",
+          "imports": "import { Button, Field, Input } from \"@sableui/react\""
+        },
         {
           "label": "Your own wording for a missing value",
           "code": "<Form onSubmit={handleSubmit}><Field label=\"Subject\" required messages={{ valueMissing: \"Enter a subject.\" }}><Input name=\"subject\" /></Field><Button type=\"submit\">Send</Button></Form>",
@@ -11107,6 +11151,7 @@
     {
       "name": "MediaTile",
       "status": "beta",
+      "composition": "AspectBox, MediaImage, a stretched link (or Card render), Badge appearance=\"overlay\", Button",
       "group": "Media & mockups",
       "register": "page",
       "path": "components/media-tile",
@@ -11208,11 +11253,26 @@
           "type": "ReactNode",
           "description": "The second line — an artist, a channel, a year."
         },
+        {
+          "name": "meta",
+          "type": "ReactNode",
+          "description": "Lines under the subtitle, in its muted type: a price beside its sale price, a count of finishes, a status Badge. A wrapping block, where the subtitle is one truncated line. Use it for a product tile instead of building one."
+        },
         {
           "name": "src",
           "type": "string",
           "description": "Cover image URL. Without one, or when it fails, the cover is GradientArt seeded by the item."
         },
+        {
+          "name": "srcSet",
+          "type": "string",
+          "description": "Responsive cover candidates, passed to the `<img>`."
+        },
+        {
+          "name": "sizes",
+          "type": "string",
+          "description": "The cover's layout width for `srcSet`, e.g. `\"(min-width: 64rem) 25vw, 50vw\"`."
+        },
         {
           "name": "alt",
           "type": "string",
@@ -11338,6 +11398,11 @@
         "Truncated titles keep their full text in the link's accessible name and in a `title` tooltip."
       ],
       "examples": [
+        {
+          "label": "Product tile",
+          "code": "<Grid minItemWidth=\"14rem\" gap={4}>\n\t{products.map((product) => (\n\t\t<MediaTile\n\t\t\tkey={product.id}\n\t\t\taspect={4 / 5}\n\t\t\ttitle={product.name}\n\t\t\tsubtitle={product.material}\n\t\t\tsrc={product.image}\n\t\t\tsrcSet={product.imageSet}\n\t\t\tsizes=\"(min-width: 64rem) 25vw, 50vw\"\n\t\t\trender={<Link to={`/products/${product.slug}`} />}\n\t\t\tbadge={product.isNew ? <Badge appearance=\"overlay\">New</Badge> : undefined}\n\t\t\tmeta={\n\t\t\t\t<>\n\t\t\t\t\t<span className=\"text-foreground\">{formatPrice(product.price)}</span>\n\t\t\t\t\t<span>{product.finishes.length} finishes</span>\n\t\t\t\t</>\n\t\t\t}\n\t\t/>\n\t))}\n</Grid>",
+          "imports": "import { Badge, Grid, MediaTile } from \"@sableui/react\"\n// <Link> = your router's link (react-router, next/link, @tanstack/router, …)"
+        },
         {
           "label": "Album grid",
           "code": "<Grid minItemWidth=\"10rem\" gap={3}>\n\t{albums.map((album) => (\n\t\t<MediaTile\n\t\t\tkey={album.id}\n\t\t\ttitle={album.title}\n\t\t\tsubtitle={album.artist}\n\t\t\tsrc={album.cover}\n\t\t\trender={<Link to={`/albums/${album.id}`} />}\n\t\t\tsubtitleRender={<Link to={`/artists/${album.artistId}`} />}\n\t\t\taction={\n\t\t\t\t<Button size=\"icon\" aria-label={`Play ${album.title}`} onClick={() => play(album)}>\n\t\t\t\t\t<Icon name=\"play\" variant=\"solid\" />\n\t\t\t\t</Button>\n\t\t\t}\n\t\t/>\n\t))}\n</Grid>",
@@ -14801,6 +14866,11 @@
           "type": "ReactNode",
           "description": "Optional supporting copy beneath the title (text-body-sm, muted)."
         },
+        {
+          "name": "trailing",
+          "type": "ReactNode",
+          "description": "End-aligned on the title's line: a price, a delivery date, a count. The title takes the rest of the row."
+        },
         {
           "name": "icon",
           "type": "ReactNode",
@@ -17687,7 +17757,7 @@
           "name": "orientation",
           "type": "\"horizontal\" | \"vertical\"",
           "default": "\"horizontal\"",
-          "description": "Horizontal for a short flow across the top of a form; vertical for long flows, narrow columns or steps with descriptions."
+          "description": "Horizontal for a short flow across the top of a form; vertical for long flows, narrow columns or steps with descriptions. A horizontal stepper narrower than 28rem (a phone) compacts itself: every disc stays, only the current step's title shows, and the other titles stay for screen readers. No breakpoint code needed."
         },
         {
           "name": "indicator",
@@ -23874,6 +23944,7 @@
         "iconStart",
         "loading",
         "loadingLabel",
+        "onClick",
         "render",
         "size",
         "variant"
@@ -24289,6 +24360,7 @@
         "disabled",
         "hint",
         "icon",
+        "leading",
         "onSelect",
         "stacked"
       ],
@@ -24621,6 +24693,7 @@
         "name",
         "orientation",
         "required",
+        "trailing",
         "validate",
         "validationDebounceTime",
         "validationMode"
@@ -24628,7 +24701,8 @@
       "Fieldset": [
         "className",
         "render",
-        "style"
+        "style",
+        "variant"
       ],
       "FieldsetLegend": [
         "className",
@@ -24676,6 +24750,7 @@
         "errors",
         "noValidate",
         "onFormSubmit",
+        "onSubmit",
         "validationMode"
       ],
       "GlidingHighlight": [
@@ -24790,10 +24865,13 @@
         "badge",
         "href",
         "loading",
+        "meta",
         "render",
         "seed",
         "size",
+        "sizes",
         "src",
+        "srcSet",
         "subtitle",
         "subtitleHref",
         "subtitleRender",
@@ -25352,6 +25430,7 @@
         "title",
         "titleClassName",
         "tone",
+        "trailing",
         "value"
       ],
       "RadioGroup": [
@@ -26377,7 +26456,7 @@
             "name": "themeStorageKey",
             "type": "string | null",
             "default": "SABLE_THEME_STORAGE_KEY",
-            "description": "localStorage key for the design theme. null disables persistence."
+            "description": "localStorage key for the design theme. null disables persistence. The default key is shared by every Sable app on an origin (several apps on localhost:5173 in development), and a stored id another app set wins over `defaultThemeId` when this app knows it too. An app with one fixed preset passes `themeId` (or `themeStorageKey={null}`); an app that lets users switch themes passes its own key."
           },
           {
             "name": "target",

package/scripts/grade.mjs

@@ -304,6 +304,9 @@ const UNIVERSAL_PROPS = new Set([
 	"minLength", "min", "max", "step", "rows", "cols", "open", "selected", "multiple", "loading",
 	// Media attributes, for components that spread onto <video>/<audio>/<img> (Video, Image).
 	"autoPlay", "muted", "loop", "playsInline", "preload", "crossOrigin", "decoding", "fetchPriority", "srcSet", "sizes",
+	// Input attributes the form contract asks for (the numeric keypad, the
+	// return key's label), on components that spread onto <input>.
+	"inputMode", "enterKeyHint", "autoCapitalize", "autoCorrect", "pattern", "list", "accept", "capture",
 ])
 const isEventProp = (p) => /^on[A-Z]/.test(p)
 const isPassthrough = (p) => p.startsWith("data-") || p.startsWith("aria-") || p.startsWith("--")
@@ -500,6 +503,14 @@ for (const file of files) {
 	/* 7. Surfaces the app built itself (informational). */
 	if (/\.(tsx|jsx)$/.test(file)) {
 		for (const { index, ...s } of surfaceInventory(text)) inventory.push({ file: rel, line: lineOf(text, index), ...s })
+		// Arrow-key handling written by hand: list navigation is behaviour Sable
+		// owns (roving focus, active descendant, typeahead), and the storefront
+		// search wrote its own. A note, since a canvas or a game has its own keys.
+		const arrows = /\bonKeyDown\b[\s\S]{0,600}?["'`]Arrow(?:Up|Down)["'`]|["'`]Arrow(?:Up|Down)["'`][\s\S]{0,600}?\bonKeyDown\b/.exec(text)
+		if (arrows) {
+			const at = text.indexOf("Arrow", arrows.index)
+			inventory.push({ file: rel, line: lineOf(text, at), tag: "onKeyDown", kind: "keyboard", classes: "ArrowUp / ArrowDown handled by hand", consider: "CommandMenu, Combobox, Menu, Select, Toolbar or Tabs, whose keyboard model is built and tested" })
+		}
 	}
 
 	/* 8. Composition. Anything exporting a component that returns a big tree is
@@ -679,10 +690,10 @@ if (conformance.length) {
 	L("  composition                 no route-like files found")
 }
 if (inventory.length) {
-	const kinds = ["surface", "media frame", "round"].map((k) => [k, inventory.filter((s) => s.kind === k).length]).filter(([, n]) => n)
+	const kinds = ["surface", "media frame", "round", "keyboard"].map((k) => [k, inventory.filter((s) => s.kind === k).length]).filter(([, n]) => n)
 	L()
-	L(`  app-owned surfaces (review, not scored) — ${inventory.length}: ${kinds.map(([k, n]) => `${n} ${k}`).join(" · ")}`)
-	for (const s of inventory.slice(0, 12)) L(`    ${s.file}:${s.line}  <${s.tag}> ${s.kind} (${s.classes}) → ${s.consider}`)
+	L(`  app-owned surfaces (notes, not scored; keeping your own is fine) — ${inventory.length}: ${kinds.map(([k, n]) => `${n} ${k}`).join(" · ")}`)
+	for (const s of inventory.slice(0, 12)) L(`    ${s.file}:${s.line}  <${s.tag}> ${s.kind} (${s.classes}) → Sable has ${s.consider}`)
 	if (inventory.length > 12) L(`    … ${inventory.length - 12} more (--json lists every one)`)
 }
 if (cliUsage) {

package/scripts/sources.mjs

@@ -195,13 +195,24 @@ export function sourcesCss(pkgRoot, root, outFile) {
  * that component unstyled, silently — so it fails. A whole-package @source is
  * correct, just heavy, so it only gets a note.
  */
+// The whole-package scan only: `dist`, `dist/` or a `dist/**` glob. A single
+// module (`dist/components/chart/chart.js`, a lazy route's) and an exclusion
+// (`@source not …`) are deliberate and trim nothing away.
+const WHOLE_DIST = /@source\s+(?!not\b)["'][^"']*(?:@sableui\/react|packages\/sable)\/dist\/?(?:\*\*(?:\/[^"']*)?)?["']/
+
 export function sourcesCheck(pkgRoot, root, cssFiles) {
 	const generated = cssFiles.find((f) => f.text.includes(SOURCES_MARKER))
 	if (!generated) {
-		const whole = cssFiles.some((f) => /@source[^;]*(?:@sableui\/react|packages\/sable)\/dist(?:\/\*\*)?[^;]*;/.test(f.text))
-		return whole ? [{ status: "info", name: "css:size", detail: "@source scans all of Sable's dist, so every component's classes ship (about 32 KB gzipped).", fix: "sable sources --write src/sable-sources.css, then import it in place of that @source." }] : []
+		const whole = cssFiles.some((f) => WHOLE_DIST.test(f.text))
+		return whole ? [{ status: "info", name: "css:size", detail: "@source scans all of Sable's dist, so every component's classes ship (about 32 KB gzipped; an app using half the catalog lands near 20 KB).", fix: "sable sources --write src/sable-sources.css, then import it in place of that @source." }] : []
 	}
 	const rel = relative(root, generated.path)
+	// The generated list only trims anything once the whole-package @source is
+	// gone: left beside it, Tailwind still scans every module, and the CSS stays
+	// the size it was.
+	const leftover = cssFiles.find((f) => f !== generated && WHOLE_DIST.test(f.text))
+	if (leftover)
+		return [{ status: "warn", name: "css:sources", detail: `${relative(root, leftover.path)} still has the whole-package @source, so ${rel} trims nothing: Tailwind scans all of Sable either way.`, fix: `Delete that @source line; ${rel} replaces it.` }]
 	const { modules, unresolved } = sableModules(pkgRoot, appSources(root))
 	if (unresolved.length && !/\/dist\/\*\*\//.test(generated.text))
 		return [{ status: "fail", name: "css:sources", detail: `${rel} lists modules, but these imports could not be traced: ${unresolved.slice(0, 4).join(", ")}.`, fix: `sable sources --write ${rel}` }]

package/skills/sable/SKILL.md

@@ -29,9 +29,11 @@ References inform an original direction. A reference or preset is optional.
    `"reduced"`), state still changes and nothing keeps moving.
 6. Write the reuse inventory: the Sable components, parts, utilities, and token
    groups used, and every app-owned UI or CSS addition with the catalog search
-   that justified it. Start from the app-owned surfaces `sable check` lists:
-   each one composes the component named beside it, or the inventory says why
-   the app owns it.
+   that justified it. Start from the app-owned surfaces `sable check` lists,
+   which are notes, not failures: for each, write one line saying you used the
+   Sable part named beside it or kept your own, and why ("composed our own
+   product tile from AspectBox + Badge: the brief wants the price over the
+   photo"). Keeping your own layout is fine. Behaviour still comes from Sable.
 7. Record what you learned: `sable docs learning-from-builds`. Keep conditional
    lessons with evidence; never fabricate human approval or preference records.
 
@@ -142,9 +144,18 @@ The installed catalog and guides are authoritative for API and token names.
 
 1. Search the installed catalog for every recognizable element or behavior:
    `sable search "<need>" --json`. Inspect the matching
-   `sable component <Name> --props` and `--examples` before using it. Use its public
-   component and composed anatomy. A native element wearing a component's classes
-   is a reinvention, even if it uses valid tokens.
+   `sable component <Name> --props` and `--examples` before using it. What a
+   result asks of you depends on what it is:
+   - **Behaviour** (controls, fields, overlays, menus, tabs, anything with focus,
+     keyboard or ARIA): always use it, never rebuild it. A native element wearing
+     a component's classes, or arrow keys handled by hand, is a reinvention even
+     if it uses valid tokens.
+   - **Parts** (Card, Entity, AspectBox, Badge, Avatar, MediaImage, layout
+     primitives): compose them freely, in whatever arrangement the design needs.
+   - **References** (patterns, blocks, and compositions marked ◇ such as
+     MediaTile): use one when its layout fits the brief. When it doesn't, compose
+     your own from parts; that is not a gap and needs no apology. Apps on Sable
+     should not all look alike.
 2. Resolve styling in this order: Sable component/variant, Sable utility or recipe,
    semantic token, then app-owned CSS for a genuinely uncovered need. Retrieve
    `sable utility <name>` and `sable token <group>` rather than guessing names.
@@ -170,7 +181,12 @@ The installed catalog and guides are authoritative for API and token names.
 Save a short brief in the project's existing design location: audience, primary
 task, content, constraints, selected identity, and meaningful states, plus each
 route's width (a Region `max`, or fluid) and why, chosen by what the person does
-there (`sable docs building-a-page`). Label invented sample content. A supplied preset is an explicit input: read its exact record and
+there (`sable docs building-a-page`). Name the product's signature surfaces: the
+one to three places its identity lives (a shop's product card and search, a music
+app's player and album tile). Design those from the brief's direction first,
+composing Sable's parts and behaviour; take a Sable reference for one only when
+it already matches that direction. Everything else (forms, settings, menus,
+tables) takes Sable's defaults. Label invented sample content. A supplied preset is an explicit input: read its exact record and
 revision, validate it through `sable preset --check <path> --json`, and read
 `sable docs using-presets`. Preserve its tokens and guidance unless the user requests
 a change or the new task requires a documented adaptation.