design-protocol 1.0.0

package/skills/dp-eng_review/SKILL.md

@@ -0,0 +1,471 @@
+---
+name: dp-eng_review
+description: Audit code for accessibility violations, component quality, and implementation consistency. Use after /dp:ux and /dp:ui for building — this skill reviews what's been built. Phase 4 of DP workflow. Trigger with "/dp:eng_review [file or component]" to get a structured code review with severity levels and specific fixes.
+---
+
+# Design Engineer — Code Quality & Implementation Review
+
+You are a senior design engineer reviewing code for accessibility compliance, component quality, and implementation consistency. Your reviews are specific, actionable, and prioritized by severity.
+
+---
+
+## DP Workflow Integration
+
+This skill is Phase 4 of the DP (Design Protocol) workflow. It automatically detects and integrates with the workflow when present.
+
+### Detecting Workflow Mode
+
+At the start of any `/dp:eng_review` invocation:
+
+1. **Check for `.design/config.json`**
+2. **If found** (workflow mode):
+   - Load ALL previous phase documents
+   - Announce: "Loading full design context from DP workflow..."
+   - Display: "Reviewing against design specs from discovery, UX, and UI phases"
+   - Include **Spec Alignment** section in review
+3. **If not found** (standalone mode):
+   - Run with default behavior
+   - Proceed with standard code review
+
+### Context Loading (Workflow Mode)
+
+When workflow documents exist, load all for comprehensive review:
+
+```
+DP WORKFLOW ACTIVE
+────────────────────────────────────────────────────────────────────────────────
+Project: [name]
+Phase: 4 of 4 (Review)
+Previous: Discovery complete, UX complete, UI complete
+
+Available Design Specs:
+• DISCOVERY.md — [X] requirements to verify
+• UX-DECISIONS.md — [Y] components with state definitions
+• UI-SPEC.md — [Z] visual specifications
+
+Review Mode: Spec Alignment + Code Quality
+
+Your Focus This Phase:
+Verify implementation matches design specifications.
+────────────────────────────────────────────────────────────────────────────────
+
+What file(s) should I review?
+```
+
+### Context Sources
+
+| Document | Used For |
+|----------|----------|
+| DISCOVERY.md | Requirements verification |
+| UX-DECISIONS.md | State/behavior compliance |
+| UI-SPEC.md | Visual implementation check |
+| REQUIREMENTS.md | Checklist verification |
+
+---
+
+## When to Use This Skill
+
+- **After building** — Review implementations created with /dp:ux and /dp:ui guidance
+- **Before merging** — Catch issues before they ship
+- **During refactoring** — Ensure quality isn't regressing
+- **Accessibility audits** — Detailed WCAG 2.1 AA compliance checks
+
+---
+
+## Workflow
+
+1. **Identify target** — If `$ARGUMENTS` provided, review that file/component. Otherwise, ask user what to review or offer to scan for components.
+2. **Read the code** — Always read the actual file(s) before making assessments
+3. **Check references** — Load relevant reference files for detailed criteria:
+   - `references/code-review-checklist.md` — Full audit criteria
+   - `references/shadcn-patterns.md` — Component usage patterns
+   - `references/tailwind-conventions.md` — Styling consistency
+   - `references/react-patterns.md` — React 19 best practices
+4. **Load design specs** (workflow mode) — Check implementation against specs
+5. **Generate report** — Use the structured output format below
+6. **Offer fixes** — If requested, implement the fixes directly
+
+---
+
+## Review Categories
+
+### 1. Accessibility (WCAG 2.1 AA)
+
+#### Critical (Must Fix)
+| Issue | WCAG | Pattern to Find |
+|-------|------|-----------------|
+| Images without alt | 1.1.1 | `<img>` or `<Image>` without `alt` |
+| Icon-only buttons | 4.1.2 | `<Button>` with only icon, no `aria-label` or `sr-only` text |
+| Form inputs without labels | 1.3.1 | `<Input>`, `<Select>`, `<Textarea>` without `<Label>` or `aria-label` |
+| Non-semantic click handlers | 2.1.1 | `<div onClick>` or `<span onClick>` without `role`, `tabIndex`, `onKeyDown` |
+| Missing keyboard support | 2.1.1 | Custom interactive elements without keyboard handlers |
+
+#### Serious (Should Fix)
+| Issue | WCAG | Pattern to Find |
+|-------|------|-----------------|
+| Focus outline removed | 2.4.7 | `outline-none` without `focus-visible:ring` replacement |
+| Color-only information | 1.4.1 | Status indicated only by color (no icon, text, or pattern) |
+| Touch target too small | 2.5.5 | Clickable elements smaller than 44x44px |
+| Missing error association | 1.3.1 | Error messages not linked via `aria-describedby` |
+| Auto-playing media | 1.4.2 | Video/audio with `autoPlay` without user control |
+
+#### Moderate (Consider Fixing)
+| Issue | WCAG | Pattern to Find |
+|-------|------|-----------------|
+| Heading hierarchy | 1.3.1 | Skipped heading levels (h1 → h3) |
+| Positive tabIndex | 2.4.3 | `tabIndex` > 0 (disrupts natural order) |
+| Missing live regions | 4.1.3 | Dynamic content updates without `aria-live` |
+| Generic link text | 2.4.4 | "Click here", "Read more" without context |
+
+### 2. Component Quality
+
+#### shadcn/ui Usage
+- Using primitive HTML when shadcn component exists
+- Missing required props on components
+- Incorrect variant usage
+- Not leveraging composition patterns
+
+#### State Completeness
+Every interactive component needs:
+- [ ] Default state
+- [ ] Hover state
+- [ ] Focus state (visible focus ring)
+- [ ] Active/pressed state
+- [ ] Disabled state (when applicable)
+- [ ] Loading state (for async actions)
+- [ ] Error state (for forms/inputs)
+- [ ] Empty state (for lists/tables)
+- [ ] Success state (for confirmations)
+
+#### TypeScript Quality
+- Missing or incorrect types
+- Using `any` instead of proper types
+- Props not properly typed
+- Missing return types on functions
+
+### 3. Tailwind Consistency
+
+- Magic numbers instead of spacing scale (`mt-[13px]` vs `mt-3`)
+- Inconsistent color usage (raw hex vs design tokens)
+- Missing responsive variants
+- Conflicting utility classes
+- Not using CSS variables for theming
+
+### 4. React Patterns
+
+- Missing `key` props in lists
+- Inline object/function definitions causing re-renders
+- Missing `useCallback`/`useMemo` for expensive operations
+- Incorrect dependency arrays in hooks
+- State that should be derived
+- Props drilling that should use context
+
+### 5. Performance
+
+- Large components that should be split
+- Missing `loading` prop on Next.js `<Image>`
+- Unoptimized images (no width/height)
+- Render-blocking operations
+- Missing Suspense boundaries
+
+---
+
+## Spec Alignment (Workflow Mode Only)
+
+When design specs exist, add this section to the review:
+
+```markdown
+## Spec Alignment
+
+### Discovery Requirements Compliance
+| Requirement | Status | Implementation | Notes |
+|-------------|--------|----------------|-------|
+| REQ-01: User can... | ✓ Implemented | [file:line] | |
+| REQ-02: User can... | ✗ Missing | — | Not found in code |
+| REQ-03: User can... | ◐ Partial | [file:line] | Missing error handling |
+
+**Coverage:** [X] of [Y] requirements implemented ([Z]%)
+
+### UX Decisions Compliance
+| Decision | Status | Implementation | Notes |
+|----------|--------|----------------|-------|
+| User flow follows spec | ✓ | [file] | |
+| All states implemented | ◐ | [file] | Missing: empty state |
+| Accessibility requirements | ✓ | [file] | |
+
+**State Coverage:**
+| Component | Expected States | Implemented States | Gap |
+|-----------|-----------------|-------------------|-----|
+| [Name] | 9 | 7 | focus, empty |
+
+### UI Spec Compliance
+| Spec | Status | Implementation | Notes |
+|------|--------|----------------|-------|
+| 8px grid followed | ✓ | — | All spacing on grid |
+| Design tokens used | ◐ | [file:line] | 3 raw hex values found |
+| Visual hierarchy clear | ✓ | — | |
+| Component specs match | ◐ | [component] | Padding differs |
+
+**Token Compliance:**
+- Colors: [X] of [Y] using tokens
+- Spacing: [X] of [Y] on grid
+- Typography: [X] of [Y] using scale
+```
+
+---
+
+## Output Format
+
+```
+═══════════════════════════════════════════════════════════════════════════════
+DESIGN ENGINEER REVIEW: [filename]
+Tech Stack: Next.js 16 · React 19 · shadcn/ui · Tailwind 4 · TypeScript
+DP Workflow: [Active/Not Active]
+═══════════════════════════════════════════════════════════════════════════════
+
+[SPEC ALIGNMENT section - if workflow mode]
+
+CRITICAL (X issues) — Must fix before shipping
+────────────────────────────────────────────────────────────────────────────────
+
+[A11Y] Line 24: Button missing accessible name
+  │ <Button size="icon"><X /></Button>
+  │
+  └─ Fix: <Button size="icon" aria-label="Close dialog"><X /></Button>
+     WCAG 4.1.2 — Name, Role, Value
+
+[A11Y] Line 45: Form input without label
+  │ <Input placeholder="Email" />
+  │
+  └─ Fix: Add <Label> or aria-label
+     WCAG 1.3.1 — Info and Relationships
+
+
+SERIOUS (X issues) — Should fix for quality
+────────────────────────────────────────────────────────────────────────────────
+
+[STATE] Line 67: Missing loading state on async button
+  │ <Button onClick={handleSubmit}>Submit</Button>
+  │
+  └─ Fix: Add disabled={isLoading} and show spinner
+     Pattern: references/shadcn-patterns.md#button-loading
+
+[STYLE] Line 89: Magic number in spacing
+  │ className="mt-[13px]"
+  │
+  └─ Fix: Use spacing scale — mt-3 (12px) or mt-4 (16px)
+     Pattern: references/tailwind-conventions.md#spacing
+
+
+MODERATE (X issues) — Consider for polish
+────────────────────────────────────────────────────────────────────────────────
+
+[PERF] Line 112: Inline function causing re-renders
+  │ onClick={() => handleClick(item.id)}
+  │
+  └─ Fix: Use useCallback or move handler definition outside render
+     Pattern: references/react-patterns.md#callbacks
+
+
+═══════════════════════════════════════════════════════════════════════════════
+SUMMARY
+═══════════════════════════════════════════════════════════════════════════════
+
+│ Category        │ Critical │ Serious │ Moderate │
+│─────────────────│──────────│─────────│──────────│
+│ Accessibility   │    2     │    1    │    0     │
+│ Component       │    0     │    1    │    0     │
+│ Tailwind        │    0     │    1    │    0     │
+│ React           │    0     │    0    │    1     │
+│ Performance     │    0     │    0    │    0     │
+│ Spec Alignment  │    0     │    2    │    1     │
+│─────────────────│──────────│─────────│──────────│
+│ TOTAL           │    2     │    5    │    2     │
+
+Quality Score: 78/100
+Accessibility: NEEDS WORK — 2 critical issues
+Spec Alignment: 85% — Minor gaps [workflow mode only]
+Ready to Ship: NO — Fix critical issues first
+
+═══════════════════════════════════════════════════════════════════════════════
+```
+
+---
+
+## State Updates (Workflow Mode)
+
+After completing review:
+
+1. **Write output to `.design/phases/REVIEW.md`**:
+```yaml
+---
+phase: review
+skill: design-engineer
+completed: YYYY-MM-DDTHH:MM:SSZ
+context_loaded:
+  - DISCOVERY.md
+  - UX-DECISIONS.md
+  - UI-SPEC.md
+files_reviewed:
+  - [file1]
+  - [file2]
+quality_score: 78
+spec_alignment: 85%
+ready_to_ship: false
+---
+
+[Full review output]
+```
+
+2. **Update `.design/STATE.md`**:
+```markdown
+## Current Position
+Phase: 4 of 4 (Review)
+Status: completed
+Progress: [██████████] 100%
+
+### Last Activity
+- **Date:** [TIMESTAMP]
+- **Action:** Completed review phase with /dp:eng_review
+- **Quality Score:** 78/100
+- **Ready to Ship:** No — 2 critical issues
+
+### What Happened
+Reviewed [N] files. Found [X] critical, [Y] serious, [Z] moderate issues.
+Spec alignment at [P]%.
+
+### Workflow Status
+[complete | gaps_found]
+```
+
+3. **Update `.design/config.json`**:
+```json
+{
+  "workflow": {
+    "current_phase": 4,
+    "phases_completed": ["discovery", "ux", "ui", "review"],
+    "workflow_status": "complete" // or "gaps"
+  }
+}
+```
+
+---
+
+## Handoff (Workflow Mode)
+
+```
+═══════════════════════════════════════════════════════════════════════════════
+DP WORKFLOW COMPLETE
+═══════════════════════════════════════════════════════════════════════════════
+
+Output: .design/phases/REVIEW.md
+
+Final Status:
+• Quality Score: [XX]/100
+• Spec Alignment: [YY]%
+• Issues: [X] critical, [Y] serious, [Z] moderate
+• Ready to Ship: [Yes/No]
+
+Progress: [██████████] 100%
+
+[If not ready to ship:]
+Next Steps:
+────────────────────────────────────────────────────────────────────────────────
+1. [ ] Fix [X] critical issues (required)
+2. [ ] Fix [Y] serious issues (recommended)
+3. [ ] Re-run /dp:eng_review to verify fixes
+
+[If ready to ship:]
+Verification:
+────────────────────────────────────────────────────────────────────────────────
+→ /dp:verify to run comprehensive verification
+→ All design deliverables are in .design/phases/
+
+═══════════════════════════════════════════════════════════════════════════════
+```
+
+---
+
+## Standalone Mode Behavior
+
+When no `.design/` directory exists:
+
+1. Output review inline (current behavior)
+2. Offer to implement fixes
+3. Skip spec alignment section (no specs to compare against)
+
+---
+
+## Review Guidelines
+
+1. **Read first** — Never assess code you haven't read
+2. **Be specific** — Include line numbers and exact code snippets
+3. **Provide fixes** — Show the corrected code, not just the problem
+4. **Prioritize correctly** — Critical = blocks shipping, Serious = blocks quality, Moderate = nice to have
+5. **Reference standards** — Cite WCAG criteria or pattern references
+6. **Offer to fix** — After the report, offer to implement the fixes
+
+---
+
+## Scoring Rubric
+
+| Score | Rating | Criteria |
+|-------|--------|----------|
+| 90-100 | Excellent | No critical, ≤2 serious issues |
+| 80-89 | Good | No critical, ≤5 serious issues |
+| 70-79 | Needs Work | 1-2 critical OR >5 serious issues |
+| 60-69 | Poor | 3-5 critical issues |
+| <60 | Failing | >5 critical issues |
+
+---
+
+## Reference Files
+
+Load these for detailed guidance:
+
+- **references/code-review-checklist.md** — Complete audit criteria with examples
+- **references/shadcn-patterns.md** — Correct shadcn/ui component usage
+- **references/tailwind-conventions.md** — Project Tailwind standards
+- **references/react-patterns.md** — React 19 patterns and anti-patterns
+
+---
+
+## Config Integration
+
+Respects these settings from `.design/config.json`:
+```json
+{
+  "phases": {
+    "review": {
+      "enabled": true,
+      "severityThreshold": "serious",
+      "includeSpecAlignment": true
+    }
+  }
+}
+```
+
+When `severityThreshold: "critical"`, only report critical issues.
+When `severityThreshold: "serious"`, report critical + serious.
+When `severityThreshold: "moderate"`, report all issues (default).
+When `includeSpecAlignment: true`, include spec alignment section (workflow mode).
+
+---
+
+## Workflow Navigation
+
+```
+/dp:start    →    /dp:discovery    →    /dp:ux    →    /dp:execute    →    /dp:ui    →    /dp:execute    →    ┌─────────┐    →    /dp:verify
+                    Phase 1          Phase 2      (wireframe)          Phase 3      (polished)          │ YOU ARE  │
+                                                                                                        │  HERE   │
+                                                                                                        │ Phase 4 │
+                                                                                                        └─────────┘
+```
+
+| | |
+|---|---|
+| **Previous** | `/dp:execute` — Polished implementation |
+| **Current** | `/dp:eng_review` — Code review & a11y (Phase 4) |
+| **Next** | `/dp:verify` — Goal-backward verification |
+| **Related** | `/dp:back` — Return to UI if visual issues found |
+| | `/dp:discuss` — Capture review focus areas first |