@polymorphism-tech/morph-spec 4.22.0 → 5.0.1

package/framework/skills/level-0-meta/morph-frontend-review/SKILL.md

@@ -1,344 +0,0 @@
----
-name: morph-frontend-review
-description: Complete frontend audit — validates design outputs (design-system, WCAG contrast,
-  mockups), static accessibility scan (TSX + Razor), responsive screenshots at 3
-  breakpoints via Playwright, axe-core a11y at runtime, and SEO (Next.js metadata). Covers Next.js
-  Triggered at end of phase-uiux and post-implementation.
-argument-hint: "[feature-name]"
-user-invocable: true
-allowed-tools: Read, Write, Edit, Bash, Glob, Grep, AskUserQuestion,
-  mcp__playwright__browser_navigate, mcp__playwright__browser_resize,
-  mcp__playwright__browser_take_screenshot, mcp__playwright__browser_snapshot,
-  mcp__playwright__browser_evaluate, mcp__playwright__browser_console_messages
-cliVersion: "4.22.0"
-stacks:
-  - nextjs
----
-
-# Frontend Review
-
-> Complete frontend audit: design outputs, static + runtime accessibility, responsive
-> screenshots and SEO. Triggered at end of `phase-uiux` (validates design) and post-implementation
-> (validates implemented code).
-
-> **Note about MCP:** The `mcp__playwright__` prefix corresponds to the Playwright server name
-> as configured in the project's `settings.json`. If the server has a different name (e.g.,
-> `plugin_playwright_playwright`), adjust the prefix in the calls below.
-
----
-
-## Step 0 — Detect Context and Stack
-
-```bash
-node .claude/skills/morph-post-implementation/scripts/detect-stack.mjs
-```
-
-Output JSON: `{ stack: "DOTNET" | "NEXTJS" | "FULLSTACK" | "UNKNOWN", frontendPath, backendPath, startCommand }`
-
-Beyond the stack, determine the **context** by examining what exists:
-
-```bash
-# Check if design outputs exist
-ls .morph/features/$ARGUMENTS/1-ui/ 2>/dev/null
-
-# Check if implemented frontend files exist
-find . -name "*.tsx" 2>/dev/null | head -5
-```
-
-- If `.morph/features/$ARGUMENTS/1-ui/design-system.md` exists → context includes **design validation**
-- If implemented frontend files exist (`.tsx`) → context includes **implementation validation**
-- Both can coexist
-
-Store `stack`, `frontendPath`, `startCommand` and the detected context — all steps depend on them.
-
----
-
-## Step 1 — Design Outputs Validation (if context includes design validation)
-
-```bash
-morph-spec validate-feature $ARGUMENTS
-```
-
-Verify existence and quality of the 4 mandatory outputs in `.morph/features/$ARGUMENTS/1-ui/`:
-
-```
-[ ] design-system.md — color palette, typography tokens, spacing
-[ ] mockups.md — wireframes with responsive states
-[ ] components.md — technical component specs
-[ ] flows.md — user journeys and edge cases
-[ ] WCAG AA Contrast: primary and text colors ≥ 4.5:1 (check design-system.md)
-[ ] Documented touch targets: ≥ 44x44px for mobile
-[ ] Loading/error/empty states defined in mockups
-```
-
-**🚫 BLOCK** if `validate-feature` fails or mandatory outputs missing.
-
-Read `design-system.md` and manually verify that primary and text colors have a contrast ratio
-≥ 4.5:1. Reference tools: WebAIM Contrast Checker (WCAG 2.1 AA criteria).
-
----
-
-## Step 2 — Static Accessibility Scan
-
-```bash
-node .claude/skills/morph-frontend-review/scripts/scan-accessibility.mjs $frontendPath
-```
-
-The script automatically detects file extensions for Next.js (`.tsx`).
-If `frontendPath` is not defined, the script uses `.` (project root).
-
-**Checks implemented:**
-
-| ID | Severity | Files | Checks |
-|----|-----------|---------|---------|
-| `IMG_MISSING_ALT` | CRITICAL | .tsx | `<img` missing `alt=` attribute |
-| `INPUT_MISSING_LABEL` | HIGH | .tsx | `<input` without `aria-label`, `aria-labelledby`, or associated `<label for=` |
-| `HEADING_HIERARCHY` | HIGH | .tsx | Heading level skip (H1→H3 skipping H2) |
-| `LINK_NO_TEXT` | HIGH | .tsx | `<a` empty or with only icon and no `aria-label` |
-| `BUTTON_NO_TEXT` | HIGH | .tsx | `<button` no text and no `aria-label` |
-| `AUTOPLAY_MEDIA` | MEDIUM | .tsx | `<video`/`<audio` with `autoPlay` without `muted` |
-
-**🚫 BLOCK** if any CRITICAL finding or HIGH count ≥ 3.
-
-Fix all CRITICALs before continuing. For HIGH < 3, record in summary as warnings.
-
----
-
-## Step 3 — Frontend Code Scan (if context includes implementation validation)
-
-### If NEXTJS or FULLSTACK:
-
-```bash
-node .claude/skills/morph-code-review-nextjs/scripts/scan-nextjs.mjs $frontendPath
-```
-
-> Skip if already run by `post-implementation` in the same session.
-
-**🚫 BLOCK** if CRITICAL findings found.
-
----
-
-## Step 4 — Responsive Screenshots (Playwright MCP)
-
-### 4a. Detect Dev Server
-
-```bash
-node .claude/skills/morph-post-implementation/scripts/detect-dev-server.mjs "$startCommand"
-```
-
-### 4b. If dev server available (exit 0):
-
-Extract the main feature URLs by reading `spec.md`:
-
-```bash
-Read: .morph/features/$ARGUMENTS/2-design/spec.md
-```
-
-For each main page (max 3), capture screenshots at 3 breakpoints:
-
-```javascript
-// Mobile (375px)
-await mcp__playwright__browser_resize({ width: 375, height: 812 });
-await mcp__playwright__browser_navigate({ url: '<feature-url>' });
-await mcp__playwright__browser_take_screenshot({
-  type: 'png',
-  filename: `.morph/features/${ARGUMENTS}/visual-screenshots/mobile-<page>.png`
-});
-
-// Tablet (768px)
-await mcp__playwright__browser_resize({ width: 768, height: 1024 });
-await mcp__playwright__browser_navigate({ url: '<feature-url>' });
-await mcp__playwright__browser_take_screenshot({
-  type: 'png',
-  filename: `.morph/features/${ARGUMENTS}/visual-screenshots/tablet-<page>.png`
-});
-
-// Desktop (1440px)
-await mcp__playwright__browser_resize({ width: 1440, height: 900 });
-await mcp__playwright__browser_navigate({ url: '<feature-url>' });
-await mcp__playwright__browser_take_screenshot({
-  type: 'png',
-  filename: `.morph/features/${ARGUMENTS}/visual-screenshots/desktop-<page>.png`
-});
-```
-
-Screenshots saved to: `.morph/features/$ARGUMENTS/visual-screenshots/`
-(works in both phase `1-ui` and `5-implement`)
-
-### 4c. If dev server NOT available (exit 1):
-
-**⚠️ WARNING: Dev server not found.**
-
-Request explicit user confirmation before skipping screenshots:
-
-```
-Dev server not detected. Responsive screenshots via Playwright cannot be captured.
-
-Options:
-1. Start the server manually and re-run /morph-frontend-review
-2. Explicitly confirm you want to skip screenshots and why
-
-Cannot proceed to axe-core without dev server.
-```
-
-**Wait for response before continuing.**
-
----
-
-## Step 5 — axe-core Runtime (Playwright MCP, if dev server active)
-
-For each feature page (use the same URLs from Step 4):
-
-```javascript
-// Navigate to the page
-await mcp__playwright__browser_navigate({ url: '<feature-url>' });
-
-// Inject axe-core via CDN and run WCAG 2.1 AA scan
-await mcp__playwright__browser_evaluate({
-  function: `async () => {
-    if (!window.axe) {
-      await new Promise((resolve, reject) => {
-        const s = document.createElement('script');
-        s.src = 'https://cdnjs.cloudflare.com/ajax/libs/axe-core/4.9.1/axe.min.js';
-        s.onload = resolve;
-        s.onerror = reject;
-        document.head.appendChild(s);
-      });
-    }
-    const results = await window.axe.run(document, {
-      runOnly: { type: 'tag', values: ['wcag2a', 'wcag2aa'] }
-    });
-    return results.violations.map(v => ({
-      id: v.id,
-      impact: v.impact,
-      description: v.description,
-      nodes: v.nodes.length,
-      helpUrl: v.helpUrl
-    }));
-  }`
-});
-```
-
-Group violations by impact:
-- `critical` / `serious` → **🚫 BLOCK** (do not create PR)
-- `moderate` / `minor` → report as warnings in summary, non-blocking
-
-Also check for accessibility-related console errors:
-
-```javascript
-await mcp__playwright__browser_console_messages({ level: 'error' });
-```
-
----
-
-## Step 6 — SEO Check (Next.js only)
-
-Scan feature `page.tsx` files to verify metadata:
-
-```bash
-# Find feature pages
-find . -name "page.tsx" -path "*$ARGUMENTS*" 2>/dev/null
-
-# Check if they have metadata
-grep -l "export const metadata\|export async function generateMetadata" $(find . -name "page.tsx" -path "*$ARGUMENTS*" 2>/dev/null)
-```
-
-Checklist per page:
-
-```
-[ ] export const metadata with title and description
-[ ] og:title and og:description (Open Graph)
-[ ] og:image defined (for social sharing)
-[ ] No duplicate titles between pages
-[ ] robots doesn't block public page indexing
-```
-
-> SEO doesn't block PR — report as warnings in final summary.
-
----
-
-## Step 7 — Responsive Design Checklist
-
-After viewing Step 4 screenshots:
-
-```
-[ ] Mobile (375px): no horizontal scroll, buttons ≥ 44px, legible text
-[ ] Tablet (768px): layout adapts (sidebar collapses, grid adjusts columns)
-[ ] Desktop (1440px): uses available space, no stretched content
-[ ] Navigation works on all breakpoints
-[ ] Forms accessible on mobile (visible labels, large enough inputs)
-```
-
-If screenshots were not captured (dev server unavailable), mark as "unverified" and
-record in summary.
-
----
-
-## Step 8 — Summary and Artifacts
-
-Create consolidated summary file:
-
-```bash
-mkdir -p ".morph/features/$ARGUMENTS/visual-screenshots"
-```
-
-Save to `.morph/features/$ARGUMENTS/visual-screenshots/morph-frontend-review-summary.md`:
-
-```markdown
-# Frontend Review — {feature}
-
-**Date:** {date}
-**Stack:** {detected stack}
-**Context:** design validation | implementation validation | both
-
-## Results
-
-### Step 1 — Design Outputs
-- validate-feature: ✅ PASS / 🚫 BLOCK
-- Outputs verified: design-system.md, mockups.md, components.md, flows.md
-- WCAG Contrast: {result}
-
-### Step 2 — Static Accessibility Scan
-- Files scanned: {N}
-- Findings: {total} ({CRITICAL: N, HIGH: N, MEDIUM: N})
-- Status: ✅ PASS / 🚫 BLOCK
-
-### Step 3 — Frontend Code Scan
-- Status: ✅ PASS / 🚫 BLOCK / ⏭️ skipped (already run)
-
-### Step 4 — Responsive Screenshots
-- Mobile (375px): {paths or "not captured"}
-- Tablet (768px): {paths or "not captured"}
-- Desktop (1440px): {paths or "not captured"}
-
-### Step 5 — axe-core Runtime
-- Critical/serious violations: {N} → ✅ / 🚫
-- Warnings (moderate/minor): {N}
-
-### Step 6 — SEO (Next.js)
-- Pages with metadata: {N}/{total}
-- Gaps: {list or "none"}
-
-## Overall Status
-
-**{✅ PASS / 🚫 BLOCK}**
-
-{If BLOCK: reason(s) listed here}
-```
-
----
-
-## Block Summary
-
-| Step | Block Condition |
-|------|-------------------|
-| Step 1 | `validate-feature` failed or mandatory outputs missing |
-| Step 2 | Any CRITICAL finding or HIGH ≥ 3 in static scan |
-| Step 3 | Any CRITICAL finding in code scan |
-| Step 5 | Dev server active + axe-core violations `critical` or `serious` |
-
-**All BLOCKs must be resolved before creating the PR (when run post-implementation).**
-
----
-
-*MORPH-SPEC by Polymorphism Tech*