@salesforce/afv-skills 1.54.0 → 1.56.0

package/skills/experience-accessibility-validate/references/reviewers/sc-4-1-2-i-name.md

@@ -73,16 +73,13 @@ Following are some preferred sufficient techniques that can help satisfy name-on
 - Keep issues concise, avoid duplicated issues or unnecessary or non-applicable problems.
 - Assume that any imported functionality works as expected and was already analyzed.
 - Components do not supplement or provide global functionalities.
-- Lightning base components (`lightning-input`, `lightning-combobox`, `lightning-textarea`, `lightning-icon`, etc.) provide their own accessible labeling, ARIA, and error handling in shadow DOM via their dedicated attributes (`label`, `alternative-text`, field-level validation). When such a component is given a `label` attribute it is already programmatically labeled — even with `variant="label-hidden"`, which hides the label visually but keeps it for assistive technology. Do **not** flag a sibling/wrapper `<label>` or `<span>` for a missing `for`/`id` when the actual control is a self-labeling Lightning component, and do not treat a visible heading as if it were the control's only label. This also covers navigation and icon base components (`lightning-vertical-navigation-item`, `lightning-vertical-navigation-item-icon`, `lightning-button-icon`, etc.): when a `label` (or `alternative-text`) attribute is supplied, the base component renders it as the visible link/control text **and** exposes it as the accessible name, and any `icon-name` is decorative — do not emit a 4.1.2 "verify the label is associated with the icon" warning, even a hedged one. The presence of the `label` attribute is the association.
-- Resolve template bindings before judging them. A template expression like `{someValue}` refers to a property or getter on the component's controller (`.js`/`.ts`) — including `@api` properties and `get someValue()` getters — not to a module-level imported constant (which LWC templates cannot bind to). Check the controller for the binding's definition before concluding a value is undefined, empty, or missing. When reviewing a diff, verify which side is the corrected code; do not assume the change introduced the problem.
-- Prefer a real `<button>` for actions; for a link, `href="#"` with `event.preventDefault()` (the canonical SLDS pattern). Don't recommend `href="javascript:void(0)"` as a first-line remediation — it's a no-op-anchor anti-pattern. It is acceptable only as a last resort when moving `<a>` → `<button>` is genuinely impossible, and even then only when paired with the full set of attributes that make the anchor behave as an accessible button (`role="button"`, keyboard activation, etc.) — `void(0)` on its own is an incomplete fix. Don't flag existing `javascript:void(0)` as a violation.
-- ARIA attribute spelling depends on the element type. On a **plain HTML element** (`div`, `span`, `button`, `input`, `a`, `img`, `iframe`, …) the only valid spelling is the W3C form `aria-labelledby` / `aria-describedby`; the hyphen-split `aria-labelled-by` / `aria-described-by` there **is** a real bug — keep flagging it. But on an **LWC component tag** (`lightning-*` or a custom `ns-name` element), the hyphen-split form is the kebab-case binding of the component's `@api ariaLabelledBy` / `ariaDescribedBy` property (each capital letter maps to `-` + lowercase), and LWC reflects it to the spec-correct `aria-labelledby` in the rendered DOM. Do **not** flag `aria-labelled-by` on a component tag as a misspelling, and do not claim it "breaks the accessible name computation" — you cannot determine that from the attribute name alone, because both `aria-labelled-by` (via `@api` property kebab-casing) and `aria-labelledby` (via LWC's ARIA reflection) can wire to the same property depending on the component. Treat a hyphen-split ARIA attribute on a component tag as a valid binding, not a violation.
 
 **ABSOLUTE AND STRICT EXCLUSION RULES FOR SC 4.1.2 'NAME' ANALYSIS (AND WHEN NOT TO FLAG):**
 
 - **PRIMARY RULE:** A user interface component **PASSES** the 'Name' criterion if it has _any_ programmatically determinable accessible name, whether visible or invisible, provided through valid HTML or ARIA.
