@su-record/vibe 2.8.24 → 2.8.26

package/skills/design-audit/frameworks/core-web-vitals.md

@@ -0,0 +1,107 @@
+---
+name: core-web-vitals
+type: framework
+applies-to: [design-audit]
+---
+
+# Core Web Vitals — Reference Card
+
+## The Three Metrics
+
+| Metric | Measures | Good | Needs Improvement | Poor |
+|--------|----------|------|-------------------|------|
+| **LCP** — Largest Contentful Paint | Loading performance | ≤2.5s | 2.5s–4.0s | >4.0s |
+| **INP** — Interaction to Next Paint | Responsiveness (replaces FID) | ≤200ms | 200ms–500ms | >500ms |
+| **CLS** — Cumulative Layout Shift | Visual stability | ≤0.1 | 0.1–0.25 | >0.25 |
+
+> **INP replaced FID** as a Core Web Vital in March 2024.
+
+## LCP — Largest Contentful Paint
+
+**What triggers LCP**: `<img>`, `<video>` poster, background-image via CSS, block-level text.
+
+### Common Causes of Poor LCP
+
+| Cause | Fix |
+|-------|-----|
+| Render-blocking resources | Move scripts to `defer`/`async`, inline critical CSS |
+| Slow server response (TTFB >600ms) | CDN, edge caching, preconnect hints |
+| LCP image not preloaded | Add `<link rel="preload" as="image">` for hero image |
+| LCP image lazy-loaded | Remove `loading="lazy"` from above-fold images |
+| Large uncompressed images | Use WebP/AVIF, set `srcset`, compress ≤200KB for hero |
+
+```html
+<!-- Good: preload LCP image, no lazy loading above fold -->
+<link rel="preload" as="image" href="/hero.webp" fetchpriority="high">
+<img src="/hero.webp" alt="Hero" fetchpriority="high" width="1200" height="600">
+```
+
+## INP — Interaction to Next Paint
+
+**What triggers INP**: Click, tap, keyboard input — measures time until next frame paint.
+
+### Common Causes of Poor INP
+
+| Cause | Fix |
+|-------|-----|
+| Long JS tasks (>50ms) blocking main thread | Break into chunks with `scheduler.yield()` |
+| Heavy event handlers | Debounce input, defer non-critical work |
+| Synchronous layout thrash | Batch DOM reads/writes, use `requestAnimationFrame` |
+| Large React re-renders on interaction | `useMemo`, `useCallback`, virtualize long lists |
+
+```ts
+// Good: yield back to browser between chunks
+async function processLargeList(items: Item[]): Promise<void> {
+  for (const chunk of chunkArray(items, 50)) {
+    processChunk(chunk);
+    await scheduler.yield(); // let browser paint between chunks
+  }
+}
+```
+
+## CLS — Cumulative Layout Shift
+
+**What causes shifts**: Elements inserted above existing content, images/iframes without dimensions, fonts swapping.
+
+### Common Causes of Poor CLS
+
+| Cause | Fix |
+|-------|-----|
+| Images without `width`/`height` | Always set explicit dimensions or `aspect-ratio` |
+| Dynamic content injection (ads, banners) | Reserve space with `min-height` placeholders |
+| Web fonts causing FOUT/FOIT | Use `font-display: swap` + preload key fonts |
+| Animations using `top`/`left`/`margin` | Use `transform` instead (compositor-only) |
+
+```css
+/* Good: reserve space before image loads */
+.hero-image {
+  aspect-ratio: 16 / 9;
+  width: 100%;
+}
+
+/* Good: compositor-only animation (no layout shift) */
+.slide-in {
+  transform: translateX(-100%);
+  transition: transform 0.3s ease;
+}
+```
+
+## Measurement Tools
+
+| Tool | Purpose |
+|------|---------|
+| Chrome DevTools → Performance | Record and analyze LCP/CLS waterfall |
+| Lighthouse | Automated audit with recommendations |
+| PageSpeed Insights | Field data (CrUX) + lab data combined |
+| Web Vitals extension | Real-time metric overlay in browser |
+| `web-vitals` npm package | Measure in production JS |
+
+## Audit Checklist
+
+- [ ] LCP element identified (DevTools → Performance → Timings)
+- [ ] LCP image preloaded and not lazy-loaded
+- [ ] All images have explicit `width` + `height` (or `aspect-ratio`)
+- [ ] No layout-shifting animations using positional properties
+- [ ] Fonts preloaded with `font-display: swap`
+- [ ] No long tasks >50ms in interaction handlers
+- [ ] Third-party scripts loaded with `async`/`defer`

