syndarix/DEV_PAGES_QUICK_REFERENCE.md

Dev Pages Quick Reference

Visual Structure Comparison

Hub & Docs Pages (Hero Pattern)

┌─────────────────────────────────────────┐
│ DevLayout Global Nav (sticky)           │
├─────────────────────────────────────────┤
│ ┌───────────────────────────────────────┐│
│ │ HERO SECTION (gradient bg)            ││
│ │ - Title                               ││
│ │ - Description                         ││
│ │ - CTA Buttons                         ││
│ └───────────────────────────────────────┘│
├─────────────────────────────────────────┤
│ MAIN CONTENT                            │
│ ┌─────────────────────────────────────┐ │
│ │ Section 1 (Grid Layout)             │ │
│ └─────────────────────────────────────┘ │
│ ┌─────────────────────────────────────┐ │
│ │ Section 2 (Grid Layout)             │ │
│ └─────────────────────────────────────┘ │
│ ┌─────────────────────────────────────┐ │
│ │ Section 3 (Grid Layout)             │ │
│ └─────────────────────────────────────┘ │
└─────────────────────────────────────────┘

Forms/Layouts/Spacing Pages (Header Pattern)

┌─────────────────────────────────────────┐
│ CUSTOM STICKY HEADER (hides global nav) │
│ [Back] | Title + Subtitle               │
├─────────────────────────────────────────┤
│ MAIN CONTENT                            │
│ ┌─────────────────────────────────────┐ │
│ │ ExampleSection 1                    │ │
│ │ - Title + Description               │ │
│ │ - Example + Code tabs               │ │
│ │ - BeforeAfter if needed             │ │
│ └─────────────────────────────────────┘ │
│ ┌─────────────────────────────────────┐ │
│ │ ExampleSection 2                    │ │
│ └─────────────────────────────────────┘ │
│ ... more sections ...                   │
├─────────────────────────────────────────┤
│ FOOTER                                  │
│ [Learn more: Link to Doc]               │
└─────────────────────────────────────────┘

Components Page (Minimal Pattern)

┌─────────────────────────────────────────┐
│ DevLayout Global Nav (sticky)           │
├─────────────────────────────────────────┤
│ ComponentShowcase (dynamically loaded)  │
│ 787 lines of component examples         │
└─────────────────────────────────────────┘

---

Page Inventory

Pages Analyzed

1. /dev/page.tsx - Design System Hub
2. /dev/components/page.tsx - Component Showcase
3. /dev/forms/page.tsx - Form Patterns
4. /dev/layouts/page.tsx - Layout Patterns
5. /dev/spacing/page.tsx - Spacing Patterns
6. /dev/docs/page.tsx - Documentation Hub
7. /dev/docs/design-system/[...slug]/page.tsx - Dynamic Doc Pages

---

Key Findings

What's Duplicated

• Custom Sticky Headers (40 lines × 3 pages = 120 lines)

  • Forms page header
  • Layouts page header
  • Spacing page header

• Custom Footers (8 lines × 3 pages = 24 lines)

  • Forms page footer
  • Layouts page footer
  • Spacing page footer

Total Duplication: 144 lines

What's Missing

• Breadcrumb navigation (all pages)
• Consistent page titles (only hero/header based)
• Footers on half the pages
• Consistent component loading patterns

What's Inconsistent

1. Header implementation (custom vs inherited)
2. Page title display (hero vs header vs frontmatter)
3. Footer presence (3 pages yes, 4 pages no)
4. Page wrapper structure (min-h-screen vs not)
5. Content padding (py-12 vs py-8)
6. 'use client' directive (Forms only)
7. Dynamic imports (Components & Spacing only)

---

Component Architecture

Current Dev Components

/src/components/dev/
├── DevLayout.tsx         - Global layout wrapper (14KB)
├── Example.tsx           - Example container with tabs (5KB)
├── BeforeAfter.tsx       - Before/after comparison
├── CodeSnippet.tsx       - Code syntax highlighting
└── ComponentShowcase.tsx  - 787-line component gallery

Proposed New Components

/src/components/dev/
├── DevPageHeader.tsx     - Shared page header with back button
├── DevBreadcrumbs.tsx    - Navigation breadcrumbs
├── DevPageFooter.tsx     - Shared footer with doc links
├── DevPageLayout.tsx     - Complete page wrapper
└── ExampleLoadingSkeleton.tsx - Consistent loading state

---

Page Usage Matrix

What Each Page Actually Has

                Hub Comp Forms Layout Spacing Docs DocsDyn
'use client'     ·   ·     ✓     ·     ·       ·    ·
Custom Header    ·   ·     ✓     ✓     ✓       ·    ·
Back Button      ·   ·     ✓     ✓     ✓       ·    ·
Page Title       H   ·     H     H     H       H    FM
Breadcrumbs      ·   ·     ·     ·     ·       ·    ·
Hero Section     ✓   ·     ·     ·     ·       ✓    ·
Footer           ·   ·     ✓     ✓     ✓       ·    ·
ExampleSection   ·   ·     ✓     ✓     ✓       ·    ·
BeforeAfter      ·   ·     ✓     ✓     ✓       ·    ·
Dynamic Imports  ·   ✓     ·     ·     ✓       ·    ·
Code Duplication Low Low   High  High  High    Low  Low

Legend:
✓ = Has it
· = Doesn't have it
H = Hero section
FM = Frontmatter

What Each Page Should Have (Target)

                Hub Comp Forms Layout Spacing Docs DocsDyn
