@salesforce/afv-skills 1.53.0 → 1.55.0

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

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

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

@@ -0,0 +1,53 @@
+# State Management UX
+
+> **Load this reference for `DYNAMIC_VISUAL` evidence of state transitions. Static captures may support critique of a depicted state's visible treatment, but cannot substantiate state coverage, transition behavior, save behavior, recovery, or timing; mark those areas `INSUFFICIENT_EVIDENCE`.**
+
+The craft of state is the craft of in-between moments — the loading shimmer, the empty canvas, the recovered failure. A well-crafted product feels considered in these moments: the skeleton matches the layout, the spinner is sized for its container, the empty state has been designed rather than left as blank space, the error feels like part of the product instead of something escaping from the database.
+
+## Why this matters
+
+Most products are judged on their happy path, but craft reveals itself in the transitions and edge cases. A loading state that shimmers in the exact shape of what's coming feels like a designed product; a generic full-page spinner feels like an unfinished one. An empty state with a thoughtful illustration and a clear next action feels like a host welcoming you in; a blank screen feels like a dead end. When a design is polished in these moments, the product feels alive and tended to. When it isn't, every wait, error, and empty view chips away at trust.
+
+---
+
+## Loading
+
+- **The indicator matches the wait.** Instant feedback for micro-operations, an inline spinner for short waits, a skeleton for longer ones, real progress for anything substantial. A spinner that flashes for a fraction of a second is worse than silence.
+- **Skeletons mirror the shape of what's coming.** Same dimensions, same item count, same layout. When the real content arrives, nothing shifts.
+- **Progress is honest.** A determinate bar moves with confidence. Fake or jumpy progress trains users to distrust every indicator the product will ever show them.
+- **The page never goes blank between routes.** Navigation lights up the new destination immediately and uses a skeleton or crossfade for the body.
+
+## Errors
+
+- **Severity matches visual weight.** Inline notes for fields, banners for sections, page-level treatments for global failures. When everything is the same shade of red, nothing reads as urgent.
+- **Errors speak to the user, not the database.** A message names what went wrong and how to recover — never a stack trace, never an opaque code.
+- **Errors don't delete the user's work.** Submission failure preserves every valid field, scrolls to the first problem, and shows how many remain. Reversible mistakes get undo, not pre-confirmation.
+
+## Empty
+
+- **Empty is designed, not abandoned.** A short, situational headline; a sentence of context; a way forward. Blank space is a defect.
+- **The flavor of empty is communicated.** "Nothing yet" reads differently from "no matches" reads differently from "you don't have access." Empty tables keep their headers.
+
+## Offline and Sync
+
+- **Offline is a state, not an error.** It's communicated calmly — visible but not alarming, self-removing the moment connectivity returns. Local interactions still feel alive; pending changes are visible. No silent data loss, ever.
+- **Sync is invisible when it works.** Indicators only appear during active syncing, pending changes, or conflicts. Conflicts surface immediately with both values visible. Stale presence is worse than no presence.
+
+## Optimism and Long Jobs
+
+- **Optimism is reserved for the safe.** Reversible, rarely-failing changes show instantly. Destructive or financial changes don't. Rollback explains itself rather than reverting silently.
+- **Long work doesn't trap the user.** Operations beyond a handful of seconds become jobs the user can navigate away from. Progress, time, and current activity are visible. Completion finds the user wherever they went. Cancellation is always honest about what happens to partial results.
+
+---
+
+## Scoring Guide
+
+**Contributes to dimensions: Reliable, Usable**
+
+| Score | Criteria |
+|-------|----------|
+| 9-10 | The in-between moments are designed. Loading, errors, empty, offline, sync, and long jobs all feel considered. The product feels tended to even when nothing is happening. |
+| 7-8 | State handling is solid for primary flows with minor gaps at edges. |
+| 5-6 | Generic errors, blank empty states, basic save behavior. The polish drops away outside the happy path. |
+| 3-4 | States unmanaged. Silent failures. Blocking spinners. The product feels brittle. |
+| 1-2 | Lost connection loses work. States show nothing. Trust is broken. |

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