package/skills/design-audit/frameworks/wcag-checklist.md

@@ -0,0 +1,64 @@
+---
+name: wcag-checklist
+type: framework
+applies-to: [design-audit]
+standard: WCAG 2.1 AA
+---
+
+# WCAG 2.1 AA — Key Criteria Reference Card
+
+## Perceivable
+
+| Criterion | Level | Requirement | Test |
+|-----------|-------|-------------|------|
+| 1.1.1 Non-text Content | A | All images have `alt` text | Check `<img>` for `alt` attribute |
+| 1.3.1 Info and Relationships | A | Structure conveyed via markup (headings, lists, labels) | Heading hierarchy is logical |
+| 1.3.3 Sensory Characteristics | A | Instructions don't rely on shape/color/location alone | "Click the red button" → add label |
+| 1.4.1 Use of Color | A | Color not the only means of conveying information | Error state uses icon + color |
+| 1.4.3 Contrast (Minimum) | AA | Text ≥ 4.5:1, large text ≥ 3:1 | Use contrast checker |
+| 1.4.4 Resize Text | AA | Text resizable to 200% without loss of content | Test at 200% browser zoom |
+| 1.4.10 Reflow | AA | Content reflows at 320px width without horizontal scroll | Test at 320px viewport |
+| 1.4.11 Non-text Contrast | AA | UI components ≥ 3:1 against adjacent colors | Buttons, inputs, focus rings |
+| 1.4.12 Text Spacing | AA | No content loss with: line-height 1.5, letter-spacing 0.12em | Apply via user stylesheet |
+| 1.4.13 Content on Hover | AA | Hover/focus content dismissible, hoverable, persistent | Tooltips must stay on hover |
+
+## Operable
+
+| Criterion | Level | Requirement | Test |
+|-----------|-------|-------------|------|
+| 2.1.1 Keyboard | A | All functionality available via keyboard | Tab through all interactions |
+| 2.1.2 No Keyboard Trap | A | Focus not trapped (except modals — must have escape) | Press Escape in all overlays |
+| 2.4.1 Bypass Blocks | A | Skip-to-content link or landmark navigation | First focusable = skip link |
+| 2.4.3 Focus Order | A | Focus order preserves meaning and operability | Tab order matches visual flow |
+| 2.4.4 Link Purpose | A | Link purpose clear from link text or context | Avoid "click here", "read more" |
+| 2.4.6 Headings and Labels | AA | Headings and labels are descriptive | No generic "Section 1" headings |
+| 2.4.7 Focus Visible | AA | Keyboard focus indicator is visible | No `outline: none` without replacement |
+
+## Understandable
+
+| Criterion | Level | Requirement | Test |
+|-----------|-------|-------------|------|
+| 3.1.1 Language of Page | A | `lang` attribute on `<html>` | Check `<html lang="en">` |
+| 3.2.1 On Focus | A | Focus doesn't trigger context change | No auto-submit on focus |
+| 3.2.2 On Input | A | Input change doesn't auto-navigate without warning | Select menus don't auto-submit |
+| 3.3.1 Error Identification | A | Errors identified and described in text | Not just red border — include message |
+| 3.3.2 Labels or Instructions | A | Labels or instructions for user input | All form fields labeled |
+| 3.3.3 Error Suggestion | AA | Suggest fixes when known (e.g., format hints) | "Use format MM/DD/YYYY" |
+| 3.3.4 Error Prevention | AA | Legal/financial submissions reversible or confirmable | Confirm before delete |
+
+## Robust
+
+| Criterion | Level | Requirement | Test |
+|-----------|-------|-------------|------|
+| 4.1.1 Parsing | A | Valid HTML (no duplicate IDs, proper nesting) | Run HTML validator |
+| 4.1.2 Name, Role, Value | A | UI components have accessible name, role, state | All custom widgets have ARIA |
+| 4.1.3 Status Messages | AA | Status messages programmatically determinable | `role="status"` or `aria-live` |
+
+## Quick Color Contrast Thresholds
+
+| Text Type | Minimum Ratio |
+|-----------|--------------|
+| Normal text (<18pt / <14pt bold) | 4.5:1 |
+| Large text (≥18pt / ≥14pt bold) | 3:1 |
+| UI components (borders, icons) | 3:1 |
+| Decorative / disabled elements | No requirement |