'use client'     ·   ·     ✓     ·     ·       ·    ·
Custom Header    ·   ·     ✗     ✗     ✗       ·    ·
Back Button      ·   ✓     ✓     ✓     ✓       ·    ✓
Page Title       H   ✓     ✓     ✓     ✓       H    FM
Breadcrumbs      ·   ✓     ✓     ✓     ✓       ·    ✓
Hero Section     ✓   ·     ·     ·     ·       ✓    ·
Footer           FTR FTR   ✓     ✓     ✓       FTR  FTR
ExampleSection   ·   ·     ✓     ✓     ✓       ·    ·
BeforeAfter      ·   ·     ✓     ✓     ✓       ·    ·
Dynamic Imports  ·   ✓     ·     ·     ✓       ·    ·
Code Duplication Red Red   Green Green Green   Red  Red

Legend:
✓ = Add/Keep
✗ = Remove
FTR = Use footer component
Red = Needs attention
Green = Ready

---

Implementation Roadmap

Phase 1: Extract Components (1-2 hours)

1. Create DevPageHeader.tsx - shared header
2. Create DevPageFooter.tsx - shared footer
3. Create DevPageLayout.tsx - wrapper component
4. Create DevBreadcrumbs.tsx - breadcrumb nav

Phase 2: Refactor Pages (2-3 hours)

1. Update Forms page - remove custom header, use DevPageLayout
2. Update Layouts page - remove custom header, use DevPageLayout
3. Update Spacing page - remove custom header, use DevPageLayout
4. Update Components page - add breadcrumbs & footer

Phase 3: Enhance (1-2 hours)

1. Add breadcrumbs to all non-hub pages
2. Standardize dynamic imports
3. Add consistent loading skeletons
4. Update Hub/Docs footers

Phase 4: Polish (30-60 min)

1. Add Table of Contents to long pages
2. Improve mobile responsiveness
3. Test navigation flow
4. Verify accessibility

Total Effort: 4-8 hours

---

Code Examples

Before (Duplicated Header)

// /dev/forms/page.tsx
export default function FormsPage() {
  return (
    <div className="min-h-screen bg-background">
      <header className="sticky top-0 z-50 w-full border-b bg-background/95">
        <div className="container mx-auto flex h-16 items-center gap-4 px-4">
          <Link href="/dev">
            <Button variant="ghost" size="icon">
              <ArrowLeft />
            </Button>
          </Link>
          <div>
            <h1 className="text-xl font-bold">Form Patterns</h1>
            <p className="text-sm text-muted-foreground">
              react-hook-form + Zod examples
            </p>
          </div>
        </div>
      </header>
      <main>...</main>
      <footer className="mt-16 border-t py-6">
        <Link href="/dev/docs/design-system/06-forms">
          Forms Documentation
        </Link>
      </footer>
    </div>
  );
}

After (Using Components)

// /dev/forms/page.tsx
import { DevPageLayout } from '@/components/dev/DevPageLayout';
import { ExampleSection } from '@/components/dev/Example';

export default function FormsPage() {
  return (
    <DevPageLayout
      title="Form Patterns"
      subtitle="react-hook-form + Zod examples"
      breadcrumbs={[
        { label: 'Hub', href: '/dev' },
        { label: 'Forms' }
      ]}
      footer={{
        label: 'Forms Documentation',
        href: '/dev/docs/design-system/06-forms'
      }}
      showBackButton
    >
      <div className="space-y-12">
        <ExampleSection
          title="Basic Form"
          description="..."
        >
          {/* Content */}
        </ExampleSection>
      </div>
    </DevPageLayout>
  );
}

Savings: 40 lines of code per page × 3 pages = 120 lines

---

Testing Checklist

After implementation:

• All pages display breadcrumbs (except Hub)
• All pages have page titles visible
• All pages have footers with doc links (or no links for hubs)
• Back button works on all detail pages
• Global nav is consistent across pages
• Mobile navigation works properly
• Dynamic imports show loading states
• No console errors or warnings

---

Files to Create/Modify

Create

• src/components/dev/DevPageHeader.tsx (NEW)
• src/components/dev/DevBreadcrumbs.tsx (NEW)
• src/components/dev/DevPageFooter.tsx (NEW)
• src/components/dev/DevPageLayout.tsx (NEW)

Modify

• src/app/dev/components/page.tsx
• src/app/dev/forms/page.tsx
• src/app/dev/layouts/page.tsx
• src/app/dev/spacing/page.tsx
• src/app/dev/page.tsx (footer)
• src/app/dev/docs/page.tsx (footer)
• src/app/dev/docs/design-system/[...slug]/page.tsx (footer)

Keep As-Is

• src/app/dev/layout.tsx
• src/components/dev/DevLayout.tsx
• src/components/dev/Example.tsx
• src/components/dev/BeforeAfter.tsx
• src/components/dev/CodeSnippet.tsx
• src/components/dev/ComponentShowcase.tsx

---

Metrics

Code Duplication

• Current: 144 lines duplicated
• After: 0 lines duplicated

File Complexity

• Current: 7 pages with inconsistent patterns
• After: 7 pages with consistent patterns

Component Count

• Current: 6 components
• After: 10 components (adding 4 reusable pieces)

Bundle Size Impact

• Estimate: +2-3KB for new components
• Offset by: Removing 144 lines of duplicated code

---

Related Documentation

For more details, see:

• /workdrive/workspace/Projects/HomeLab/fast-next-template/DEV_PAGES_STRUCTURE_ANALYSIS.md - Full technical analysis
• /workdrive/workspace/Projects/HomeLab/fast-next-template/frontend/docs/design-system/ - Design system docs
• /workdrive/workspace/Projects/HomeLab/fast-next-template/CLAUDE.md - Project guidelines