@salesforce/afv-skills 1.54.0 → 1.56.0

package/skills/experience-design-validate/references/forms-flows.md

@@ -0,0 +1,57 @@
+# Forms & Flows
+
+> **Skip this reference if the design has no destructive actions, no save model, no multi-step flows, no checkout, no timelines, and no first-run experience — i.e. no journey to craft.**
+
+Forms and flows are where craft compounds. A delete confirmation that names what's about to die, a save indicator that fades at exactly the right moment, an undo toast with a visible countdown — these are the small considered moments that separate a polished product from a functional one. Good craft here feels like the product respects your work; poor craft feels like the product is indifferent to it.
+
+## Why this matters
+
+Flows are where users feel either confident or cornered. A confirmation dialog that uses generic "Are you sure?" copy and a gray "OK" button feels like a form letter; one that names the specific item, explains the consequence, and uses error-styled "Delete project" feels designed by someone who cared. A multi-step flow with a confident step indicator and a graceful "save and exit" feels like a partner; one that resets your inputs on validation feels like an adversary. The craft is in the calibration — friction proportional to consequence, save status unambiguous, every step earning its place. Done well, the product feels trustworthy and humane. Done badly, every save and submit becomes an act of faith.
+
+---
+
+## Destructive Actions
+
+- **Friction is calibrated to consequence.** Archiving gets an undo toast. Deleting gets a simple confirmation. Destroying a project gets specifics and consequences. Wiping an account requires typing the name. Friction matched to stakes reads as respectful.
+- **Confirmations name the thing.** "Delete 'Q4 Marketing Plan'?" reads as designed; "Are you sure?" reads as a template. The destructive button names the action — "Delete project," not "OK."
+- **Reversible actions earn an undo, not a confirmation.** Destructive actions never sit next to the most-used neighbor. Soft-delete with a recovery window reads as a designed safety net.
+
+## Save
+
+- **The save model is unambiguous.** The user always knows whether their work is saved, saving, or unsaved. A drifting "Saved" indicator that lies during failure is a critical breach of trust.
+- **Failure preserves work.** A save that fails never leaves the user thinking it succeeded. Content stays, retry is offered, navigation away from unsaved work prompts a guard.
+- **Draft and published states are visually distinct.** "Draft," "Published," "Modified since last publish" each read at a glance.
+
+## Multi-Step Flows
+
+- **Steps feel earned.** Each one addresses a different topic or depends on an earlier choice. Two steps that could've been one read as bloat.
+- **The step indicator tells the truth.** Position, progress, and completion visible. Branching paths show the actual route. Hidden steps stay hidden.
+- **Back never punishes; the flow can be paused.** Returning to a previous step preserves what was entered. Long flows offer "save and exit" and resume the user where they were.
+- **Submission is reviewable and resilient.** Irreversible work gets a summary with edit links. The final button names the action ("Place Order," not "Done"). Submission failure preserves everything — one error to fix, not a full re-entry.
+
+## Checkout
+
+- **The summary stays visible throughout.** Items, pricing, and total in view at every step. Security signals live where the anxiety lives — next to the card input. Confirmation closes the loop with specifics and a copyable reference.
+
+## Timelines
+
+- **Time scale is the user's primary handle.** Day, week, month, quarter, year — toggled cleanly. Today is unmistakable. Detail opens beside the timeline, not away from it. Direct manipulation feels confident — drag to move, drag the endpoint to resize.
+
+## Onboarding
+
+- **Time-to-first-value is the goal.** Every screen between signup and first success has to earn its place. A long onboarding before the user gets to do anything reads as bureaucratic.
+- **Empty states do onboarding's job.** The first time the user lands on an empty section, the screen explains what will live here and offers a way to make the first one. Tours don't lock the UI; tooltips arrive one at a time and never block the thing they're describing.
+
+---
+
+## Scoring Guide
+
+**Contributes to dimensions: Useful, Usable, Reliable**
+
+| Score | Criteria |
+|-------|----------|
+| 9-10 | Friction is calibrated. Save status is unambiguous. Multi-step flows preserve work and recover from failure. Onboarding earns its time. |
+| 7-8 | Flows handle destruction, saving, and multi-step competently with minor gaps. |
+| 5-6 | Some flows lose data on error. Generic confirmation copy. Onboarding overstays. |
+| 3-4 | Flows lose work. Destructive actions sit next to safe ones. No undo. |
+| 1-2 | Catastrophic flow failures. Users routinely lose what they typed. |

package/skills/experience-design-validate/references/interaction.md

