@sableui/react 0.0.0-stage → 0.1.0

package/scripts/review-evidence.mjs

@@ -0,0 +1,120 @@
+/** Review completeness is measurable; visual quality still requires a reviewer. */
+import { createHash } from "node:crypto"
+import { existsSync, readFileSync, realpathSync, statSync } from "node:fs"
+import { resolve } from "node:path"
+
+export const DIMENSIONS = [
+	"purpose-story", "hierarchy-type", "layout-rhythm", "color-material",
+	"interaction", "motion", "responsive", "accessibility",
+]
+export const CHECKS = ["primary-flow", "keyboard", "overflow", "reduced-motion"]
+
+export function reviewTemplate() {
+	return {
+		schemaVersion: 1,
+		build: { name: "", brief: "", revision: "", sourceHash: "" },
+		reviewer: { name: "", method: "agent" },
+		artifacts: [],
+		dimensions: DIMENSIONS.map((id) => ({ id, status: "untested", observation: "", evidence: [] })),
+		checks: CHECKS.map((id) => ({ id, status: "untested", observation: "", evidence: [] })),
+		iterations: [],
+		openIssues: [],
+	}
+}
+
+const filled = (value) => typeof value === "string" && value.trim().length > 0
+const object = (value) => value !== null && typeof value === "object" && !Array.isArray(value)
+
+export function assessReview(review, { baseDir, sourceHash }) {
+	const limitations = "Validates recorded evidence and review completeness. It does not inspect images or certify visual quality."
+	if (review == null) return { status: "unreviewed", issues: ["No review supplied. Use sable grade --template."], limitations }
+	const issues = []
+	let revisions = false
+	const issue = (message) => issues.push(message)
+	if (!object(review)) return { status: "evidence-incomplete", issues: ["Review must be a JSON object."], limitations }
+	if (review.schemaVersion !== 1) issue("schemaVersion must be 1.")
+	if (!filled(review.build?.name) || !filled(review.build?.brief)) issue("build.name and build.brief are required.")
+	if (review.build?.sourceHash !== sourceHash) issue("build.sourceHash must match the current graded sourceHash; recapture and review after source changes.")
+	if (!filled(review.reviewer?.name) || !["human", "agent"].includes(review.reviewer?.method)) issue("reviewer needs a name and method (human or agent).")
+
+	const artifacts = Array.isArray(review.artifacts) ? review.artifacts : []
+	const artifactHashes = {}
+	if (!artifacts.length) issue("Provide artifacts from the rendered build.")
+	const byId = new Map()
+	for (const artifact of artifacts) {
+		if (!object(artifact) || !filled(artifact.id)) { issue("Every artifact needs an id."); continue }
+		if (byId.has(artifact.id)) { issue(`Duplicate artifact id: ${artifact.id}.`); continue }
+		let valid = true
+		let resolvedPath
+		const invalid = (message) => { issue(`Artifact ${artifact.id}: ${message}`); valid = false }
+		if (!["screenshot", "recording", "report"].includes(artifact.kind)) invalid("kind must be screenshot, recording, or report.")
+		if (!filled(artifact.state)) invalid("state is required.")
+		if (!filled(artifact.path)) invalid("path is required.")
+		else {
+			const path = resolve(baseDir, artifact.path)
+			try {
+				if (!existsSync(path) || !statSync(path).isFile() || statSync(path).size === 0) invalid(`missing or empty file: ${artifact.path}.`)
+				else {
+					resolvedPath = realpathSync(path)
+					if (process.platform === "win32") resolvedPath = resolvedPath.toLowerCase()
+					const sha256 = createHash("sha256").update(readFileSync(path)).digest("hex")
+					artifactHashes[artifact.id] = sha256
+					if (artifact.sha256 !== sha256) invalid("sha256 must match the inspected file. See artifactHashes for current bytes; inspect changed artifacts before accepting a new hash.")
+				}
+			} catch { invalid(`cannot read file: ${artifact.path}.`) }
+		}
+		if (artifact.kind === "screenshot" || artifact.kind === "recording") {
+			const { width, height } = artifact.viewport ?? {}
+			if (!Number.isInteger(width) || width <= 0 || !Number.isInteger(height) || height <= 0) invalid("viewport needs positive integer width and height.")
+			if (!["light", "dark"].includes(artifact.colorMode)) invalid("colorMode must be light or dark.")
+			if (!["full", "reduced"].includes(artifact.motion)) invalid("motion must be full or reduced.")
+		}
+		byId.set(artifact.id, { ...artifact, valid, resolvedPath })
+	}
+	const validArtifacts = [...byId.values()].filter((artifact) => artifact.valid)
+	const screenshots = validArtifacts.filter((artifact) => artifact.kind === "screenshot")
+	if (!screenshots.some((artifact) => artifact.viewport.width >= 1024)) issue("Include a wide screenshot (viewport width >= 1024).")
+	if (!screenshots.some((artifact) => artifact.viewport.width <= 480)) issue("Include a narrow screenshot (viewport width <= 480).")
+	if (!validArtifacts.some((artifact) => artifact.motion === "reduced")) issue("Include evidence captured with reduced motion.")
+
+	function evidence(ids, label) {
+		if (!Array.isArray(ids) || !ids.length) { issue(`${label}: reference at least one artifact.`); return }
+		for (const id of ids) if (!byId.get(id)?.valid) issue(`${label}: unknown or invalid artifact ${String(id)}.`)
+	}
+	function observations(entries, required, statuses, label) {
+		const list = Array.isArray(entries) ? entries : []
+		for (const id of required) {
+			const matches = list.filter((entry) => object(entry) && entry.id === id)
+			if (matches.length !== 1) { issue(`${label}: expected one ${id} observation.`); continue }
+			const entry = matches[0]
+			if (!statuses.includes(entry.status)) issue(`${label} ${id}: invalid status.`)
+			if (entry.status === "untested") issue(`${label} ${id}: untested.`)
+			if (entry.status === "revise" || entry.status === "fail") revisions = true
+			if (!filled(entry.observation)) issue(`${label} ${id}: describe what was observed.`)
+			evidence(entry.evidence, `${label} ${id}`)
+		}
+		for (const entry of list) if (!required.includes(entry?.id)) issue(`${label}: unknown id ${String(entry?.id)}.`)
+	}
+	observations(review.dimensions, DIMENSIONS, ["pass", "revise", "untested"], "Dimension")
+	observations(review.checks, CHECKS, ["pass", "fail", "untested"], "Check")
+	if (!Array.isArray(review.iterations)) issue("iterations must be an array; use [] if no revision was needed.")
+	else for (const [index, iteration] of review.iterations.entries()) {
+		if (!filled(iteration?.defect) || !filled(iteration?.action)) issue(`Iteration ${index + 1}: describe the defect and action.`)
+		evidence(iteration?.before, `Iteration ${index + 1} before`)
+		evidence(iteration?.after, `Iteration ${index + 1} after`)
+		if (Array.isArray(iteration?.before) && Array.isArray(iteration?.after) && iteration.after.some((id) => iteration.before.includes(id))) issue(`Iteration ${index + 1}: before and after must use distinct captures.`)
+		if (Array.isArray(iteration?.before) && Array.isArray(iteration?.after)) {
+			const beforePaths = new Set(iteration.before.map((id) => byId.get(id)?.resolvedPath).filter(Boolean))
+			if (iteration.after.some((id) => beforePaths.has(byId.get(id)?.resolvedPath))) issue(`Iteration ${index + 1}: before and after reference the same file; changing artifact ids does not create a new capture.`)
+		}
+	}
+	if (!Array.isArray(review.openIssues)) issue("openIssues must be an array; use [] only when no issues remain.")
+	else if (review.openIssues.length) revisions = true
+	return {
+		status: issues.length ? "evidence-incomplete" : revisions ? "revision-needed" : "review-recorded",
+		issues,
+		openIssues: review.openIssues ?? [],
+		artifactHashes,
+		limitations,
+	}
+}

