@salesforce/afv-skills 1.53.0 → 1.55.0

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

@@ -0,0 +1,61 @@
+# Components
+
+> **Skip this reference if the input contains no buttons, forms, modals, lists/tables, or feedback components. Within the file, sections are independent: skip "Buttons" if no buttons exist, "Forms" if no forms, "Overlays" if no modals/drawers/popovers/tooltips, "Lists & Tables" if no list or table UI, "Feedback" if no toasts/alerts/progress/empty states.**
+
+## Why this matters
+
+Components are where craft compounds — every button, input, and overlay is a small artifact a designer either sweated over or shrugged at, and the difference is felt across an entire product. When components are well-crafted, the interface feels purposeful: a single primary action draws the eye, inputs line up to the pixel, hover and pressed states confirm every touch, and overlays settle into place with calm, considered motion. When they are sloppy, the surface feels noisy and unresolved — competing buttons, mismatched heights, half-built states, modals that pop instead of arrive. A polished component system is one of the clearest signals that designers cared about the small details users feel but never name.
+
+---
+
+## Buttons
+
+- **The eye lands on one action.** Each screen has a single primary button that is unmistakably the thing to do. When two buttons compete for primacy, neither wins and the screen feels indecisive.
+- **Hierarchy reads at a glance.** Primary, secondary, and tertiary feel like three distinct registers — not three flavors of the same button.
+- **Destructive actions don't masquerade as the answer.** "Delete" is never the bright filled button next to "Cancel." It's quieter, set apart, and only takes on full danger styling inside the dialog that confirms it.
+- **Buttons feel resolved, not assembled.** Heights match across a row. Adjacent buttons and inputs align to the pixel. Icons inside feel optically centered. Every press answers back — hover hints, the click depresses, focus lands cleanly.
+
+## Form Controls
+
+- **Inputs line up.** Same heights, same border treatment, same internal padding. Mismatch reads as carelessness even before the user can articulate why.
+- **One label position rules the form.** Above, floating, or to the side — pick one and commit. Mixing reads as multiple drafts merged together. Placeholder text never does the label's job.
+- **Errors arrive when the user is done, not while they're typing.** Per-keystroke validation feels accusatory. Errors clear the moment correction begins, and never shove the layout around.
+- **Selects, toggles, and checkboxes feel like one family.** A dropdown trigger looks like a sibling of the text input next to it. The system feels designed, not collected.
+
+## Overlays
+
+- **The right surface for the moment.** Modals interrupt for genuine blocking decisions; drawers hold detail; popovers handle quick contextual pickers; tooltips stay strictly supplementary. When a modal could've been a page, the screen feels claustrophobic.
+- **Modals arrive, they don't pop.** Entry has the calm of a considered transition. Width feels chosen, not arbitrary. The frame holds while the body scrolls — header and footer stay put, the primary action visible without hunting.
+- **Drawers don't push the world around.** Opening one shouldn't shift the parent layout.
+- **Tooltips whisper.** A short line, two at most. They wait briefly to appear, fade rather than fly, and never restate the visible label.
+- **Stacking is rare and shallow.** Modal-on-modal reads as missing IA. Drawers don't pile. Escape always dismisses; backdrop click closes anything not holding unsaved work.
+
+## Lists & Tables
+
+- **One template, repeated cleanly.** Every row shares the same anatomy. Density is chosen and committed — same row heights, padding that doesn't drift between cells. The table reads as a single instrument.
+- **Alignment respects the data.** Numbers right, text left, actions last. Mixed alignment within a column makes the eye lose its rail.
+- **One separation strategy at a time.** Zebra stripes or borders or whitespace — never a combination. Combining turns a quiet table into a cage. Headers stay subordinate to the data they label.
+- **The whole row responds to the cursor.** Hover and click extend across the full width. Cards in a grid are one click target, not a patchwork. Selection looks selected — distinct from hover.
+- **Cards in a grid keep their rhythm.** Same width across the row. Truncation rather than reflow.
+- **Empty doesn't mean blank.** Empty lists keep their headers, name what would live here, and offer a way to make the first one. Skeletons mirror the shape of what's coming — so the page doesn't lurch when data arrives.
+
+## Feedback
+
+- **Toasts confirm; alerts persist.** Toasts handle "we did the thing." Alerts handle "you need to handle the thing." A critical error delivered as a five-second toast reads as careless. One toast position for the whole product.
+- **Severity has a visual register.** Info, success, warning, error each carry their own color and icon — never color alone, never red used twice for unrelated meanings. Severity escalates calmly as stakes rise.
+- **Progress feels honest.** A determinate bar moves like it means it. Fake or jumpy progress trains users to distrust every indicator. Skeletons match the final layout — generic gray rectangles read as unfinished.
+- **Empty states are designed, not abandoned.** A short headline, a sentence of context, and a way forward. A blank canvas is a defect.
+
+---
+
+## Scoring Guide
+
+**Contributes to dimensions: Usable, Reliable, Well-Crafted**
+
+| Score | Criteria |
+|-------|----------|
+| 9-10 | The component system feels considered. One primary draws the eye. Inputs and buttons share a single rhythm. Overlays arrive calmly. Lists and cards keep their structure across every state. Feedback is calibrated and complete. |
+| 7-8 | Strong component patterns with minor gaps. |
+| 5-6 | Competing primaries, mismatched heights, generic empty states. Validation feels accusatory. Feedback is partial. |
+| 3-4 | Components feel assembled rather than designed. Destructive actions blend in. Overlays pop. Empty states are blank. |
+| 1-2 | No coherent component voice. The interface reads as a collection of defaults. |

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