+- **DETERMINE HOW THE ACCESSIBLE NAME IS SUPPLIED IN THE PROVIDED MARKUP BEFORE CONCLUDING A NAME IS MISSING.** Before flagging an element for a missing name, determine its role and applicable accessible-name sources. Check for text content only when the role or host-language semantics support naming from content; otherwise look for a native labeling mechanism, `aria-label`, `aria-labelledby`, or a valid `<label>` association. Proximity alone is not a naming relationship: an adjacent `<label>`, heading, or text node names a control only when the markup explicitly associates them. A named `<fieldset>`, `<section>`, `role="group"`, or `role="radiogroup"` provides group context but does **not** supply an accessible name to each descendant control; every descendant input, button, or other control still needs its own valid name. Evaluate the group container separately: a `<legend>` names its containing `<fieldset>`, while `aria-label` or `aria-labelledby` names the group element on which it appears. Also do not flag an icon or `<svg>` marked `aria-hidden="true"` or `role="presentation"` for a missing name: it is intentionally removed from the accessibility tree, while the interactive parent must provide its own name.
 - **DO NOT FLAG:** If an element already has a programmatically determinable name via:
-  - Its text content (e.g., button text, heading text, link text).
+  - Its text content when its role or host-language semantics support naming from content (e.g., button text, heading text, link text).
   - An associated `<label>` element.
   - An `aria-label` attribute.
   - An `aria-labelledby` attribute (and the referenced ID exists within the provided code).
@@ -103,3 +100,5 @@ Following are some preferred sufficient techniques that can help satisfy name-on
     - **For `spinbutton` and similar roles (e.g., `slider`, `progressbar`)**: Ensure `aria-valuemin`, `aria-valuemax`, and `aria-valuenow` use **numeric** values. Flag as an error if non-numeric values are used.
 - **Focus strictly on identifying where a user interface component's _accessible name_ cannot be programmatically determined, or where an explicit ARIA naming attribute (if used) is invalid or misleading (e.g., empty `aria-label`, `aria-labelledby` referencing non-existent ID).**
   - **DO NOT flag Salesforce Lightning Base Components (e.g., `lightning-card`, `lightning-record-edit-form`, `lightning-input-field`, `lightning-button`). Assume these components **automatically pass** the 'Name' criterion because Salesforce ensures their accessible names are handled implicitly and correctly.** Only flag if a custom override _explicitly breaks_ their inherent name determination, which is highly unlikely in standard usage.
+- **ARIA SPELLING IS ELEMENT-SPECIFIC:** Plain HTML elements use `aria-labelledby` and `aria-describedby`; the hyphen-split `aria-labelled-by` or `aria-described-by` spelling is invalid there. On an LWC component tag, however, the hyphen-split spelling can be the kebab-case binding for an `@api ariaLabelledBy` or `ariaDescribedBy` property. Do not conclude that the component lacks a name from the spelling alone.
+- **ASSOCIATE THE ACTUAL CONTROL:** An accessible name attached to a non-focusable wrapper around a composite editor does not name the editor's internal control unless the wrapper forwards it. Recommend extending the control to accept or forward the naming relationship, or using its supported labeling prop.

package/skills/experience-accessibility-validate/references/reviewers/sc-4-1-2-ii-role.md

@@ -93,7 +93,4 @@ Rules to follow:
 - Keep issues concise, avoid duplicated issues or unnecessary or non-applicable problems.
 - Assume that any imported functionality works as expected and was already analyzed.
 - Components do not supplement or provide global functionalities.