@@ -0,0 +1,47 @@
+# Trust & Safety
+
+> **Skip this reference if the design shows no auth surfaces, no privacy controls, no permission UI, no destructive settings, and no risk-bearing actions.**
+
+Craft in trust surfaces is the visual proof that a product takes consequences seriously. It shows up in the placement of a verification icon, the elevation of a danger zone, the restraint of a sensitive-data mask, the calibrated visual weight of a warning versus a critical confirmation. This reference judges the visual treatment of trust signals, the staging of authentication, and the progressive elevation of risk surfaces.
+
+## Why this matters
+
+Trust is a felt quality, not a feature — and craft is what makes a user feel safe before they read any copy. When craft is high, sensitive moments feel deliberate: the lock icon sits where the eye expects it, the danger zone is visually quarantined from the rest of the settings, warnings escalate in visual weight as stakes increase, and confirmations carry the right amount of friction without theatrics. When craft is low, trust surfaces feel either gaudy (every action a red banner) or careless (a destructive button styled like a save button). The visual register of risk is something users absorb subconsciously — a misstep here is the difference between confidence and unease.
+
+---
+
+## Trust Signals
+
+- **Visual polish is itself a trust signal.** Misaligned elements, mismatched typography, and broken layouts read as carelessness with everything else — including the user's data.
+- **Verification indicators sit where the eye expects them.** A single recognizable icon, placed consistently across the product, with a quiet explanation on hover.
+- **Sensitive data is masked by default.** A visibility toggle returns it on demand. Showing a credit card number or a phone number unprompted reads as careless.
+
+## Authentication
+
+- **Login is staged, not stuffed.** Identity first, credential second. A single mega-form for everything reads as bureaucratic.
+- **Password fields are forgiving.** A show/hide toggle and live validation reduce the anxiety of typing into a black box.
+
+## Consent
+
+- **Cookie banners don't trap the user.** Dismissing without accepting is as easy as accepting. "Essential only" carries the same visual weight as "Accept all." A banner that blocks content until the user accepts reads as coercive.
+
+## Risk Communication
+
+- **Severity escalates with consequence.** Informational notes, cautionary highlights, warnings that pause the user, and critical confirmations that demand typing — each carries a distinct visual weight. When everything is the same shade of red, nothing reads as urgent.
+- **Warnings appear before the point of no return.** Not after, not during — before. A warning that arrives after the action committed is theater.
+- **The same severity treatment is never used for unequal risks.** When archiving and deleting wear the same warning, the user stops trusting the warnings.
+- **Destructive settings are visually quarantined.** A "danger zone" set apart from ordinary settings — not interleaved with everyday toggles where a misclick is one row away.
+
+---
+
+## Scoring Guide
+
+**Contributes to dimensions: Reliable, Coherent, Well-Crafted**
+
+| Score | Criteria |
+|-------|----------|
+| 9-10 | Trust is earned through every interaction. Sensitive moments feel deliberate. Risk is calibrated. The danger zone is unmistakable. |
+| 7-8 | Trust patterns are mostly consistent with minor gaps in disclosure or symmetry. |
+| 5-6 | Bundled consent. Inconsistent warning severity. A few dark patterns. |
+| 3-4 | Dark patterns. Invasive defaults. The product feels indifferent to consequence. |
+| 1-2 | Trust is actively broken. Hidden data collection. Misleading consent. |

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

