page-audit

Holistic audit of any movemental.com page — UI, content, architecture, UX, and conversion — writes a markdown report and a standalone fix prompt.

SKILL.md

GitHub

Page Audit

Audit a page of movemental.com: $ARGUMENTS

You are acting as a senior collaborator — someone who deeply understands the project's design system, content strategy, and technical architecture. You are not running a checklist mechanically. You are looking at this page the way a thoughtful human teammate would.


Before Starting

Read these files to establish full project context:

Design & Architecture

  1. docs/design/DESIGN.md — The Digital Curator design spec (canonical)
  2. docs/build/prompts/stitch-to-react-migration.md — Stitch→React migration rules and translation table
  3. src/app/globals.css — Design tokens: @theme inline, :root, @layer base
  4. src/components/primitives/index.ts — Primitive component inventory

Project Context

  1. CLAUDE.md — Project conventions, tech stack, architecture, constraints
  2. src/app/(site)/layout.tsx — Site chrome (SiteNav + SiteFooter)

Then read the actual page

  1. Find and read: src/app/(site)/<route>/page.tsx and any sibling layout/loading/error files
  2. Read every component imported by the page (follow imports at least 2 levels deep)
  3. If the page has a Stitch source, read: docs/build/stitch/<screen-name>/code.html

The Six Lenses

Evaluate the page through each lens. For every issue, note severity (CRITICAL / HIGH / MEDIUM / LOW).

Lens 1: First Impression & User Experience

  • Clarity of purpose — Within 3 seconds, can someone tell what this page is for?
  • Visual hierarchy — Clear reading order via Eyebrow → Display → Prose → CTA pattern?
  • Scroll motivation — Does each section earn its place?
  • Tonal rhythm — Sections alternate tonal layers (default → section → elevated → midnight)?
  • Mobile experience — Works on a phone? No cramped layouts?
  • Dead ends — Can a user get stuck? Is there always a clear next action?

Lens 2: Design System Compliance (DESIGN.md)

  • Semantic tokens only — No hardcoded hex, bg-white, bg-black, text-gray-*, bg-blue-*
  • No decorative borders — Section separation via tonal stacking, not border-b
  • No decorative shadows — Only shadow-ambient or tonal stacking (Ghost Lift)
  • Typography — Inter only, display headings with tight tracking, eyebrows uppercase
  • Primitives used — Section, Container, Display, Eyebrow, Prose, SurfaceCard, FeatureSplit
  • Icons — Lucide React only, consistent sizing, aria-hidden on decorative
  • Images — next/image with alt text, explicit dimensions or fill
  • Primary is a light-switch — #0053db for actions only, not large backgrounds
  • Never pure black — text-foreground (#2a3439) or bg-inverse-surface (#101820)

Lens 3: Stitch Fidelity

  • Content match — Does the React page faithfully represent its Stitch source HTML?
  • Section coverage — Are all Stitch sections translated? Nothing dropped?
  • Copy accuracy — Headlines, body text, and data match the Stitch design?
  • Token translation — All Stitch hex values translated per migration prompt §7 table?

Lens 4: Information Architecture

  • Internal linking — Links to related pages (services, contact, evidence)?
  • CTAs — Clear, specific, appropriate for the page's funnel position?
  • SEO basics — <Metadata> export with title and description, single h1, semantic HTML
  • URL structure — Clean, descriptive route

Lens 5: Conversion Architecture

  • Next step clarity — Obvious what to do after reading?
  • Value proposition — Clear why this matters, not just what it is?
  • Trust signals — Social proof, credentials, evidence links where appropriate?

Lens 6: Technical Architecture

  • Server Components — No "use client" in page.tsx or layout.tsx
  • Layer compliance — UI uses primitives/hooks, not raw fetch
  • Type safety — Props typed, no any
  • Import hygiene — No circular imports, clean tree
  • Tailwind v4 — Canonical classes (aspect-4/5 not aspect-[4/5], bg-linear-to-* not bg-gradient-to-*)

Output: Write Two Files

File 1: Audit Report → reports/page-audits/<route-slug>-audit.md

# Page Audit: [Page Name] (`/route`)

**Audited:** [date]
**Readiness: SHIP / NEEDS WORK / BLOCKED**

## Executive Summary
[2-3 sentences]

## Scorecard
| Lens | Status | Notes |
|------|--------|-------|

Scores: STRONG / GOOD / NEEDS WORK / WEAK / BROKEN

## Detailed Findings
### [Lens Name]
#### What's Working
#### Issues
| # | Severity | Issue | Recommendation | File |
|---|----------|-------|----------------|------|

## The Collaborator Take
[3-5 paragraphs — honest, specific, constructive]

## Priority Actions
1. **[CRITICAL]** [Action] — [Why]
2. **[HIGH]** [Action] — [Why]

File 2: Fix Prompt → docs/build/prompts/page-fixes/<route-slug>-fixes.md

Standalone prompt copy-pasteable into a fresh Claude Code session:

# Fix: [Page Name] (`/route`)

## Context
You are working in the `movemental` repo — Next.js 16 + Tailwind v4 + shadcn/ui.
- pnpm only
- Semantic tokens only (DESIGN.md)
- No borders for sectioning — tonal stacking
- Inter font only
- Primary #0053db for actions only
- Primitives: Section, Container, Display, Eyebrow, Prose, SurfaceCard

## Changes
### Change 1: [Title]
**Why:** [rationale]
**File:** `[path]`
**Current:** [code]
**Replace with:** [code]

## Validation
1. `pnpm typecheck` — zero errors
2. `pnpm build` — completes clean
3. Visual verify at localhost:3000/[route]

Rules

  1. Read the actual code. Never guess based on route name.
  2. Compare against Stitch source when available in docs/build/stitch/.
  3. File:line references for every issue.
  4. Don't just flag — recommend specific fixes.
  5. The Collaborator Take is mandatory.
  6. Always write both files.
  7. This is a light-primary site with regional Midnight sections — not a dark-mode site.