@@ -0,0 +1,53 @@
+# Interaction
+
+> **Load this reference only with `DYNAMIC_VISUAL` evidence that directly exercises or records hover, click, focus, drag, touch, keyboard, or motion behavior. Static screenshots cannot substantiate interaction craft; mark interaction coverage `INSUFFICIENT_EVIDENCE` rather than inferring behavior.**
+
+## Why this matters
+
+Interaction is where a static surface becomes a living thing — and where craft is felt before it is seen. When interactions are well-crafted, the interface answers every gesture: a button presses back, a hover hints, a drop animates into place, a focus ring lands instantly and tastefully. The product feels responsive, alive, considerate. When interactions are sloppy, the surface feels dead — clicks land in silence, hovers do nothing, motion is either missing or jangly, and the user starts to doubt whether the interface is even working. Interaction craft is what separates products that feel inert from products that feel inhabited.
+
+---
+
+## Affordance and States
+
+- **The eye sorts interactive from inert without hovering.** Buttons look like buttons. Links carry two visible signals. Static elements never borrow interactive styling. Icon-only buttons say what they are — a tooltip, a label, or both.
+- **The primary action is obvious.** One filled button per logical section, sitting where the eye expects it. Secondary actions live one degree quieter.
+- **Every interactive element has a full life.** Default, hover, pressed, focus, disabled — each visibly distinct. Hover hints, press confirms — the two are different. Missing states make the interface feel half-built.
+- **Focus lands cleanly.** Keyboard focus shows up instantly at a consistent offset, tasteful against light and dark. A disabled element feels disabled and quietly explains why.
+- **Selected is heavier than hover.** When both apply at once, they're still distinguishable.
+
+## Motion
+
+- **Every animation earns its place.** If removing the motion doesn't reduce comprehension, the motion shouldn't exist. Decoration without purpose reads as showy.
+- **Similar transitions share a tempo.** Micro-feedback is quick. Layout changes are moderate. Cross-view transitions are slightly slower. Drift in tempo costs the product its rhythm. Reduced-motion preferences are honored.
+- **Motion never reflows the page.** A "smooth" animation that pushes neighboring content is a layout bug wearing a bowtie.
+
+## Micro-interactions
+
+- **Click feedback lands in a single frame.** The button presses, the toggle commits past its midpoint, the dropdown opens with calm — no waiting to see whether anything took.
+- **The wait sets the indicator.** A flash for the very fast, an inline spinner for a brief pause, a skeleton for longer. A spinner that appears for 80ms and vanishes feels worse than silence.
+
+## Drag, Touch, and Keyboard
+
+- **Drag and drop feels confident on any input.** Dragged items lift, neighbors make room, valid drops light up, invalid ones say no, cancel always recovers. Keyboard parity is real, not theoretical.
+- **Touch targets feel comfortable to tap, not cramped.** Adjacent controls give fingers breathing room. Destructive actions hold their distance. Primary actions land in the thumb's reach.
+- **Keyboard shortcuts shadow visible UI.** They accelerate, never replace. Platform conventions are respected. Single-key shortcuts step aside in text inputs.
+
+## Selection and Latency
+
+- **Selection is unmistakable.** What's chosen, how to change it, and what to do with it — all clear at a glance. A floating action bar handles bulk operations without shifting the layout.
+- **Every input is acknowledged within a frame.** Optimistic feedback is reserved for the safe and reversible. Search and filtering feel alive but never anxious — calm refinement, not jittery flicker.
+
+---
+
+## Scoring Guide
+
+**Contributes to dimensions: Usable, Reliable, Well-Crafted**
+
+| Score | Criteria |
+|-------|----------|
+| 9-10 | The interface feels inhabited. Every gesture is answered. Motion is purposeful and quiet. Touch and keyboard parity is real. Latency is invisible. |
+| 7-8 | Strong interaction craft with minor gaps in states or motion consistency. |
+| 5-6 | Functional but unpolished. Some interactions land in silence; durations drift; touch targets feel cramped. |
+| 3-4 | The surface feels dead. Missing states. Inconsistent motion. Keyboard or touch fails. |
+| 1-2 | Clicks vanish into silence. The interface feels uninhabited. |

package/skills/experience-design-validate/references/navigation.md