package/skills/design-audit/orchestrator.md

@@ -0,0 +1,64 @@
+---
+name: design-audit-orchestrator
+type: orchestrator
+agents: [a11y-auditor, performance-auditor, responsive-auditor, slop-detector, scorer]
+---
+
+# Design Audit Orchestrator
+
+## Workflow
+
+### Phase 1: Launch Dimension Auditors
+- **Agent**: a11y-auditor, performance-auditor, responsive-auditor, slop-detector
+- **Input**: Target files or component paths + optional design-context.json
+- **Output**: Per-dimension findings `{dimension, findings[], severity}` scored 0–4
+- **Parallel**: yes — all 4 auditors run simultaneously
+
+### Phase 2: Aggregate Scores
+- **Agent**: scorer
+- **Input**: All 4 dimension results from Phase 1
+- **Output**: Score table (per-dimension + overall), severity-tagged finding list (P0–P3)
+- **Parallel**: no — requires all dimension results
+
+### Phase 3: Generate Report
+- **Agent**: orchestrator (self)
+- **Input**: Scored results from Phase 2
+- **Output**: Prioritized report with P0→P3 sections and per-dimension summaries
+- **Parallel**: no
+
+### Phase 4: Suggest Next Skill
+- **Agent**: orchestrator (self)
+- **Input**: Overall score and dominant failure dimension from Phase 3
+- **Output**: Recommended next skill (`/design-normalize`, `/design-critique`, `/design-polish`)
+- **Parallel**: no
+
+## DAG (Dependency Graph)
+
+```mermaid
+graph TD
+    A[Phase 1a: a11y-auditor] --> E[Phase 2: Scorer]
+    B[Phase 1b: performance-auditor] --> E
+    C[Phase 1c: responsive-auditor] --> E
+    D[Phase 1d: slop-detector] --> E
+    E --> F[Phase 3: Generate Report]
+    F --> G[Phase 4: Next Skill Suggestion]
+```
+
+## Error Handling
+
+| Phase | Failure Mode | Strategy |
+|-------|-------------|----------|
+| Phase 1 | Auditor finds no applicable items (e.g., no images for perf) | Return score 4 (N/A treated as pass) |
+| Phase 1 | Target file unreadable | Skip file, log warning, continue with others |
+| Phase 1 | design-context.json missing | Proceed with defaults, note missing context |
+| Phase 2 | <2 dimension scores returned | Warn user, compute partial overall score |
+| Phase 3 | 0 findings across all dimensions | Output "No issues found" report — do not suppress |
+| Phase 4 | Score at boundary of multiple next-skill suggestions | Present all applicable options ranked by score |
+
+## Scalability Modes
+
+| Mode | When | Agents Used |
+|------|------|-------------|
+| Full | Normal operation | All 4 auditors + scorer |
+| Reduced | Single-concern audit | Target auditor only (e.g., a11y-auditor alone) |
+| Single | Quick slop check | slop-detector only — fast AI-pattern scan |

