From b047199bc5ea77a337fcdac1a72f8e13e45d7d06 Mon Sep 17 00:00:00 2001 From: Eric Gullickson <16152721+ericgullickson@users.noreply.github.com> Date: Sun, 15 Feb 2026 17:19:45 -0600 Subject: [PATCH] docs: add GuidePage documentation (refs #203) - Create CLAUDE.md for GuidePage directory with architecture docs - Create CLAUDE.md index for pages/ directory Co-Authored-By: Claude Opus 4.6 --- frontend/src/pages/CLAUDE.md | 20 +++++++++++++++ frontend/src/pages/GuidePage/CLAUDE.md | 34 ++++++++++++++++++++++++++ 2 files changed, 54 insertions(+) create mode 100644 frontend/src/pages/CLAUDE.md create mode 100644 frontend/src/pages/GuidePage/CLAUDE.md diff --git a/frontend/src/pages/CLAUDE.md b/frontend/src/pages/CLAUDE.md new file mode 100644 index 0000000..8f26542 --- /dev/null +++ b/frontend/src/pages/CLAUDE.md @@ -0,0 +1,20 @@ +# frontend/src/pages/ + +Page-level components and routing targets. + +## Files + +| File | What | When to read | +| ---- | ---- | ------------ | +| `HomePage.tsx` | Public landing page (Home, Features, About, Guide, Sign Up, Login) | Modifying public site | +| `SettingsPage.tsx` | Settings page component | User settings | +| `SecuritySettingsPage.tsx` | Security settings page | Security/privacy settings | + +## Subdirectories + +| Directory | What | When to read | +| --------- | ---- | ------------ | +| `GuidePage/` | Public user guide at `/guide` (10 sections, TOC, screenshots) | Guide content or structure | +| `HomePage/` | HomePage sub-components (HeroCarousel, FeaturesGrid) | Landing page features | +| `admin/` | Admin-only pages | Admin functionality | +| `__tests__/` | Page-level integration tests | Testing pages | diff --git a/frontend/src/pages/GuidePage/CLAUDE.md b/frontend/src/pages/GuidePage/CLAUDE.md new file mode 100644 index 0000000..897bf76 --- /dev/null +++ b/frontend/src/pages/GuidePage/CLAUDE.md @@ -0,0 +1,34 @@ +# frontend/src/pages/GuidePage/ + +Public-facing user guide page at `/guide`. Renders `docs/USER-GUIDE.md` content as styled React components with screenshots. + +## Files + +| File | What | When to read | +| ---- | ---- | ------------ | +| `GuidePage.tsx` | Main page component with layout, nav bar, and section rendering | Modifying page structure or navigation | +| `GuideTableOfContents.tsx` | Sticky sidebar TOC (desktop) / collapsible accordion TOC (mobile) | Modifying TOC behavior or styling | +| `guideTypes.ts` | Section metadata (id, title, subSections) used by TOC and anchors | Adding/renaming sections | + +## Subdirectories + +| Directory | What | When to read | +| --------- | ---- | ------------ | +| `components/` | Shared components (GuideScreenshot, GuideTable) | Modifying screenshot or table rendering | +| `sections/` | 10 content section components (one per guide chapter) | Updating guide content | + +## Architecture + +- Static JSX components (no react-markdown dependency); content changes require editing section files directly +- Each section is 150-250 lines of JSX; individual files prevent a 2000+ line monolith +- GuideScreenshot provides consistent lazy loading (`loading="lazy"`), responsive sizing, and WebP support across all sections +- GuideTable renders MUI Table from `headers[]` and `rows[][]` arrays, preventing verbose MUI Table boilerplate in each section +- The page has its own public nav bar (matching HomePage style) because it is accessible without authentication +- `/guide` route is detected in App.tsx and rendered outside the authenticated `/garage/*` shell + +## Key Patterns + +- Section anchor IDs must match `guideTypes.ts` section IDs for TOC smooth scroll to work +- Screenshots stored in `frontend/public/guide/` as static assets with `loading="lazy"` +- TOC uses `window.innerWidth < 768` breakpoint: sidebar on desktop, MUI Accordion on mobile +- Guide link in HamburgerDrawer uses `window.location.href` (not Zustand navigation) because `/guide` is outside the `/garage/*` shell