@sableui/react 0.0.0-stage → 0.1.1

package/llms/tasks/reviewing-motion.md

@@ -0,0 +1,92 @@
+# Task: review motion as playable behavior
+
+Use this workflow when a meaningful transition, direct manipulation, media, or
+story depends on time. Sable already supplies motion tokens and behavior
+primitives. This guide reviews their composition and any external driver. A
+deliberately static arrival is valid; every surface does not need animation.
+
+## State what the movement should explain
+
+For each behavior under review, record the trigger, the elements or state that
+change, the intended relationship, the driver, and the expected final state.
+Include duration or scroll range when known, easing, interruption/reversal,
+keyboard/touch equivalence, and the reduced-motion result. For a reference, keep
+observed behavior separate from a proposed recreation.
+
+Example: expanding a selected workshop exposes its details while retaining the
+date choice. Repeated toggles should end in the user's latest requested state,
+without an invisible focus target or an extra queued transition. Reduced motion
+can reveal the same content immediately while preserving focus and feedback.
+
+## Capture the kind of evidence the claim needs
+
+| Evidence | What it establishes | What it does not establish |
+|---|---|---|
+| Still screenshot | A visible state at capture time | Duration, smoothness, trigger, or reversal |
+| Timestamped frame sequence | Sampled states and their recorded capture times | Continuous motion between samples or a measured frame rate |
+| Playable recording | The recorded sequence, including visible response to actions | Other devices, refresh rates, or unrecorded inputs |
+| Runtime event/animation report | Logged events, computed values, or declared timing | Perceived quality or that every declared animation ran |
+
+Use a recording when available. Otherwise retain real sampled frames and a
+small manifest listing their order, timestamps, actions, and observed outcomes.
+Do not synthesize intermediate frames or assign evenly spaced timestamps to
+captures that were not taken that way. If recording is unavailable, say so;
+observed behavior can still be reported with its limits.
+
+Record viewport, route/state, color mode, full/reduced motion, input actions, and
+capture conditions. Preserve the real playback speed. A slowed study copy may
+help inspection, but label its retiming and retain the original. Mask or avoid
+private data before capture. Include the source hash and hashes of final artifacts.
+
+## Make the evidence inspectable
+
+Provide a local review page with playback controls, or an ordered frame viewer
+with previous/next controls and visible timestamps. Do not autoplay a review
+recording. For a video, native controls are sufficient:
+
+```html
+<figure>
+  <video controls preload="metadata" poster="open-menu.webp"
+    aria-describedby="motion-note" src="menu-toggle.webm"></video>
+  <figcaption id="motion-note">
+    Desktop, full motion. Open, close during entry, then reopen.
+    This recording shows the observed run, not a performance benchmark.
+  </figcaption>
+</figure>
+```
+
+Use actual files from the run, provide text describing the actions and outcomes,
+and captions or an equivalent transcript when meaningful audio is present. Open
+the saved review artifact and confirm it plays or advances correctly; a file's
+existence alone is insufficient.
+
+## Test the behavior, including interruption
+
+Operate the trigger, reverse it before completion, repeat it, and navigate or
+resize during it when those are plausible product actions. Check that the final
+state matches intent, input does not queue unexpectedly, focus remains usable,
+and canceled work does not report success. Inspect the behavior at normal speed:
+is the response immediate enough for its frequency, and does the movement explain
+the change without delaying access to content?
+
+Repeat relevant behavior with reduced motion enabled. This should preserve state,
+focus, status, and controls; hiding the animated content is not an equivalent
+result. Test a custom driver directly—Sable's policy cannot disable an unrelated
+animation by itself. Pause or otherwise control meaningful persistent media as
+appropriate to the surface, and verify its static/loading fallback.
+
+## Record conclusions at the right confidence
+
+Separate source-declared timing, runtime measurements, and visual observations.
+A CSS duration is not elapsed end-to-end latency. State where a value was measured
+and what the measurement covers; avoid precise timing claims from visual guesses.
+Use specific findings such as "closing during entry left focus in the hidden
+panel," then retain the repaired run beside the original.
+
+The existing `sable grade` review schema accepts `recording` and `report`
+artifacts as well as screenshots; see [reviewing-a-design.md](./reviewing-a-design.md)
+for their hashes and required context. A frame manifest can be a report, with its
+linked frame files preserved. The validator checks the referenced artifact bytes,
+not every link inside a report or the quality of playback. Keep full and reduced
+evidence distinct, mark unexercised behaviors untested, and promote a motion
+lesson only within the contexts the observation supports.

package/llms/tasks/using-presets.md