-- Lightning base components (`lightning-input`, `lightning-combobox`, `lightning-textarea`, `lightning-icon`, etc.) provide their own accessible labeling, ARIA, and error handling in shadow DOM via their dedicated attributes (`label`, `alternative-text`, field-level validation). When such a component is given a `label` attribute it is already programmatically labeled — even with `variant="label-hidden"`, which hides the label visually but keeps it for assistive technology. Do **not** flag a sibling/wrapper `<label>` or `<span>` for a missing `for`/`id` when the actual control is a self-labeling Lightning component, and do not treat a visible heading as if it were the control's only label. This also covers navigation and icon base components (`lightning-vertical-navigation-item`, `lightning-vertical-navigation-item-icon`, `lightning-button-icon`, etc.): when a `label` (or `alternative-text`) attribute is supplied, the base component renders it as the visible link/control text **and** exposes it as the accessible name, and any `icon-name` is decorative — do not emit a 4.1.2 "verify the label is associated with the icon" warning, even a hedged one. The presence of the `label` attribute is the association.
-- Resolve template bindings before judging them. A template expression like `{someValue}` refers to a property or getter on the component's controller (`.js`/`.ts`) — including `@api` properties and `get someValue()` getters — not to a module-level imported constant (which LWC templates cannot bind to). Check the controller for the binding's definition before concluding a value is undefined, empty, or missing. When reviewing a diff, verify which side is the corrected code; do not assume the change introduced the problem.
-- Prefer a real `<button>` for actions; for a link, `href="#"` with `event.preventDefault()` (the canonical SLDS pattern). Don't recommend `href="javascript:void(0)"` as a first-line remediation — it's a no-op-anchor anti-pattern. It is acceptable only as a last resort when moving `<a>` → `<button>` is genuinely impossible, and even then only when paired with the full set of attributes that make the anchor behave as an accessible button (`role="button"`, keyboard activation, etc.) — `void(0)` on its own is an incomplete fix. Don't flag existing `javascript:void(0)` as a violation.
-- ARIA attribute spelling depends on the element type. On a **plain HTML element** (`div`, `span`, `button`, `input`, `a`, `img`, `iframe`, …) the only valid spelling is the W3C form `aria-labelledby` / `aria-describedby`; the hyphen-split `aria-labelled-by` / `aria-described-by` there **is** a real bug — keep flagging it. But on an **LWC component tag** (`lightning-*` or a custom `ns-name` element), the hyphen-split form is the kebab-case binding of the component's `@api ariaLabelledBy` / `ariaDescribedBy` property (each capital letter maps to `-` + lowercase), and LWC reflects it to the spec-correct `aria-labelledby` in the rendered DOM. Do **not** flag `aria-labelled-by` on a component tag as a misspelling, and do not claim it "breaks the accessible name computation" — you cannot determine that from the attribute name alone, because both `aria-labelled-by` (via `@api` property kebab-casing) and `aria-labelledby` (via LWC's ARIA reflection) can wire to the same property depending on the component. Treat a hyphen-split ARIA attribute on a component tag as a valid binding, not a violation.
+- Prefer a real `<button>` for actions. Do not recommend `href="javascript:void(0)"` as a role fix: that value alone does not give an anchor button semantics. If converting the anchor is impossible, any anchor-based remediation must provide the complete role and keyboard behavior needed for an accessible button. Do not flag an existing `javascript:void(0)` value by itself as a role violation.

package/skills/experience-accessibility-validate/references/reviewers/sc-4-1-2-iii-value.md

@@ -91,7 +91,3 @@ _Rules to follow_:
 - Keep issues concise, avoid duplicated issues or unnecessary or non-applicable problems.
 - Assume that any imported functionality works as expected and was already analyzed.
 - Components do not supplement or provide global functionalities.