@@ -0,0 +1,35 @@
+# Usability
+
+> **Skip this reference if the design has no decisions to make, no actions to take, and no flow to navigate — i.e. nothing for craft to make smoother.**
+
+Usability craft is the difference between a product that you operate and one that operates with you. It's the visible system status that tells you the save went through, the predictable interaction that lets you trust your muscle memory, the consistent pattern that makes the second use easier than the first. Good usability craft is invisible when it works — you just feel competent. Poor usability craft makes you feel stupid for not knowing where the controls are.
+
+## Why this matters
+
+Designs win or lose on the small moments of feedback and predictability. When a click produces an immediate visible response, when a state change is announced through motion or color, when consistent patterns mean the user never has to relearn — the product feels responsive and trustworthy. When those moments are missing, every interaction carries doubt: did it work, am I in the right place, is this the same control I used yesterday. Craft here is about respect — respecting the user's time, attention, and prior learning by making the system answer back when spoken to.
+
+---
+
+## Feedback and Predictability
+
+- **The system answers back when spoken to.** Every action produces a visible response — a state change, a confirmation, a transition — within the moment of the click. Silence reads as broken.
+- **Patterns repeat.** The same kind of action looks and behaves the same across the product. When a "save" feels different on two screens, the user has to relearn instead of trust their muscle memory.
+- **The user's place in the system is always visible.** Where they are, what's selected, what they just did. A page that wipes context after every interaction asks the user to rebuild it constantly.
+- **Edges are designed.** Empty states, errors, loading, and success all feel like part of the same product — not afterthoughts grafted onto the happy path.
+- **Hierarchy matches priority.** What's important looks important. When secondary actions outweigh primary ones visually, the user has to fight the design to do the right thing.
+- **Interactive elements look interactive.** A button that looks like a label, a link that looks like static text, a card that hides a click target — each forces the user to discover by trial.
+- **Simpler is preferred when both work.** Two controls where one would do, three options where two cover the cases — the extras add cognitive load without adding capability.
+
+---
+
+## Scoring Guide
+
+**Contributes to dimensions: Usable, Useful, Well-Crafted**
+
+| Score | Criteria |
+|-------|----------|
+| 9-10 | Edges are designed. Interactive elements look interactive. Hierarchy matches priority. The product responds to every input with visible craft. |
+| 7-8 | Most flows feel responsive and predictable. Minor gaps in edge-state polish. |
+| 5-6 | Happy path is fine; edges feel unfinished. Some controls don't feel interactive. |
+| 3-4 | Inconsistent feedback. Edge states neglected. Hierarchy fights the user. |
+| 1-2 | No visible system response. Interactions feel unanswered. |

package/skills/experience-design-validate/references/visual-system.md