@@ -0,0 +1,87 @@
+# Task: use a portable preset
+
+Bundled presets are maintained with Sable. Personal presets are app-owned JSON
+files that use the same component and token contract. Canvas and the skill read
+the same portable format; no separate review app is required.
+
+The schema contains `schemaVersion: 1`, a lowercase slug `id`, `label`, positive
+`revision`, authoring `sableVersion`, `defaultMode`, `fonts.sans`/`fonts.mono`
+(optional `display`), design `direction`, optional `references`, and
+`tokens.shared`, `tokens.light`, and `tokens.dark` objects. Token keys omit `--`.
+Both mode objects declare the full semantic color set, including `background`,
+`foreground`, `primary`, and their paired roles.
+Other supported values include typography, radii, control density, motion,
+shadows, spacing, workspace surfaces, and layering. `sable preset --template`
+prints a complete starting record; the public `PRESET_TOKEN_NAMES` is authoritative.
+
+Font stacks are requirements, not downloaded fonts. Declare matching stacks in
+the font metadata and tokens. Resolve internal palette variables before saving;
+portable presets may reference public Sable tokens, not private palette names.
+The validator rejects unknown tokens and CSS that can escape its declaration.
+It does not certify contrast or that a CSS value makes visual sense.
+
+Motion durations are nominal times at scale 1. `presetCss()` and the CLI connect
+them to the live `--motion-scale` policy, so reduced motion still stops recipes.
+Keep existing duration or motion-scale references when authoring CSS expressions;
+do not freeze the current operating system preference into duration values.
+
+## Import and customize
+
+Open Canvas, choose Export, and import the JSON file. An imported preset is
+registered as a custom theme, while the inspector uses the default theme.
+Review the Sable component scenes in both modes. Customize, add direction notes,
+and download a JSON record. Preserve the original record when developing variants.
+
+## Build a product
+
+Place the file in the target project's `.sable/presets/` directory. Read its exact
+ID, revision, tokens, fonts, guidance, and evidence before starting. The product
+brief determines content, layout, and behavior; guidance informs those decisions.
+
+```bash
+pnpm exec sable preset --check .sable/presets/clay.json --json
+pnpm exec sable preset --css .sable/presets/clay.json > src/clay.css
+```
+
+Import the generated CSS after Sable's stylesheet. Load the declared fonts.
+Register the manifest without editing the library:
+
+```tsx
+import { SableThemeProvider } from "@sableui/react"
+import { parsePreset, presetManifest } from "@sableui/react/presets"
+import record from "../.sable/presets/clay.json"
+import "./clay.css"
+
+const preset = parsePreset(record)
+const customThemes = [presetManifest(preset)]
+
+export function App() {
+  return (
+    <SableThemeProvider customThemes={customThemes}
+      defaultThemeId={preset.id} defaultPreference={preset.defaultMode}>
+      {/* Compose the user's product from Sable components. */}
+    </SableThemeProvider>
+  )
+}
+```
+
+`presetCss(preset)` also compiles CSS in browser/build tooling. Generated selectors
+are scoped by `data-sable-theme`; importing a stylesheet alone does not activate it.
+Use a unique preset ID so it cannot override a bundled theme or another record.
+Record any intentional adaptation and run the validation and rendered review in
+[building-with-sable.md](./building-with-sable.md).
+
+## Upgrade the package and skill
+
+```bash
+pnpm update @sableui/react --latest
+pnpm exec sable setup --agent --update
+pnpm exec sable preset --check .sable/presets/clay.json --json
+pnpm exec sable doctor
+```
+
+The skill loads instructions from the installed package on every task. Setup
+refreshes unchanged managed entry files and preserves local edits. Local presets
+and project preferences survive upgrades. `sableVersion` records provenance;
+validation uses the current installed token vocabulary. Review the changelog
+and recheck the product when upgrading.

package/llms/taste/asset-plan.template.json

@@ -0,0 +1,53 @@
+{
+  "schemaVersion": 1,
+  "recordType": "asset-plan",
+  "status": "planned",
+  "surface": "Describe the target surface and audience",
+  "direction": {
+    "message": "What the assets should make understandable",
+    "sharedTreatment": "Composition, material, light or line, and color relationships",
+    "intentionalDifferences": "How subjects remain distinguishable within the set"
+  },
+  "initialPayloadBudgetBytes": null,
+  "assets": [
+    {
+      "id": "primary-visual",
+      "kind": "illustration",
+      "role": "Explain this asset's job in the surface",
+      "subject": "Specify the actual subject and important details",
+      "source": {
+        "origin": "unresolved",
+        "location": null,
+        "creator": null,
+        "usageStatus": "unresolved",
+        "permissionOrLicense": null,
+        "attribution": null
+      },
+      "treatment": "Specify framing, material, light or geometry, and color",
+      "variants": [
+        {
+          "id": "wide",
+          "placement": "Describe where and at which viewport this is used",
+          "focalSubject": "What must survive the crop",
+          "crop": "Describe framing and any reserved text area",
+          "path": null,
+          "width": null,
+          "height": null,
+          "format": null,
+          "budgetBytes": null,
+          "actualBytes": null
+        }
+      ],
+      "accessibility": {
+        "decorative": false,
+        "textAlternative": null
+      },
+      "fallback": "Describe the usable missing/loading-media state",
+      "readiness": "planned",
+      "verification": []
+    }
+  ],
+  "fonts": [],
+  "reviewedCaptures": [],
+  "openQuestions": []
+}