-- Lightning base components (`lightning-input`, `lightning-combobox`, `lightning-textarea`, `lightning-icon`, etc.) provide their own accessible labeling, ARIA, and error handling in shadow DOM via their dedicated attributes (`label`, `alternative-text`, field-level validation). When such a component is given a `label` attribute it is already programmatically labeled — even with `variant="label-hidden"`, which hides the label visually but keeps it for assistive technology. Do **not** flag a sibling/wrapper `<label>` or `<span>` for a missing `for`/`id` when the actual control is a self-labeling Lightning component, and do not treat a visible heading as if it were the control's only label. This also covers navigation and icon base components (`lightning-vertical-navigation-item`, `lightning-vertical-navigation-item-icon`, `lightning-button-icon`, etc.): when a `label` (or `alternative-text`) attribute is supplied, the base component renders it as the visible link/control text **and** exposes it as the accessible name, and any `icon-name` is decorative — do not emit a 4.1.2 "verify the label is associated with the icon" warning, even a hedged one. The presence of the `label` attribute is the association.
-- Resolve template bindings before judging them. A template expression like `{someValue}` refers to a property or getter on the component's controller (`.js`/`.ts`) — including `@api` properties and `get someValue()` getters — not to a module-level imported constant (which LWC templates cannot bind to). Check the controller for the binding's definition before concluding a value is undefined, empty, or missing. When reviewing a diff, verify which side is the corrected code; do not assume the change introduced the problem.
-- Prefer a real `<button>` for actions; for a link, `href="#"` with `event.preventDefault()` (the canonical SLDS pattern). Don't recommend `href="javascript:void(0)"` as a first-line remediation — it's a no-op-anchor anti-pattern. It is acceptable only as a last resort when moving `<a>` → `<button>` is genuinely impossible, and even then only when paired with the full set of attributes that make the anchor behave as an accessible button (`role="button"`, keyboard activation, etc.) — `void(0)` on its own is an incomplete fix. Don't flag existing `javascript:void(0)` as a violation.
-- ARIA attribute spelling depends on the element type. On a **plain HTML element** (`div`, `span`, `button`, `input`, `a`, `img`, `iframe`, …) the only valid spelling is the W3C form `aria-labelledby` / `aria-describedby`; the hyphen-split `aria-labelled-by` / `aria-described-by` there **is** a real bug — keep flagging it. But on an **LWC component tag** (`lightning-*` or a custom `ns-name` element), the hyphen-split form is the kebab-case binding of the component's `@api ariaLabelledBy` / `ariaDescribedBy` property (each capital letter maps to `-` + lowercase), and LWC reflects it to the spec-correct `aria-labelledby` in the rendered DOM. Do **not** flag `aria-labelled-by` on a component tag as a misspelling, and do not claim it "breaks the accessible name computation" — you cannot determine that from the attribute name alone, because both `aria-labelled-by` (via `@api` property kebab-casing) and `aria-labelledby` (via LWC's ARIA reflection) can wire to the same property depending on the component. Treat a hyphen-split ARIA attribute on a component tag as a valid binding, not a violation.

package/skills/experience-design-validate/SKILL.md