package/skills/design-audit/rubrics/ai-slop-patterns.md

@@ -0,0 +1,83 @@
+# AI Slop Detection — Pattern Reference
+
+Patterns that indicate AI-generated defaults rather than deliberate design decisions. Each entry describes the visual signature and why it signals slop.
+
+---
+
+## Pattern 1: Cyan/Neon-on-Dark Accent
+
+**Visual signature**: Electric cyan (`#00D8FF`, `#22D3EE`) or neon green/purple as the sole accent color on a dark gray or near-black background. Often applied to buttons, badges, and chart lines simultaneously.
+
+**Why it's slop**: This palette is the default "tech/SaaS" output for most AI image and code generators. It signals no brand research was done.
+
+**Legitimate exception**: Cyberpunk-themed games, developer tools with a deliberate retro-terminal aesthetic, or products with documented brand guidelines using these colors.
+
+---
+
+## Pattern 2: Purple-to-Blue Gradient Hero
+
+**Visual signature**: A full-bleed hero section or page background using a diagonal or radial gradient from `#7C3AED` (purple) to `#2563EB` (blue). Often combined with white or light text and a "glow" effect.
+
+**Why it's slop**: The most overused AI-generated hero background across all categories and industries. Applied without regard for brand personality.
+
+**Legitimate exception**: Brand explicitly uses purple and blue as primary colors with documented rationale.
+
+---
+
+## Pattern 3: Hero Metric Template
+
+**Visual signature**: An oversized number (60–80px font, often bold or gradient-colored) with a tiny label below it (`"Active Users"`, `"Revenue"`, `"Uptime"`). Three or four of these arranged in a row as the primary dashboard view.
+
+**Why it's slop**: It's a structural template, not a data visualization decision. Used regardless of whether the numbers are meaningful or whether the user needs them front and center.
+
+**Legitimate exception**: Real-time operational dashboards where these metrics are the primary user task.
+
+---
+
+## Pattern 4: Identical 3-Up Card Grid
+
+**Visual signature**: Exactly three cards in a horizontal row, each containing an icon (top-left or centered), a short bold title, and 1–2 lines of description text. Repeated verbatim as a features section, benefits section, or team section.
+
+**Why it's slop**: The 3-up grid is the default content-filling pattern for every AI-generated landing page. It imposes a visual structure regardless of whether the content benefits from comparison.
+
+**Legitimate exception**: Content is genuinely comparative (pricing tiers, product variants), or the grid contains more than 3 genuinely distinct items.
+
+---
+
+## Pattern 5: Default Glassmorphism
+
+**Visual signature**: Cards and panels with `backdrop-filter: blur(12px)`, a semi-transparent white or colored background (`rgba(255,255,255,0.1)`), and a subtle border (`rgba(255,255,255,0.2)`). Applied as the primary surface treatment across all cards.
+
+**Why it's slop**: Glassmorphism is a specific aesthetic that requires a layered background to function visually. AI applies it universally as a "modern" default, often on solid-color backgrounds where it produces no effect.
+
+**Legitimate exception**: OS-style UIs, media applications with rich background imagery, or products where glass surfaces are part of a coherent aesthetic system.
+
+---
+
+## Pattern 6: Bounce/Elastic Functional Animation
+
+**Visual signature**: UI elements that overshoot their final position with `cubic-bezier` bounce or spring easing during state transitions — modals sliding in with elastic overshoot, buttons that wobble on hover, list items that bounce into view.
+
+**Why it's slop**: Bounce easing communicates playfulness. Applied to functional transitions (modals, form submissions, navigation) it creates a tonally inconsistent experience and feels unpolished in professional contexts.
+
+**Legitimate exception**: Mobile games, children's apps, or products with an explicitly playful brand personality where the animation reinforces brand voice.
+
+---
+
+## Pattern 7: Inter/Roboto as Lazy Default
+
+**Visual signature**: Inter or Roboto used as both heading and body font across a product with no visible typography hierarchy differentiation. No font scale customization — using default weights and sizes from the framework.
+
+**Why it's slop**: These fonts are excellent but are chosen by AI because they are safe and system-default-adjacent. Font selection should reflect brand personality and audience expectations.
+
+**Legitimate exception**: Products that have explicitly evaluated their font options and chosen Inter/Roboto for legibility, neutrality, or performance reasons — with documented rationale.
+
+---
+
+## Pattern 8: Gradient Text on Metrics/Statistics
+
+**Visual signature**: Key numbers, statistics, or headings rendered with a linear gradient applied to the text itself (`background-clip: text; -webkit-text-fill-color: transparent`), typically the same purple-to-blue or cyan-to-blue range.
+
+**Why it's slop**: Gradient text is visually noisy and reduces readability. It is applied wholesale by AI to make numbers "pop" without considering whether the visual effect serves the data's meaning.
+
+**Legitimate exception**: Brand wordmarks, decorative headings where legibility is secondary to visual impact, or hero statements where the gradient is part of a consistent typographic system.