@@ -0,0 +1,51 @@
+# Navigation
+
+> **Skip this reference if the input is a single screen with no IA, no nav system, no tabs, no breadcrumbs, no search, and no inter-page linking.**
+
+## Why this matters
+
+Navigation is the structural craft of a product — the bones beneath every surface — and a user feels its quality long before they could articulate it. When navigation is well-crafted, the product feels orienting: you always know where you are, where you can go, and what is one click away; the active state catches the eye, breadcrumbs settle in calmly, and the sidebar collapses with a confidence that suggests someone thought about it. When it is poorly crafted, the product feels like a maze — labels mismatch destinations, the active state drifts, mobile becomes a hamburger graveyard, and every click feels like a guess. Great navigation is invisible discipline; bad navigation is the first thing users complain about.
+
+---
+
+## Information Architecture
+
+- **The map is shallow and task-shaped.** No primary destination feels like an excavation. Labels mirror what the user came to do, not the engineering team's diagram. The top level is small enough to scan in one glance.
+- **No junk drawers.** Sections labeled "Other" or "More" without further structure read as places where decisions weren't made.
+- **Every label promises what it delivers.** A click that lands somewhere unexpected breaks trust faster than any visual flaw. The same destination never has two labels.
+
+## The Nav Frame
+
+- **The frame holds still.** Primary navigation stays in the same place across every screen. When it drifts, the product feels assembled by different teams.
+- **The chrome chooses its style.** Sidebar for many destinations or top bar for a few — never a hamburger on desktop pretending to be a navigation system.
+- **Active state announces itself.** The current location reads at a glance — distinct from hover, distinct from default, calm rather than shouty. It lights up the moment the click lands, even if content is still on the way.
+- **Collapsed states still navigate.** A collapsed sidebar with unrecognizable icons isn't a feature, it's a riddle.
+
+## Tabs and Breadcrumbs
+
+- **Tabs hold parallel views, not pages.** When the content behind a tab feels like a different topic, that topic deserved a destination. Tabs stay modest in number, never wrap to a second row, and use short uniform labels. The active indicator sits cleanly — a precise underline sized to the label.
+- **Breadcrumbs settle into the page; they don't compete with it.** Smaller than the page title, muted, with the current page rendered as plain text. Long trails fold their middle into an ellipsis.
+
+## Search and URLs
+
+- **Search lands where the eye looks and answers calmly.** Top-center or top-right on desktop, persistent on mobile, summoned by shortcut from anywhere. Suggestions arrive without jittery flicker. Exact matches go straight to the destination.
+- **The URL is shareable and human-readable.** Every meaningful state has its own address. Back returns to where the user was — filters, scroll, and tab selection preserved.
+- **Missing destinations explain themselves.** "Doesn't exist" looks different from "you can't see this." Both offer a way back. Transitions between pages never go blank.
+
+## Responsive
+
+- **Each viewport gets its own nav.** Full sidebar on desktop, icon rail on tablet, bottom tabs or drawer on mobile. A shrunken desktop nav on a phone is the giveaway of unfinished work. Mobile primary actions sit in the thumb zone.
+
+---
+
+## Scoring Guide
+
+**Contributes to dimensions: Useful, Usable**
+
+| Score | Criteria |
+|-------|----------|
+| 9-10 | The user always knows where they are and where they can go. IA mirrors tasks. Active state is unmistakable. URL and back behave as expected. Each viewport has its own nav voice. |
+| 7-8 | Navigation is solid with minor inconsistencies in active state, breadcrumbs, or mobile transformation. |
+| 5-6 | Functional but with junk drawers, drifting active state, or mobile that's a reflowed desktop. |
+| 3-4 | Confusing IA, broken back behavior, labels that mismatch destinations. |
+| 1-2 | Users can't tell where they are or where to go. |

package/skills/experience-design-validate/references/performance.md

