@sableui/react 0.17.0 → 0.19.0

package/scripts/grade.mjs

@@ -33,10 +33,12 @@ import { existsSync, readFileSync, readdirSync, statSync } from "node:fs"
 import { createHash } from "node:crypto"
 import { dirname, extname, join, relative, resolve } from "node:path"
 import { fileURLToPath } from "node:url"
-import { ignoreGlob, lintText, makeRules, surfaceInventory } from "./lint-rules.mjs"
+import { compositionNotes, ignoreGlob, lintText, makeRules, partMirrors, surfaceInventory } from "./lint-rules.mjs"
+import { cssNotes, modeCoverage } from "./app-css.mjs"
 import { labelContrastScanner, statusTextDrift } from "./label-contrast.mjs"
 import { skeletonize } from "./skeleton.mjs"
 import { assessReview, reviewTemplate } from "./review-evidence.mjs"
+import { adoptionReport, swapLines } from "./adoption.mjs"
 
 const HERE = dirname(fileURLToPath(import.meta.url))
 const PKG_ROOT = join(HERE, "..")
@@ -112,6 +114,31 @@ const motionTokens = new Set(
 const RULES = makeRules({ semanticTokens, motionTokens, labelContrast: await labelContrastScanner(PKG_ROOT, REGISTRY.themes?.default), statusText: (css) => statusTextDrift(css, REGISTRY.themes?.default) }).filter((r) => r.scope !== "package")
 const PROP_SURFACE = REGISTRY.propSurface?.items ?? {}
 const ICONS = new Set(REGISTRY.iconContract?.names ?? [])
+/** Other sets' names <Icon> resolves to a contract name (`menu` → bars): they draw, so they are not off-contract. */
+const ICON_ALIASES = REGISTRY.iconContract?.aliases ?? {}
+const iconKnown = (n) => ICONS.has(n) || Boolean(ICON_ALIASES[n]) || Boolean(APP_ICONS?.names.has(n))
+/** The contract names nearest an unknown one: sharing a word first, then by edit distance. */
+function nearestIcons(name, limit = 3) {
+	const distance = (a, b) => {
+		const row = Array.from({ length: b.length + 1 }, (_, i) => i)
+		for (let i = 1; i <= a.length; i++) {
+			let prev = row[0]
+			row[0] = i
+			for (let j = 1; j <= b.length; j++) {
+				const cur = row[j]
+				row[j] = Math.min(row[j] + 1, row[j - 1] + 1, prev + (a[i - 1] === b[j - 1] ? 0 : 1))
+				prev = cur
+			}
+		}
+		return row[b.length]
+	}
+	const parts = new Set(name.toLowerCase().split(/[-_\s]+/))
+	return [...ICONS]
+		.map((c) => ({ c, s: distance(name.toLowerCase(), c) - (c.split("-").some((p) => parts.has(p)) ? 3 : 0) }))
+		.sort((a, b) => a.s - b.s)
+		.slice(0, limit)
+		.map((x) => x.c)
+}
 /**
  * The names an app adds with `composeIconSets(appExtras, reiconIconSet)`. That is
  * the sanctioned way to extend the set, and the grade cannot read a set's names
@@ -375,6 +402,18 @@ const routeSkeletons = []
    of listing from memory. The lookalike-* lint rules fail the unambiguous
    cases; this lists the rest. */
 const inventory = []
+/** UI sources for the adoption report: how much of the app is built from Sable. */
+const uiSources = []
+/** The app's own stylesheets, read for what its TSX does not show (app-css.mjs). */
+const cssSources = []
+/**
+ * Rebuilt parts and overrides: elements whose class names mirror a Sable part,
+ * and what the app's CSS does to Sable from outside. Notes for the reuse
+ * inventory, never scored: each is answered there ("used the part" or "kept
+ * mine, because …").
+ */
+const rebuiltParts = []
+const PART_NAMES = new Set((REGISTRY.components ?? []).flatMap((c) => [c.name, ...(c.subcomponents ?? []).map((s) => (typeof s === "string" ? s : s.name))]))
 
 /**
  * Attribute names on one JSX open tag, stopping at the tag's own `>`.
@@ -434,6 +473,11 @@ for (const file of files) {
 		findings.contract.push({ ...v, file: rel })
 	}
 
+	if (ctx.isStylesheet) {
+		cssSources.push({ rel, text })
+		for (const n of cssNotes(text)) rebuiltParts.push({ file: rel, ...n })
+	}
+
 	if (!/\.(tsx|jsx|ts|js)$/.test(extname(file) ? file : "")) continue
 
 	/* 2. Imports that name something the subpath they come from does not export.
@@ -496,13 +540,18 @@ for (const file of files) {
 	for (const [local, { name }] of imported) {
 		if (name !== "Icon") continue
 		for (const m of code.matchAll(new RegExp(`<${local}\\s+[^>]*name=["']([^"']+)["']`, "g"))) {
-			if (!ICONS.has(m[1]) && !APP_ICONS?.names.has(m[1])) findings.offContractIcon.push({ file: rel, name: m[1], line: lineOf(text, m.index) })
+			if (!iconKnown(m[1])) findings.offContractIcon.push({ file: rel, name: m[1], suggest: nearestIcons(m[1]), line: lineOf(text, m.index) })
 		}
 	}
 
 	/* 7. Surfaces the app built itself (informational). */
 	if (/\.(tsx|jsx)$/.test(file)) {
+		uiSources.push({ rel, text })
 		for (const { index, ...s } of surfaceInventory(text)) inventory.push({ file: rel, line: lineOf(text, index), ...s })
+		for (const m of partMirrors(text, PART_NAMES))
+			rebuiltParts.push({ file: rel, line: lineOf(text, m.index), kind: "rebuilt part", what: `<${m.tag} className="${m.token}">`, consider: `${m.part}${m.hint ? ` (${m.hint})` : ""}` })
+		for (const n of compositionNotes(text, PART_NAMES))
+			rebuiltParts.push({ file: rel, line: lineOf(text, n.index), kind: "composition", what: n.what, consider: n.consider })
 		// 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.
@@ -521,6 +570,106 @@ for (const file of files) {
 	}
 }
 
+/* 6b. Icon names that reach <Icon> through the app's own wrapper. A work tracker
+      wrote `function Glyph({ name }) { return <Icon name={aliases[name] || name} /> }`
+      and passed it `users`, `menu`, `columns`: nine names the set lacks, each an
+      icon that rendered nothing, none of them visible to the check above, which
+      reads only literal `<Icon name="…">`. A component that forwards one of its
+      props into Icon's `name` (or into another wrapper's) is a wrapper; the
+      literals passed to it are judged, after its alias map if it has one. An
+      alias map is itself a note: it renames names the set does not have. */
+const iconAliasNotes = []
+{
+	const DECL = /(?:^|\n)[ \t]*(?:export\s+(?:default\s+)?)?(?:function\s+([A-Z]\w*)\s*\(\s*\{([^}]*)\}|const\s+([A-Z]\w*)\s*(?::[^=\n]+)?=\s*\(\s*\{([^}]*)\}[^\n]*?=>)/g
+	const wrappers = new Map() // name → { prop, target, aliases, file, line }
+	const sources = uiSources.map(({ rel, text }) => {
+		const icons = [...sableImports(text)].filter(([, v]) => v.name === "Icon").map(([local]) => local)
+		const decls = [...text.matchAll(DECL)].map((m) => ({ name: m[1] ?? m[3], params: (m[2] ?? m[4]).split(",").map((p) => p.trim().split(/[\s:=]/)[0]).filter(Boolean), index: m.index }))
+		return { rel, text, icons, decls }
+	})
+	const forwardsTo = (body, target, prop, params) => {
+		for (const m of body.matchAll(new RegExp(`<${target}\\b[^>]*?\\b${prop}=\\{([^}]*)\\}`, "g"))) {
+			const param = params.find((p) => new RegExp(`\\b${p}\\b`).test(m[1]))
+			if (param) return { param, expr: m[1] }
+		}
+		return null
+	}
+	for (let round = 0; round < 3; round++) {
+		for (const { rel, text, icons, decls } of sources) {
+			decls.forEach((d, i) => {
+				if (wrappers.has(d.name)) return
+				const body = text.slice(d.index, decls[i + 1]?.index ?? text.length)
+				const targets = [...icons.map((t) => [t, "name"]), ...[...wrappers].map(([w, v]) => [w, v.prop])]
+				for (const [target, prop] of targets) {
+					const hit = forwardsTo(body, target, prop, d.params)
+					if (!hit) continue
+					// `aliases[name] || name`: the object literal it indexes, read as pairs.
+					const mapName = /\b(\w+)\s*\[\s*\w+\s*\]/.exec(hit.expr)?.[1]
+					const literal = mapName ? new RegExp(`\\b${mapName}\\b[^=\\n]*=\\s*\\{([^{}]*)\\}`).exec(body)?.[1] : null
+					const aliases = literal ? new Map([...literal.matchAll(/["']?([\w-]+)["']?\s*:\s*["']([\w-]+)["']/g)].map((p) => [p[1], p[2]])) : null
+					wrappers.set(d.name, { prop: hit.param, target, aliases, file: rel, line: lineOf(text, d.index) })
+					break
+				}
+			})
+		}
+	}
+	const known = iconKnown
+	/** A literal passed to a wrapper, followed through its alias map to the name Icon gets. */
+	const resolveIcon = (wrapper, value) => {
+		let name = value
+		for (let w = wrappers.get(wrapper), hops = 0; w && hops < 5; w = wrappers.get(w.target), hops++) name = w.aliases?.get(name) ?? name
+		return name
+	}
+	for (const [name, w] of wrappers) {
+		if (!w.aliases) continue
+		const renamed = [...w.aliases].filter(([from, to]) => !ICONS.has(from) && !APP_ICONS?.names.has(from) && known(to))
+		for (const [from, to] of w.aliases) if (!known(to)) findings.offContractIcon.push({ file: w.file, name: to, via: `${name} alias map (${from})`, suggest: nearestIcons(to), line: w.line })
+		if (renamed.length)
+			iconAliasNotes.push({ file: w.file, line: w.line, kind: "icon aliases", what: `${name} renames ${renamed.length} icon name(s) the set does not have: ${renamed.slice(0, 6).map(([a, b]) => `${a}→${b}`).join(", ")}${renamed.length > 6 ? ", …" : ""}`, consider: "the set's own names (sable icon <name> says which exist), or composeIconSets to add the glyphs; a stand-in glyph (archive→inbox) makes two different things look the same" })
+	}
+	for (const { rel, text } of sources) {
+		for (const [name, w] of wrappers) {
+			for (const m of text.matchAll(new RegExp(`<${name}\\b[^>]*?\\b${w.prop}=["']([^"']+)["']`, "g"))) {
+				const resolved = resolveIcon(name, m[1])
+				if (!known(resolved)) findings.offContractIcon.push({ file: rel, name: m[1], via: name, suggest: nearestIcons(resolved), line: lineOf(text, m.index) })
+			}
+		}
+	}
+}
+rebuiltParts.push(...iconAliasNotes)
+{
+	// One line per mirrored class per file (`crumb` ×4 is one finding), and the
+	// parts first: what to swap before what to retune.
+	const ORDER = ["rebuilt part", "composition", "icon aliases", "override", "fixed height"]
+	const grouped = new Map()
+	for (const r of rebuiltParts) {
+		const key = r.kind === "rebuilt part" ? `${r.file}|${r.what}` : `${r.file}|${r.line}|${r.what}`
+		const seen = grouped.get(key)
+		if (seen) seen.count = (seen.count ?? 1) + 1
+		else grouped.set(key, { ...r })
+	}
+	rebuiltParts.splice(0, rebuiltParts.length, ...[...grouped.values()].sort((a, b) => ORDER.indexOf(a.kind) - ORDER.indexOf(b.kind) || a.file.localeCompare(b.file) || a.line - b.line))
+}
+
+/* 9. Both colour modes. An app that retints Sable on :root and writes nothing
+      for .dark ships a dark mode nobody designed: Sable's dark palette under the
+      app's light accents. A warning, not a score: one mode can be the brief, but
+      then the app should say so by never offering the other. */
+const SEMANTIC = new Set((REGISTRY.tokens?.semantic ?? []).map((t) => t.name))
+const coverage = modeCoverage(cssSources, SEMANTIC)
+const MODE_CONTROL = /^(?:ThemeSwitcher|ThemeSelector|useSableTheme)$/
+const modeControl = uiSources.some(({ text }) => [...sableImports(text).values()].some((v) => MODE_CONTROL.test(v.name)))
+const modes = {
+	informationalOnly: true,
+	lightTokens: coverage.light,
+	darkTokens: coverage.dark,
+	lightOnly: coverage.lightOnly,
+	modeControl,
+	status: coverage.lightOnly.length >= 3 ? "warn" : "ok",
+	meaning: "Colour tokens the app sets for light with no dark value, and whether it ships a light/dark control. Not scored.",
+	fix: 'Put both modes in a preset (sable preset --template, then sable preset --css), and mount ThemeSwitcher under SableThemeProvider so both can be reviewed. A light-only brief pins light (SableThemeProvider defaultPreference="light") and says so.',
+}
+
 function lineOf(text, index) {
 	return text.slice(0, index).split("\n").length
 }
@@ -632,6 +781,12 @@ if (reviewPath) {
 }
 const review = assessReview(reviewDocument, { baseDir: reviewPath ? dirname(resolve(CWD, reviewPath)) : CWD, sourceHash })
 const clean = !Object.values(counts).some(Boolean)
+let appDeps = null
+try {
+	const pkg = JSON.parse(readFileSync(join(CWD, "package.json"), "utf8"))
+	appDeps = { ...pkg.dependencies, ...pkg.devDependencies }
+} catch { /* no package.json here: imports alone decide */ }
+const adoption = adoptionReport({ files: uiSources, components: REGISTRY.components ?? [], deps: appDeps })
 const exitCode = flags.has("strict") && (!clean || review.status !== "review-recorded") ? 1 : 0
 
 const result = {
@@ -655,6 +810,9 @@ const result = {
 		byKind: Object.fromEntries(["surface", "media frame", "round"].map((k) => [k, inventory.filter((s) => s.kind === k).length])),
 		surfaces: inventory,
 	},
+	adoption,
+	rebuiltParts: { informationalOnly: true, meaning: "Elements and styles that stand in for a Sable part or reach into one: use the part (or its variant or prop), or record why the app keeps its own. Not scored.", total: rebuiltParts.length, items: rebuiltParts },
+	modes,
 	cliUsage,
 	appIcons: APP_ICONS ? { file: APP_ICONS.file, names: APP_ICONS.names.size } : null,
 	findings,
@@ -696,6 +854,24 @@ if (inventory.length) {
 	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 (rebuiltParts.length) {
+	L()
+	L(`  rebuilt parts and overrides (notes, not scored) — ${rebuiltParts.length}`)
+	for (const r of rebuiltParts.slice(0, 12)) L(`    ${r.file}:${r.line}  ${r.what}${r.count ? ` ×${r.count}` : ""} → ${r.consider}`)
+	if (rebuiltParts.length > 12) L(`    … ${rebuiltParts.length - 12} more (--json → rebuiltParts.items)`)
+}
+if (modes.status === "warn" || !modeControl) {
+	L()
+	if (modes.status === "warn") L(`  colour modes (warning, not scored) — ${modes.lightOnly.length} colour token(s) set for light only: ${modes.lightOnly.slice(0, 6).map((t) => `--${t.name}`).join(", ")}${modes.lightOnly.length > 6 ? ", …" : ""}`)
+	if (!modeControl) L("  colour modes — no ThemeSwitcher, ThemeSelector or useSableTheme: nothing lets anyone switch modes to review both")
+	L(`    ${modes.fix}`)
+}
+if (adoption.level !== "empty") {
+	L()
+	L(`  adoption (notes, not scored) — ${adoption.level}: ${adoption.summary}`)
+	L(`    ${adoption.recommendation}`)
+	for (const line of swapLines(adoption, 12, "    ")) L(line)
+}
 if (cliUsage) {
 	L()
 	L(`  sable CLI                   ${cliUsage.invocations} invocation(s)`)

package/scripts/lint-rules.mjs

@@ -399,6 +399,132 @@ export function surfaceInventory(text) {
 	return out
 }
 
+/**
+ * Class names that say which Sable part an element is standing in for. An app
+ * that writes `<span className="crumb">` and styles `.crumb` in its own CSS
+ * passes every token rule and the surface inventory above, which reads only
+ * Tailwind's utilities: a work tracker shipped hand-built breadcrumbs, a topbar,
+ * property rows, a brand row, status dots and an avatar stack through a 100/100
+ * grade that way, each a part Sable ships. Matched on the whole class, or the
+ * class minus its leading app words (`issue-toolbar` → `toolbar`), so a word
+ * inside a longer name (`property-label`) does not count. Curated, like
+ * adoption's aliases: these are names an app gives a rebuilt part.
+ */
+const PART_CLASSES = [
+	[/^(?:bread)?crumbs?$/, "Breadcrumbs"],
+	[/^(?:top|app|header|title)-?bar$/, "WorkspaceBar", "in a Workspace; AppHeader on a page"],
+	[/^tool-?bar$/, "Toolbar"],
+	[/^tab-?bar$/, "TabsList"],
+	[/^status-?bar$/, "StatusBar"],
+	[/^(?:property|prop-row|property-row|meta-row)$/, "PropertyRow"],
+	[/^(?:brand|logo)(?:-row)?$/, "SidebarBrand"],
+	[/^(?:[a-z]+-)?dot$/, "StatusDot"],
+	[/^(?:avatars|avatar-(?:stack|group|list|row)|(?:team|user|member)-avatars|facepile)$/, "AvatarGroup"],
+	[/^(?:account|profile)-(?:row|menu|footer|switcher)$|^user-(?:menu|footer)$|^(?:sidebar|nav|rail)-(?:footer|account|user)$/, "SidebarAccount", "in SidebarFooter, as the account Menu's trigger"],
+	[/^(?:nav|sidebar|rail)-(?:group|section)(?:-label)?$/, "SidebarGroup"],
+	[/^(?:notifications?|(?:notification|file|list|user|member|contact)-(?:row|item))$/, "Entity", "rows in a CardList"],
+	[/^(?:kbd|keycap)$/, "Kbd"],
+	[/^(?:badge|chip|pill)$/, "Badge"],
+	[/^(?:empty-state|blank-state)$/, "EmptyState"],
+	[/^(?:spinner|loader)$/, "Spinner"],
+	[/^skeleton$/, "Skeleton"],
+	[/^(?:divider|separator)$/, "Separator"],
+	[/^progress(?:-bar|-track)?$/, "Progress"],
+	[/^(?:modal|dialog)$/, "Dialog"],
+	[/^(?:drawer|side-sheet)$/, "Sheet"],
+	[/^segmented(?:-control)?$/, "ToggleGroup"],
+]
+/** Tailwind utilities, whose last word can look like a part name (`bg-card`). */
+const UTILITY_CLASS = /^(?:bg|text|border|ring|shadow|fill|stroke|outline|from|to|via|divide|accent|caret|decoration|placeholder|size|w|h|min|max|p[xytrbl]?|m[xytrbl]?|gap|rounded|motion|sable)-/
+
+/**
+ * The elements in one file whose class names mirror a Sable part, for the
+ * reuse inventory. `parts` is the set of names Sable exports (components and
+ * their parts), so a map entry the catalog does not have is never reported.
+ * An element that already holds the part (`<div className="tabbar"><TabsList>`)
+ * is a layout wrapper, not a rebuild, and is skipped.
+ */
+export function partMirrors(text, parts) {
+	const src = maskMarkupTemplates(stripComments(text))
+	const out = []
+	for (const m of openingTags(src, /^[a-z][a-z0-9]*$/)) {
+		if (insideRender(src, m.index)) continue
+		for (const token of classesOf(m.attrs).plain) {
+			if (UTILITY_CLASS.test(token) || !/^[a-z][a-z0-9-]*$/.test(token)) continue
+			const words = token.split("-")
+			const candidates = words.map((_, i) => words.slice(i).join("-"))
+			const hit = PART_CLASSES.find(([re]) => candidates.some((c) => re.test(c)))
+			if (!hit || !parts.has(hit[1])) continue
+			if (new RegExp(`<${hit[1]}\\b`).test(elementContent(src, m).inner)) continue
+			out.push({ index: m.index, tag: m.tag, token, part: hit[1], ...(hit[2] ? { hint: hit[2] } : {}) })
+			break
+		}
+	}
+	return out
+}
+
+/**
+ * Sable parts composed in a way another part already does better: the shape a
+ * records workspace drifted into when nothing said otherwise. Read lexically
+ * from one file's JSX, so each is a note for the reuse inventory, never a
+ * failure. `parts` is the set of names the installed catalog exports, so a note
+ * never points at a part this version does not have.
+ */
+const COMPOSITION_NOTES = [
+	{
+		within: "Sidebar",
+		has: /<SideNav\b/,
+		what: "SideNav inside a Sidebar",
+		consider: "SidebarNav with SidebarGroup and SidebarItem: the rail's own rows, on the same columns as SidebarBrand and SidebarAccount (SideNav brings another set)",
+		needs: "SidebarGroup",
+	},
+	{
+		within: "SidebarFooter",
+		has: /<(?:Entity|Badge)\b/,
+		what: "an Entity or Badge in the rail's footer",
+		consider: "SidebarAccount as the account Menu's trigger: one row, with settings and appearance in its menu and a detail line in place of a badge",
+		needs: "SidebarAccount",
+	},
+	{
+		within: "CollapsiblePanel",
+		has: /<DataTable\b/,
+		what: "a DataTable per group inside Collapsibles",
+		consider: "one DataTable with groupBy and groups: one header, columns that line up, a count and an add action per group",
+		needs: "DataTable",
+	},
+	{
+		within: "WorkspaceBar",
+		has: /<TabsList(?![^>]*variant=)/,
+		what: "underline tabs in a WorkspaceBar",
+		consider: "TabsList variant=\"pill\": a view switch in tool chrome reads as a control beside the bar's others; underline is the page-section idiom",
+		needs: "Tabs",
+	},
+]
+
+export function compositionNotes(text, parts) {
+	const src = stripComments(text)
+	const out = []
+	for (const note of COMPOSITION_NOTES) {
+		if (!parts.has(note.needs)) continue
+		const open = new RegExp(`<${note.within}\\b[^>]*>`, "g")
+		for (const m of src.matchAll(open)) {
+			const end = src.indexOf(`</${note.within}>`, m.index)
+			if (end < 0) continue
+			const inner = src.slice(m.index + m[0].length, end)
+			const hit = note.has.exec(inner)
+			if (!hit) continue
+			out.push({ index: m.index + m[0].length + hit.index, what: note.what, consider: note.consider })
+			break
+		}
+	}
+	// A native date field: the OS draws its own format and size, beside a
+	// product that formats dates its own way everywhere else.
+	const date = /<(?:input|Input)\b[^>]*\btype=["']date["']/.exec(src)
+	if (date && parts.has("DatePicker"))
+		out.push({ index: date.index, what: "a native date input", consider: "DatePicker (size=\"xs\" in a property row, formatOptions for the trigger text)" })
+	return out
+}
+
 /**
  * Build the rule table against a token contract.
  *

package/scripts/wiring.mjs

@@ -303,7 +303,8 @@ function addTailwindPlugin(text) {
  */
 export function fixWiring({ root, pkgRoot, report, framework, dryRun = false, install = true, quiet = false }) {
 	const results = []
-	const flagged = new Map(report.checks.filter((c) => c.status === "fail" || c.status === "warn" || (c.status === "info" && c.name === "dedupe")).map((c) => [c.name, c]))
+	// Adoption is how the app is built, not how it is wired: no fix of ours applies.
+	const flagged = new Map(report.checks.filter((c) => c.name !== "adoption" && (c.status === "fail" || c.status === "warn" || (c.status === "info" && c.name === "dedupe"))).map((c) => [c.name, c]))
 	const handled = new Set()
 	const done = (check, detail, file) => {
 		handled.add(check)

package/skills/entry/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: sable
-description: Build websites and apps with Sable, develop reusable presets from inspiration, audit interfaces, polish designs, and fix scoped defects using the installed library.
+description: Use for any UI work in a project that depends on @sableui/react (a page, a component, styling, layout, theming, or a UI fix), even when the request does not mention Sable. Builds websites and apps from the installed Sable library, develops reusable presets from inspiration, audits and polishes interfaces, and fixes scoped defects.
 ---
 
 # Sable

package/skills/sable/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: sable
-description: Build original websites and apps with Sable, turn inspiration into reusable presets, audit existing interfaces, polish a selected design, and fix a scoped defect on a short path. Use for Sable design and UI work, not unrelated backend tasks.
+description: Use for any UI work in a project that depends on @sableui/react (a page, a component, styling, layout, theming, or a UI fix), even when the request does not mention Sable. Builds websites and apps from the installed Sable library, turns inspiration into reusable presets, audits and polishes existing interfaces, and fixes scoped defects. Not for unrelated backend tasks.
 ---
 
 # Sable
@@ -35,7 +35,11 @@ the check turns up more than the fix. Say that you escalated, and why.
    `sable lint`, and `sable grade` and exits 1 if any fails. Repair the findings
    instead of suppressing them, then run it again until it passes. Act on its
    notes too: they don't fail the check but name real work, such as trimming the
-   CSS to the components the app imports (`sable sources`). Also run the
+   CSS to the components the app imports (`sable sources`), an Adoption block
+   listing app-built components Sable already ships, which you put to the user
+   (see "Adoption" under Verify and deliver), a Rebuilt parts block (elements
+   and app CSS standing in for a part, or reaching into one), and a colour-modes
+   warning, which you fix rather than explain. Also run the
    project's own build and type checks.
 2. Review the rendered design: `sable docs reviewing-a-design`. Capture desktop and
    mobile in every promised colour mode, and judge brief fit, composition,
@@ -49,8 +53,8 @@ the check turns up more than the fix. Say that you escalated, and why.
    `"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,
-   which are notes, not failures: for each, write one line saying you used the
+   that justified it. Start from the app-owned surfaces and rebuilt parts
+   `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.
@@ -64,6 +68,9 @@ results, plus any step its notes call for. A passing check is a contract result,
 
 These are agent skill modes, not shell commands. Use `$sable` in Codex and
 `/sable` in Claude Code or Cursor; natural requests work in compatible agents.
+A request that never says "Sable" ("add a pricing page", "make the header
+sticky") in a project that depends on `@sableui/react` is still this skill:
+route it by the rules below and build it from the library.
 
 | Mode | Outcome |
 | --- | --- |
@@ -75,6 +82,11 @@ These are agent skill modes, not shell commands. Use `$sable` in Codex and
 
 `create` is an alias for `build`. A bare new-product brief means `build`; an editing
 follow-up means `polish`, unless it names one defect, which is a `fix`. A request for direction only stops before implementation.
+"Move this app onto Sable" (or convert, migrate, "use Sable properly") is never
+a `build`: that would start the product over. Run `sable check`, show the user
+the Adoption swaps in one short list, ask once which to move, then `polish` them
+a screen at a time without asking again for each. The user should not need to
+know the mode names; route plain requests yourself.
 “Show alternatives” produces bounded rendered studies and stops at comparison when
 the user reserves the choice. Explore only when requested or when competing choices
 materially affect the brief; do not require three designs for every build.
@@ -89,6 +101,15 @@ IosSheet, NavigationStack). Never import from `konsta`; sable-lint flags it
 (`native-ui-import`). `sable target ios --component <Name>` confirms a decision;
 almost every component is `preserve`. Every rule below applies to the prototype.
 
+A **tool** brief (an editor, a console, or a records workspace such as an issue
+tracker, a support queue or a pipeline, "like Linear", "compact and technical")
+selects the workspace register. Read `sable docs building-a-tool` before
+composing; a records workspace starts from `sable pattern TrackerPage
+--skeleton`. Its rail is Sidebar's own parts (SidebarGroup, SidebarAccount), its
+list is one grouped DataTable, its inspector is a `Panel narrow="sheet"`, reading
+tabs sit in `<Density value="comfortable">`, and "compact" in the brief means a
+preset with `type-base` 13 or 14, not per-tier type overrides.
+
 For inspiration, extract useful visual relationships into a preset. For an audit,
 evaluate the target product. A URL does not automatically mean copying its page.
 An explicit reconstruction request fixes reference fidelity; preserve that scope
@@ -151,7 +172,11 @@ rather than redoing it:
 
 `sable init` installs the discoverable entry files for Codex/Cursor and Claude
 Code; in an app wired by hand, run `sable setup --agent` once from the project root. `--target codex|claude|cursor|all` selects
-hosts. For Claude Code, setup also prints a Stop hook that runs `sable check`
+hosts. Setup also writes a short managed block into `AGENTS.md` and `CLAUDE.md`,
+the instructions every task reads, that sends UI requests through this skill
+even when they don't name it. It replaces only the text between its
+`<!-- sable:begin … -->` and `<!-- sable:end -->` markers; `--no-instructions`
+skips it. For Claude Code, setup also prints a Stop hook that runs `sable check`
 before a task can end; it writes that hook to `.claude/settings.json` only with
 `--hook`, so add it only when the user wants it. The hook is one plain command
 (for example `pnpm exec sable check --stop-hook`) with no `cd` or `&&`, so it runs
@@ -186,6 +211,16 @@ The installed catalog and guides are authoritative for API and token names.
      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.
+
+   Search before you name anything. Before writing an app-local component or
+   CSS class for a part you can recognize, search its plain name and its role:
+   `sable search breadcrumb`, `sable search "top bar"`, `sable search "property
+   row"`. Parts count: `PropertyRow`, `WorkspaceBar` and `CollapsibleIndicator`
+   are listed by name and `sable component <Part>` answers with the entry that
+   documents them. A disagreement with what you found (a height, a size, where a
+   heading sits) is answered by the part's variant or prop, or reported as a
+   missing variant; it is never a reason to rebuild the part. Check icon names
+   with `sable icon <name>` before using them: an unknown name draws nothing.
 2. Resolve styling in this order: Sable component/variant, Sable utility or recipe,
    semantic token, then app-owned CSS for a genuinely uncovered need. Colour
    beyond the roles (tags, avatars, labels, legends) comes from the generated
@@ -213,7 +248,8 @@ The installed catalog and guides are authoritative for API and token names.
    consume it. In another app, implement only genuinely app-specific structure;
    report a missing library hook. Do not modify installed package files or build
    parallel controls as a shortcut. Preserve existing non-Sable work unless a
-   migration was requested.
+   migration was requested, but don't leave it unmentioned: when `sable check`
+   reports adoption `none` or `low`, ask the user (see "Adoption" below).
 
 ## Develop or use a preset
 
@@ -240,6 +276,14 @@ the build and the finish checklist, and look at it rendered. Don't stop at a sav
 file plus a list of wiring steps for the user. Stop after saving only when the
 user says so or the project has no app yet.
 
+Ship both colour modes unless the brief rules one out. App colours go in a
+preset with light and dark values (`sable preset --template`, then `sable
+preset --css`), never as light-only overrides on `:root`: those leave dark mode
+as Sable's palette under the app's accents. Mount `ThemeSwitcher` under
+`SableThemeProvider` (a settings menu, the sidebar footer) so the user can
+switch modes and review both. A one-mode brief pins that mode
+(`defaultPreference`) and says so in the brief.
+
 Without a preset, develop an appropriate direction from the brief. Use the bundled
 presets as starting points or create original app-owned tokens. When the project has
 its own visual atlas, retrieve references with `sable atlas --search "<problem>"
@@ -281,6 +325,20 @@ contract violations, design judgments, intentional choices, and verified library
 gaps. A visual-only review leaves code and unobserved behavior untested. For
 `polish`, reuse the existing direction and inspect the affected product or preset.
 
+**Adoption.** An app can be wired for Sable and barely use it: an earlier agent
+never loaded this skill and wrote its own Modal, Button and Tabs on Sable's
+tokens. `sable check` reports it under Adoption (`sable grade --json` →
+`adoption`): how many UI files compose Sable, the app-built components Sable
+already ships (behaviour first), and the app's `foundation`. When the level is
+`none` or `low`, during any mode, ask the user before moving working screens, with
+the host's question tool if it has one. Show the swaps and what each gains
+("your Modal has no focus trap or Esc; Sable's Dialog has both"). Recommend the
+move plainly when the foundation is `ad-hoc`; offer it gently when the app has
+its `own` primitives; ask whether Sable replaces another `library` or only covers
+new work. Record the answer in the project's instructions, outside the Sable
+block, so the next task doesn't ask again. `sable docs auditing-an-app` has the
+full guide.
+
 Every build and polish ends with the finish checklist near the top of this skill. Notes on it:
 
 - `sable check` gives one combined result; while iterating, `sable lint <paths> --json`,

package/skills/sable/agents/openai.yaml

@@ -1,6 +1,6 @@
 interface:
   display_name: "Sable"
-  short_description: "Build, develop presets, audit, and polish with Sable"
+  short_description: "Any UI work in a Sable app: build, presets, audit, polish, fix"
   default_prompt: "Use $sable build to create my idea with the installed Sable components, tokens, and design guides, then inspect and polish the working result."
 policy:
   allow_implicit_invocation: true

package/targets/ios.json

@@ -78,6 +78,15 @@
       ],
       "guidance": "Use the Sable component as it is, in the preset. Adapt layout and touch targets to the phone; do not swap in a native lookalike or restyle it."
     },
+    "ActivityHeatmap": {
+      "source": "ActivityHeatmap",
+      "strategy": "preserve",
+      "importFrom": "@sableui/react",
+      "components": [
+        "ActivityHeatmap"
+      ],
+      "guidance": "Use the Sable component as it is, in the preset. Adapt layout and touch targets to the phone; do not swap in a native lookalike or restyle it."
+    },
     "AppHeader": {
       "source": "AppHeader",
       "strategy": "replace",