package/llms/taste/composition-follows-content.md

@@ -0,0 +1,20 @@
+# Composition follows content
+
+Mixed-width feature audits gave primary ideas more space. The reusable decision
+is that emphasis follows the importance and shape of the content. A particular
+7/5 grid is only one implementation.
+
+Write the section's job before choosing its container. A comparison needs shared
+baselines; a sequence needs order; a single artifact benefits from uninterrupted
+space; subordinate facts can live in a ruled list. A card earns its edge when it
+groups a distinct object or interactive destination. Space can group text without
+a container.
+
+Inspect the whole page at reduced scale. If every section has the same silhouette,
+check whether the content actually has the same job. Vary width or density when
+the story changes, while keeping alignment anchors and a small spacing vocabulary.
+Preserve predictable repetition for equivalent records, forms, and frequent tasks.
+
+Provenance: distilled from the bundled mixed-width feature pattern and editorial
+reference audits. This is conditional precedent, not evidence that asymmetry is
+always better. Retrieve `sable learn --show composition-follows-content --json`.

package/llms/taste/hierarchy-is-a-relationship.md

@@ -0,0 +1,22 @@
+# Hierarchy is a relationship
+
+Prior builds picked real `text-title-*` utilities for feature titles
+whose role in the composition was closer to a display heading. Every token was
+valid; the hierarchy still flattened. Another build reproduced a measured 128px
+display size inside a narrower container, turning roughly three lines into six.
+
+Choose the semantic HTML heading level separately from its visual tier. Set the
+text, available measure, tier, weight, and adjacent spacing together, then inspect
+the rendered line count on desktop and mobile. If the phrase is factual or
+approved, change the layout before rewriting it. Load the actual font before
+judging the result; fallback metrics are different.
+
+Transfer this to display-led reading and persuasion surfaces. In an operating
+tool, task hierarchy and scan speed may call for smaller type and consistent rows.
+Large type and light weight are possible choices, never a universal recipe for
+quality.
+
+Provenance: distilled from the Sable build pipeline's recorded
+typography and line-wrap defects. This is a curated precedent, not a fresh visual
+test of the current package. Retrieve the structured record with
+`sable learn --show hierarchy-is-a-relationship --json`.

package/llms/taste/lessons.json