package/skills/design-audit/rubrics/scoring.md

@@ -0,0 +1,63 @@
+# Design Audit — Detailed Scoring Rubric
+
+Each dimension scored 0–4. Score the lowest applicable level that matches observed issues.
+
+---
+
+## 1. Accessibility (a11y)
+
+| Score | Criteria |
+|-------|----------|
+| **4** | All interactive elements keyboard-reachable; ARIA roles correct; contrast ≥ 4.5:1 everywhere; all images have meaningful alt text; every form input has a label; focus indicators visible; `aria-live` on dynamic regions; skip-to-content present |
+| **3** | 1–2 minor issues: e.g., one icon missing `aria-label`, or skip link absent on a simple page |
+| **2** | Multiple issues but no complete blockers: e.g., some form inputs unlabeled, focus order inconsistent in one section |
+| **1** | Significant gaps: contrast failures on primary text, keyboard traps present, or no ARIA on custom widgets |
+| **0** | Critical failures: interactive elements unreachable by keyboard, no contrast at all on key text, or screen reader produces nonsense navigation |
+
+---
+
+## 2. Performance
+
+| Score | Criteria |
+|-------|----------|
+| **4** | All below-fold images lazy-loaded with `srcset` and modern formats; ≤3 font files with `font-display: swap`; critical CSS inlined; JS code-split at routes; no layout shift on media; no duplicate deps |
+| **3** | 1–2 minor gaps: e.g., one non-critical image missing `loading="lazy"`, or a fourth font file loaded |
+| **2** | Several issues: missing lazy load on multiple images, no `font-display`, or a blocking script in `<head>` |
+| **1** | Major issues: no image optimization at all, large unneeded CSS framework fully loaded, or significant layout shifts |
+| **0** | Critical: blocking JS on `<head>` delays render, images 5× larger than necessary, LCP asset entirely unoptimized |
+
+---
+
+## 3. Responsive
+
+| Score | Criteria |
+|-------|----------|
+| **4** | Mobile-first breakpoints; all touch targets ≥ 44×44px; no horizontal scroll at any viewport; typography scales cleanly; container queries used where appropriate; navigation adapts correctly |
+| **3** | 1–2 small gaps: e.g., one touch target slightly under 44px, or minor horizontal overflow on a niche breakpoint |
+| **2** | Several issues: some touch targets too small, typography doesn't scale, navigation doesn't adapt on mobile |
+| **1** | Layout broken at common breakpoints; horizontal scroll present; fixed-width elements causing overflow |
+| **0** | Completely non-responsive: desktop layout forced on mobile, content unreadable at 375px |
+
+---
+
+## 4. Theming
+
+| Score | Criteria |
+|-------|----------|
+| **4** | All colors via CSS custom properties; dark mode supported or explicitly opted out with documentation; spacing, radius, and shadows all use design tokens; component variants use data attributes or classes only |
+| **3** | 1–3 hardcoded values in low-visibility areas; no inline styles on primary surfaces |
+| **2** | Multiple hardcoded values scattered through components; some spacing arbitrary; dark mode partial or inconsistent |
+| **1** | Most values hardcoded; design tokens exist but rarely used; inline styles prevalent |
+| **0** | No token system; all values inline or in scattered magic numbers; dark mode completely absent if required |
+
+---
+
+## 5. AI Slop Detection
+
+| Score | Criteria |
+|-------|----------|
+| **4** | No AI template patterns; color scheme, typography, and layout reflect deliberate brand choices; animations serve function; design feels intentional and specific to this product |
+| **3** | 1 pattern present but with partial justification (e.g., gradient used sparingly, not as the dominant aesthetic) |
+| **2** | 2–3 patterns present; design leans on AI defaults without clear brand rationale |
+| **1** | 4–5 patterns present; the overall aesthetic is indistinguishable from generic AI-generated UI |
+| **0** | Full AI slop template: neon/cyan accents, purple-blue gradient hero, glassmorphism cards, 3-up icon grids, Inter font, gradient metric text — all present simultaneously |

