# Page Audit > Audits any movemental.com page across UI, content, architecture, UX, and conversion, then writes a markdown report and a standalone fix prompt. - Skill: `joshuashepherd/page-audit` (Agent Skill) - Install (CLI): `npx skillmds add joshuashepherd/page-audit` - Raw SKILL.md: https://api.skillmd.com/api/skills/joshuashepherd/page-audit/raw - Safety review: CAUTION (external: skill-scanner PASS, skillspector PASS) - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Product & Planning, Web & Frontend, Product Analytics, Web Performance - Tags: Conversion, Design System, Markdown Report, Nextjs, Page Audit, Tailwind, Ui Audit, Ux Audit - Author: JoshuaShepherd (https://skillmd.com/u/joshuashepherd) - Updated: 2026-08-22 - Page: https://skillmd.com/skills/joshuashepherd/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)//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//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** — `` 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/-audit.md` ```markdown # 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/-fixes.md` Standalone prompt copy-pasteable into a fresh Claude Code session: ```markdown # 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.