@sableui/react 0.18.0 → 0.19.0

package/scripts/adoption.mjs

@@ -98,6 +98,11 @@ const ALIASES = {
 	chip: ["Pill", "Badge"], tag: ["Badge"], alert: ["Banner"], callout: ["Note"], confirmdialog: ["DestructiveActionModal", "Dialog"],
 	contextmenu: ["ContextMenu"], hovercard: ["ContextCard"], numberinput: ["NumberField"], otpinput: ["OtpField"], pininput: ["OtpField"],
 	colorpicker: ["ColorField"], rating: ["RadioCard"], stepper: ["Stepper"], wizard: ["Stepper"], kbd: ["Kbd"],
+	property: ["PropertyRow"], propertyrow: ["PropertyRow"], proprow: ["PropertyRow"], picker: ["Select", "Combobox"],
+	statusmark: ["StatusDot"], statusindicator: ["StatusDot"], presencedot: ["StatusDot"], avatarstack: ["AvatarGroup"],
+	facepile: ["AvatarGroup"], topnav: ["WorkspaceBar", "AppHeader"], appbar: ["WorkspaceBar", "AppHeader"],
+	headerbar: ["WorkspaceBar", "AppHeader"], themetoggle: ["ThemeSwitcher"], modetoggle: ["ThemeSwitcher"],
+	darkmodetoggle: ["ThemeSwitcher"], colormodeswitch: ["ThemeSwitcher"],
 }
 
 /**
@@ -107,6 +112,14 @@ const ALIASES = {
  */
 function matcher(components) {
 	const byName = new Map(components.map((c) => [c.name.toLowerCase(), c]))
+	// Parts count: `PropertyRow`, `WorkspaceBar` and `AvatarGroup` are exported
+	// names an app's `Property` or `TeamAvatars` stands in for. A part inherits
+	// its entry's group, so a part of a behaviour component is behaviour too.
+	for (const c of components)
+		for (const s of c.subcomponents ?? []) {
+			const name = typeof s === "string" ? s : s.name
+			if (name && !byName.has(name.toLowerCase())) byName.set(name.toLowerCase(), { name, group: c.group, partOf: c.name })
+		}
 	return (appName) => {
 		if (STRUCTURAL.test(appName)) return []
 		const w = words(appName)
@@ -167,7 +180,7 @@ export function adoptionReport({ files, components, deps = null }) {
 			const behaviour = hits.some(isBehaviour)
 			const body = text.slice(index, starts.find((s) => s > index) ?? text.length)
 			if (behaviour && !HAND_BEHAVIOUR.some((re) => re.test(body))) continue
-			swaps.push({ file: rel, line: lineOf(text, index), name, sable: hits.map((c) => c.name), behaviour })
+			swaps.push({ file: rel, line: lineOf(text, index), name, sable: hits.map((c) => c.name), behaviour, ...(hits[0].partOf ? { partOf: hits[0].partOf } : {}) })
 		}
 	}
 
@@ -233,7 +246,7 @@ function recommendationOf({ level, foundation, libraries, behaviourSwaps }) {
 
 /** One line per swap, for text output. */
 export function swapLines(report, limit = 12, indent = "      ") {
-	const lines = report.swaps.slice(0, limit).map((s) => `${indent}${s.file}:${s.line}  ${s.name} → Sable has ${s.sable.join(" or ")}${s.behaviour ? " (behaviour)" : ""}`)
+	const lines = report.swaps.slice(0, limit).map((s) => `${indent}${s.file}:${s.line}  ${s.name} → Sable has ${s.sable.join(" or ")}${s.partOf ? ` (part of ${s.partOf})` : ""}${s.behaviour ? " (behaviour)" : ""}`)
 	if (report.swaps.length > limit) lines.push(`${indent}… ${report.swaps.length - limit} more: sable grade <paths> --json → adoption.swaps`)
 	return lines
 }

package/scripts/app-css.mjs

@@ -0,0 +1,129 @@
+/**
+ * app-css — what an app's own stylesheets do to Sable that its TSX does not show.
+ *
+ * The surface inventory and the part mirrors read className strings. An app that
+ * styles semantic classes in a .css file hides the rest: a work tracker passed a
+ * 100/100 grade with 48/42/34/25px bar and row heights, `.issue-table th { height:
+ * 25px; padding … }` re-laying Sable's table from outside, a disclosure chevron
+ * rotated by `[aria-expanded=false] svg`, and its light colours overridden on
+ * :root with nothing for dark — so dark mode rendered Sable's dark palette under
+ * the app's light accents, and nobody had a control to see it.
+ *
+ * Everything here is a note for the reuse inventory except `modes`, which grade
+ * reports as a warning: a half-themed palette is a defect a user sees the moment
+ * they switch modes, while a fixed height or a reached-in selector can be a
+ * deliberate choice. Lexical, like the rest of grade; it parses enough CSS to
+ * know each declaration's selector and the @-rules around it.
+ */
+
+/** Every declaration block with its selector and enclosing @-rule preludes. */
+export function cssRules(css) {
+	const src = css.replace(/\/\*[\s\S]*?\*\//g, (m) => m.replace(/[^\n]/g, " "))
+	const rules = []
+	const stack = []
+	let start = 0
+	let quote = null
+	for (let i = 0; i < src.length; i++) {
+		const c = src[i]
+		if (quote) {
+			if (c === "\\") i++
+			else if (c === quote) quote = null
+			continue
+		}
+		if (c === '"' || c === "'") quote = c
+		else if (c === "{") {
+			const prelude = src.slice(start, i).split(";").at(-1).trim()
+			stack.push({ prelude, index: start + src.slice(start, i).lastIndexOf(prelude), body: i + 1 })
+			start = i + 1
+		} else if (c === "}") {
+			const top = stack.pop()
+			if (top && !top.prelude.startsWith("@")) {
+				const body = src.slice(start, i)
+				const context = stack.map((s) => s.prelude)
+				// Nested rules: `.a { .b { … } }` — the declarations are the block's own text.
+				rules.push({ selector: top.prelude, context, body, index: top.index, bodyIndex: top.body })
+			}
+			start = i + 1
+		}
+	}
+	return rules
+}
+
+const declarations = (body) =>
+	[...body.matchAll(/(?:^|;|\})\s*(--[\w-]+|[a-z-]+)\s*:\s*([^;{}]+)/g)].map((m) => ({ prop: m[1], value: m[2].trim(), offset: m.index + m[0].indexOf(m[1]) }))
+
+const lineOf = (text, index) => text.slice(0, index).split("\n").length
+
+/** A selector's last compound names a bar, a row, a header or a table cell. */
+const BAR_OR_ROW = /(?:^|[\s>+~])(?:th|td|tr|thead|header)(?![\w-])|\.[\w-]*(?:bar|row|header|cell|tab|toolbar|item)(?![\w-])/
+/** The density ladder's own names, re-declared by hand. */
+const LADDER = /^--(?:control-(?:xs|sm|md|lg|cta)|chrome-bar-height|status-bar-height)$/
+
+/**
+ * Notes on one stylesheet. `semantic` is the theme contract's colour token
+ * names, used by `modes` across all of an app's stylesheets, not here.
+ */
+export function cssNotes(css) {
+	const notes = []
+	const seen = new Set()
+	const add = (index, kind, what, consider) => {
+		const key = `${kind}|${what}`
+		if (seen.has(key)) return
+		seen.add(key)
+		notes.push({ line: lineOf(css, index), kind, what, consider })
+	}
+	for (const r of cssRules(css)) {
+		const decls = declarations(r.body)
+		const at = (d) => r.bodyIndex + d.offset
+		if (/\[(?:aria-expanded|data-panel-open|data-open|data-state)[^\]]*\][^{,]*\bsvg\b/.test(r.selector) && decls.some((d) => /^(?:transform|rotate)$/.test(d.prop) && /rotate/.test(`${d.prop} ${d.value}`))) {
+			add(r.index, "rebuilt part", `${r.selector} rotates a disclosure chevron by hand`, "CollapsibleIndicator, which flips with the panel and eases (Accordion, Select and Menu triggers already flip theirs)")
+		}
+		if (/(?:^|[\s>+~])(?:th|td|thead|tr)(?![\w-])/.test(r.selector) && /^[.#[]/.test(r.selector.trim())) {
+			const props = decls.filter((d) => /^(?:height|min-height|padding|padding-block|padding-inline|font-size|font-weight)$/.test(d.prop))
+			if (props.length) add(r.index, "override", `${r.selector} { ${props.map((d) => d.prop).join(", ")} } re-lays a Sable table from outside`, "the table's density (rows follow a Workspace or Density scope), a column's className for its width, CardContent flush for edge padding")
+		}
+		if (/\[data-(?:selected|highlighted|active|checked|pressed)\]/.test(r.selector) && /^[.#]/.test(r.selector.trim())) {
+			add(r.index, "override", `${r.selector} restyles a Sable state from outside`, "the state's own tokens set on the theme (--muted for a selected row), or the component's variant")
+		}
+		for (const d of decls) {
+			const px = /^(\d+(?:\.\d+)?)px$/.exec(d.value)?.[1]
+			if (/^(?:height|min-height)$/.test(d.prop) && px && Number(px) >= 16 && Number(px) <= 64 && BAR_OR_ROW.test(r.selector)) {
+				add(at(d), "fixed height", `${r.selector} { ${d.prop}: ${d.value} }`, "the density ladder: --chrome-bar-height, --status-bar-height or --control-* follow the register (WorkspaceBar, StatusBar, a Density scope) instead of pinning one size")
+			}
+		}
+		const ladder = decls.filter((d) => LADDER.test(d.prop) && /^\d/.test(d.value))
+		if (ladder.length) {
+			const where = [...r.context.filter((c) => c.startsWith("@media")), r.selector].join(" ")
+			add(at(ladder[0]), "fixed height", `${where} { ${ladder.map((d) => `${d.prop}: ${d.value}`).join("; ")} } re-declares the density ladder`, "Workspace's density prop or <Density value=…>; the compact and comfortable ladders are already measured")
+		}
+	}
+	return notes
+}
+
+/** The selectors and @-rules that put a declaration in the dark mode. */
+const DARK = /\.dark\b|\[data-(?:mode|theme|color-scheme)=["']?dark|prefers-color-scheme:\s*dark|:root\.dark|html\.dark|\[data-dark\]/
+
+/**
+ * Light and dark coverage of the theme's colour tokens across every stylesheet.
+ * Returns the tokens an app sets only for light, and whether it set any dark
+ * values at all. A preset carries both modes; hand-written :root overrides
+ * usually carry one.
+ */
+export function modeCoverage(sheets, semantic) {
+	const light = new Map()
+	const dark = new Set()
+	for (const { rel, text } of sheets) {
+		for (const r of cssRules(text)) {
+			const scope = [...r.context, r.selector].join(" ")
+			const isDark = DARK.test(scope)
+			for (const d of declarations(r.body)) {
+				const name = d.prop.slice(2)
+				if (!d.prop.startsWith("--") || !semantic.has(name)) continue
+				if (isDark) dark.add(name)
+				else if (!light.has(name)) light.set(name, { file: rel, line: lineOf(text, r.index) })
+			}
+		}
+	}
+	const lightOnly = [...light].filter(([name]) => !dark.has(name)).map(([name, at]) => ({ name, ...at }))
+	return { light: light.size, dark: dark.size, lightOnly }
+}

package/scripts/grade.mjs

@@ -33,7 +33,8 @@ 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"
@@ -113,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
@@ -378,6 +404,16 @@ const routeSkeletons = []
 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 `>`.
@@ -437,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.
@@ -499,7 +540,7 @@ 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) })
 		}
 	}
 
@@ -507,6 +548,10 @@ for (const file of files) {
 	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.
@@ -525,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
 }
@@ -666,6 +811,8 @@ const result = {
 		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,
@@ -707,6 +854,18 @@ 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}`)

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/skills/sable/SKILL.md

@@ -35,9 +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`), or an Adoption block
+   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). Also run the
+   (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,
@@ -51,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.
@@ -99,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
@@ -200,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
@@ -255,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>"