package/skills/design-audit/templates/report.md

@@ -0,0 +1,88 @@
+# Design Audit Report: {{TARGET}}
+
+**Date**: {{DATE}}
+**Auditor**: {{AUDITOR}}
+**Scope**: {{SCOPE_DESCRIPTION}}
+**Design Context**: {{CONTEXT_SOURCE}} (design-context.json / defaults)
+
+---
+
+## Scores
+
+| Dimension | Score | Grade | Key Issues |
+|-----------|-------|-------|------------|
+| Accessibility | {{A11Y_SCORE}}/4 | {{A11Y_GRADE}} | {{A11Y_SUMMARY}} |
+| Performance | {{PERF_SCORE}}/4 | {{PERF_GRADE}} | {{PERF_SUMMARY}} |
+| Responsive | {{RESP_SCORE}}/4 | {{RESP_GRADE}} | {{RESP_SUMMARY}} |
+| Theming | {{THEME_SCORE}}/4 | {{THEME_GRADE}} | {{THEME_SUMMARY}} |
+| AI Slop | {{SLOP_SCORE}}/4 | {{SLOP_GRADE}} | {{SLOP_SUMMARY}} |
+| **Overall** | **{{TOTAL_SCORE}}/20** | **{{TOTAL_PCT}}%** | |
+
+Grade scale: 4=Excellent, 3=Good, 2=Moderate, 1=Major Issues, 0=Critical
+
+---
+
+## Findings
+
+### P0 — Blocker (breaks functionality)
+
+{{#P0_FINDINGS}}
+- [{{DIMENSION}}] {{DESCRIPTION}} — `{{FILE}}:{{LINE}}`
+{{/P0_FINDINGS}}
+{{#NO_P0}}
+- None
+{{/NO_P0}}
+
+### P1 — Critical (significant UX impact)
+
+{{#P1_FINDINGS}}
+- [{{DIMENSION}}] {{DESCRIPTION}} — `{{FILE}}:{{LINE}}`
+{{/P1_FINDINGS}}
+{{#NO_P1}}
+- None
+{{/NO_P1}}
+
+### P2 — Important (noticeable quality gap)
+
+{{#P2_FINDINGS}}
+- [{{DIMENSION}}] {{DESCRIPTION}} — `{{FILE}}:{{LINE}}`
+{{/P2_FINDINGS}}
+{{#NO_P2}}
+- None
+{{/NO_P2}}
+
+### P3 — Minor (polish opportunity)
+
+{{#P3_FINDINGS}}
+- [{{DIMENSION}}] {{DESCRIPTION}} — `{{FILE}}:{{LINE}}`
+{{/P3_FINDINGS}}
+{{#NO_P3}}
+- None
+{{/NO_P3}}
+
+---
+
+## Recommendations
+
+{{#RECOMMENDATIONS}}
+{{INDEX}}. {{RECOMMENDATION}}
+{{/RECOMMENDATIONS}}
+
+---
+
+## Next Steps
+
+| Condition | Recommended Skill |
+|-----------|-------------------|
+| Design system inconsistencies found | `/design-normalize` |
+| UX/usability concerns noted | `/design-critique` |
+| Score ≥ 16/20, minor polish only | `/design-polish` |
+
+---
+
+## Audit Metadata
+
+- Files scanned: {{FILE_COUNT}}
+- Total findings: {{TOTAL_FINDINGS}} (P0: {{P0_COUNT}}, P1: {{P1_COUNT}}, P2: {{P2_COUNT}}, P3: {{P3_COUNT}})
+- Platform: {{PLATFORM}}
+- Stack: {{STACK}}

package/skills/design-critique/rubrics/ux-heuristics.md

@@ -0,0 +1,143 @@
+# Nielsen's 10 Usability Heuristics — Code Review Adaptation
+
+Scoring per heuristic: 0 (violated) → 4 (excellent). Focus on what is observable in the code.
+
+---
+
+## H1 — Visibility of System Status
+
+**What to look for in code**: Loading states on async actions, progress indicators, state-driven class/attribute changes, `aria-live` regions for dynamic content.
+
+| Score | Code Evidence |
+|-------|---------------|
+| **4** | Every async action has a loading state; progress shown for multi-step ops; dynamic regions use `aria-live` |
+| **3** | Most async actions covered; 1 operation missing feedback |
+| **2** | Loading states on primary actions only; secondary actions have no feedback |
+| **1** | Only a spinner on page load; form submissions and mutations give no feedback |
+| **0** | No loading states anywhere; UI freezes silently on async calls |
+
+---
+
+## H2 — Match Between System and Real World
+
+**What to look for**: Label copy, icon choices, terminology in component props and display text, logical grouping of related items.
+
+| Score | Code Evidence |
+|-------|---------------|
+| **4** | All labels use user-facing language (not internal field names); icons are universally understood; groupings match mental models |
+| **3** | Mostly natural language; 1–2 developer-facing terms exposed in UI |
+| **2** | Mixed: some labels match user expectations, others use internal/technical terminology |
+| **1** | Predominantly technical labels (`user_id`, `ts`, `ref_code`) in visible UI |
+| **0** | Raw API field names or database column names exposed directly to users |
+
+---
+
+## H3 — User Control and Freedom
+
+**What to look for**: Cancel buttons on dialogs and forms, undo functionality, ability to navigate back, escape-to-close on modals.
+
+| Score | Code Evidence |
+|-------|---------------|
+| **4** | Undo available for destructive actions; all modals closeable via Escape; cancel on all multi-step flows |
+| **3** | Most paths have exits; one flow lacks a clear back/cancel |
+| **2** | Cancel exists on modals but destructive actions (delete, submit) have no undo |
+| **1** | No undo; several flows trap the user until completion |
+| **0** | Irreversible destructive actions with no confirmation or recovery path |
+
+---
+
+## H4 — Consistency and Standards
+
+**What to look for**: Reuse of shared components, consistent prop naming, same action always produces same UI response, platform conventions followed.
+
+| Score | Code Evidence |
+|-------|---------------|
+| **4** | Shared component library used throughout; same action triggers same visual pattern; follows platform HIG |
+| **3** | 1–2 inconsistencies (e.g., one custom button not using Button component) |
+| **2** | Some shared components but several one-off implementations for identical patterns |
+| **1** | Each page re-implements its own UI patterns; no shared components |
+| **0** | Same action produces visually different results on different screens |
+
+---
+
+## H5 — Error Prevention
+
+**What to look for**: Input validation (inline, not just on submit), confirmation dialogs on destructive actions, disabled states on invalid forms, input constraints (maxLength, type, pattern).
+
+| Score | Code Evidence |
+|-------|---------------|
+| **4** | Inline validation; destructive actions confirmed; submit disabled until valid; input types constrain input |
+| **3** | Confirmation dialogs present; validation on submit but not inline |
+| **2** | Some validation; destructive actions have confirmation but forms don't validate until submit |
+| **1** | No inline validation; destructive actions unconstrained |
+| **0** | No validation or confirmation; data loss possible without warning |
+
+---
+
+## H6 — Recognition Rather Than Recall
+
+**What to look for**: Breadcrumbs, visible current state in navigation, contextual help text, search suggestions, recently used items.
+
+| Score | Code Evidence |
+|-------|---------------|
+| **4** | Current location always visible; options surfaced in context; search includes suggestions |
+| **3** | Navigation shows current state; options visible on primary flows |
+| **2** | Some affordances; secondary flows require user to remember where they are |
+| **1** | No breadcrumbs; navigation doesn't indicate current section; users must recall paths |
+| **0** | Deep nested flows with no orientation cues |
+
+---
+
+## H7 — Flexibility and Efficiency
+
+**What to look for**: Keyboard shortcuts, bulk actions, saved defaults, power-user paths that bypass multi-step flows.
+
+| Score | Code Evidence |
+|-------|---------------|
+| **4** | Keyboard shortcuts for primary actions; bulk selection; smart defaults pre-populated |
+| **3** | Good defaults; 1–2 keyboard shortcuts on critical actions |
+| **2** | No shortcuts; forms have some defaults but key fields are always blank |
+| **1** | Every task requires the same number of steps regardless of user expertise |
+| **0** | Power users actively slowed down (e.g., forced onboarding on repeat visits) |
+
+---
+
+## H8 — Aesthetic and Minimalist Design
+
+**What to look for**: Signal-to-noise ratio in rendered output; unnecessary decorative elements; information density relative to task complexity.
+
+| Score | Code Evidence |
+|-------|---------------|
+| **4** | Every visible element serves a task or provides necessary context; no decorative noise |
+| **3** | Mostly clean; 1–2 decorative elements that could be removed without loss |
+| **2** | Several decorative elements that compete with primary content |
+| **1** | UI is visually busy; primary actions compete with decoration |
+| **0** | Information overload; users cannot identify primary action without significant scanning |
+
+---
+
+## H9 — Help Users Recognize and Recover from Errors
+
+**What to look for**: Error message copy (specific, human-readable, with next steps), error placement (near the problem), error state styling.
+
+| Score | Code Evidence |
+|-------|---------------|
+| **4** | Errors are specific, placed next to the problem, and suggest a fix; styled distinctly |
+| **3** | Clear error messages; placed correctly; fix suggestion sometimes missing |
+| **2** | Error messages exist but are generic ("Something went wrong") or placed in a toast far from the issue |
+| **1** | Raw error codes or API messages exposed to users |
+| **0** | No error states; failures silently ignored or produce white screens |
+
+---
+
+## H10 — Help and Documentation
+
+**What to look for**: Tooltips on complex fields, onboarding flows for new users, empty states with guidance, contextual help links.
+
+| Score | Code Evidence |
+|-------|---------------|
+| **4** | Tooltips on non-obvious fields; empty states guide next action; onboarding present for new users |
+| **3** | Empty states with calls-to-action; tooltips on some complex fields |
+| **2** | Generic empty states ("No data found") without guidance |
+| **1** | No tooltips, empty state guidance, or onboarding |
+| **0** | Confusing UI with no help and no path to documentation |