Page Audit

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

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

Then read the actual page

7. Find and read: src/app/(site)/<route>/page.tsx and any sibling layout/loading/error files
8. Read every component imported by the page (follow imports at least 2 levels deep)
9. 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.