@@ -0,0 +1,56 @@
+# Performance
+
+> **Load this reference only with `DYNAMIC_VISUAL` evidence that directly shows timing, latency, loading, scrolling, animation, or layout stability. Static screenshots and source code cannot substantiate felt performance; mark performance coverage `INSUFFICIENT_EVIDENCE` rather than inferring it.**
+
+Craft in performance is the felt quality of an interface that responds the moment you ask it to. It lives in the precision of an instant feedback flash, the calm of a skeleton screen that lands exactly where the content will be, the discipline of motion that doesn't shove the layout around, and the absence of jolts as content settles into place. This reference judges whether the interface feels effortless — load behavior, interaction latency, layout stability, and the formatting craft of numbers, dates, and units that hold the surface together.
+
+## Why this matters
+
+Performance is the most invisible form of craft — users rarely praise a fast app, but they always feel a slow one. When craft is high, the interface feels weightless: pages snap in, content lands without shifting, every press is acknowledged before the user wonders if anything happened, and animations feel quietly confident. When craft is low, the experience feels janky and unsure of itself — buttons that move as you reach for them, skeletons that don't match the content they preview, dropdowns that hang, numbers that change format mid-table. Polish at this layer is what makes the rest of the design feel real instead of staged.
+
+---
+
+## Loading
+
+- **The page never opens to white.** Meaningful structure or a designed loading state arrives quickly. The interface becomes usable before it's complete — primary actions work first, secondary content fills in.
+- **Skeletons mirror what's coming.** Same layout, same dimensions, same item count. When the real content lands, nothing shifts. Repeat visits feel instant.
+
+## Interaction
+
+- **Every press is acknowledged immediately.** No silent moments, no wondering if the click registered. Typing feels alive. Dropdowns and route changes open with confidence — no third-of-a-second hang.
+- **The wait sets the indicator.** A flash for the very fast, an inline spinner for a brief pause, a skeleton or progress for longer. A spinner that flashes for a fraction of a second is worse than silence. Long work goes background and returns the UI.
+
+## Layout Stability
+
+- **Content lands where it landed.** Buttons don't move as the user reaches. The page doesn't jump as a late image arrives. Layout shift is the visible signature of an unfinished page. Skeletons reserve their final size; toasts overlay rather than push.
+- **Lists settle, not lurch.** Append doesn't shift earlier content. Back navigation restores scroll position.
+
+## Scale
+
+- **Large lists feel as smooth as small ones.** Scrolling through thousands of rows doesn't drag or hang. Filtering and sorting respond instantly. Dashboards load independently — one slow widget never holds the rest of the page hostage.
+- **Spatial UIs hold their frame rate.** Pan, zoom, and drag feel smooth. Stutter during direct manipulation is the giveaway of a canvas not engineered for the work.
+
+## Perceived Performance
+
+- **The product feels faster than it is.** Optimistic feedback for low-risk actions; content streamed in rather than withheld; the most important elements first. Long operations let the user keep working, with completion finding them wherever they go.
+- **Offline is detected immediately.** Cached content stays usable; new work queues for sync. The interface doesn't pretend the network is fine.
+
+## Formatting Craft
+
+- **Recent times read as human time; older times settle into absolute dates.** "Just now," "5 min ago," "Yesterday" feel natural for recent activity. Past a week, real dates arrive. Ambiguous numeric dates ("1/15/24") are avoided. Time zones surface only when they matter.
+- **Numbers are formatted for fastest comprehension.** "1.2M" reads faster than "1,247,893" on a dashboard. Full precision belongs in detail views. Number columns right-align so decimals stack. Zero is not null — "—" or "N/A" tells the user nothing was measured. The same metric is formatted the same everywhere.
+- **Type, spacing, and stacking follow systems.** When the user enlarges text, the interface scales gracefully. Stacking order is predictable — toasts above modals, tooltips above everything. Adjacent gaps that read as 12, 14, 16, and 18 pixels feel improvised.
+
+---
+
+## Scoring Guide
+
+**Contributes to dimension: Reliable**
+
+| Score | Criteria |
+|-------|----------|
+| 9-10 | The product feels effortless. Pages snap in. Every interaction is acknowledged. Nothing shifts. Numbers, dates, and units are formatted with discipline. |
+| 7-8 | Mostly responsive with minor lulls or layout shifts. Formatting is mostly consistent. |
+| 5-6 | Some sluggish moments. Layout shifts as content arrives. Mixed number formats. |
+| 3-4 | Slow primary flows. Visible jank. Buttons move as the user reaches. Large lists choke. |
+| 1-2 | Long waits with no feedback. Clicks unresponsive. The interface feels janky and unsure of itself. |

package/skills/experience-design-validate/references/records.md

@@ -0,0 +1,60 @@
+# Entities & Objects
+
+> **Skip this reference if the design shows no records, objects, detail pages, status fields, metadata, versioning, collaboration, or workflow surfaces.**
+
+Craft in entity design is felt in how confidently a record presents itself — the calm authority of a well-structured header, the rhythm of metadata that recedes without disappearing, the visual grammar of status that reads at a glance. This reference judges the visual and structural craft of object pages, status systems, metadata treatment, versioning surfaces, collaboration cues, and workflow visualizations.
+
+## Why this matters
+
+Entities are the protagonists of most software — every record a user touches is a small first impression of the product's care and competence. When craft is high, an object feels solid: identity is unmistakable, status reads at a glance, metadata sits politely in the margins, and history feels like a designed surface rather than a log. When craft is low, records feel like form dumps — labels everywhere, statuses competing for attention, timestamps in three formats, and presence indicators that lie about who is there. The difference is the felt sense that someone arranged this carefully versus someone wired it up.
+
+---
+
+## Object Anatomy
+
+- **The header establishes identity at a glance.** The user knows what this thing is, what state it's in, who owns it, and what they can do with it — without scrolling.
+- **Read mode is designed, not a disabled form.** Inputs greyed out and read-only is the giveaway of an entity surface that wasn't actually composed for reading. Body content is organized by relevance — what users look at most lives in the default view. Empty optional fields stay quiet.
+- **Creation is fast and forward.** Minimum viable fields, then drop the user into the new record. No record is an orphan — every object links back to its parent context.
+
+## Status
+
+- **Statuses are a small, closed set with semantic meaning.** A handful of states the user can hold in mind. "Awaiting approval" reads as designed; "PENDING_APPROVER_REVIEW" leaks the database into the page.
+- **Status is communicated by more than color.** A label, an icon shape, or both — never color alone. The mapping holds across the product. Only valid transitions show as actions; invalid moves don't appear as disabled options.
+
+## Metadata
+
+- **System metadata recedes.** Findable but never competing with primary content. Timestamps speak in human time when recent, transitioning to absolute as content ages. People references show face and name together. Reference numbers offer copy in one click.
+- **Empty values say something.** A "—" or "Not set" tells the user a value wasn't recorded; blank space hides whether the field even exists. Date and time formats hold across the product.
+
+## History and Versioning
+
+- **History is one click away.** A clear timeline with attribution: who, when, what changed. Diffs are visible, not just listed — additions highlighted, deletions struck through.
+- **Viewing a historical version is unmistakable.** A banner makes the time-travel state clear. Restoring creates a new entry — nothing silently lost.
+
+## Collaboration
+
+- **Presence is honest.** Active, idle, and recently-active are visually distinct. A stale "online" indicator is worse than no presence at all.
+- **Comments thread, resolve, and notify; conflicts surface rather than silently overwrite.** Ownership is visible and transferable. The user's own permission level is in view — they can tell what they're allowed to do without trying and failing.
+
+## Messaging Surfaces
+
+- **The conversation lives in three calm panels.** List, thread, context. AI-generated content is visually distinct from human messages — a model's reply never silently passes for a person's. System events render as compact inline notes rather than full-width cards.
+
+## Workflow
+
+- **Sequential processes show their steps.** Each node has a status — pending, running, succeeded, failed — and failures explain themselves inline. Cells awaiting computation declare it ("Click to run," "Pending") rather than going blank.
+- **Configuration overlays the work, not replaces it.** A side drawer keeps the table visible. Batch progress is honest and cancellable.
+
+---
+
+## Scoring Guide
+
+**Contributes to dimensions: Useful, Coherent, Reliable**
+
+| Score | Criteria |
+|-------|----------|
+| 9-10 | Entities are instantly identifiable. Status systems are closed and semantic. Metadata recedes politely. History and collaboration are first-class. |
+| 7-8 | Entity structure is clear with minor gaps in status discipline or metadata treatment. |
+| 5-6 | Status communicated by color alone. Inconsistent metadata. History hidden behind menus. |
+| 3-4 | Records read as form dumps. Stale presence. No history. |
+| 1-2 | Objects feel disorienting. No coherent identity or status system. |