@@ -0,0 +1,158 @@
+# Craft
+
+> **Always load. Craft is the heart of this skill — it applies to every visual design.**
+
+This is the lens. Every finding in a craft audit is, ultimately, an observation about whether the design feels considered or careless. This file holds the felt qualities — what high craft looks like, what low craft looks like, and the decisions that separate them.
+
+## Why this matters
+
+Craft is what users notice without naming. They don't say "the kerning is tight" or "the hierarchy is calibrated" — they say "this feels nice," or, more often, they don't say anything because it just works. Bad craft, by contrast, is felt as friction: a screen that's too busy, an empty state that looks unfinished, three things shouting for attention at once, an animation a beat too long. Craft compounds. Each small decision ladders into the felt quality of the whole.
+
+A design with high craft has visible authorship. Someone made consistent decisions and defended them. A design with low craft has visible compromise — many people contributed under pressure, no one took responsibility for the whole, and the rough edges are where the conversations didn't happen.
+
+The goal of this reference is not to enforce style. It's to teach the reader to see what considered work looks like.
+
+---
+
+## The lens — what high-craft work feels like
+
+When evaluating, hold the design against these felt qualities. Each is a question the audit answers.
+
+### Breathable
+
+The design has room to breathe. White space is a structural element, not waste. The eye can rest. Nothing is shouting; nothing is crammed. There's air around primary actions; there's room between sections; the screen feels like it could be quieter without being emptier.
+
+**What weak craft looks like:** every element fights for space; sections butt up against each other; the screen feels like a checklist of things that had to be included.
+
+### Approachable
+
+A new user can guess what to do without a manual or a tour. The right path is the obvious path. The design isn't trying to teach itself — it's trying to be itself.
+
+**What weak craft looks like:** tooltips and "?"-icons and "click here to learn more" everywhere. Onboarding flows that have to explain what the buttons do. Settings panels that look like a control room.
+
+### Inviting to experiment
+
+The design rewards curiosity. Hovering reveals delight; clicking reveals possibility; empty states feel like an invitation, not a dead end. Users who try things feel encouraged to try more.
+
+**What weak craft looks like:** the design is brittle — exploration feels punishing. Errors are loud. Empty states say "no items" without telling the user how to create the first one. The product feels like it doesn't expect to be tinkered with.
+
+### Considered, not assembled
+
+The design feels like one person made consistent decisions, then defended them. The visual language is unified — type, color, motion, spacing all on the same scales. Drift between screens is rare and feels intentional when it happens.
+
+**What weak craft looks like:** the seams show. Different screens look like different products. Patterns are reinvented; controls behave inconsistently; one section is breathable and the next is dense for no clear reason. The product feels like it was built by a committee.
+
+### Quiet, not shouty
+
+No screen has eight things competing to be primary. The hierarchy is calm — the eye knows where to land first, second, third. Color is used with purpose. Bold weight, large sizes, and accent colors are reserved, not sprinkled.
+
+**What weak craft looks like:** every panel has a border, every label has a background, every button is filled. The visual volume knob is at 9 everywhere. Important things and unimportant things look the same.
+
+### Delightful
+
+There are small moments of considered detail. A transition that lands at the right speed. A micro-interaction that confirms an action without celebrating it. An empty state that has personality. A loading state that's been thought through. None of it is loud — but you notice it isn't there if it isn't.
+
+**What weak craft looks like:** every state is generic. Empty is "no data." Loading is a spinner. Error is a red banner. Nothing feels chosen.
+
+### Confident
+
+The design has a point of view. It doesn't hedge. It picks one way to do things and commits. Settings are sensible defaults, not a quorum of options. The product feels willing to make decisions on the user's behalf — and the decisions feel right.
+
+**What weak craft looks like:** every workflow has three modes. Every screen has a "switch view" toggle. Every preference is a setting. The product is asking the user to design it.
+
+---
+
+## The decisions that separate high craft from low craft
+
+Two designers solving the same brief. What does the higher-craft one do differently?
+
+- **Restraint over inclusion.** They cut features and elements until what remains feels essential. Lower-craft work tends to add — every meeting produces another button, badge, banner, or option.
+
+- **Hierarchy over enumeration.** They design what's important to be loudest, what's secondary to be quieter, and what's tertiary to almost disappear. Lower-craft work treats every element as equally important.
+
+- **One taste over many tastes.** They pick a small visual vocabulary — a few sizes, a few weights, a few tones, a few shapes — and use them consistently everywhere. Lower-craft work accumulates variations.
+
+- **Considered emptiness over filled space.** They use white space as structure, especially around primary actions. Lower-craft work fills available space because it feels productive.
+
+- **Designed states over default states.** They author every state — empty, loading, error, partial, edge — as a deliberate moment. Lower-craft work leaves states to chance: spinners, blank panels, generic messages.
+
+- **Confident defaults over configurable surfaces.** They make decisions for the user. Lower-craft work delegates decisions back to the user via settings, toggles, and modes.
+
+- **Quiet polish over loud features.** They invest in micro-interactions, transitions, hover states, and the felt smoothness of the experience. Lower-craft work invests in the demoable surface and skips the in-between.
+
+These are the moves a comparative audit names.
+
+---
+
+## How to use this reference
+
+When auditing, hold the design against the lens. For each felt quality (breathable, approachable, inviting, considered, quiet, delightful, confident), ask:
+
+- Does the design earn this adjective?
+- Where, specifically, does it earn it? (Cite a region or screen.)
+- Where, specifically, does it fall short?
+
+Findings flow from the lens, not from the rules. A rule that doesn't translate into something a user could feel doesn't belong in a craft audit.
+
+---
+
+## How findings teach
+
+Every finding must do four things, not one. The skill earns its keep by teaching, not by checklisting.
+
+1. **Problem** — what feels off, in plain language. The kind of thing a designer would say in a critique.
+
+   Example: *"The toolbar feels overworked. There are seven controls in the top row competing for attention; the eye can't tell what's primary."*
+
+2. **Why it weakens craft** — the principle being violated.
+
+   Example: *"Hierarchy is calm when the design tells the eye where to land first. When everything in a row is the same visual weight, the user has to do the work the design should have done. The design feels assembled rather than authored."*
+
+3. **What better looks like** — the improved version.
+
+   Example: *"One primary action visible at full weight. Secondary actions visually quieter — text-only buttons, no fill. Rare actions tucked into an overflow menu. The toolbar reads in three glances: primary, secondary, the rest."*
+
+4. **Fix** — the specific design move.
+
+   Example: *"Promote 'Save' to the only filled button in the toolbar. Demote 'Commit' and the rename action to text buttons. Move 'Builder Settings' and 'Salesforce Org Settings' into the existing overflow menu — they're rarely used in any single session."*
+
+A finding that lists the problem without teaching the principle is rejected. A finding that prescribes the fix without explaining the principle teaches nothing. The point is to leave the reader's eye sharper than you found it.
+
+---
+
+## Anti-patterns in craft audits
+
+The craft audit is **not** a code review. The following kinds of findings do not belong:
+
+- "Three font-family CSS variables for the same intent."
+- "Six near-duplicate light grays in `app.css`."
+- "`outline: none` without `:focus-visible` replacement on line 137."
+- "Two button base classes — `button toolbar-btn` vs `toolbar-icon-button`."
+- "Inline `setTimeout(300)` for click-vs-double-click detection."
+
+If the finding is about a token, a class, a selector, a timeout, an ARIA attribute, or anything else inside the implementation — rewrite it as a felt observation or delete it. The user doesn't see CSS. They see a design.
+
+The same observations, at the felt level:
+
+- "Font usage lacks consistency. The product reads in different voices depending on the screen."
+- "Surface colors feel scattered. The eye can't tell which grays are intentional and which are accidents."
+- "Toolbar buttons feel inconsistent — some are framed, some aren't, the row reads as assembled."
+- With `DYNAMIC_VISUAL` evidence only: "The agent name's directly exercised rename gesture has no visible cue before activation, so the interaction feels hidden."
+
+The first list is what a CSS lint would say. The second is what an interior decorator would say.
+
+Do not convert source-code clues into felt claims. Focus visibility, keyboard operation, and hidden gestures require direct evidence; route accessibility compliance to `experience-accessibility-validate`.
+
+---
+
+## Scoring Guide
+
+**Contributes to dimensions: Well-Crafted, Coherent**
+
+| Score | Criteria |
+|-------|----------|
+| 9–10 | The design feels authored. Restraint is visible — small visual vocabulary, generous space, calm hierarchy. Every state is designed. Motion is purposeful. The eye lands where it should; the user knows what to do without instruction. The product feels confident and quiet. Delight is present in small, considered ways. |
+| 7–8 | High-craft work with minor opportunities. The lens mostly holds. A few screens drift; one or two states feel templated; the visual vocabulary is mostly disciplined but shows some accumulation. The design feels considered overall. |
+| 5–6 | Functional but uneven. The design earns some craft adjectives — usually breathable or approachable — but not others. Hierarchy works on the main screens; secondary screens feel rushed. Empty states are generic. The seams show on close inspection. |
+| 3–4 | Visibly rough. The design feels assembled. Multiple felt qualities fail — the screen is too busy, the hierarchy is flat, the empty states are blank, the visual vocabulary is fragmented. The user can use the product but doesn't enjoy it. |
+| 1–2 | No craft. The design feels abandoned. Browser defaults; missing states; visual chaos; no point of view. Using it feels like work. |

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

