@sableui/react 0.0.0-stage → 0.1.1

package/llms/tasks/building-an-ios-prototype.md

@@ -0,0 +1,105 @@
+# Task: building an iOS app prototype
+
+An iOS prototype is a clickable iPhone app that runs in the browser, for demos,
+presentations and user testing. It is not a native app and not for production.
+
+## The rule: Sable first
+
+**Every screen is built from Sable components, in the chosen preset.** Rows,
+lists, inputs, switches, sliders, search, selects, buttons, forms, toasts,
+empty states, cards and all content are Sable — exactly as on the web.
+
+The Sable iOS adapter (`@sableui/react/ios`) supplies only the iOS **system
+chrome** Sable has no equivalent for:
+
+| Chrome | Adapter |
+| --- | --- |
+| App frame, status bar, safe areas | `NativeApp` |
+| A screen | `IosPage` |
+| Navigation bar: title, large title, back, bar actions | `IosNavbar`, `IosBackLink`, `IosIconButton` |
+| Tab bar | `IosTabbar`, `IosTab` |
+| Sheet presentation (detents, drag, Escape) | `IosSheet` (its content is Sable) |
+| Push and pop between screens | `NavigationStack`, `useNavigation` |
+
+**Never import from `konsta`.** Konsta is the adapter's optional peer, not a
+component library for the app; `sable-lint` flags a direct import
+(`native-ui-import`). If a screen needs something Sable does not have, report
+it as a library gap; do not reach for a native control or hand-build one.
+
+`sable target ios --component <Name> --json` gives the decision for any
+component: `preserve` (use the Sable component — almost everything),
+`replace` (an adapter chrome component), `contextual` (Button and PageHeader:
+the adapter only in the navigation bar, Sable everywhere else), `recompose`
+(desktop patterns rebuilt from Sable parts for a phone, e.g. a table becomes
+Entity rows in a Card) or `redesign` (desktop workspace tools).
+
+## How iOS screens look in Sable
+
+- **Grouped settings:** a section heading (`text-title-sm text-muted-foreground`)
+  over a `Card` with `CardList` and `Entity` rows; a `Switch`, value text or
+  chevron in each row's `action`.
+- **Forms:** `Form` with `Field` around `Input`, `Textarea`, `Select`, `Slider`.
+- **Lists that drill down:** interactive `Entity` rows in a `Card` that call
+  `useNavigation().push(id, <NextScreen />)`.
+- **Search:** `SearchInput` on the page margin.
+- **Feedback:** `toast()` inside `ToastProvider`; `EmptyState` for no results.
+- Align content to the native page margin with `px-(--ios-inset)` so it lines
+  up with large titles. The adapter spaces a screen's first content below its
+  title.
+
+## Setup
+
+1. Install `konsta` in the consuming project only when an iOS prototype is
+   requested (`pnpm add konsta`). It is the adapter's optional peer.
+2. Give the prototype its own HTML entry, separate from the web app, with one
+   stylesheet:
+
+   ```css
+   @import "tailwindcss";
+   @import "@sableui/react/styles.css";
+   @import "@sableui/react/theme/verdant.css"; /* the preset, or themes.css */
+   @import "@sableui/react/ios/styles.css";
+   @source "../node_modules/@sableui/react/dist";
+   ```
+
+   Set the preset with `data-sable-theme` on `<html>`. The adapter maps the
+   preset onto the chrome (background, ink, accent, fonts), so chrome and
+   content follow the same preset and light or dark mode. It pins Tailwind's
+   spacing and radii on the chrome only, so a preset's density and corners
+   reach your Sable content and the chrome keeps iOS geometry.
+3. Compose: `NativeApp` at the root (`mode` sets light or dark, also on
+   `<html>` so portaled Sable popups follow); one `NavigationStack` per tab,
+   each holding an `IosPage` with an `IosNavbar` and Sable content; an
+   `IosTabbar` of `IosTab`s with Sable `Icon`s; `IosSheet` around Sable forms.
+   Keep the app's `IconProvider`.
+4. Frame it on a host page with `PhoneFrame` from `@sableui/react/ios/preview`
+   and `@sableui/react/ios/frame.css` (Sable's Phone around an iframe at
+   402×874, scaled as a whole device). To follow a host's live look, call
+   `useIosPreviewBridge(frameRef, { mode })` on the host and
+   `useIosPreviewTheme()` in the prototype.
+5. Verify light and dark, keyboard focus, reduced motion, back and edge swipe,
+   independent tabs, sheet drag, Escape and cancel, form validation and save,
+   and empty-state recovery. Run `sable-lint` over the prototype: it is a Sable
+   app and the same rules apply.
+
+## Geometry hooks
+
+`--ios-inset` (16px page margin), `--ios-safe-top` (62px), `--ios-header-height`,
+`--ios-tabbar-bottom`, `--ios-content-bottom` and `--ios-motion`, for the
+standard 402×874 phone. Reduced transparency removes the glass blur.
+
+## Engineering handoff
+
+The prototype's colors, fonts, radii and spacing are the preset's tokens.
+Engineers take styles from the preset export (Customize → Export, or
+`sable preset`), not code from the prototype.
+
+Platform: iOS 27 on a 6.3" iPhone Pro. Chrome by Konsta UI 5.5 (MIT) through
+the adapter.
+
+```sh
+sable target ios --json
+sable target ios --component Switch --json     # preserve: Sable Switch
+sable target ios --component BottomNav --json  # replace: IosTabbar + IosTab
+sable target ios --component Button --json     # contextual: Sable except in the nav bar
+```