package/skills/experience-design-validate/references/responsive.md

@@ -0,0 +1,48 @@
+# Responsive Design
+
+> **Skip this reference if the input targets a single fixed viewport with no media queries, no mobile/tablet/desktop variants, and no embedded use case.**
+
+## Why this matters
+
+Responsive craft is the discipline of composing the same product gracefully across every viewport, and it is one of the surest signs that a designer thought past the artboard. When it is well-crafted, mobile feels designed for the thumb, tablet earns its width with side-by-side layouts, desktop uses space for density rather than empty margins, and the spaces between breakpoints never feel cramped or abandoned. When it is poorly crafted, the product feels like one screen warped to fit others — buttons drift off the edge, text walls appear at wide widths, mobile becomes a sad shrunken desktop. Considered responsiveness is what makes a product feel native everywhere it lives.
+
+---
+
+## Across Breakpoints
+
+- **Each viewport feels intentional.** Not a single layout warped to fit, but distinct compositions that look designed for the size they live at. The dead zones between common breakpoints are tended — content doesn't crowd, clip, or strand itself in awkward gutters.
+- **Content priority leads the layout.** Most important elements stay visible; decoration drops away first; secondary content collapses or moves before primary content does. Multi-column layouts collapse with grace — never an orphan trailing item that exposes the grid's seams.
+- **Spacing scales with the viewport.** Generous on desktop, moderate on tablet, modest but never zero on mobile. Hierarchy holds at every width.
+
+## Mobile
+
+- **Mobile is its own design, not a shrunken desktop.** Designed for the thumb, the glance, and the interruption. Targets feel comfortable to tap, not cramped. Primary actions live in thumb territory; rare or dangerous ones sit out of reach.
+- **Single-column layouts feel calm, not stretched.** Buttons, inputs, and cards span the width with intent. Body text never shrinks below comfort. Safe areas — notches, home indicators, rounded corners — are accommodated rather than fought.
+
+## Tablet
+
+- **Tablet earns its width.** Side-by-side list/detail layouts, persistent navigation, two-pane workflows — not a stretched phone screen. Both orientations feel designed. Touch parity holds at the larger size; every action remains reachable by tap alone.
+
+## Desktop
+
+- **Space serves density, not emptiness.** A narrow centered column with massive margins on a wide screen reads as wasted real estate. Multi-column architecture is composed with deliberate widths and breathable gaps.
+- **The layout works from a small laptop to a wide monitor.** Ultrawide doesn't yield endless empty gutters; small desktop doesn't crowd. Max-width keeps reading lines from sprawling.
+- **Mouse and keyboard precision are leveraged.** Hover layers, right-click menus, drag-and-drop, shortcuts, command palette — the input device's strengths are used rather than ignored. Density modes give intensive users a calmer view.
+
+## Embedded
+
+- **An embedded surface behaves like a guest.** Minimal chrome, compact controls, denser spacing. Visual integration respects the host's palette and typography. Overflow stays inside — the embed never pushes the host's layout around. A path to the full experience exists when space gets tight.
+
+---
+
+## Scoring Guide
+
+**Contributes to dimensions: Well-Crafted, Usable**
+
+| Score | Criteria |
+|-------|----------|
+| 9-10 | Every viewport feels intentionally composed. Mobile is designed for the thumb. Desktop uses space for density. The spaces between breakpoints are tended. |
+| 7-8 | Strong responsive craft with minor gaps at edge widths. |
+| 5-6 | Mobile reads as a reflowed desktop. Some breakpoints feel cramped or empty. |
+| 3-4 | Touch targets are too small. The layout fights the viewport. |
+| 1-2 | Layout breaks at common viewports. The product wasn't designed for the screens it lives on. |