@@ -0,0 +1,163 @@
+---
+name: experience-design-validate
+description: "Use this skill to run a visual-craft audit of a rendered UI and produce an evidence-grounded Craft Report across Useful, Usable, Reliable, Coherent, and Well-Crafted. Invoke it for craft audits, visual critiques, design comparisons, felt-quality reviews, or visual-craft readiness checks on screenshots (.png, .jpg, .jpeg, .webp, .gif), Figma frames, rendered prototypes, and live URLs. Do not use it for source-code review, SLDS compliance (use design-systems-slds-validate), or accessibility compliance (use experience-accessibility-validate)."
+metadata:
+  version: "1.0"
+  domains: ["Experience"]
+  relatedSkills:
+    - "design-systems-slds-validate"
+    - "experience-accessibility-validate"
+    - "experience-lwc-generate"
+    - "experience-lwc-security-validate"
+---
+
+# Experience Design Validate
+
+Evaluate the visual craft of rendered software: what the eye sees and the felt quality those visible decisions create. Judge relationships, hierarchy, restraint, consistency, and care rather than CSS, tokens, or implementation technique.
+
+This is a **visual-craft-only** audit. It does not establish WCAG conformance, keyboard or screen-reader support, behavioral usability, implementation quality, or production release readiness. Route accessibility compliance to `experience-accessibility-validate` and SLDS compliance to `design-systems-slds-validate`.
+
+## Use and boundaries
+
+Use this skill to:
+
+- Critique visual craft at a design checkpoint.
+- Explain why a rendered design feels considered, cramped, calm, fragmented, or delightful.
+- Compare the craft of two or more designs solving the same brief.
+- Identify design moves that would lift a visible experience from good to great.
+
+Do not use this skill for:
+
+- Implementation or code review. For LWC generation or security review, use `experience-lwc-generate` or `experience-lwc-security-validate` as appropriate.
+- Accessibility compliance, including WCAG, screen-reader, keyboard, or focus-order validation. Use `experience-accessibility-validate`.
+- SLDS design-token compliance. Use `design-systems-slds-validate`.
+- Claims about real-user behavior. Recommend a usability study when impact depends on behavior rather than visible evidence.
+
+## Visual evidence contract
+
+Rendered pixels are mandatory. Prefer screenshots because they preserve the exact evidence reviewed.
+
+1. **Screenshots:** use supplied full-page or region captures directly.
+2. **Live URL:** if browser capability is available, open the URL, exercise only the relevant paths, capture screenshots, and retain the URL and viewport as evidence. Otherwise ask for screenshots.
+3. **Figma:** if Figma capability is available, fetch or export the named rendered frames. Treat a frame as static unless prototype behavior is actually exercised. Otherwise ask for frame exports or screenshots.
+4. **Screen recording or interactive prototype:** inspect observable transitions and capture representative frames when tooling supports it.
+5. **Source code, design descriptions, or inaccessible links:** do not infer the rendered result. Render with available capability; otherwise request screenshots.
+
+If no rendered pixels are available:
+
+- **Interactive run:** ask the user for screenshots or another rendered artifact and pause the audit.
+- **Non-interactive run:** return status `INSUFFICIENT_VISUAL_EVIDENCE` with a short statement of the missing artifact. Do not score, assign a verdict, create findings, or imply readiness.
+
+### Evidence modes
+
+Declare one mode before analysis:
+
+| Mode | What it can support | What it cannot support |
+|---|---|---|
+| `STATIC_VISUAL` | Visible hierarchy, spacing, typography, color, density, composition, consistency, and the visible treatment of the captured moment | Interaction behavior, transitions between states, responsive adaptation beyond captured viewports, latency, runtime performance, or unseen states |
+| `MULTI_VIEW_STATIC` | Static visual evidence across supplied screens, states, or viewport captures, including cross-screen coherence | The behavior connecting captures, timing, input response, runtime performance, or states not shown |
+| `DYNAMIC_VISUAL` | Static qualities plus behavior directly exercised or recorded: interaction feedback, transitions, state changes, and perceived performance | Unexercised paths, unrecorded states, accessibility compliance, or measured performance beyond what was observed |
+
+A static screenshot of a loading, error, or empty state supports critique of that state's **visible treatment only**. It does not substantiate state coverage, transition behavior, or performance. Never lower a score because an unobserved state or behavior was not supplied; mark that coverage `INSUFFICIENT_EVIDENCE` instead.
+
+## Five dimensions
+
+| Dimension | Felt question |
+|---|---|
+| **Useful** | Does the visible content earn the space and attention it occupies? |
+| **Usable** | Does the visible hierarchy and affordance make the intended path feel obvious? |
+| **Reliable** | Do the observed states and feedback make the experience feel predictable? |
+| **Coherent** | Does the visible experience feel made by one team with one taste? |
+| **Well-Crafted** | Does the visible design feel precise, considered, and delightful? |
+
+Use a 1-10 score only when the available evidence adequately covers a dimension. Use `INSUFFICIENT_EVIDENCE` when an applicable dimension cannot be supported. Use `N/A` only when the dimension or topic genuinely does not apply, never merely because evidence is missing.
+
+Read `references/scoring-rubric.md` for scoring anchors, verdict rules, severity definitions, and the complete report contract.
+
+## Craft lens
+
+Ask whether the rendered experience feels:
+
+- **Breathable:** space structures the composition and gives the eye room.
+- **Approachable:** the intended path is visually obvious without explanation.
+- **Inviting:** visible states encourage exploration rather than present dead ends.
+- **Considered:** repeated decisions form a system rather than an accumulation.
+- **Quiet:** hierarchy is calm; few elements compete to be primary.
+- **Delightful:** detail and personality are purposeful, not ornamental noise.
+- **Confident:** the design has a point of view and avoids unnecessary hedging.
+
+## Audit workflow
+
+Follow this order:
+
+1. Establish the evidence mode and inventory every supplied or captured artifact.
+2. If no rendered pixels exist, follow the insufficient-visual-evidence behavior and stop.
+3. Look before consulting rules. Record up to three honest first impressions for each design.
+4. Build the coverage and relevance ledger. For every dimension and reference topic, record `SCORED`, `N/A`, or `INSUFFICIENT_EVIDENCE`, the evidence mode, and a concise reason.
+5. Load `references/craft.md`, `references/scoring-rubric.md`, and `references/visual-system.md`. Load only conditional references whose topic is both relevant and observable in the evidence mode.
+6. Score only supported dimensions. Select the **highest anchor whose applicable, observable criteria are fully supported**; use an odd score only when evidence clearly exceeds that anchor without fully supporting the next.
+7. Write findings. Cap findings at five per dimension and deduplicate cross-dimensional root causes.
+8. Write the Craft Report, including the ledger and evidence limitations.
+
+## Progressive disclosure
+
+Always load:
+
+- `references/scoring-rubric.md`: scoring, coverage, severity, verdict, and report schema.
+- `references/craft.md`: felt qualities of considered work.
+- `references/visual-system.md`: visible layout, typography, color, and surfaces.
+
+Load only when relevant **and observable**:
+
+| Reference | Evidence needed |
+|---|---|
+| `references/components.md` | Visible buttons, inputs, modals, lists, tables, or feedback components |
+| `references/navigation.md` | Visible navigation, tabs, breadcrumbs, search, or wayfinding |
+| `references/responsive.md` | Captures from multiple viewports or directly exercised resizing |
+| `references/forms-flows.md` | Multiple visible steps or directly exercised form behavior |
+| `references/data.md` | Visible charts, dashboards, metrics, filters, results, or tables |
+| `references/records.md` | Visible records, detail pages, status, metadata, or collaboration |
+| `references/ai.md` | Visible AI, agent, chat, citations, or model output |
+| `references/trust.md` | Visible auth, privacy, consent, permissions, or destructive settings |
+| `references/usability.md` | Visible task structure; do not infer behavioral usability |
+| `references/interaction.md` | `DYNAMIC_VISUAL` evidence of interaction or motion |
+| `references/state.md` | `DYNAMIC_VISUAL` state transitions; static state captures support appearance only |
+| `references/performance.md` | `DYNAMIC_VISUAL` evidence of timing, latency, or layout stability |
+
+## Finding voice
+
+Speak at the felt level and anchor claims to visible evidence.
+
+Good: "The toolbar feels overworked; too many controls compete for attention, so the eye cannot find the primary action."
+
+Wrong scope: "Three button classes use inconsistent spacing tokens." That belongs in implementation or SLDS review.
+
+Each finding must include `severity`, `primary_dimension`, optional `related_dimensions`, `location`, `problem`, `why_it_weakens_craft`, `what_better_looks_like`, and `fix`. When one problem appears in three or more places, create one finding with a count and representative location.
+
+## Comparative audits
+
+Audit each design independently with the same evidence requirements and rubric. The report must include:
+
+- Per-design evidence mode, coverage ledger, first impressions, dimension scores, evidence, and gap to the next supported level.
+- A side-by-side comparison table that preserves `N/A` and `INSUFFICIENT_EVIDENCE` rather than forcing numeric comparisons.
+- A result of `A_HIGHER_CRAFT`, `B_HIGHER_CRAFT`, `TIE`, or `MIXED`. Use `MIXED` when leadership varies by dimension or evidence coverage prevents an overall ranking.
+- Differentiating dimensions, concrete craft moves each design makes better, and improvements each could borrow without copying.
+
+Do not crown a winner when the evidence supports a tie or mixed outcome.
+
+## Output
+
+If the user explicitly supplies an output path, write there exactly; that path overrides the naming convention. Otherwise use `YYYY-MM-DD-<target-slug>-craft-audit-<VERDICT>.md`, with uppercase `PASS`, `WARN`, `FAIL`, or `LIMITED`.
+
+The report must make its scope explicit: verdicts and readiness implications cover **visual craft only**, not accessibility, functional correctness, measured performance, or production release approval.
+
+Recommendations and cross-cutting patterns each contain **zero to five** items. Include only evidence-backed, useful entries; never add filler to reach a quota. End with the fix prompt defined in `references/scoring-rubric.md` only when at least one actionable recommendation exists.
+
+## Core principles
+
+1. **Pixels first.** No rendered evidence means no visual-craft audit.
+2. **Eye first, rules second.** Record first impressions before rubric analysis.
+3. **Evidence bounds claims.** Unobserved behavior is unknown, not defective.
+4. **Felt level, not implementation level.** Describe visual experience, not code.
+5. **Teach while auditing.** Explain why each finding matters and what better feels like.
+6. **Severity over volume.** A few sharp findings beat a padded checklist.

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

