Integrate impeccable design quality tools
Selective integration from pbakaus/impeccable (Apache 2.0): Reference material (docs/reference/impeccable/): - 7 design guides: typography, color-and-contrast, spatial-design, motion-design, interaction-design, responsive-design, ux-writing - 3 critique references: cognitive-load, heuristics-scoring, personas - 4 skill references for internal use: audit, critique, polish, frontend-design (anti-patterns list) New skills: - /audit — technical quality scoring (0-20) across 5 dimensions: accessibility, performance, theming, responsive, design quality - /critique — UX design review using Nielsen's 10 heuristics (0-40), adapted for FA's sensitive audience context Updated skills: - /review-component — added interactive states checklist and design anti-patterns checklist (8 checks each) - /preflight — added visual QA spot-check section (transitions, focus-visible, touch targets, spacing consistency) No code changes — all existing components, tokens, and theme untouched. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
This commit is contained in:
119
.claude/skills/audit/SKILL.md
Normal file
119
.claude/skills/audit/SKILL.md
Normal file
@@ -0,0 +1,119 @@
|
||||
---
|
||||
name: audit
|
||||
description: Run technical quality checks across accessibility, performance, theming, responsive design, and anti-patterns. Generates a scored report with P0-P3 severity ratings. Adapted from impeccable (Apache 2.0).
|
||||
user-invocable: true
|
||||
argument-hint: "[component or area to audit]"
|
||||
---
|
||||
|
||||
Run systematic **technical** quality checks on a component or area and generate a scored report. This is assessment-only — don't fix issues, document them.
|
||||
|
||||
**Target:** $ARGUMENTS
|
||||
|
||||
## Preparation
|
||||
|
||||
1. Read `docs/design-system.md` for FA design conventions
|
||||
2. Read the component/area source files
|
||||
3. Reference `docs/reference/impeccable/` for detailed design guidelines when scoring
|
||||
|
||||
## Diagnostic Scan
|
||||
|
||||
Score each dimension 0-4.
|
||||
|
||||
### 1. Accessibility (A11y)
|
||||
|
||||
**Check for**:
|
||||
- Contrast ratios < 4.5:1 for text, < 3:1 for large text and UI components
|
||||
- Missing ARIA: interactive elements without proper roles, labels, or states
|
||||
- Keyboard navigation: missing focus-visible indicators, illogical tab order
|
||||
- Semantic HTML: divs instead of buttons, missing landmarks, heading hierarchy
|
||||
- Form issues: inputs without labels, poor error messaging
|
||||
- Touch targets < 44px (critical for FA's audience — elderly, distressed)
|
||||
|
||||
**Score**: 0=Fails WCAG A, 1=Major gaps, 2=Partial effort, 3=AA mostly met, 4=AA fully met
|
||||
|
||||
### 2. Performance
|
||||
|
||||
**Check for**:
|
||||
- Expensive animations: animating layout properties instead of transform/opacity
|
||||
- Missing optimisation: unoptimised assets, missing lazy loading
|
||||
- Bundle concerns: unnecessary imports, unused dependencies
|
||||
- Render performance: unnecessary re-renders, missing memoisation
|
||||
|
||||
**Score**: 0=Severe issues, 1=Major problems, 2=Partial, 3=Mostly optimised, 4=Excellent
|
||||
|
||||
### 3. Theming & Token Compliance
|
||||
|
||||
**Check for**:
|
||||
- Hardcoded colours not using theme palette or CSS variables
|
||||
- Hardcoded spacing not using theme.spacing() or token values
|
||||
- Hardcoded typography not using theme.typography variants
|
||||
- Inconsistent token usage: wrong tier (primitive instead of semantic)
|
||||
- Component tokens missing `$description` fields
|
||||
|
||||
**Score**: 0=Hardcoded everything, 1=Minimal tokens, 2=Inconsistent, 3=Good with minor gaps, 4=Full token compliance
|
||||
|
||||
### 4. Responsive Design
|
||||
|
||||
**Check for**:
|
||||
- Fixed widths that break on mobile
|
||||
- Touch targets < 44px on interactive elements
|
||||
- Horizontal scroll/overflow on narrow viewports
|
||||
- Text scaling: layouts that break when text size increases
|
||||
- Missing responsive padding (mobile vs desktop)
|
||||
|
||||
**Score**: 0=Desktop-only, 1=Major issues, 2=Partial, 3=Good, 4=Fluid and responsive
|
||||
|
||||
### 5. Design Quality
|
||||
|
||||
**Check against these anti-patterns** (from impeccable frontend-design guidelines):
|
||||
- Gray text on coloured backgrounds (looks washed out)
|
||||
- Cards nested inside cards (visual noise)
|
||||
- Identical card grids with no variation
|
||||
- Bounce/elastic easing (dated, tacky)
|
||||
- Every button styled as primary (no hierarchy)
|
||||
- Redundant copy (headers restating the same info)
|
||||
- Glassmorphism/blur used decoratively
|
||||
- Missing interactive states (hover without focus, or vice versa)
|
||||
|
||||
**Score**: 0=Multiple anti-patterns, 1=Several issues, 2=A couple, 3=Mostly clean, 4=Intentional, distinctive design
|
||||
|
||||
## Report Format
|
||||
|
||||
### Audit Health Score
|
||||
|
||||
| # | Dimension | Score | Key Finding |
|
||||
|---|-----------|-------|-------------|
|
||||
| 1 | Accessibility | ? | |
|
||||
| 2 | Performance | ? | |
|
||||
| 3 | Theming & Tokens | ? | |
|
||||
| 4 | Responsive Design | ? | |
|
||||
| 5 | Design Quality | ? | |
|
||||
| **Total** | | **??/20** | **[Rating]** |
|
||||
|
||||
**Ratings**: 18-20 Excellent, 14-17 Good, 10-13 Acceptable, 6-9 Poor, 0-5 Critical
|
||||
|
||||
### Executive Summary
|
||||
- Score and rating
|
||||
- Issue count by severity (P0/P1/P2/P3)
|
||||
- Top 3-5 critical issues
|
||||
- Recommended next steps
|
||||
|
||||
### Detailed Findings
|
||||
|
||||
Tag each issue **P0-P3**:
|
||||
- **P0 Blocking**: Prevents task completion — fix immediately
|
||||
- **P1 Major**: WCAG AA violation or significant UX issue — fix before release
|
||||
- **P2 Minor**: Annoyance, workaround exists — fix in next pass
|
||||
- **P3 Polish**: Nice-to-fix — address if time permits
|
||||
|
||||
For each issue:
|
||||
- **[P?] Issue name**
|
||||
- **Location**: Component, file, line
|
||||
- **Category**: Accessibility / Performance / Theming / Responsive / Design Quality
|
||||
- **Impact**: How it affects users
|
||||
- **Recommendation**: How to fix it
|
||||
|
||||
### Positive Findings
|
||||
Note what's working well — good practices to maintain.
|
||||
|
||||
**NEVER**: Report issues without explaining impact. Provide generic recommendations. Skip positive findings. Mark everything as P0.
|
||||
124
.claude/skills/critique/SKILL.md
Normal file
124
.claude/skills/critique/SKILL.md
Normal file
@@ -0,0 +1,124 @@
|
||||
---
|
||||
name: critique
|
||||
description: UX design review — evaluates visual hierarchy, emotional journey, cognitive load, and overall quality using Nielsen's heuristics (scored 0-40). Adapted from impeccable (Apache 2.0).
|
||||
user-invocable: true
|
||||
argument-hint: "[component or area to critique]"
|
||||
---
|
||||
|
||||
Conduct a holistic UX design critique. Think like a design director giving feedback — evaluate whether the interface actually works as a designed experience, not just technically.
|
||||
|
||||
**Target:** $ARGUMENTS
|
||||
|
||||
## Preparation
|
||||
|
||||
1. Read `docs/design-system.md` for FA design context and brand guidelines
|
||||
2. Read `docs/memory/decisions-log.md` for design rationale
|
||||
3. Read the target component/area source and stories
|
||||
4. Reference `docs/reference/impeccable/cognitive-load.md` for the 8-item checklist
|
||||
5. Reference `docs/reference/impeccable/heuristics-scoring.md` for scoring criteria
|
||||
|
||||
**FA context reminder**: Funeral Arranger serves families often in grief or distress. The design must feel warm, trustworthy, transparent, and calm. Clarity over cleverness. Accessibility is critical — users may be elderly, emotional, or unfamiliar with technology.
|
||||
|
||||
## Phase 1: Design Critique
|
||||
|
||||
Evaluate across these dimensions:
|
||||
|
||||
### 1. Visual Hierarchy
|
||||
- Does the eye flow to the most important element first?
|
||||
- Is there a clear primary action visible within 2 seconds?
|
||||
- Do size, colour, and position communicate importance correctly?
|
||||
- Is there visual competition between elements of different weights?
|
||||
|
||||
### 2. Information Architecture & Cognitive Load
|
||||
- Is the structure intuitive for a first-time user?
|
||||
- Is related content grouped logically?
|
||||
- Are there too many choices at once? (>4 at a decision point = flag it)
|
||||
- **Run the 8-item cognitive load checklist** from `docs/reference/impeccable/cognitive-load.md`
|
||||
- Report failure count: 0-1 = low (good), 2-3 = moderate, 4+ = critical
|
||||
|
||||
### 3. Emotional Journey
|
||||
- Does the interface feel warm and trustworthy (appropriate for FA)?
|
||||
- Would a grieving family member feel "this is for me"?
|
||||
- Are there design interventions at anxiety-prone moments (pricing, commitment, forms)?
|
||||
- Does the experience end well (confirmation, clear next step)?
|
||||
|
||||
### 4. Discoverability & Affordance
|
||||
- Are interactive elements obviously interactive?
|
||||
- Would a user know what to do without instructions?
|
||||
- Are hover/focus states providing useful feedback?
|
||||
|
||||
### 5. Composition & Balance
|
||||
- Does the layout feel balanced?
|
||||
- Is whitespace used intentionally?
|
||||
- Is there visual rhythm in spacing and repetition?
|
||||
|
||||
### 6. Typography as Communication
|
||||
- Does the type hierarchy signal what to read first, second, third?
|
||||
- Is body text comfortable to read? (line length 45-75ch, adequate size)
|
||||
- Do font choices reinforce FA's warm, professional tone?
|
||||
|
||||
### 7. Colour with Purpose
|
||||
- Is colour used to communicate, not just decorate?
|
||||
- Does the warm gold/copper brand palette feel cohesive?
|
||||
- Are accent colours drawing attention to the right things?
|
||||
- Does it work for colourblind users?
|
||||
|
||||
### 8. States & Edge Cases
|
||||
- Empty states: Do they guide users toward action?
|
||||
- Loading states: Do they reduce perceived wait time?
|
||||
- Error states: Are they helpful and non-blaming? (critical for FA — no aggressive red labels)
|
||||
- Success states: Do they confirm and guide next steps?
|
||||
|
||||
### 9. Microcopy & Voice
|
||||
- Is the writing clear and concise?
|
||||
- Does it sound warm and professional (FA's tone)?
|
||||
- Are labels and buttons unambiguous?
|
||||
- Does error copy help users fix the problem without distress?
|
||||
|
||||
## Phase 2: Present Findings
|
||||
|
||||
### Design Health Score
|
||||
|
||||
Score each of Nielsen's 10 heuristics 0-4 (consult `docs/reference/impeccable/heuristics-scoring.md`):
|
||||
|
||||
| # | Heuristic | Score | Key Issue |
|
||||
|---|-----------|-------|-----------|
|
||||
| 1 | Visibility of System Status | ? | |
|
||||
| 2 | Match System / Real World | ? | |
|
||||
| 3 | User Control and Freedom | ? | |
|
||||
| 4 | Consistency and Standards | ? | |
|
||||
| 5 | Error Prevention | ? | |
|
||||
| 6 | Recognition Rather Than Recall | ? | |
|
||||
| 7 | Flexibility and Efficiency | ? | |
|
||||
| 8 | Aesthetic and Minimalist Design | ? | |
|
||||
| 9 | Error Recovery | ? | |
|
||||
| 10 | Help and Documentation | ? | |
|
||||
| **Total** | | **??/40** | **[Rating]** |
|
||||
|
||||
**Ratings**: 36-40 Excellent, 28-35 Good, 20-27 Acceptable, 12-19 Poor, 0-11 Critical
|
||||
|
||||
### Overall Impression
|
||||
Brief gut reaction — what works, what doesn't, the single biggest opportunity.
|
||||
|
||||
### What's Working
|
||||
2-3 things done well. Be specific about why they work.
|
||||
|
||||
### Priority Issues
|
||||
3-5 most impactful design problems, ordered by importance.
|
||||
|
||||
For each issue, tag **P0-P3**:
|
||||
- **[P?] What**: Name the problem
|
||||
- **Why it matters**: How it hurts users (especially in FA's sensitive context)
|
||||
- **Fix**: Concrete recommendation
|
||||
|
||||
### FA Audience Check
|
||||
Walk through the primary user flow as:
|
||||
1. **Bereaved family member** (60+, first time, emotional, possibly on mobile)
|
||||
2. **Arrangement planner** (30-50, comparing options, price-sensitive, wants transparency)
|
||||
|
||||
For each persona, list specific pain points found.
|
||||
|
||||
### Minor Observations
|
||||
Quick notes on smaller issues worth addressing.
|
||||
|
||||
**Remember**: Be direct and specific. Say what's wrong AND why it matters. Prioritise ruthlessly. Don't soften criticism — honest feedback ships better design.
|
||||
@@ -78,3 +78,14 @@ Result: PASS (safe to commit)
|
||||
Use `PASS`, `FAIL`, or `WARN`. If any critical check fails, the result is `FAIL (do not commit)`. If only warnings, result is `PASS (safe to commit)` with warnings listed.
|
||||
|
||||
If `--fix` was passed, attempt to fix issues automatically (e.g., run `npm run build:tokens` for stale tokens) and re-check.
|
||||
|
||||
### 6. Visual QA spot-check (manual review, non-blocking)
|
||||
|
||||
If a component was recently modified, do a quick visual review of the source code for these common issues (adapted from impeccable /polish):
|
||||
|
||||
- **Transition consistency**: All interactive state changes should use `150ms ease-in-out` (FA convention). Flag mismatches.
|
||||
- **Focus-visible**: Every interactive element should have a `:focus-visible` style. Flag any that rely only on hover.
|
||||
- **Touch targets**: Interactive elements should have `minHeight >= 44px` for the largest size (or the mobile-intended size).
|
||||
- **Spacing consistency**: Padding/gap values should use `theme.spacing()` or token CSS variables, not raw px.
|
||||
|
||||
These are advisory — report as `INFO` lines after the main results. Do not block commit for these.
|
||||
|
||||
@@ -46,4 +46,22 @@ Review a component against FA Design System conventions and report pass/fail for
|
||||
- [ ] Long content / overflow
|
||||
- [ ] autodocs tag present
|
||||
|
||||
### Interactive states (ref: docs/reference/impeccable/interaction-design.md)
|
||||
- [ ] Default (resting) state is styled
|
||||
- [ ] Hover state provides visual feedback (not just cursor change)
|
||||
- [ ] Focus-visible state is distinct from hover (keyboard users never see hover)
|
||||
- [ ] Active/pressed state feels responsive
|
||||
- [ ] Disabled state is visually diminished but still distinguishable
|
||||
- [ ] Transitions use 150ms ease-in-out (FA convention)
|
||||
|
||||
### Design anti-patterns (ref: docs/reference/impeccable/frontend-design-skill.md)
|
||||
- [ ] No grey text on coloured backgrounds (use a shade of the background colour instead)
|
||||
- [ ] No cards nested inside cards (flatten hierarchy with spacing/typography)
|
||||
- [ ] No identical card grids with zero variation (vary content, size, or emphasis)
|
||||
- [ ] No bounce/elastic easing (use ease-out-quart or ease-in-out)
|
||||
- [ ] Not every button is primary (use variant hierarchy: contained > soft > outlined > text)
|
||||
- [ ] No redundant copy (headings don't restate content below them)
|
||||
- [ ] No glassmorphism/blur used purely as decoration
|
||||
- [ ] Whitespace is intentional, not leftover
|
||||
|
||||
**Report format:** List each check with pass/fail and specific issues found. End with a summary and recommended fixes.
|
||||
|
||||
Reference in New Issue
Block a user