package/llms/tasks/building-with-sable.md

@@ -0,0 +1,73 @@
+# Task: build an idea with Sable
+
+Start with the product the user wants: a portfolio, shop, booking service, app,
+or another concrete task. A preset supplies visual decisions; the brief supplies
+content, information architecture, and behavior. Inspiration is optional.
+
+## One workflow
+
+1. Install and wire Sable using [getting-started.md](./getting-started.md).
+   Run `pnpm exec sable setup --agent` to connect the package-owned skill.
+2. Choose a bundled preset, customize one in Canvas, or use `inspire` to develop
+   an original preset from references. See [creating-a-preset.md](./creating-a-preset.md).
+   Starting directly from an idea is equally valid.
+3. Put a downloaded preset in `.sable/presets/<id>.json` in the target project.
+   Ask the agent to build your idea using that exact file. Read
+   [using-presets.md](./using-presets.md) for validation, CSS, and fonts.
+4. Build from Sable's installed components, patterns, utilities, and tokens.
+   Inspect and operate the real result, then repair observed problems.
+
+Examples in Codex:
+
+```text
+$sable build a portfolio for a furniture designer
+$sable inspire these references into a warm, compact shop preset
+$sable build a ceramics shop using .sable/presets/clay.json
+$sable audit our checkout and report prioritized findings
+$sable polish our checkout and repair the reported issues
+```
+
+Claude Code and Cursor use `/sable` with the same modes. `create` is a `build`
+alias. These are agent instructions; the shell CLI serves catalog resources and
+validates records. Other agents can read the package's `skills/sable/SKILL.md`.
+
+`inspire` produces a preset and component preview. `audit` evaluates an existing
+interface and reports by default. A reference URL does not request a cloned site.
+Develop alternative rendered directions when requested or when a consequential
+choice needs comparison. A three-design comparison is not a mandatory build step.
+
+## Required library use
+
+Read the installed package's `AGENTS.md` and `registry.json` consume block. Search
+for each recognizable element with `sable search "<need>" --json`; inspect the
+matching `component <Name> --props` and `--examples` before implementation.
+Use Sable's composed anatomy and supported variants. A hand-built button, field,
+menu, dialog, table, or card that imitates a shipped component violates the contract.
+
+Resolve styling through component variants, documented utilities/recipes, then
+semantic tokens. App-owned CSS handles uncovered content and composition; it
+does not replace component appearance or behavior. Inspect a relevant pattern's
+skeleton; compose an original layout if its structure does not fit the brief.
+Read [choosing-a-component.md](./choosing-a-component.md) and
+[designing-a-surface.md](./designing-a-surface.md).
+
+For a real library gap, record the unsuccessful search and missing capability.
+In the Sable repository, add the capability to the package under `CONTRIBUTING.md`
+before consuming it. In another project, report the gap and preserve the package;
+implement genuinely app-specific structure without creating parallel controls.
+
+## Finish the working product
+
+Run `sable doctor`, `sable lint <source paths> --json`, and the project's build/type
+checks. Inspect desktop/mobile layouts, operate the primary task and recovery
+path, and check keyboard focus, fonts, reduced motion, and meaningful states.
+Use [reviewing-a-design.md](./reviewing-a-design.md),
+[reviewing-a-journey.md](./reviewing-a-journey.md), and
+[reviewing-motion.md](./reviewing-motion.md) as applicable.
+
+Passing static checks does not establish visual quality. Review composition,
+hierarchy, rhythm, imagery, and brief fit in the actual product. Deliver the
+working result, preset/revision used, checks, and any material limitations.
+Include a reuse inventory: imported Sable components and parts, retrieved token
+groups/utilities, and the reason for each app-owned UI/CSS addition. Inspect source
+ownership; valid classes on a hand-built control still violate the contract.