@@ -0,0 +1,54 @@
+# AI & Agent UX
+
+> **Skip this reference if the design shows no AI, LLM, agent, chat, citation, or model-output surfaces.**
+
+Craft in AI surfaces is the difference between a model that feels considered and one that feels duct-taped. It lives in the visual rhythm of a multi-step progress timeline, the restraint of a "thinking" indicator that respects screen real estate, the elegance of an inline citation marker, and the quiet confidence of reasoning that sits subordinate to the answer. This reference judges the visual and behavioral craft of agent progress, disclosure, reasoning, confidence, citations, and review surfaces.
+
+## Why this matters
+
+AI features are where craft becomes load-bearing — users decide in seconds whether to trust output, and that decision rests almost entirely on visual signals. When craft is high, the interface feels like it understands its own limits: progress is shown with precision, citations sit close to the claim they support, confidence is conveyed without drama, and reasoning collapses politely until invited. When craft is low, AI surfaces feel either showy (every token streaming, walls of "thinking", verbose tool logs) or evasive (no provenance, no progress, no way out). The visual treatment of AI is where the product proves it has thought about how the model fits into a human's workflow.
+
+---
+
+## Agent Progress
+
+- **The work is visible as a timeline.** Each step has a status the user can read at a glance — pending, active, complete. A vague "thinking..." for thirty seconds reads as the product hiding from itself. Tool use is named, not narrated; verbose logs read as developer output left in production.
+- **Stop is always available, and the input area stays alive.** The user can interrupt and clarify mid-flight. On completion, progress collapses politely — a summary remains, the scaffolding recedes. Failure preserves what was done.
+
+## Disclosure
+
+- **AI is unmistakable in conversation.** A distinct avatar or label tells the user when they're talking to a model rather than a person. Ambiguity here is a small ethical breach.
+- **AI-generated content carries a persistent signal until reviewed.** Handoffs between AI and human agents are clear. An escape to a human is always reachable.
+
+## Reasoning
+
+- **Reasoning is subordinate to the answer.** The result leads; the explanation sits quietly below or behind a click. A wall of reasoning above the answer reads as showing off. Default is short; depth is on demand.
+- **Tool invocations are collapsible.** What was called and what came back, summarized; full output one click away. Raw model internals stay out of production.
+
+## Confidence
+
+- **Confidence is communicated without drama.** A simple visual register beats a percentage. Numeric confidence reads as false precision to most users. The source of uncertainty is named when possible. High-stakes outputs prompt review.
+
+## Citations
+
+- **Claims and their sources sit close together.** A citation marker right after the claim, not collected at the bottom. Markers are subtle but reachable. Sources are specific — page, section, timestamp — not just a document name.
+- **Quoted text and AI interpretation look different.** Source quality is visible — recency, authority, primary versus user-generated. Conflicts between sources are surfaced rather than hidden. Cited links go directly to the source.
+
+## Human Review
+
+- **High-stakes AI output goes through a human gate.** Irreversible or third-party-affecting actions pause for explicit approval. The review queue presents proposed action, context, confidence, reasoning, and approve/reject/edit in one view.
+- **Override is easy and unjudged.** No dark pattern friction punishes the human for disagreeing with the model. Batch approval exists but never defaults to "approve all."
+
+---
+
+## Scoring Guide
+
+**Contributes to dimensions: Useful, Reliable, Coherent**
+
+| Score | Criteria |
+|-------|----------|
+| 9-10 | The AI surface understands its own limits. Progress reads at a glance, citations sit near their claims, confidence is communicated without drama, and review gates handle the high-stakes work. |
+| 7-8 | AI disclosure is present. Confidence and citations are mostly consistent. |
+| 5-6 | Vague "thinking" indicators. Citations missing or batched. Confidence over-hedged or unstated. |
+| 3-4 | The AI is a black box. No disclosure. Citations absent or misleading. |
+| 1-2 | No disclosure. No guardrails. Outputs presented as fact without sources. |

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