@@ -0,0 +1,183 @@
+# Visual System
+
+> **Always load for any visual design. Skip only if the input is purely textual or pre-visual (a wireframe with no visual decisions yet made).**
+
+What does the design look like? This reference judges the felt qualities of the visual system — layout, typography, color, surfaces, and visual assets — at the level a designer would discuss them in a critique. Not at the level of CSS variables.
+
+## Why this matters
+
+The visual system is the voice of the product. It's what users see before they read a word. A coherent visual system feels like one person made it; a fragmented one feels like a committee shipped it. Two designers can have the same layout brief and end up in completely different places — one with a system that feels intentional and quiet, one with a system that feels accumulated and loud.
+
+Visual system findings are about *taste applied consistently*. The eye notices when the type sizes don't relate to each other, when the grays are slightly off from each other, when borders happen sometimes and not other times, when icons are different weights, when avatars are different sizes. None of these failures is catastrophic alone. Together, they're what separates "looks pro" from "looks built."
+
+---
+
+## Layout
+
+### What good layout feels like
+
+- **One focal point per screen.** The eye knows where to land first. Everything else is calmer.
+- **Generous whitespace around what matters.** Primary actions and headlines have air around them. Density is reserved for content where users need to compare or scan many items at once.
+- **A consistent rhythm.** The vertical beat of the page is predictable — sections are spaced consistently, and the spacing between a heading and its content is tighter than the spacing between sections.
+- **Aligned, not approximate.** Elements share precise edges, not "near enough" edges. The eye can detect 2-pixel misalignment even when it can't name it.
+- **Density matched to context.** A dev tool earns dense, utilitarian layout. A consumer onboarding screen earns generous breathability. The layout reflects what the product is trying to be.
+
+### Felt observations to make
+
+- The eye knows where to land within the first second.
+- Primary content is clearly heavier than chrome (toolbars, headers, sidebars).
+- Headings are closer to their content than to the section above.
+- Page margins are equal and don't change between similar pages.
+- Whitespace around primary actions feels deliberate, not accidental.
+- The grid feels consistent — columns don't shift between similar pages.
+- Toolbar heights, sidebar widths, and content margins feel consistent across screens.
+- Sticky headers stay put; scroll position is preserved when navigating away and back.
+
+### What weak layout looks like
+
+- The eye doesn't know where to start. Multiple things tied for primary.
+- Sections butt up against each other; nothing breathes.
+- Spacing varies subtly between similar screens — same component, different padding.
+- Elements are *almost* aligned (a few pixels off) — looks like a mistake, not a choice.
+- Page margins are uneven; one page has a wide gutter, another has none.
+- Density mismatches the context — a marketing page is dense, a dashboard is sparse.
+
+---
+
+## Typography
+
+### What good typography feels like
+
+- **A small set of sizes, used consistently.** The product has 4–6 distinct text sizes that map to clear roles: page heading, section heading, body, label, metadata. Each role has one size. The reader knows what kind of text is what at a glance.
+- **A tight set of weights.** Two or three weights. Bold for headlines, regular for body, perhaps medium for emphasis. Weight isn't sprinkled across the design.
+- **Headlines have presence.** They feel like something to land on, not something to scroll past. The line break is intentional.
+- **Body text is readable.** Lines are at a comfortable length (not edge-to-edge across a wide screen). Line-height is generous enough that reading feels relaxed.
+- **One voice across the product.** The product speaks in one type voice, not three.
+
+### Felt observations to make
+
+- Type sizes feel like steps in a scale, not arbitrary choices.
+- Headings stand out clearly. The hierarchy is unmistakable.
+- Body text feels comfortable to read at a glance.
+- The number of weights in active use feels small.
+- Numbers in tables align (don't twitch as values change).
+- Truncated text is signaled cleanly with an ellipsis, with full content available on hover or expand.
+- Text doesn't run edge-to-edge across the entire viewport on wide screens.
+
+### What weak typography looks like
+
+- The product has many sizes that don't relate to each other — 13px, 14px, 15px, 16px all visible.
+- Three or four weights mixed without clear logic.
+- Headings and body text feel similar in weight or size — flat hierarchy.
+- Body text runs the entire width of a wide screen, exhausting to read.
+- Numbers in tables shift position as values change — feels unfinished.
+- Capitalization is inconsistent: "Save Changes" here, "save changes" there, "SAVE" elsewhere.
+
+---
+
+## Color
+
+### What good color feels like
+
+- **A small, intentional palette.** The product uses few colors and uses them consistently. Each color earns its place — brand, action, error, success, neutral. Nothing decorative.
+- **Surfaces feel intentional.** Three or four surface tones — page background, card, hover, selected — each visibly distinct. The eye doesn't have to ask "is this a different gray?"
+- **Color signals meaning.** Green is positive, red is negative, the brand color is reserved for primary moments. The mapping is consistent everywhere.
+- **Restraint with accent color.** The brand color appears where it matters — primary actions, key indicators — not as decoration.
+- **Considered dark mode (if present).** Dark mode is its own design, not a color-inverted afterthought.
+
+### Felt observations to make
+
+- The palette feels tight and disciplined.
+- Surface tones feel distinct from each other — no near-duplicates.
+- The brand or accent color is used sparingly and purposefully.
+- Status colors (positive, negative, warning) are consistent across the product.
+- Dark mode (if present) feels like its own designed surface.
+- Information isn't carried by color alone — pair with icon, label, or position.
+
+### What weak color looks like
+
+- Many near-identical grays accumulating across surfaces — the eye registers wear.
+- The accent color is everywhere, including decorative uses, so primary actions don't stand out.
+- Status colors flip meaning between views (green meant "complete" here, "ready to start" there).
+- Dark mode looks like a contrast inversion of light mode, not a designed surface.
+- The palette feels accumulated — colors added by different contributors over time.
+
+---
+
+## Surfaces
+
+### What good surfaces feel like
+
+- **Cards, panels, modals all feel like one family.** Same border treatment, same radii, same elevation language. A card on one screen is recognizable as a card on another.
+- **Elevation has intent.** When something is lifted (modal, popover, sticky element), the elevation is clear and consistent. Shadows are tasteful, not heavy.
+- **Borders are restrained.** Not every container has a border. When a border appears, it earns its place — separating things that need separating.
+- **Radii are limited.** The product picks one or two corner radii and sticks to them. Cards aren't 4px-rounded in one place and 12px-rounded in another.
+
+### Felt observations to make
+
+- Cards across the product feel like the same family.
+- Modals and popovers feel like the same family.
+- Borders appear where separation is needed, not as decoration.
+- Shadows are subtle and consistent — same elevation gets the same shadow.
+- Corner radii are consistent within a context.
+
+### What weak surfaces look like
+
+- Cards on different screens have different radii, different shadows, different border treatments — the family is fragmented.
+- Borders everywhere — every container framed for no reason.
+- Shadows are too heavy or inconsistent — some elements feel like they're floating in front of glass, others feel painted on.
+- A modal looks like a card looks like a popover looks like a panel — no elevation hierarchy.
+
+---
+
+## Visual Assets
+
+### What good visual assets feel like
+
+- **Icons are one family.** Same stroke weight, same style (outlined vs filled), same proportions. They look like a set, not a collection.
+- **Icons are sized consistently in the same context.** A toolbar icon is the same size as another toolbar icon.
+- **Imagery has intent.** Photos and illustrations feel chosen, not searched-and-pasted. They support the content, not decorate it.
+- **Avatars are consistent.** Same size, same shape, same fallback treatment.
+- **Empty states have personality.** When the product needs to fill space because there's nothing to show, the design uses the moment — a small illustration, a clear invitation, a personality.
+
+### Felt observations to make
+
+- Icons feel like a set — consistent stroke weight and style.
+- Icons in similar contexts are similar sizes.
+- Avatars are the same shape (round vs square) across the product.
+- Imagery feels chosen, not generic.
+- Empty states are designed moments, not blank screens with "No items."
+
+### What weak visual assets look like
+
+- Icons mix outlined and filled styles randomly. Stroke weights vary.
+- Toolbar icons are different sizes from each other.
+- Stock photography that doesn't match the brand voice.
+- Avatars are round in one place, square in another.
+- Empty states are blank, with a generic "No data" string.
+
+---
+
+## Cross-cutting felt qualities
+
+When evaluating the visual system as a whole, ask:
+
+- **Does the system feel like it has a point of view?** Or does it feel like an accumulation of contributions?
+- **Could a new contributor extend this system without guessing?** The patterns should be self-documenting.
+- **Does the visual vocabulary feel small?** Disciplined products use few sizes, weights, colors, and shapes — and use them everywhere.
+- **Is anything shouting that doesn't need to?** Bold weights, accent colors, large sizes, and heavy borders should be reserved.
+- **Where does the eye land first? Second? Third?** If you can't answer, hierarchy is broken.
+
+---
+
+## Scoring Guide
+
+**Contributes to dimensions: Well-Crafted, Coherent**
+
+| Score | Criteria |
+|-------|----------|
+| 9–10 | The visual system feels disciplined and intentional. Small vocabulary used consistently. Hierarchy is calm; restraint is visible. Surfaces, type, color, and assets all read as one family. The eye lands where it should. |
+| 7–8 | Strong visual system with minor inconsistencies. The discipline is mostly visible; small drift in secondary screens. |
+| 5–6 | Functional but uneven. Some inconsistencies are felt — type sizes drift, surface colors don't quite match, icons are mixed weights. The system reads as accumulated. |
+| 3–4 | Visibly fragmented. Multiple type sizes without logic, color used decoratively, surfaces don't relate, icons from different families. The product feels assembled by different hands. |
+| 1–2 | No visual system. Browser defaults visible; nothing relates to anything else; chaos. |