package/scripts/skeleton.mjs

@@ -0,0 +1,248 @@
+/**
+ * skeleton — reduce a pattern's source to its composition tree.
+ *
+ * Why this exists: the patterns tier answers "how does a page compose", but it
+ * answers it inside 130 lines of realistic demo source — fixture arrays, copy,
+ * per-cell formatting. An agent picking a starting point has to read all of it
+ * to see the four decisions that actually matter (which shell, which region cap,
+ * which grid, what nests where), and a 782KB registry means it often reads the
+ * pattern it already guessed instead of comparing all eight.
+ *
+ * A skeleton is the same tree with the content removed: elements, the props that
+ * carry layout meaning, and nesting. DashboardPage goes from 127 lines to ~25.
+ * Cheap enough to print all eight and choose, which is the point — composition
+ * is the decision that has to be right before any component is picked.
+ *
+ * This is lexical, not a parser. It leans on the fact that pattern source is
+ * ours and is formatted by Biome: one element per line, tabs for depth, so the
+ * indentation already IS the tree. That trade buys zero dependencies in a file
+ * that ships to consumers. It is exact for the patterns in this package (a test
+ * pins every one of them) and makes no claim about arbitrary JSX.
+ */
+
+/**
+ * Props that survive. These are the ones that change the SHAPE of the page —
+ * caps, spans, rhythm, direction, emphasis tier. Everything else (`label`,
+ * `icon`, `href`, `placeholder`, event handlers) describes content, and content
+ * is the thing the reader is trying to see past.
+ */
+const STRUCTURAL = new Set([
+	"align",
+	"as",
+	"aside",
+	"bleed",
+	"className",
+	"cols",
+	"count",
+	"density",
+	"direction",
+	"fill",
+	"footer",
+	"gap",
+	"header",
+	"inset",
+	"justify",
+	"level",
+	"max",
+	"minItemWidth",
+	"orientation",
+	"ratio",
+	"register",
+	"safeArea",
+	"side",
+	"sidebar",
+	"size",
+	"span",
+	"start",
+	"sticky",
+	"tone",
+	"variant",
+	"wrap",
+])
+
+/** Props whose value is a nested subtree — rendered as a branch label, not a prop. */
+const SLOT_HINT = /^([a-zA-Z][a-zA-Z0-9]*)=\{\(?$/
+/** A whole attribute on one line: `max="form"`, `gap={3}`, `cols={{ base: 1 }}`. */
+const SIMPLE_ATTR = /^([a-zA-Z][a-zA-Z0-9]*)=(?:"([^"]*)"|\{(.*)\})$/
+const OPEN_TAG = /^<([A-Za-z][\w.]*)/
+
+/**
+ * Pull the structural props out of a tag's attribute text.
+ *
+ * Hand-rolled rather than a regex because prop values nest braces —
+ * `cols={{ base: 1, sm: 2 }}` — and the obvious `\{([^}]*)\}` truncates at the
+ * first `}`, which silently turns a responsive breakpoint map (the single most
+ * important thing a Grid line has to say) into a malformed fragment.
+ */
+function structuralProps(text) {
+	const kept = []
+	let i = 0
+	while (i < text.length) {
+		const rest = text.slice(i)
+		const m = rest.match(/^\s*([a-zA-Z][a-zA-Z0-9]*)/)
+		if (!m) {
+			i += 1
+			continue
+		}
+		const key = m[1]
+		i += m[0].length
+		if (text[i] !== "=") {
+			if (STRUCTURAL.has(key)) kept.push(key) // boolean shorthand
+			continue
+		}
+		i += 1
+		let value
+		if (text[i] === '"') {
+			const end = text.indexOf('"', i + 1)
+			value = text.slice(i + 1, end === -1 ? text.length : end)
+			i = end === -1 ? text.length : end + 1
+			if (STRUCTURAL.has(key)) kept.push(`${key}="${value}"`)
+		} else if (text[i] === "{") {
+			let depth = 0
+			const from = i
+			for (; i < text.length; i++) {
+				if (text[i] === "{") depth++
+				else if (text[i] === "}" && --depth === 0) {
+					i++
+					break
+				}
+			}
+			value = text.slice(from + 1, i - 1)
+			// A JSX value (`header={<AppHeader … />}`) is a slot, not a prop: the
+			// element is composition, and printing it inline dumps its whole
+			// subtree onto the parent's line. Multi-line slots become branches in
+			// skeletonize(); a one-line JSX prop on a one-line tag is just dropped.
+			if (STRUCTURAL.has(key) && !value.trimStart().startsWith("<")) kept.push(`${key}={${value}}`)
+		}
+	}
+	return kept
+}
+
+/** `<Grid cols={…} gap={3}` → `{ name, props }`, ignoring content-carrying props. */
+function readTag(trimmed) {
+	const name = trimmed.match(OPEN_TAG)[1]
+	// Cut at the `>` that ends the OPEN tag, tracking quotes and braces. Trimming
+	// a trailing `>` instead is wrong for the very common one-line element
+	// `<span className="x">text</span>`, where the leftover `</span` scans as a
+	// bare attribute and every such line prints a phantom `span` prop.
+	const rest = trimmed.slice(1 + name.length)
+	let end = rest.length
+	let depth = 0
+	let quote = null
+	for (let i = 0; i < rest.length; i++) {
+		const c = rest[i]
+		if (quote) {
+			if (c === quote) quote = null
+		} else if (c === '"' || c === "'") quote = c
+		else if (c === "{") depth++
+		else if (c === "}") depth--
+		else if (c === ">" && depth === 0) {
+			end = rest[i - 1] === "/" ? i - 1 : i
+			break
+		}
+	}
+	return { name, props: structuralProps(rest.slice(0, end)) }
+}
+
+/**
+ * @param {string} code A pattern's `code` string from registry.json.
+ * @returns {{ tree: string, elided: number }} `tree` is the skeleton; `elided`
+ *   counts module-scope fixture bindings dropped ahead of the component.
+ */
+export function skeletonize(code) {
+	const lines = code.split("\n")
+
+	// Drop module scope. Patterns declare their demo data above the component;
+	// none of it is composition.
+	const start = lines.findIndex((l) => /^(export )?function [A-Z]/.test(l))
+	const head = start === -1 ? [] : lines.slice(0, start)
+	const elided = head.filter((l) => /^const [A-Za-z]/.test(l)).length
+	const body = start === -1 ? lines : lines.slice(start)
+
+	const out = []
+	let baseIndent = null
+	// A tag whose props Biome broke across lines is still one element. Track it
+	// so those lines land back on the tag instead of appearing to be its children
+	// — `density="compact"` indented under `<Entity>` reads as a child element,
+	// which is the one thing a composition tree must never get wrong.
+	let open = null
+
+	for (const line of body) {
+		const indent = line.match(/^\t*/)[0].length
+		const t = line.trim()
+		if (!t) continue
+
+		if (open) {
+			if (/^\/?>$/.test(t)) {
+				open = null
+				continue
+			}
+			const attr = t.match(SIMPLE_ATTR)
+			if (attr && indent > open.indent && attr[3] !== undefined && attr[3].trimStart().startsWith("<")) {
+				// `header={<AppHeader title={…} />}` on its own line: the same branch
+				// shape as a multi-line slot — a label, then the element beneath it.
+				if (baseIndent === null) baseIndent = open.indent
+				const depth = Math.max(0, indent - baseIndent)
+				const inner = attr[3].trim()
+				if (OPEN_TAG.test(inner)) {
+					const { name, props } = readTag(inner)
+					out.push({ depth, text: `${attr[1]}:` }, { depth: depth + 1, text: null, name, props })
+				}
+				continue
+			}
+			if (attr && indent > open.indent) {
+				if (STRUCTURAL.has(attr[1])) {
+					open.node.props.push(
+						attr[2] !== undefined ? `${attr[1]}="${attr[2]}"` : `${attr[1]}={${attr[3]}}`,
+					)
+				}
+				continue
+			}
+			if (indent <= open.indent) open = null
+		}
+
+		let node = null
+		if (OPEN_TAG.test(t)) {
+			const { name, props } = readTag(t)
+			node = { text: null, name, props }
+			// No terminator on this line → its remaining props are still coming.
+			if (!/\/?>$/.test(t)) open = { indent, node }
+		} else if (/^\{[^}]*\.map\(/.test(t)) {
+			// `{items.map((item) => (` — one element repeated. The reader needs to
+			// know a repeat happens here; the iteration variable is noise.
+			node = { text: "{…repeat}" }
+		} else {
+			const slot = t.match(SLOT_HINT)
+			if (slot) node = { text: `${slot[1]}:` }
+		}
+		if (node === null) continue
+
+		if (baseIndent === null) baseIndent = indent
+		out.push({ depth: Math.max(0, indent - baseIndent), ...node })
+	}
+
+	// Everything prints self-closing: depth comes from indentation, so a closing
+	// tag would be a second line saying what the first line already said.
+	for (const n of out) {
+		if (n.text === null) n.text = `<${n.name}${n.props.length ? ` ${n.props.join(" ")}` : ""} />`
+	}
+
+	// Collapse runs of identical siblings. Five <SidebarItem /> lines say exactly
+	// as much as one line saying there are five, and the difference is the whole
+	// nav fitting on screen next to the rest of the page.
+	const collapsed = []
+	for (const node of out) {
+		const prev = collapsed[collapsed.length - 1]
+		if (prev && prev.depth === node.depth && prev.text === node.text) {
+			prev.count = (prev.count ?? 1) + 1
+			continue
+		}
+		collapsed.push({ ...node })
+	}
+
+	const tree = collapsed
+		.map((n) => `${"  ".repeat(n.depth)}${n.text}${n.count ? `  ×${n.count}` : ""}`)
+		.join("\n")
+
+	return { tree, elided }
+}

package/skills/entry/SKILL.md

@@ -0,0 +1,34 @@
+---
+name: sable
+description: Build websites and apps with Sable, develop reusable presets from inspiration, audit interfaces, and polish designs using the installed library.
+---
+
+# Sable
+
+Load the maintained instructions from this project's installed Sable package
+before carrying out the request. This entry delegates so a package upgrade
+supplies the updated skill, contracts, and guides together.
+
+From the target project's dependency context, run:
+
+```sh
+node -p "require.resolve('@sableui/react/registry.json')"
+```
+
+Read `skills/sable/SKILL.md` under the returned registry's parent directory and
+follow it for the user's request. Use that package's `bin/sable.mjs` for retrieval.
+In the Sable monorepo, read `packages/sable/skills/sable/SKILL.md` directly.
+
+If the package is missing, install `@sableui/react` from npm with the project's
+package manager.
+Read the installed registry's `consume` block and `AGENTS.md` to wire React,
+Tailwind, CSS source scanning, and fonts. Do not fetch an unrelated public package
+named `sable` or `sable-ui`. Explain missing access and continue
+independent brief work when installation is blocked.
+
+Primary modes are `build <idea> [using <preset>]`, `inspire <references or brief>`,
+`audit <existing interface>`, and `polish <target>`. `create` aliases `build`.
+These are agent modes, not terminal subcommands. Every build must query and use
+the installed Sable components, variants, utilities, tokens, layouts, and guides,
+then run its design lint and inspect the working result. Do not begin UI code
+without loading the package skill.

package/skills/sable/SKILL.md

@@ -0,0 +1,187 @@
+---
+name: sable
+description: Build original websites and apps with Sable, turn inspiration into reusable presets, audit existing interfaces, and polish a selected design. Use for Sable design and UI work, not unrelated backend tasks.
+---
+
+# Sable
+
+Build the user's idea with the installed Sable library. The product brief determines
+content, structure, and behavior; a preset supplies theme values and design guidance.
+References inform an original direction. A reference or preset is optional.
+
+## Route the request
+
+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.
+
+| Mode | Outcome |
+| --- | --- |
+| `build <idea> [using <preset or path>]` | Develop the brief, implement the requested product with Sable, inspect and operate it, repair observed issues, and deliver the working result. |
+| `inspire <references or description>` | Study the inspiration, develop a direction, and save a previewable, editable preset. Stop before a full product build. |
+| `audit <existing interface>` | Inspect existing work and report prioritized design, behavior, accessibility, and Sable-contract findings. Apply repairs only when requested. |
+| `polish <target or instruction>` | Improve the current product or preset while preserving its selected direction, then verify affected states. |
+
+`create` is an alias for `build`. A bare new-product brief means `build`; an editing
+follow-up means `polish`. A request for direction only stops before implementation.
+“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.
+
+An explicit iOS/iPhone **app prototype** request selects the optional iOS target.
+Read `sable docs building-an-ios-prototype` before composing. The rule is **Sable
+first**: every screen is Sable components in the chosen preset — settings rows are
+Card + CardList + Entity with Switch, forms are Form + Field + Input, search is
+SearchInput, feedback is toast. `@sableui/react/ios` supplies only system chrome
+(NativeApp, IosPage, IosNavbar, IosBackLink, IosIconButton, IosTabbar, IosTab,
+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.
+
+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
+and document necessary departures. Current user instructions override older presets
+and preferences. Infer the target from the project and conversation; ask only for
+missing information that materially changes the work.
+
+## Resolve and set up the installed library
+
+Start in the target app, not this skill's folder. Read project instructions. Resolve
+`@sableui/react/registry.json` from that project's dependency context:
+
+```sh
+node -p "require.resolve('@sableui/react/registry.json')"
+```
+
+The registry's parent is the package root; read its `AGENTS.md` and use its
+`bin/sable.mjs`. In the Sable repository use `packages/sable/bin/sable.mjs` and
+`packages/sable/registry.json`. Below, `sable` means this resolved CLI invoked with
+the target project as its working directory. Never fetch an unrelated public
+package with bare `npx sable`, or invent shell `build`, `inspire`, or `audit` commands.
+
+If Sable is absent, read the trusted repository or package README's install recipe
+and registry `consume` block. Install from npm with the project's package
+manager, for example `pnpm add @sableui/react`; no registry setup or token is
+needed. Do not substitute an unrelated package with a similar name.
+
+Complete setup before implementing UI:
+
+- Match the installed package's React, React DOM, Tailwind, and Node requirements.
+- Dedupe React in the bundler. Import Tailwind, then Sable's stylesheet; add the
+  package `dist` glob to Tailwind `@source`, relative to the consumer stylesheet.
+- Load the selected fonts through the project's font setup. Presets declare stacks;
+  they do not load files. Reicon works by default; IconProvider can replace or extend the set.
+- Run `sable doctor`, repair wiring issues, and verify the app renders a real
+  Sable component. Reuse an existing app server; never start duplicate instances.
+
+Run `sable setup --agent` once from the project root to install discoverable entry
+files for Codex/Cursor and Claude Code. `--target codex|claude|cursor|all` selects
+hosts. The entry files read this installed package's instructions on each task;
+upgrading the package updates the workflow. After an upgrade, use
+`sable setup --agent --update` to refresh managed entry metadata when needed.
+Keep project-specific preferences in project instructions rather than editing
+package files. Agents without skill discovery can read this file directly.
+
+## Build with the actual Sable resources
+
+Before UI code, run `sable manifest --json`, read `sable docs building-with-sable`,
+`sable docs designing-a-surface`, and `sable docs choosing-a-component`. Read relevant
+foundations through `sable docs typography|spacing|shape|surfaces|motion|scrolling|accessibility`.
+The installed catalog and guides are authoritative for API and token names.
+
+**Required for every build and UI repair:**
+
+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.
+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.
+   Use paired typography, spacing steps, density/control ladders, relative surfaces,
+   concentric geometry, scroll policies, and supported motion recipes.
+3. Inspect a relevant `sable pattern <Name> --skeleton` and layout contracts when
+   composing a page. Reuse a pattern when its information architecture fits;
+   otherwise compose an original layout from Sable primitives. Do not force a
+   dashboard or marketing shell onto a different product brief.
+4. Put identity in app-owned theme tokens, composition, and assets. Component
+   `className` is for layout; fill, edges, corners, ink, and interaction appearance
+   come from supported variants. Do not override controls to imitate a reference.
+   Entity rows use `CardList`; edge-to-edge tables use `CardContent flush`.
+5. When the catalog has no fit, document the search, missing capability, and owner.
+   In the Sable monorepo, follow `CONTRIBUTING.md`, add the library capability, then
+   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.
+
+## Develop or use a preset
+
+Save a short brief in the project's existing design location: audience, primary
+task, content, constraints, selected identity, and meaningful states. 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.
+
+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>"
+--contrast --limit 3 --json` and `--show <id>`, and actually view returned images;
+the package ships none, so otherwise work from the user's references. Retrieve applicable lessons with
+`sable learn --search "<problem>" --json`. Optional preference retrieval uses an
+explicit scope and distinguishes human choices from agent observations. Empty
+memory is valid; opening tools or completing a build does not supply human taste.
+
+For `inspire`, read `sable docs creating-a-preset`. Inspect supplied references with
+available browser/image/design tools. Distinguish measured, estimated, derived,
+and user-edited decisions; do not claim a screenshot proves animation timing or
+hidden behavior. Record transferable typography, surfaces, spacing, imagery, and
+motion principles. The user's future product determines its own layout and content.
+Save a versioned preset in `.sable/presets/<id>.json`, validate it, and provide a
+Sable-component preview or import it into Canvas. Stop at the preset.
+
+Canvas can import and download the same preset format. A downloaded file must be
+placed in the target project before the agent can read it; a browser export does
+not itself write into that project. Use `sable preset --css <path>` to generate
+scoped CSS, load fonts, and apply the preset ID with Sable's theme APIs. Never
+register a personal preset as a bundled library theme just to build one app.
+
+When alternatives matter, keep content and primary behavior fixed, vary meaningful
+composition and another relevant dimension, and inspect desktop/mobile/interaction
+states. `sable explore` supports three to six evidence-bound directions; a smaller
+comparison can be delivered directly. Respect a reserved user choice; otherwise
+make and identify an agent selection and continue the authorized build.
+
+When imagery or fonts carry the direction, read `sable docs creating-design-assets`.
+Produce or obtain actual assets within authorization, verify loading and responsive
+crops, and retain source/readiness notes. Atlas images are reference evidence, not
+product assets. A palette alone does not establish a finished design.
+
+## Verify and deliver
+
+For `audit`, read `sable docs auditing-an-app`; report by default and distinguish
+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.
+
+Every build includes `sable docs reviewing-a-design`, `sable doctor`,
+`sable lint <source paths> --json`, and the project's build/type checks. Repair
+findings instead of suppressing them to finish. Inspect real desktop/mobile
+layouts, operate the primary task and recovery path, check keyboard/touch and
+loading/empty/error/success states, font loading, focus, and reduced motion.
+Audit source ownership as well as lint: identify the Sable components and composed
+parts actually imported, the utilities/token groups used, and every app-owned UI
+or CSS addition. Ordinary semantic content and domain logic are app-owned; a
+recognizable control or surface must use its library implementation. Explain any
+uncovered capability with the catalog search and the smallest necessary addition.
+Include this reuse inventory with the build's evidence so conformance is reviewable.
+For connected flows read `reviewing-a-journey`; for meaningful temporal behavior
+read `reviewing-motion` and observe interruption as well as playback.
+
+Iterate on observed defects and recapture changed states. Contract checks cannot
+judge beauty: assess brief fit, composition, hierarchy, rhythm, imagery, and
+interaction in the rendered product. Deliver the result, preset/revision used,
+checks performed, and material limitations. Preserve useful conditional lessons
+through `learning-from-builds`; never fabricate human approval or preference records.

package/skills/sable/agents/openai.yaml

@@ -0,0 +1,6 @@
+interface:
+  display_name: "Sable"
+  short_description: "Build, develop presets, audit, and polish with Sable"
+  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