@@ -0,0 +1,59 @@
+# Data & Analytics
+
+> **Skip this reference if the design has no charts, dashboards, metrics, filters, search, tables, or lists — nothing that turns numbers into something you can feel.**
+
+Data is where craft is most often abandoned and most rewarded when it isn't. A chart that's titled with the question it answers, colored with one accent and a chorus of grays, sorted purposefully, and stripped of non-data ink — that chart respects the reader. A dashboard that opens with the most important metric in the top-left and surfaces anomalies first feels like it was designed by someone who had to use it. The craft is in restraint: fewer colors, fewer gridlines, no rainbow scales, no truncated axes, no decorative donut centers.
+
+## Why this matters
+
+A well-crafted data view tells you something in five seconds. A poorly crafted one shows you a screenful of numbers and trusts you to figure out what matters. The difference is rarely about the data itself — it's about composition, hierarchy, color discipline, number formatting, and the dozens of small decisions that determine whether a chart feels like an artifact of clear thinking or a default chart-library output. When data is presented with craft, the product feels analytical and trustworthy. When it isn't, even accurate numbers feel suspect, and the reader has to do the work the designer should have done.
+
+---
+
+## Charts
+
+- **Each chart answers one question.** The title tells the reader what they're about to learn. A chart with a generic label like "Sales" has wasted its opening line.
+- **The chart type fits the data.** Bars compare categories, lines show trends over time, pies show parts of a whole — and only when there are few enough slices to read at a glance. A bar chart for time-series, a pie chart with a dozen slices, or a scatter plot used for ranking all read as defaults. Tables outperform charts when the user needs exact values.
+- **Restraint carries the visual weight.** Gridlines fade to the lightest element. 3D effects are gone. Bars are sorted with intent. The Y-axis on bar charts starts at zero — truncated axes read as misleading.
+- **Annotations highlight the takeaway.** A callout, a highlighted point, a trend indicator — the chart doesn't make the reader hunt for the message. Projected and historical data look different.
+
+## Color in Charts
+
+- **Color discipline carries the message.** Sequential data uses a single hue light to dark; diverging data meets at a meaningful midpoint. Categorical palettes stay small. Beyond a handful of distinct hues, the eye gives up.
+- **The accent color marks what matters.** The most important series wears the brand color; everything else recedes to gray. Emphasis comes from muting context, not brightening every line.
+- **Semantic color is consistent across the product.** Green always means good. Red always means bad. Reversing that mapping in one chart undoes instinct everywhere.
+
+## Metrics
+
+- **Every metric carries context.** A number alone says less than a number with a comparison, a target, or a trend. A metric without context is decoration.
+- **Number formatting is uniform.** Same separators, same decimal precision, same units across the same view. Two formats for the same metric type undoes the calm of a dashboard. Zero is not null — "—" or "No data" tells the user nothing was measured.
+
+## Dashboards
+
+- **The dashboard answers articulable questions.** If the team can't say what questions it's for, it's a data gallery. Hierarchy walks the eye top-left to bottom-right; anomalies surface first; widgets sit on a grid.
+- **The time range is global and visible.** A single control governs the dashboard. Comparison mode pairs current and prior data clearly. Drill-down is invited from each summary.
+
+## Filters and Search
+
+- **Filters apply immediately for cheap operations; expensive ones get an Apply button.** Active filters are unmistakably visible — chips above the content, clear individually and in total. Empty results explain themselves and offer a way to broaden.
+- **Search scope is communicated.** Matching text is highlighted in results. Clearing search preserves filters; clearing filters preserves search.
+
+## Tables and Lists
+
+- **Format reflects how users use the data.** Compare, scan, act, or distribute — each pattern wants a different shape. The most important column reads first. Default sort matches the user's most common need.
+- **Bulk actions float, never push.** Calculations live in a footer when they matter. View switching preserves filters and selection. Auto-refresh doesn't shove the user around.
+- **Raw database fields and ISO timestamps never reach the user.** A field labeled `created_at_utc` or a timestamp like `2024-03-14T17:32:01.000Z` reads as a leaked implementation detail.
+
+---
+
+## Scoring Guide
+
+**Contributes to dimensions: Useful, Coherent**
+
+| Score | Criteria |
+|-------|----------|
+| 9-10 | Data presentations form a coherent system. Charts answer specific questions. Metrics carry context. Dashboards lead with anomalies. Filters and search are predictable. |
+| 7-8 | Most data has context and consistent formatting. Minor gaps in chart-color discipline or filter behavior. |
+| 5-6 | Mixed number formats, metrics without comparison, charts with truncated axes, filter state lost on navigation. |
+| 3-4 | Misleading visualizations. Inconsistent semantic color. Numbers without units. Tables show raw fields. |
+| 1-2 | No coherent data presentation. Charts mislead. Metrics carry no meaning. |

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. |