package/skills/experience-design-validate/references/scoring-rubric.md

@@ -0,0 +1,257 @@
+# Scoring Rubric
+
+Use this rubric to judge the visual craft of a rendered design across five dimensions. Scores describe only the evidence observed in the declared evidence mode.
+
+## Scoring rules
+
+Every score must be:
+
+- **Evidence-based:** cite specific, visible or directly observed qualities.
+- **Bounded:** do not treat unobserved screens, behavior, states, responsiveness, or performance as good or bad.
+- **Repeatable:** another reviewer should land within one point using the same evidence.
+- **Actionable:** name what the next supported level requires.
+- **Felt:** judge the visible experience, not implementation or intent.
+
+### Anchor selection
+
+Use the anchors at 2, 4, 6, 8, and 10. For each dimension:
+
+1. Determine which criteria are applicable and observable in the declared evidence mode.
+2. Evaluate anchors from 10 downward.
+3. Assign the **highest anchor whose applicable, observable criteria are all fully supported by evidence**.
+4. Assign the odd score above that anchor only when all criteria at the anchor are supported and the evidence clearly exceeds it but does not fully support the next anchor. For example, 7 means all applicable criteria at 6 are supported and some, but not all, applicable criteria at 8 are supported.
+5. Assign 1 only when observed evidence falls below the applicable criteria at anchor 2.
+6. Use `INSUFFICIENT_EVIDENCE` rather than a number when evidence cannot support the applicable dimension. Use `N/A` only when the dimension genuinely does not apply.
+
+Do not start from an assumed middle score. Do not average unknowns into a score. When evidence supports multiple anchors, choose the highest fully supported anchor, not the lowest level whose criteria happen to be met.
+
+## Scale and visual-craft implication
+
+| Score | Level | Visual-craft implication only |
+|---|---|---|
+| 10 | Exceptional | Reference-quality visual craft; suitable to showcase for craft |
+| 9 | Near-exceptional | Visually excellent with trivial polish opportunities |
+| 8 | Strong | Visually ready with minor craft opportunities |
+| **7** | **Good** | **Meets the visual-craft threshold with a minor polish plan** |
+| 6 | Above adequate | Visually functional but craft is uneven |
+| 5 | Adequate | Clear visible friction or roughness remains |
+| 4 | Below standard | Significant craft issues diminish the visible experience |
+| 3 | Poor | Multiple visible craft failures make the design feel rushed |
+| 2 | Very poor | Fundamental visible craft failures require major rework |
+| 1 | Critical | The rendered design feels visually broken or abandoned |
+
+These implications do not approve accessibility, functional behavior, security, measured performance, or production release.
+
+## Verdict
+
+- **PASS:** every applicable dimension is scored and all scores are at least 7.
+- **WARN:** every applicable dimension is scored; at least one is below 7 and none is below 5.
+- **FAIL:** every applicable dimension is scored and at least one is below 5.
+- **LIMITED:** at least one applicable dimension is `INSUFFICIENT_EVIDENCE`. Report supported scores as provisional observations, but do not imply complete visual-craft readiness.
+
+`N/A` dimensions do not affect the verdict. If no dimension can be scored, do not issue a Craft Report verdict; follow the `INSUFFICIENT_VISUAL_EVIDENCE` behavior in `SKILL.md` when no rendered pixels exist, or return `LIMITED` with the coverage ledger when pixels exist but support no dimension-level score.
+
+## Dimension anchors
+
+### Useful
+
+Felt question: *Does the visible content earn the space and attention it occupies?*
+
+| Anchor | Observable criteria |
+|---|---|
+| 10 | Every visible element appears purposeful; priority and restraint anticipate the user's visible needs; no decorative dead weight competes for attention. |
+| 8 | Core visible goals are well supported; most elements clearly earn their place; only minor tangents remain. |
+| 6 | The visible value is understandable, but some content feels tangential, unfinished, or weakly prioritized. |
+| 4 | Multiple visible elements do not earn their space; clutter obscures the apparent purpose. |
+| 2 | The surface is dominated by content that does not visibly support the apparent core task. |
+
+Do not infer whether features meet real user needs from pixels alone. Qualify the score as visible usefulness and flag behavioral assumptions for research.
+
+### Usable
+
+Felt question: *Does the visible hierarchy make the intended path feel effortless?*
+
+| Anchor | Observable criteria |
+|---|---|
+| 10 | The intended path is visually unmistakable; complex structure feels simple; visible affordances prevent likely mistakes. |
+| 8 | Primary actions and next steps are clear with minor hierarchy or affordance gaps. |
+| 6 | The path is discoverable but invites hesitation; some visible actions compete or lack clarity. |
+| 4 | Common visible paths appear confusing, fragmented, or poorly prioritized. |
+| 2 | The rendered surface provides little visible guidance toward a core task. |
+
+Static evidence supports visible hierarchy and affordance only, not task completion, recovery behavior, keyboard operation, or observed user success.
+
+### Reliable
+
+Felt question: *Do the observed states and feedback make the experience feel predictable?*
+
+For `DYNAMIC_VISUAL` evidence, use these anchors:
+
+| Anchor | Dynamic observable criteria |
+|---|---|
+| 10 | Every directly exercised relevant state and transition is clear, calm, and designed; observed feedback and timing remove uncertainty. |
+| 8 | Major exercised states and feedback are clear; only minor observed edge gaps remain. |
+| 6 | Observed states function but some treatment is generic, ambiguous, or poorly timed. |
+| 4 | Directly observed feedback is missing, contradictory, or visibly brittle. |
+| 2 | Observed behavior leaves the user unable to tell what happened or whether work persisted. |
+
+For `STATIC_VISUAL` or `MULTI_VIEW_STATIC` evidence, score only the visible communication of depicted states and consequences:
+
+| Anchor | Static observable criteria |
+|---|---|
+| 10 | Every depicted relevant state or consequence is immediately legible, calm, specifically authored, and unambiguous in context. |
+| 8 | Major depicted states and consequences are clear and specifically treated; only minor visual-communication gaps remain. |
+| 6 | Depicted states are identifiable, but some treatment is generic, ambiguous, or weakly prioritized. |
+| 4 | Important depicted state or consequence cues are contradictory, hard to associate, or visually overwhelmed. |
+| 2 | The depicted state leaves the viewer unable to tell what is true, what changed in the captured moment, or which visible action has serious consequences. |
+
+Qualify every static Reliable score as **depicted-state visual communication only**. A static score cannot substantiate state coverage, transition behavior, save behavior, feedback timing, persistence, or performance. Use `INSUFFICIENT_EVIDENCE` when no relevant state or consequence is visibly depicted, or when behavior is necessary to score the dimension responsibly.
+
+### Coherent
+
+Felt question: *Does the visible experience feel like the same hand made it?*
+
+| Anchor | Observable criteria |
+|---|---|
+| 10 | Every supplied screen shares one disciplined visual language; variants have clear visible purpose; patterns repeat consistently. |
+| 8 | Core screens are visibly consistent with minor deviations in secondary areas. |
+| 6 | The main visual language is recognizable, but repeated patterns drift. |
+| 4 | Major visible inconsistencies make surfaces feel assembled by separate teams. |
+| 2 | Supplied screens feel like unrelated products with no discernible shared system. |
+
+One screenshot may support internal composition coherence, but cross-screen coherence requires multiple screens.
+
+### Well-Crafted
+
+Felt question: *Does the rendered design feel precise, considered, and delightful?*
+
+| Anchor | Observable criteria |
+|---|---|
+| 10 | Every observed detail feels intentional and precise; hierarchy, type, spacing, alignment, color, and any exercised motion work as one quiet whole. |
+| 8 | Execution is visibly strong and consistent with only minor polish opportunities. |
+| 6 | Execution is generally sound but visible alignment, spacing, hierarchy, or state-treatment gaps remain. |
+| 4 | Multiple visible inconsistencies or unfinished treatments make the design feel rough. |
+| 2 | Pervasive visual quality failures make the rendered design feel broken or abandoned. |
+
+Do not require motion, responsiveness, dark mode, reduced motion, or unseen states unless they are relevant and directly evidenced.
+
+## Coverage and relevance ledger
+
+The report must include a ledger before scores. Create one row for every dimension and every reference topic considered.
+
+| Field | Allowed content |
+|---|---|
+| `item` | Dimension or reference topic |
+| `relevance` | `APPLICABLE` or `N/A` |
+| `coverage` | `SCORED`, `INSUFFICIENT_EVIDENCE`, or `N/A` |
+| `evidence_mode` | `STATIC_VISUAL`, `MULTI_VIEW_STATIC`, or `DYNAMIC_VISUAL` |
+| `evidence` | Artifact, screen, state, viewport, recording segment, or directly observed action |
+| `reason` | Why it is scored, not applicable, or insufficiently evidenced |
+
+`N/A` means the topic is absent or irrelevant. `INSUFFICIENT_EVIDENCE` means it is relevant but not observable. Never collapse these states into `Unknown`, and never invent a score to make the table complete.
+
+## Finding severity
+
+- **critical:** An observed visual-craft failure blocks comprehension of the primary surface or makes a destructive/high-consequence path visibly unsafe. Address before claiming visual-craft readiness.
+- **major:** A repeated or prominent issue substantially weakens hierarchy, confidence, or task clarity. It materially lowers one or more dimensions.
+- **minor:** A localized issue causes noticeable friction or inconsistency without undermining the primary path.
+- **polish:** A small refinement would improve precision or delight but does not create meaningful confusion.
+
+Each finding has one `primary_dimension`, the dimension most directly weakened by the root cause, and zero or more `related_dimensions`. Record the finding once and reference related dimensions rather than duplicating it. If severity could fit multiple levels, use the highest supported severity.
+
+## Output discipline
+
+- Cap findings at five per dimension.
+- Consolidate a problem seen in three or more places into one finding with a count and representative location.
+- Include zero to five cross-cutting patterns. A pattern must span multiple findings.
+- Include zero to five recommendations, ordered by expected effect on observed visual craft.
+- Do not add findings, patterns, or recommendations merely to fill the schema.
+- Flag recommendations dependent on real-user behavior for usability research.
+- Keep accessibility findings out of this report and route compliance to `experience-accessibility-validate`.
+
+## Craft Report schema
+
+```text
+scope: visual-craft-only
+verdict: PASS | WARN | FAIL | LIMITED
+evidence_mode: STATIC_VISUAL | MULTI_VIEW_STATIC | DYNAMIC_VISUAL
+evidence_inventory: [artifacts, screens, states, viewports, or recording segments reviewed]
+evidence_limitations: [what this evidence cannot substantiate]
+
+first_impressions: [0-3 felt observations recorded before rubric analysis]
+
+coverage_relevance_ledger:
+  - item: [dimension or reference topic]
+    relevance: APPLICABLE | N/A
+    coverage: SCORED | INSUFFICIENT_EVIDENCE | N/A
+    evidence_mode: [mode]
+    evidence: [specific artifact or observation, or none]
+    reason: [concise rationale]
+
+dimensions:
+  - name: Useful | Usable | Reliable | Coherent | Well-Crafted
+    score: [1-10] | INSUFFICIENT_EVIDENCE | N/A
+    evidence: [specific observed evidence]
+    gap_to_next_level: [next fully supportable craft improvement] | N/A
+
+findings:
+  - severity: critical | major | minor | polish
+    primary_dimension: [one dimension]
+    related_dimensions: [zero or more other dimensions]
+    location: [screen, region, state, viewport, or Figma node; never file:line]
+    problem: [visible or directly observed issue]
+    why_it_weakens_craft: [design principle and felt effect]
+    what_better_looks_like: [improved visible experience]
+    fix: [specific design move]
+
+cross_cutting_patterns: [0-5 evidence-backed themes]
+recommendations: [0-5 evidence-backed prioritized moves]
+fix_prompt: [self-contained design directive] | OMITTED_NO_ACTIONS
+```
+
+The report must state that the verdict indicates visual-craft readiness only and is not an accessibility, functionality, performance, security, or production-release approval.
+
+## Comparative schema
+
+Preserve the complete individual audit for each design, then add:
+
+```text
+comparison_result: A_HIGHER_CRAFT | B_HIGHER_CRAFT | TIE | MIXED
+
+designs:
+  - id: Design A
+    first_impressions: [0-3 observations]
+    strongest_visible_move: [evidence-backed strength]
+    gaps: [0-5 evidence-backed gaps or INSUFFICIENT_EVIDENCE entries]
+  - id: Design B
+    first_impressions: [0-3 observations]
+    strongest_visible_move: [evidence-backed strength]
+    gaps: [0-5 evidence-backed gaps or INSUFFICIENT_EVIDENCE entries]
+
+comparison_table:
+  - dimension: [dimension]
+    design_a: [1-10] | INSUFFICIENT_EVIDENCE | N/A
+    design_b: [1-10] | INSUFFICIENT_EVIDENCE | N/A
+    outcome: A | B | TIE | NOT_COMPARABLE
+    evidence: [why]
+
+differentiating_dimensions: [0-5 dimensions]
+craft_moves:
+  design_a: [0-5 moves Design A executes better]
+  design_b: [0-5 moves Design B executes better]
+borrow_without_copying: [0-5 grounded opportunities]
+```
+
+Use `TIE` when supported scores and qualitative evidence are materially equivalent. Use `MIXED` when each design leads in different dimensions or unequal evidence prevents a responsible overall ranking.
+
+## Fix prompt
+
+Include a fix prompt only when the report has at least one recommendation. It must:
+
+- Open with a one-sentence felt goal and a short design brief.
+- List only the report's evidence-backed recommendations, in priority order.
+- Name the affected screen or region and felt outcome for each move.
+- End with verification on fresh rendered evidence and identify dimensions expected to improve.
+- Preserve parts of the design that already work.
+
+Use design language, not CSS variables, class names, file paths, or implementation diffs. If there are no actionable recommendations, emit `OMITTED_NO_ACTIONS`.