@@ -0,0 +1,57 @@
+{
+  "schemaVersion": 1,
+  "lessons": [
+    {
+      "schemaVersion": 1,
+      "id": "hierarchy-is-a-relationship",
+      "title": "Choose type together with measure and content",
+      "tags": ["typography", "hierarchy", "editorial", "display", "wrapping", "spacing"],
+      "register": "page",
+      "mode": "either",
+      "principle": "A correct size token does not guarantee the intended hierarchy. Compare rendered size, weight, line count, measure, and adjacent content as one composition.",
+      "appliesWhen": "A display-led page feels timid or a headline wraps into many more lines than the brief intended.",
+      "avoidWhen": "Do not inflate headings in task-dense workspace chrome or replace factual copy merely to force a preferred wrap.",
+      "provenance": { "kind": "curated-precedent", "source": "Distilled recurring typography defects in maintained build reviews", "date": "2026-09-06" },
+      "evidence": [{ "kind": "source", "path": "llms/taste/hierarchy-is-a-relationship.md", "observation": "Prior builds used valid title tokens but flattened display-led feature headings; narrow containers also turned a three-line headline into six lines." }]
+    },
+    {
+      "schemaVersion": 1,
+      "id": "composition-follows-content",
+      "title": "Give unequal content unequal emphasis",
+      "tags": ["composition", "story", "layout", "rhythm", "asymmetry", "cards"],
+      "register": "page",
+      "mode": "either",
+      "principle": "Choose a section's structure from what it must communicate: a sequence, comparison, decision, object, or reading passage. Repetition is useful when the content is equivalent.",
+      "appliesWhen": "Distinct sections all collapse into centered headings above identical icon-and-card grids.",
+      "avoidWhen": "Do not make equally important records different sizes or rearrange a familiar operating flow to manufacture novelty.",
+      "provenance": { "kind": "curated-precedent", "source": "Distilled mixed-width feature and editorial reference audit patterns", "date": "2026-09-06" },
+      "evidence": [{ "kind": "source", "path": "llms/taste/composition-follows-content.md", "observation": "Reference audits preserved larger feature areas for primary ideas while secondary facts used compact rows, captions, or rules." }]
+    },
+    {
+      "schemaVersion": 1,
+      "id": "motion-needs-a-reason",
+      "title": "Use motion to explain a change",
+      "tags": ["motion", "animation", "interaction", "reduced", "timing", "restraint"],
+      "register": "either",
+      "mode": "either",
+      "principle": "Declare a trigger, purpose, duration, interruption behavior, and reduced-motion result. A static initial state can be intentional; every user action still needs understandable feedback.",
+      "appliesWhen": "A build has indiscriminate scroll reveals, generic spring entrances, or no feedback between meaningful states.",
+      "avoidWhen": "Do not transfer slow editorial choreography into frequent workspace operations, hide initial content while waiting for animation, or simulate scroll-driven behavior with an entrance fade.",
+      "provenance": { "kind": "curated-precedent", "source": "Contrasting editorial motion and dense technical tool reference audits", "date": "2026-09-06" },
+      "evidence": [{ "kind": "source", "path": "llms/taste/motion-needs-a-reason.md", "observation": "Editorial audits recorded deliberate cascades; technical audits recorded short ease-out feedback without overshoot. Their motion grammars were different." }]
+    },
+    {
+      "schemaVersion": 1,
+      "id": "surface-states-travel-together",
+      "title": "Retheme the complete interaction state",
+      "tags": ["color", "contrast", "hover", "interaction", "surface", "theme"],
+      "register": "either",
+      "mode": "either",
+      "principle": "Foreground, fill, border, hover, focus, selected, and disabled states form one surface contract. Inspect the actual rendered states after an override.",
+      "appliesWhen": "An existing control is moved onto an inverted, tinted, or media-backed section.",
+      "avoidWhen": "Do not add per-call-site color overrides when the theme already expresses the intended semantic surface.",
+      "provenance": { "kind": "curated-precedent", "source": "Recorded dark-band button hover regression in build guidance", "date": "2026-09-06" },
+      "evidence": [{ "kind": "source", "path": "llms/taste/surface-states-travel-together.md", "observation": "An outline button had readable resting text on a dark band, but its inherited hover foreground was tuned for a light surface and disappeared." }]
+    }
+  ]
+}

package/llms/taste/motion-needs-a-reason.md

@@ -0,0 +1,21 @@
+# Motion needs a reason
+
+Editorial reference audits found shared entrance timelines, small travel, and
+slower media transitions. Technical tool audits found short ease-out feedback and
+no overshoot. Copying one grammar into the other loses the purpose that made it
+work.
+
+For each meaningful change, record trigger, user benefit, driver, duration/ease,
+interruption behavior, and reduced-motion result. Feedback confirms an action;
+spatial motion can explain where content went; activity distinguishes waiting
+from failure. Initial reading content can paint immediately. A deliberate static
+choice is valid when no information is gained by animation.
+
+Use Sable's motion tokens and primitives where they express that decision. Custom
+CSS and external animation drivers must also honor the motion policy. Inspect a
+real state change and reduced-motion mode; a resting screenshot cannot establish
+timing, interruption behavior, or that content remains available.
+
+Provenance: distilled from the contrasting calm editorial and dense technical
+reference audit grammars. Timing numbers in an old audit are observations, not
+mandatory new defaults. Retrieve `sable learn --show motion-needs-a-reason --json`.

package/llms/taste/surface-states-travel-together.md

@@ -0,0 +1,20 @@
+# Surface states travel together
+
+A recorded build defect placed an outline button on a dark band and
+overrode its resting foreground. The inherited hover foreground still belonged to
+a light surface. The button was legible in screenshots and lost its label on hover.
+
+Prefer a coherent semantic surface scope. If an override is required, inspect
+the component's full variant contract and verify fill, text, border, hover,
+focus-visible, disabled, and selected states as appropriate. Use a matching
+foreground token with each surface token. Do not assume one resting override
+replaces every state-specific class.
+
+Check the rendered control with pointer and keyboard, in each supported color
+mode. Moving a control onto media also requires checking the least legible part
+of the image, including after crop changes. A local state test is stronger evidence
+than a claim that the palette has passed a token contrast test elsewhere.
+
+Provenance: a dark-band button hover failure documented in the Sable reference
+build workflow. This packaged distillation preserves the failure mechanism without
+requiring access to private reference artifacts.