package/llms/tasks/choosing-a-component.md

@@ -0,0 +1,109 @@
+# Task: choosing between similar components
+
+Sable has several components that look alike and do different jobs. Choosing
+the wrong one usually still renders, so nothing fails. It shows up later as
+a focus trap where none belonged, a menu that cannot hold a form, or a status
+that a screen reader never announces. Use the tables below before you compose.
+For each component, `npx sable component <Name> --detail full` has the full
+contract.
+
+The question to ask is always **what the user is doing**, not what it looks like.
+
+## Surfaces that open over the page
+
+| The user is… | Use | Not |
+|---|---|---|
+| Making a focused decision or filling a short form, and the page should wait | `Dialog` | `Sheet` (too much room), `Popover` (no focus trap) |
+| Confirming something irreversible | `DestructiveActionModal` | a `Dialog` you style red: it already handles the async confirm, the spinner and the verb-first labels |
+| Working through a long or secondary task beside the page context (filters, details, an edit form) | `Sheet` | `Dialog` (cramps long content) |
+| Viewing media full-bleed | `Dialog` with `DialogContent size="fullscreen"` | `Dialog` at its default size (500px cap) |
+| Adjusting a few controls anchored to a trigger, without leaving the flow | `Popover` | `Menu` (cannot hold inputs) |
+| Reading a rich preview of a link or a name on hover or focus | `ContextCard` | `Tooltip` (plain text only), `Popover` (needs a click) |
+| Reading a short label for an icon or control | `Tooltip` | anything that holds interactive content: tooltips are not reachable by touch |
+| Jumping anywhere or running a command by name | `CommandMenu` | `Combobox` (one field's value, not app-wide actions) |
+| Sending a quick rating and message | `Feedback` | a hand-built `Popover` + `Textarea` |
+
+## Lists of actions
+
+| The user is… | Use | Not |
+|---|---|---|
+| Choosing one action from a list under a button | `Menu` | `Select` (that picks a *value*) |
+| Reaching secondary actions for a row or card | `DotsMenu` | a bare `Menu` with a hand-made icon trigger |
+| Acting on the thing under the pointer (right-click or long press) | `ContextMenu`, always mirrored in a visible `DotsMenu` | `ContextMenu` alone: it is undiscoverable |
+| Changing a few settings that each show their current value | `SettingsMenu` | a `Menu` of toggles that hides each current state |
+| Running a main action that has close variations | a `Button` beside an icon `Button` that opens a `Menu` | a hand-fused split control |
+
+## Picking a value
+
+| The user is… | Use | Not |
+|---|---|---|
+| Picking one of 2–5 visible options | `Radio` (`RadioGroup`) | `Select`: hiding five options behind a click costs a click |
+| Picking one option that needs a title and description | `RadioCard` (in a `RadioGroup`) | `Radio` with hand-styled cards |
+| Picking several options that need a title and description | `CheckboxCard` | `Checkbox` with hand-styled cards |
+| Picking one of many known options | `Select` | `Combobox`, unless the list is long enough to need typing |
+| Picking one of a long or searchable list | `Combobox` | `Select` (no filtering) |
+| Picking several from a long list | `Combobox multiple` with `ComboboxChips` | a column of `Checkbox`es past about eight items |
+| Turning a setting on or off with an immediate effect | `Switch` | `Checkbox` (that is a form value applied on submit) |
+| Agreeing to something, or ticking a form value submitted later | `Checkbox` | `Switch` |
+| Switching a view mode, or pressing a formatting toggle | `Toggle` / `ToggleGroup` | `Tabs` (those swap content panels) |
+| Entering a one-time code | `OtpField` | `Input type="number"` |
+| Entering a number, nudging with keys or steppers | `NumberField` | `Input type="number"` |
+| Scrubbing a number by dragging, in tool chrome | `ScrubField` | `Slider` (page register) |
+| Choosing a value along a range | `Slider` | `NumberField` when the exact value matters more than position |
+| Adding files | `FileDropzone`, with accepted files listed as `Attachment` rows | a bare `<input type="file">` |
+
+## Showing more or less
+
+| The user is… | Use | Not |
+|---|---|---|
+| Switching between peer views of one object | `Tabs` | `Accordion` (stacked, not peer) |
+| Scanning several sections and opening one or more | `Accordion` | a column of `Collapsible`s you coordinate by hand |
+| Opening one optional block | `Collapsible` | `Accordion` with one item |
+| Reading a long block that starts clipped | `ShowMore` | a fixed-height box with `overflow-auto` |
+
+## Status, progress and feedback
+
+| What you are communicating | Use | Not |
+|---|---|---|
+| Work happening, with a known percentage | `Progress` | `Meter` (not task progress) |
+| How full something is within a known range (storage, quota, strength) | `Meter`, or `Meter shape="ring"` in a stat card | `Progress` |
+| Where the user is in a multi-step flow | `Stepper` | `Progress` (loses which step) |
+| Content loading in place, with a known shape | `Skeleton` | `Spinner` (makes the layout jump when content lands) |
+| A short wait with no known shape | `Spinner` | `Skeleton` |
+| Someone typing, or a reply composing | `Spinner appearance="dots"` / `StreamingText` | the ring `Spinner` |
+| The whole app booting | `PageLoader` | a centred `Spinner` |
+| The result of an action, transient | `Toast` | `Banner` (persistent) |
+| A one-line status beside the thing it describes | `InlineStatus` | `Toast` (detached from the cause) |
+| Guidance or a caveat inside content | `Note` | `Banner` |
+| A page-wide announcement | `Banner` | `Note` |
+| Which scope or environment the user is in (preview, staging) | `Banner` with a `label` chip | a hand-built strip |
+| Nothing here yet, with a next step | `EmptyState` | an empty `Table` |
+| A failure with a recovery action, in a region | `EmptyState tone="destructive"` (`surface="card"` among cards, `size="lg"` for a page) | `Note tone="destructive"` |
+| A state label (live, failed, draft) | `Badge appearance="plain" tone=… dot` (dot plus label) | `StatusDot` alone: it is decorative and silent |
+| Metadata or a category | `Badge`; `Pill` when it can be selected | `Badge appearance="plain" dot` (that is a status) |
+
+## Tables and trees
+
+| The data is… | Use | Not |
+|---|---|---|
+| Static rows you lay out by hand | `Table` | `DataTable` |
+| Rows from an array that need sorting or selection | `DataTable` | `Table` plus hand-written sort state |
+| Files, folders, layers or an outline | `Tree` (`TreeRow icon`) | a nested list built by hand |
+
+## Navigation
+
+| The user is… | Use | Not |
+|---|---|---|
+| Moving between the app's top-level areas on desktop | `Sidebar` inside `AppShell` | `SideNav` |
+| Moving between sub-pages of a section (settings, docs) | `SideNav` | `Sidebar` (that is app chrome) |
+| Moving between top-level areas on mobile | `BottomNav` | a hamburger-only `Sheet` |
+| Paging through results with known counts | `Pagination` | `Button variant="secondary" loading` |
+| Continuing a feed | `<Button variant="secondary" loading loadingLabel="Loading…">` | `Pagination` |
+
+## When nothing fits
+
+Compose from layout primitives (`Stack`, `Row`, `Grid`, `Region`) and the
+closest component. Do not restyle a component into a different one. If you
+find yourself fighting a component's role, you are holding the wrong one.
+Retrieve its `usage.bestPractices`, which name the neighbouring component to
+use instead.

package/llms/tasks/converting-an-app.md

@@ -0,0 +1,139 @@
+# Task: converting an existing app to Sable
+
+Migrating a React app that has its own styles. The order below front-loads the
+decisions that invalidate later work if you get them wrong.
+
+## 0. Classify every surface first
+
+Before touching a component, **list the routes and assign a register to each** —
+see fork 1 in `llms.txt`. Do not decide once for the app. Every conversion so far
+has applied a single register throughout and been wrong somewhere: the tell is a
+route with arrow-key or bracket-key bindings (triage), or one that never scrolls,
+sitting in a page-register app.
+
+Converting a tool with page-register instincts produces something that passes
+every lint and still looks wrong. The measurable tells that a surface was built
+with page instincts but is actually a tool:
+
+| tell | page register | you are probably a tool |
+|---|---|---|
+| dominant control height | 40–44px | should be 32 (24 in dense chrome) |
+| dominant radius | 8–16px, some pills | ~5px, **no pills in chrome** |
+| dominant UI type | 14px / 600 | 10–12px at 450–550 |
+| panel grouping | `Card` | `PanelSection` + hairlines |
+
+Measure these in the running app before deciding — `getComputedStyle` over every
+button and text node takes a minute and settles the argument.
+
+## 1. Wire the package
+
+Follow **Consuming** in `llms.txt`: `.npmrc`, `pnpm add`, React dedupe, the CSS
+import order, `@source`, fonts, providers. React dedupe is the one that fails
+loudest and least clearly ("invalid hook call").
+
+## 2. Delete your own tokens
+
+The most reliable signal that a conversion is real: the app's own CSS variable
+block shrinks to almost nothing. Anything that remains should be *domain* colour,
+not UI colour.
+
+Grep for orphaned references afterwards. A CSS variable that no longer exists
+resolves to nothing and the declaration is dropped — **silently**. A checkerboard
+built on two renamed variables rendered as blank for four releases before anyone
+noticed.
+
+## 3. Replace the shell, then the chrome, then the leaves
+
+Shell first (`AppShell` or `Workspace`), because it establishes the density scope
+and the landmarks. Then panels/headers. Leaf components last — they are the
+easiest and the least consequential.
+
+Expect the shell swap to delete more code than it adds. If it does not, you are
+probably keeping a layout that Sable would have given you.
+
+## 4. Icons
+
+**Reicon works by default.** No icon provider is needed. To use another icon
+package, map Sable's semantic names in an app-owned IconSet and mount it through
+IconProvider. To add domain-specific names while retaining Reicon:
+
+```tsx
+import { IconProvider, composeIconSets, reiconIconSet } from "@sableui/react"
+<IconProvider set={composeIconSets(appExtras, reiconIconSet)} />
+```
+
+Keep only the names Sable's contract does not carry and let everything else fall
+through. First set to return non-null wins.
+
+**A set must return `null` to fall through — not a placeholder.** This is the trap
+both hand-copied adapters fell into, and it is silent in the worst way: ending
+your renderer with `{node ?? <circle cx="12" cy="12" r="9" />}` means an unknown
+name draws a grey dot, so a typo, an off-contract name and a real icon all look
+like something rendered. Return `null` and the next set gets a turn; miss every
+set and you see nothing, which is at least visibly wrong.
+
+Verify the adapter rather than trusting it — nothing in Sable can see it, and
+`sable-lint` does not check it:
+
+```tsx
+// Every contract name resolves, and an unknown one returns null.
+const names = registry.iconContract.names   // registry.json
+names.filter((n) => !mySet.render({ name: n }))          // → must be []
+mySet.render({ name: "definitely-not-an-icon" })         // → must be null
+```
+
+Do not hand-copy a name→component mapping. Every app that did ended up with a
+drifted copy.
+
+## 5. Verify by measuring, not by looking
+
+```bash
+npx sable-lint            # lints ./src; pass dirs to change (npx sable-lint app components)
+```
+
+`sable-lint` ships with the package and reads the token vocabulary from the
+`registry.json` of the version you installed, so it checks your app against your
+exact tokens. It exits 1 on any violation. `--rules` explains each one; `--ignore
+'<glob>'` skips a data/fixture layer, where a hex value is content rather than a
+style. A rare, genuine exception takes an auditable
+`// design-lint-disable-next-line <ruleId> -- <reason>`.
+
+Then your own `tsc` and tests. (`pnpm design-lint && pnpm build:registry &&
+pnpm test:run` are the *in-repo* gates — they only run inside the Sable repo.)
+
+Then in the browser, check the things a screenshot cannot show:
+
+- every left edge in a hierarchy panel resolves to the rail or an exact multiple
+- control heights match the ladder for the register you chose
+- `--panel`, `--canvas` etc. resolve to real values, not empty
+- **the fonts actually loaded.** `--font-*` resolving is not evidence: the token
+  names a family, and if the host never fetched it the browser silently falls back
+  to `system-ui` while every token check passes. One app rendered in the wrong
+  typeface for its entire life this way, and the documented checks all passed on
+  it. The theme names the family; **the host loads it.** Ask the font system, not
+  the cascade:
+
+  ```js
+  // In the browser console. Both must be true.
+  document.fonts.check("1em Figtree")     // the theme's sans
+  document.fonts.check("1em DM Mono")     // the theme's mono
+  ```
+
+  If either is false, add the `@font-face`/link the theme expects — see the theme's
+  entry in `registry.json → themes` for the families it assumes.
+- a converted colour renders the same bytes as before — compare notations through
+  one canvas readback, never against a constant, because the readback itself has
+  an offset
+
+## Known-good example
+
+Glitch (an image-compositing tool) converted in one pass: `globals.css` went
+229 → 49 lines, its local `components/workspace/` was deleted entirely, and the
+layers panel lost 174 lines by adopting `Tree`.
+
+## Read next
+
+- [building-a-tool.md](./building-a-tool.md) or
+  [building-a-page.md](./building-a-page.md)
+- `DESIGN.md → Registers`
+- `llms/reference/token-intent.md`

package/llms/tasks/creating-a-preset.md

@@ -0,0 +1,43 @@
+# Task: create a preset from inspiration
+
+A preset is a versioned design input: Sable theme values, font requirements,
+design guidance, and optional attributed observations. It is reusable across
+products. It does not encode a reference site's content or page structure.
+
+Use the agent's `inspire` mode with images, URLs, a description, or a combination.
+Inspect the actual supplied evidence. Record typography relationships, surface
+contrast, spacing, shape, imagery treatment, and observed motion. Label each
+reference decision as measured, estimated, derived, or user-edited. A screenshot
+cannot establish animation timing, hidden behavior, or an unseen responsive state.
+
+Choose an original direction suitable for the user's future product. Map that
+direction onto the installed Sable token vocabulary. Preserve readable semantic
+roles and supported control behavior rather than recoloring every primitive
+independently. Load fonts through the consuming project's font setup.
+
+```bash
+pnpm exec sable preset --template
+pnpm exec sable preset --check .sable/presets/clay.json --json
+pnpm exec sable preset --css .sable/presets/clay.json
+```
+
+The template starts from a complete Base theme snapshot. Give it a unique ID and
+label; author its tokens, direction, and reference observations. Avoid IDs of
+bundled themes. Save the record at `.sable/presets/<id>.json`. Advance `revision`
+when changing a shared record; keep earlier revisions when reproducibility matters.
+
+Preview using real Sable components or import the JSON in Canvas. Inspect both
+light and dark modes and test long text, focus, disabled controls, floating
+surfaces, and errors. Token validation checks the contract and safe CSS structure;
+rendered review establishes contrast, coherence, and suitability.
+
+Canvas's Export view downloads this same format with resolved theme values and
+the current customizations. Enter a name and design guidance, save the JSON, and
+place it in the target project. The browser cannot write into that project for
+the agent. An imported preset can be edited and downloaded as a new revision.
+
+Deliver the preset, its component preview, fonts to load, and any unverified
+observations. Stop before building a full product. The next step is a concrete
+`build <idea> using <preset file>` request, described in
+[building-with-sable.md](./building-with-sable.md) and
+[using-presets.md](./using-presets.md).

package/llms/tasks/creating-design-assets.md

@@ -0,0 +1,96 @@
+# Task: create assets that carry the design
+
+Use this workflow when imagery, illustration, or type materially establishes the
+surface's identity or explains its content. A useful asset changes what someone
+understands or feels. Adding a decorative image to every section is unnecessary.
+
+## Define the asset's job before producing it
+
+Keep the asset plan with the surface brief, for example `design/<surface>/assets.json`.
+The optional [asset-plan template](../taste/asset-plan.template.json) is a plain
+planning record, not a `sable grade` or `sable explore` schema. Fill only relevant
+fields; `null` means unresolved, never tested or zero cost.
+
+For each important asset, specify:
+
+| Decision | Concrete example |
+|---|---|
+| Role and message | A workshop photograph shows the scale of the table and what a visitor will make. |
+| Subject and composition | Hands working clay at lower right; clear space at upper left for the heading. |
+| Visual treatment | Side lighting, warm paper background, shallow shadows; retain clay texture and avoid a glossy product-render finish. |
+| Relationship to the set | Product illustrations share line weight and viewpoint while their silhouettes distinguish the actual varieties. |
+| Placement and crop | Wide establishing view on desktop; a tighter alternate composition on mobile that retains both hands and the object. |
+| Source and readiness | User-provided photo with confirmed usage scope; original SVG; generated illustration; or explicitly provisional placeholder. |
+| Delivery target | Expected display dimensions, format candidates, byte budget, and loading priority. |
+
+Words such as "premium" or "editorial" need these visible decisions to become
+actionable. For an exact reference reconstruction, preserve its imagery roles and
+framing; report unavailable source assets or substitutions. Atlas captures are
+study evidence, not a product asset library.
+
+## Produce the right material
+
+- Use provided assets when they fit the brief and permitted usage. Record their
+  source, creator when known, license or permission reference, attribution needs,
+  and any unresolved usage restriction. Finding an image online does not establish
+  permission to ship it. Do not label unresolved rights as cleared.
+- Use original SVG or other code-native art for diagrams, marks, or illustration
+  systems that benefit from controlled geometry. Build a representative set before
+  repeating it: six recolored versions of one symbol may fail to distinguish six
+  subjects. Informative marks must not imply inaccurate counts or measurements.
+- Use an available image-generation workflow for original raster material when
+  it serves the brief. Include subject, framing, light, material, palette, crop
+  constraints, and exclusions in the prompt. Inspect the actual result; a prompt
+  is not an asset. Record generated origin honestly. Generated scenes are not
+  evidence of a real customer's product, venue, testimonial, or outcome.
+- For video, define the subject, shot sequence or loop, pacing, crop, poster, and
+  whether sound is meaningful. Use supplied, appropriately sourced, or generated
+  footage within the task's scope. Keep a usable poster/fallback. Motion review is
+  covered in [reviewing-motion.md](./reviewing-motion.md).
+
+For fonts, record family and role, required weights, language/glyph coverage,
+source, and relevant license. Load the actual files through the app's supported
+font pipeline, such as local `@font-face`, a framework loader, or a provider link.
+Declaring a font in a theme does not load it. Verify the font system and rendered
+text, including fallback, long titles, numerals, and relevant accented characters.
+An unavailable face needs an honest substitute rather than a broken provider URL.
+
+## Compose, crop, and deliver
+
+Test assets in the layout early with real copy. Choose the image focal point and
+text position together. Use `srcset`/`sizes` for resolution choices and `<picture>`
+or another explicit art-direction mechanism when the mobile composition should
+change. Inspect crops at the actual breakpoints: scaling a wide frame can remove
+its subject or leave unusably tiny detail.
+
+Give meaningful images useful alternative text; keep decorative imagery out of
+the reading order. Avoid baking essential copy into an image when live text can
+carry it. Provide equivalent information for a diagram or meaningful video.
+
+Choose a project-specific byte budget, including the combined initial image and
+font payload. Measure actual output bytes. Compare formats and encodings at the
+required size; retain a lossless or vector original when useful, and inspect the
+optimized export for damaged edges, banding, small-text loss, or changed color.
+Do not preload every asset or lazy-load the primary visual by habit. Verify the
+chosen loading behavior in the actual page, including slow or failed media.
+
+A temporary placeholder may unblock composition. Label it in the review/asset
+plan, preserve its intended dimensions, and make missing material clear to the
+reviewer. Replace it before calling that visual complete, or state the remaining
+limitation. Generation prompts and implementation notes belong in authoring
+artifacts, not the finished product flow.
+
+## Verify the assembled result
+
+Inspect desktop and mobile renders after fonts and media load, then test their
+fallback states. Check that the asset advances the intended message, remains
+recognizable at its smallest use, has a consistent relationship to the set, and
+does not compromise text or controls. Retain before/after evidence when revising
+an asset or crop; changing a file without viewing the new bytes is not review.
+
+Record delivered paths, dimensions, bytes, and the captures actually inspected.
+Use [reviewing-a-design.md](./reviewing-a-design.md) to connect those artifacts to
+the build's source hash. Include local asset directories in the fingerprint;
+remote resources need separate provenance because the source hash cannot freeze
+their contents. Reuse a successful treatment as a conditional principle, not a
+requirement that every future brand use the same illustration or font pairing.