diff --git a/ANALYSIS_SUMMARY.md b/ANALYSIS_SUMMARY.md new file mode 100644 index 0000000..89b70ff --- /dev/null +++ b/ANALYSIS_SUMMARY.md @@ -0,0 +1,346 @@ +# /dev/ Pages Structure Analysis - Summary + +## Files Generated + +This analysis has produced **3 comprehensive documents**: + +1. **DEV_PAGES_STRUCTURE_ANALYSIS.md** (758 lines) + - Complete technical analysis of all 7 pages + - Detailed structure for each page + - 8 identified inconsistencies + - 8 specific recommendations + - Code duplication analysis + - Complete refactor proposal + +2. **DEV_PAGES_QUICK_REFERENCE.md** (400+ lines) + - Visual ASCII diagrams of page structures + - Quick-find tables and matrices + - Implementation roadmap + - Before/after code examples + - Testing checklist + - File modification guide + +3. **COMPONENT_IMPLEMENTATION_GUIDE.md** (600+ lines) + - Complete code for 5 new components + - Detailed usage examples + - Step-by-step implementation checklist + - Migration instructions for each page + - Testing commands + +--- + +## Key Findings at a Glance + +### Problem Statement +The `/dev/` pages exhibit **significant structural inconsistencies** that result in: +- 144 lines of duplicated code +- Inconsistent header implementations (3 pages) +- Inconsistent footer implementations (3 pages) +- No breadcrumb navigation +- Inconsistent page title display + +### Scope +- **Pages Analyzed:** 7 +- **Components Analyzed:** 6 +- **Lines of Code Reviewed:** 2,500+ +- **Inconsistencies Found:** 8 +- **Code Duplication:** 144 lines +- **Duplicated Components:** Headers (3) + Footers (3) + +--- + +## What's Wrong (The 8 Inconsistencies) + +1. **Header Implementation (CRITICAL)** + - Forms, Layouts, Spacing: Custom sticky headers + - Hub, Components, Docs: Inherited from DevLayout + - Problem: 40 lines × 3 pages = 120 lines duplicated + +2. **Page Title/Breadcrumbs (CRITICAL)** + - No breadcrumb navigation anywhere + - Page titles shown in: Hero sections, Headers, Frontmatter + - Missing: Consistent breadcrumb pattern + +3. **Footer Implementation (INCONSISTENT)** + - 3 pages have footers (Forms, Layouts, Spacing) + - 4 pages have no footers (Hub, Components, Docs, Dynamic) + - Problem: 8 lines × 3 pages = 24 lines duplicated + +4. **Page Layout Wrapper (INCONSISTENT)** + - Forms/Layouts/Spacing: min-h-screen wrapper + - Hub/Docs: No wrapper or different structure + - Components: No wrapper at all + +5. **Content Container Padding (MINOR)** + - py-12 on some pages + - py-8 on other pages + - Should be standardized + +6. **'use client' Directive (INCONSISTENT)** + - Forms: Uses 'use client' + - Others: Server components (inconsistent pattern) + +7. **Component Loading/Code Splitting (INCONSISTENT)** + - Components: Dynamic with loading state + - Spacing: Dynamic with skeleton loading + - Forms/Layouts: No dynamic imports + - Should use consistent pattern + +8. **ExampleSection Organization (INCONSISTENT)** + - Forms/Layouts/Spacing: Use ExampleSection + - Hub/Components/Docs: Don't use ExampleSection + +--- + +## Proposed Solution + +Create **5 new reusable components** to replace the duplicated code: + +``` +NEW COMPONENTS: +├── DevPageHeader.tsx - Shared header (replaces 120 lines) +├── DevPageFooter.tsx - Shared footer (replaces 24 lines) +├── DevBreadcrumbs.tsx - Navigation breadcrumbs (new feature) +├── DevPageLayout.tsx - Complete wrapper (combines above) +└── ExampleLoadingSkeleton.tsx - Consistent loading states (new feature) +``` + +**Impact:** +- Eliminates 144 lines of code duplication +- Adds breadcrumb navigation to all pages +- Standardizes page structure +- Improves maintainability +- Better UX consistency + +--- + +## Implementation Plan + +### Phase 1: Extract Components (1-2 hours) +Create the 5 new components with full TypeScript types and documentation. + +### Phase 2: Refactor Pages (2-3 hours) +Update the 7 pages to use new components: +- Forms page: Remove 40 lines of header/footer code +- Layouts page: Remove 40 lines of header/footer code +- Spacing page: Remove 40 lines of header/footer code +- Components page: Add breadcrumbs & footer +- Hub page: Add footer +- Docs page: Add footer +- Docs Dynamic: Add breadcrumbs & footer + +### Phase 3: Enhance (1-2 hours) +- Add breadcrumbs to all detail pages +- Standardize dynamic imports +- Update loading states + +### Phase 4: Polish (30-60 min) +- Test all navigation flows +- Verify mobile responsiveness +- Check accessibility + +**Total Time Estimate: 4-8 hours** + +--- + +## Page Comparison Matrix + +### Current State +``` +Feature Hub Comp Forms Layout Spacing Docs DocsDyn +Custom Header · · ✓ ✓ ✓ · · +Back Button · · ✓ ✓ ✓ · · +Page Title H · H H H H FM +Breadcrumbs · · · · · · · +Footer · · ✓ ✓ ✓ · · +Hero Section ✓ · · · · ✓ · +Code Duplication Low Low HIGH HIGH HIGH Low Low +``` + +### Target State +``` +Feature Hub Comp Forms Layout Spacing Docs DocsDyn +Custom Header · · ✗ ✗ ✗ · · +Back Button · ✓ ✓ ✓ ✓ · ✓ +Page Title H ✓ ✓ ✓ ✓ H FM +Breadcrumbs · ✓ ✓ ✓ ✓ · ✓ +Footer FTR FTR ✓ ✓ ✓ FTR FTR +Hero Section ✓ · · · · ✓ · +Code Duplication - - - - - - - +``` + +--- + +## Code Metrics + +### Before Implementation +- Total components: 6 +- Duplicated lines: 144 +- Inconsistent patterns: 8 +- Pages without footers: 4 +- Pages without breadcrumbs: 7 + +### After Implementation +- Total components: 10 (adding 4 reusable components) +- Duplicated lines: 0 +- Inconsistent patterns: 0 +- Pages without footers: 0 +- Pages without breadcrumbs: 0 + +### Bundle Impact +- New code: ~2-3 KB +- Removed code: ~6 KB +- Net savings: ~3-4 KB + +--- + +## File Changes Summary + +### Files to Create +1. `src/components/dev/DevPageHeader.tsx` +2. `src/components/dev/DevBreadcrumbs.tsx` +3. `src/components/dev/DevPageFooter.tsx` +4. `src/components/dev/DevPageLayout.tsx` +5. `src/components/dev/ExampleLoadingSkeleton.tsx` + +### Files to Modify +1. `src/app/dev/page.tsx` - Add footer +2. `src/app/dev/components/page.tsx` - Add breadcrumbs/footer +3. `src/app/dev/forms/page.tsx` - Refactor with DevPageLayout +4. `src/app/dev/layouts/page.tsx` - Refactor with DevPageLayout +5. `src/app/dev/spacing/page.tsx` - Refactor with DevPageLayout +6. `src/app/dev/docs/page.tsx` - Add footer +7. `src/app/dev/docs/design-system/[...slug]/page.tsx` - Add breadcrumbs/footer + +### Files to Keep As-Is +1. `src/app/dev/layout.tsx` +2. `src/components/dev/DevLayout.tsx` +3. `src/components/dev/Example.tsx` +4. `src/components/dev/BeforeAfter.tsx` +5. `src/components/dev/CodeSnippet.tsx` +6. `src/components/dev/ComponentShowcase.tsx` + +--- + +## How to Use These Documents + +### For Quick Overview +→ Read **DEV_PAGES_QUICK_REFERENCE.md** +- Visual diagrams +- Quick matrices +- Implementation roadmap + +### For Complete Details +→ Read **DEV_PAGES_STRUCTURE_ANALYSIS.md** +- Deep technical analysis +- Detailed comparison tables +- Complete recommendations + +### For Implementation +→ Read **COMPONENT_IMPLEMENTATION_GUIDE.md** +- Copy-paste ready code +- Step-by-step checklist +- Usage examples + +--- + +## Pages Analyzed + +1. `/dev/page.tsx` (Design System Hub) + - Server component + - Hero section with 3 content areas + - No header, footer, or breadcrumbs + - Status: Add footer + +2. `/dev/components/page.tsx` (Component Showcase) + - Server component + - Minimal structure (just ComponentShowcase wrapper) + - No header, footer, breadcrumbs, or title + - Status: Add all + +3. `/dev/forms/page.tsx` (Form Patterns) + - Client component + - Custom sticky header + footer + - 6 ExampleSections + - Status: Refactor to use DevPageLayout + +4. `/dev/layouts/page.tsx` (Layout Patterns) + - Server component + - Custom sticky header + footer + - 7 ExampleSections + - Status: Refactor to use DevPageLayout + +5. `/dev/spacing/page.tsx` (Spacing Patterns) + - Server component + - Custom sticky header + footer + - 7 ExampleSections + - Dynamic imports with skeleton loading + - Status: Refactor to use DevPageLayout + +6. `/dev/docs/page.tsx` (Documentation Hub) + - Server component + - Hero section with 3 doc sections + - No header, footer, or breadcrumbs + - Status: Add footer + +7. `/dev/docs/design-system/[...slug]/page.tsx` (Dynamic Docs) + - Server component + - Reads markdown files + - Minimal structure + - No breadcrumbs or footer + - Status: Add both + +--- + +## Success Criteria + +After implementation, all pages should: +- [ ] Have consistent header styling +- [ ] Show breadcrumb navigation (except Hub) +- [ ] Have page titles visible +- [ ] Have footers with documentation links +- [ ] Back buttons work on detail pages +- [ ] Global navigation is accessible +- [ ] Mobile layout is responsive +- [ ] No console errors +- [ ] Build passes without warnings +- [ ] E2E tests pass + +--- + +## Next Steps + +1. Review these documents with your team +2. Prioritize implementation phases +3. Create the 5 new components +4. Refactor the 7 pages +5. Test thoroughly +6. Commit changes with detailed commit message + +--- + +## Related Resources + +- **CLAUDE.md** - Project guidelines and conventions +- **frontend/docs/design-system/** - Design system documentation +- **frontend/src/components/dev/** - Current dev components +- **frontend/src/app/dev/** - All dev pages + +--- + +## Questions? + +Key questions answered in the detailed documents: + +- **Why create new components?** DRY principle - eliminate 144 lines of duplication +- **Why breadcrumbs?** Better navigation for nested routes +- **Why standardize footers?** Consistent UX across all pages +- **How long will this take?** 4-8 hours total (4 phases) +- **Will this break anything?** No - only adding/refactoring, not removing features +- **Should I do all pages at once?** Recommended: Phase 1 (components) + Phase 2 (pages) = 3-5 hours + +--- + +Generated: November 2, 2025 +Analysis Type: Very Thorough (Complete structure analysis) +Scope: All 7 pages under /dev/ route diff --git a/COMPONENT_IMPLEMENTATION_GUIDE.md b/COMPONENT_IMPLEMENTATION_GUIDE.md new file mode 100644 index 0000000..0f0c964 --- /dev/null +++ b/COMPONENT_IMPLEMENTATION_GUIDE.md @@ -0,0 +1,629 @@ +# Component Implementation Guide + +This document provides detailed code for implementing the proposed dev page components. + +## 1. DevPageHeader Component + +**File:** `src/components/dev/DevPageHeader.tsx` + +```typescript +'use client'; + +import Link from 'next/link'; +import { ArrowLeft } from 'lucide-react'; +import { Button } from '@/components/ui/button'; +import { cn } from '@/lib/utils'; + +interface DevPageHeaderProps { + title: string; + subtitle?: string; + showBackButton?: boolean; + backHref?: string; +} + +/** + * DevPageHeader + * Shared sticky header for detail pages with optional back button + * + * Replaces duplicated headers in forms, layouts, and spacing pages + * + * @example + * + */ +export function DevPageHeader({ + title, + subtitle, + showBackButton = false, + backHref = '/dev', +}: DevPageHeaderProps) { + return ( +
+
+ {showBackButton && ( + + + + )} +
+

{title}

+ {subtitle && ( +

{subtitle}

+ )} +
+
+
+ ); +} +``` + +--- + +## 2. DevBreadcrumbs Component + +**File:** `src/components/dev/DevBreadcrumbs.tsx` + +```typescript +'use client'; + +import Link from 'next/link'; +import { ChevronRight, Home } from 'lucide-react'; +import { cn } from '@/lib/utils'; + +interface Breadcrumb { + label: string; + href?: string; +} + +interface DevBreadcrumbsProps { + items: Breadcrumb[]; + className?: string; +} + +/** + * DevBreadcrumbs + * Breadcrumb navigation for showing page hierarchy + * + * @example + * + */ +export function DevBreadcrumbs({ items, className }: DevBreadcrumbsProps) { + return ( + + ); +} +``` + +--- + +## 3. DevPageFooter Component + +**File:** `src/components/dev/DevPageFooter.tsx` + +```typescript +import Link from 'next/link'; + +interface DevPageFooterProps { + documentationLink?: { + label: string; + href: string; + }; +} + +/** + * DevPageFooter + * Shared footer for dev pages with optional documentation link + * + * @example + * + */ +export function DevPageFooter({ documentationLink }: DevPageFooterProps) { + return ( +
+
+ {documentationLink ? ( +

+ Learn more:{' '} + + {documentationLink.label} + +

+ ) : ( +

+ Part of the FastNext Design System +

+ )} +
+
+ ); +} +``` + +--- + +## 4. DevPageLayout Component + +**File:** `src/components/dev/DevPageLayout.tsx` + +```typescript +import { ReactNode } from 'react'; +import { DevPageHeader } from './DevPageHeader'; +import { DevBreadcrumbs } from './DevBreadcrumbs'; +import { DevPageFooter } from './DevPageFooter'; +import { cn } from '@/lib/utils'; + +interface Breadcrumb { + label: string; + href?: string; +} + +interface DocumentationLink { + label: string; + href: string; +} + +interface DevPageLayoutProps { + title?: string; + subtitle?: string; + breadcrumbs?: Breadcrumb[]; + showBackButton?: boolean; + backHref?: string; + footer?: DocumentationLink | boolean; + children: ReactNode; + className?: string; +} + +/** + * DevPageLayout + * Complete page layout wrapper for dev pages + * + * Combines header, breadcrumbs, main content, and footer + * + * @example + * + * {/* Page content */} + * + */ +export function DevPageLayout({ + title, + subtitle, + breadcrumbs, + showBackButton = false, + backHref = '/dev', + footer, + children, + className, +}: DevPageLayoutProps) { + // Determine footer configuration + let footerLink: DocumentationLink | undefined; + if (typeof footer === 'object' && footer !== null) { + footerLink = footer; + } + + return ( +
+ {/* Breadcrumbs (optional) */} + {breadcrumbs && breadcrumbs.length > 0 && ( + + )} + + {/* Page Header (optional) */} + {title && ( + + )} + + {/* Main Content */} +
+ {children} +
+ + {/* Footer */} + {footer !== false && } +
+ ); +} +``` + +--- + +## 5. ExampleLoadingSkeleton Component + +**File:** `src/components/dev/ExampleLoadingSkeleton.tsx` + +```typescript +import { cn } from '@/lib/utils'; + +interface ExampleLoadingSkeletonProps { + count?: number; + className?: string; +} + +/** + * ExampleLoadingSkeleton + * Loading placeholder for dynamically imported example components + * + * @example + * const Example = dynamic(() => import('@/components/dev/Example'), { + * loading: () => , + * }); + */ +export function ExampleLoadingSkeleton({ + count = 1, + className, +}: ExampleLoadingSkeletonProps) { + return ( +
+ {Array.from({ length: count }).map((_, i) => ( +
+ {/* Title skeleton */} +
+ + {/* Description skeleton */} +
+
+
+
+ + {/* Content skeleton */} +
+
+ ))} +
+ ); +} +``` + +--- + +## 6. Example Page Refactoring + +### Forms Page (BEFORE) + +```typescript +export default function FormsPage() { + const [isSubmitting, setIsSubmitting] = useState(false); + // ... rest of state + + return ( +
+
+
+ + + +
+

Form Patterns

+

+ react-hook-form + Zod validation examples +

+
+
+
+ +
+ {/* Content sections */} +
+ +
+
+

+ Learn more:{' '} + + Forms Documentation + +

+
+
+
+ ); +} +``` + +### Forms Page (AFTER) + +```typescript +'use client'; + +import { useState } from 'react'; +import { DevPageLayout } from '@/components/dev/DevPageLayout'; +import { ExampleSection } from '@/components/dev/Example'; +import { BeforeAfter } from '@/components/dev/BeforeAfter'; +// ... other imports + +export default function FormsPage() { + const [isSubmitting, setIsSubmitting] = useState(false); + // ... rest of state + + return ( + +
+ {/* Content sections remain the same */} +
+ + ); +} +``` + +--- + +## 7. Updated Component Imports + +### Update Example.tsx exports (if extracting ExampleSection) + +```typescript +// src/components/dev/Example.tsx + +export function Example({ ... }) { ... } +export function ExampleGrid({ ... }) { ... } +export function ExampleSection({ ... }) { ... } +export { ExampleLoadingSkeleton } from './ExampleLoadingSkeleton'; +``` + +### Update spacing/page.tsx dynamic imports + +```typescript +import dynamic from 'next/dynamic'; +import { ExampleLoadingSkeleton } from '@/components/dev/ExampleLoadingSkeleton'; + +const Example = dynamic( + () => import('@/components/dev/Example').then((mod) => ({ + default: mod.Example + })), + { loading: () => } +); + +const ExampleSection = dynamic( + () => import('@/components/dev/Example').then((mod) => ({ + default: mod.ExampleSection + })), + { loading: () => } +); + +const BeforeAfter = dynamic( + () => import('@/components/dev/BeforeAfter').then((mod) => ({ + default: mod.BeforeAfter + })), + { loading: () => } +); +``` + +--- + +## 8. Implementation Checklist + +### Step 1: Create New Components +- [ ] Create `DevPageHeader.tsx` +- [ ] Create `DevBreadcrumbs.tsx` +- [ ] Create `DevPageFooter.tsx` +- [ ] Create `DevPageLayout.tsx` +- [ ] Create `ExampleLoadingSkeleton.tsx` + +### Step 2: Update Forms Page +- [ ] Import `DevPageLayout` +- [ ] Remove custom header +- [ ] Remove custom footer +- [ ] Wrap content with `DevPageLayout` +- [ ] Add breadcrumbs config +- [ ] Test navigation and styling + +### Step 3: Update Layouts Page +- [ ] Import `DevPageLayout` +- [ ] Remove custom header +- [ ] Remove custom footer +- [ ] Wrap content with `DevPageLayout` +- [ ] Add breadcrumbs config +- [ ] Test navigation and styling + +### Step 4: Update Spacing Page +- [ ] Import `DevPageLayout` +- [ ] Remove custom header +- [ ] Remove custom footer +- [ ] Update dynamic imports to use `ExampleLoadingSkeleton` +- [ ] Wrap content with `DevPageLayout` +- [ ] Add breadcrumbs config +- [ ] Test navigation and styling + +### Step 5: Update Components Page +- [ ] Import `DevPageLayout` and `DevBreadcrumbs` +- [ ] Add breadcrumbs +- [ ] Add footer with doc link +- [ ] Update dynamic import to use `ExampleLoadingSkeleton` +- [ ] Test navigation and styling + +### Step 6: Update Hub Page +- [ ] Import `DevPageFooter` +- [ ] Add footer component +- [ ] Test styling + +### Step 7: Update Docs Page +- [ ] Import `DevPageFooter` +- [ ] Add footer component +- [ ] Test styling + +### Step 8: Update Dynamic Docs Page +- [ ] Import `DevPageLayout` or `DevPageFooter` +- [ ] Add breadcrumbs +- [ ] Add footer +- [ ] Test navigation + +### Step 9: Testing +- [ ] All pages have consistent headers +- [ ] Breadcrumbs display correctly +- [ ] Back buttons work +- [ ] Footers are present and styled +- [ ] Mobile responsiveness intact +- [ ] No console errors + +--- + +## Usage Examples + +### Simple Detail Page (Forms/Layouts/Spacing) + +```typescript + +
+ {/* Your content */} +
+ +``` + +### Hub Page (with footer only) + +```typescript + + {/* Hero section */} + {/* Content sections */} + +``` + +### With Breadcrumbs Only + +```typescript + + {/* Content */} + +``` + +--- + +## Migration Summary + +| Page | Changes | +|------|---------| +| Forms | Remove header/footer, add DevPageLayout | +| Layouts | Remove header/footer, add DevPageLayout | +| Spacing | Remove header/footer, add DevPageLayout, update imports | +| Components | Add breadcrumbs/footer, update imports | +| Hub | Add DevPageFooter | +| Docs | Add DevPageFooter | +| Docs Dynamic | Add DevPageLayout with breadcrumbs | + +--- + +## Testing Commands + +```bash +# Type check +npm run type-check + +# Lint +npm run lint + +# E2E tests +npm run test:e2e + +# Build +npm run build +``` + diff --git a/DEV_PAGES_QUICK_REFERENCE.md b/DEV_PAGES_QUICK_REFERENCE.md new file mode 100644 index 0000000..b47617b --- /dev/null +++ b/DEV_PAGES_QUICK_REFERENCE.md @@ -0,0 +1,352 @@ +# 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) +```typescript +// /dev/forms/page.tsx +export default function FormsPage() { + return ( +
+
+
+ + + +
+

Form Patterns

+

+ react-hook-form + Zod examples +

+
+
+
+
...
+
+ + Forms Documentation + +
+
+ ); +} +``` + +### After (Using Components) +```typescript +// /dev/forms/page.tsx +import { DevPageLayout } from '@/components/dev/DevPageLayout'; +import { ExampleSection } from '@/components/dev/Example'; + +export default function FormsPage() { + return ( + +
+ + {/* Content */} + +
+ + ); +} +``` + +**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 + diff --git a/DEV_PAGES_STRUCTURE_ANALYSIS.md b/DEV_PAGES_STRUCTURE_ANALYSIS.md new file mode 100644 index 0000000..453749a --- /dev/null +++ b/DEV_PAGES_STRUCTURE_ANALYSIS.md @@ -0,0 +1,758 @@ +# Page Structure Analysis: /dev/ Routes + +## Executive Summary + +The `/dev/` pages show **significant inconsistencies** in structure, header implementation, and layout patterns. While they share a common `DevLayout` wrapper through the parent `layout.tsx`, individual pages implement their own headers and footers inconsistently, leading to duplicated code and potential maintenance issues. + +--- + +## Detailed Page Analysis + +### 1. `/dev/page.tsx` (Design System Hub) + +**Path:** `/workdrive/workspace/Projects/HomeLab/fast-next-template/frontend/src/app/dev/page.tsx` + +**Structure:** +- No `'use client'` directive (Server Component) +- No custom header (relies entirely on shared `DevLayout`) +- No footer +- Hero section with gradient background +- Multiple content sections separated by `` +- 3 main content areas: Demo Pages Grid, Documentation Links, Key Features + +**Breadcrumbs:** None +**Page Title:** None (relies on h1 in hero section: "Design System Hub") +**Footer:** None +**Header/Nav:** Inherited from `DevLayout` only + +**Components Used:** +- Icon components (Palette, Layout, Ruler, FileText, BookOpen, ArrowRight, Sparkles) +- Card, CardContent, CardDescription, CardHeader, CardTitle +- Badge, Separator, Button + +**Layout Pattern:** +``` +DevLayout (sticky header with global nav) +├── Hero Section (gradient, py-12) +├── Main Content (container, px-4, py-12) +│ ├── Demo Pages Section (space-y-12) +│ │ └── Grid (md:grid-cols-2) +│ ├── Separator +│ ├── Documentation Links Section +│ │ └── Grid (sm:grid-cols-2, lg:grid-cols-4) +│ ├── Separator +│ └── Key Features Section +│ └── Grid (sm:grid-cols-2, lg:grid-cols-3) +``` + +--- + +### 2. `/dev/components/page.tsx` (Component Showcase) + +**Path:** `/workdrive/workspace/Projects/HomeLab/fast-next-template/frontend/src/app/dev/components/page.tsx` + +**Structure:** +- No `'use client'` directive (Server Component) +- Dynamic imports with loading state +- No custom header +- No footer +- Minimal page structure - just renders `` + +**Breadcrumbs:** None +**Page Title:** None +**Footer:** None +**Header/Nav:** Inherited from `DevLayout` only + +**Components Used:** +- Dynamic `ComponentShowcase` (787 lines, code-split) + +**Layout Pattern:** +``` +DevLayout (sticky header with global nav) +├── Main Content +│ └── ComponentShowcase (dynamically loaded) +│ └── (787 lines of component examples) +``` + +**Issues:** +- Minimal structure - just a wrapper around ComponentShowcase +- No breadcrumbs to show navigation depth +- No page title/description + +--- + +### 3. `/dev/forms/page.tsx` (Form Patterns Demo) + +**Path:** `/workdrive/workspace/Projects/HomeLab/fast-next-template/frontend/src/app/dev/forms/page.tsx` + +**Structure:** +- `'use client'` directive (Client Component) +- Custom sticky header with back button and title +- Content organized in `ExampleSection` components +- Custom footer with documentation link + +**Breadcrumbs:** Implicit (back button in header) +**Page Title:** "Form Patterns" (in sticky header) +**Footer:** Yes (mt-16, border-t, py-6) +**Header/Nav:** Custom implementation (does NOT use `DevLayout`) + +**Components Used:** +- Custom sticky header with back button +- Example, ExampleSection, BeforeAfter +- Form components: Input, Label, Textarea, Select +- react-hook-form, Zod validation +- Card, Button, Badge, Alert + +**Layout Pattern:** +``` +Custom Sticky Header +├── Back button → /dev +├── Title: "Form Patterns" +├── Subtitle: "react-hook-form + Zod validation examples" + +Main Content (container, mx-auto, px-4, py-8) +├── Introduction (max-w-3xl) +├── ExampleSection × 6 +│ ├── Basic Form +│ ├── Complete Form +│ ├── Error States +│ ├── Loading States +│ ├── Zod Patterns +└── Footer (mt-16, border-t) + └── Link to /dev/docs/design-system/06-forms +``` + +**Unique Features:** +- Back button to return to hub +- Two-tab Example components (Preview/Code) +- BeforeAfter comparisons for accessibility patterns +- Custom state management (isSubmitting, submitSuccess) + +--- + +### 4. `/dev/layouts/page.tsx` (Layout Patterns Demo) + +**Path:** `/workdrive/workspace/Projects/HomeLab/fast-next-template/frontend/src/app/dev/layouts/page.tsx` + +**Structure:** +- Server Component (no `'use client'`) +- Custom sticky header with back button and title +- Content organized in `ExampleSection` components +- Custom footer with documentation link + +**Breadcrumbs:** Implicit (back button in header) +**Page Title:** "Layout Patterns" (in sticky header) +**Footer:** Yes (mt-16, border-t, py-6) +**Header/Nav:** Custom implementation (NOT `DevLayout`) + +**Components Used:** +- Custom sticky header (identical structure to forms page) +- Example, ExampleSection, BeforeAfter +- Card components, Badge, Button +- Grid3x3 icon + +**Layout Pattern:** +``` +Custom Sticky Header +├── Back button → /dev +├── Title: "Layout Patterns" +├── Subtitle: "Essential patterns for pages, dashboards, and forms" + +Main Content (container, mx-auto, px-4, py-8) +├── Introduction (max-w-3xl) +├── ExampleSection × 7 +│ ├── 1. Page Container +│ ├── 2. Dashboard Grid +│ ├── 3. Form Layout +│ ├── 4. Sidebar Layout +│ ├── 5. Centered Content +│ ├── Decision Tree (Grid vs Flex) +│ └── Responsive Patterns +└── Footer (mt-16, border-t) + └── Link to /dev/docs/design-system/03-layouts +``` + +**Issues:** +- Duplicates same header pattern as `/dev/forms/page.tsx` +- Both implement nearly identical sticky headers + +--- + +### 5. `/dev/spacing/page.tsx` (Spacing Patterns Demo) + +**Path:** `/workdrive/workspace/Projects/HomeLab/fast-next-template/frontend/src/app/dev/spacing/page.tsx` + +**Structure:** +- Server Component (no `'use client'`) +- Dynamic imports for heavy components (Example, ExampleSection, BeforeAfter) +- Custom sticky header with back button and title +- Content organized in `ExampleSection` components +- Custom footer with documentation link + +**Breadcrumbs:** Implicit (back button in header) +**Page Title:** "Spacing Patterns" (in sticky header) +**Footer:** Yes (mt-16, border-t, py-6) +**Header/Nav:** Custom implementation (NOT `DevLayout`) + +**Components Used:** +- Custom sticky header +- Dynamically loaded: Example, ExampleSection, BeforeAfter +- Card, Badge, Button +- Ruler icon + +**Layout Pattern:** +``` +Custom Sticky Header +├── Back button → /dev +├── Title: "Spacing Patterns" +├── Subtitle: "Parent-controlled spacing philosophy" + +Main Content (container, mx-auto, px-4, py-8) +├── Introduction (max-w-3xl) +├── ExampleSection × 7 +│ ├── Spacing Scale +│ ├── Gap for Flex/Grid +│ ├── Space-y for Vertical Stacks +│ ├── Anti-patterns +│ ├── Decision Tree +│ └── Common Patterns +└── Footer (mt-16, border-t) + └── Link to /dev/docs/design-system/04-spacing-philosophy +``` + +**Notable:** +- Uses dynamic imports with loading skeletons (performance optimization) +- Spacing page doesn't use `'use client'` but Example/ExampleSection ARE client components + +--- + +### 6. `/dev/docs/page.tsx` (Documentation Hub) + +**Path:** `/workdrive/workspace/Projects/HomeLab/fast-next-template/frontend/src/app/dev/docs/page.tsx` + +**Structure:** +- Server Component (no `'use client'`) +- No custom header (relies on `DevLayout`) +- No footer +- Hero section with gradient background +- Multiple documentation sections + +**Breadcrumbs:** None +**Page Title:** None (relies on h2 in hero: "Design System Documentation") +**Footer:** None +**Header/Nav:** Inherited from `DevLayout` only + +**Components Used:** +- Icon components (BookOpen, Sparkles, Layout, Palette, Code2, FileCode, Accessibility, Lightbulb, Search) +- Card, CardContent, CardDescription, CardHeader, CardTitle +- Badge, Button + +**Layout Pattern:** +``` +DevLayout (sticky header with global nav) +├── Hero Section (gradient, py-16) +│ ├── Title: "Design System Documentation" +│ ├── Description +│ └── CTA Buttons (3 variants) +├── Main Content (container, mx-auto, px-4, py-12) +│ └── Max-w-6xl +│ ├── Getting Started Section +│ │ └── Grid (md:grid-cols-2) +│ ├── Core Concepts Section +│ │ └── Grid (md:grid-cols-2, lg:grid-cols-3) +│ └── References Section +│ └── Grid (md:grid-cols-2) +``` + +--- + +### 7. `/dev/docs/design-system/[...slug]/page.tsx` (Dynamic Documentation) + +**Path:** `/workdrive/workspace/Projects/HomeLab/fast-next-template/frontend/src/app/dev/docs/design-system/[...slug]/page.tsx` + +**Structure:** +- Server Component with async rendering +- Reads markdown files from disk +- No custom header (relies on `DevLayout`) +- No footer +- Minimal wrapper structure + +**Breadcrumbs:** None +**Page Title:** Extracted from markdown frontmatter +**Footer:** None +**Header/Nav:** Inherited from `DevLayout` only + +**Components Used:** +- MarkdownContent (renders parsed markdown) +- gray-matter (for frontmatter parsing) + +**Layout Pattern:** +``` +DevLayout (sticky header with global nav) +├── Main Content (container, mx-auto, px-4, py-8) +│ └── Max-w-4xl +│ └── MarkdownContent +│ └── Rendered markdown from file system +``` + +**Notable:** +- Uses `generateStaticParams()` for static generation +- Minimal structure - just content wrapper +- No breadcrumbs despite being nested route + +--- + +## Structure Comparison Table + +| Aspect | Hub | Components | Forms | Layouts | Spacing | Docs | Docs Dynamic | +|--------|-----|-----------|-------|---------|---------|------|------| +| `'use client'` | No | No | YES | No | No | No | No | +| Custom Header | No | No | YES | YES | YES | No | No | +| Sticky Header | N/A | N/A | YES | YES | YES | N/A | N/A | +| Back Button | No | No | YES | YES | YES | No | No | +| Page Title Display | Hero only | None | Header | Header | Header | Hero only | Frontmatter | +| Breadcrumbs | None | None | Implicit | Implicit | Implicit | None | None | +| Custom Footer | No | No | YES | YES | YES | No | No | +| Hero Section | YES | No | No | No | No | YES | No | +| Footer Documentation Link | No | No | YES | YES | YES | No | No | +| ExampleSection Usage | No | No | YES | YES | YES | No | No | +| BeforeAfter Usage | No | No | YES | YES | YES | No | No | +| Dynamic Imports | No | YES | No | No | YES | No | No | +| Content Sections | 3 | 1 | 6 | 7 | 7 | 3 | 1 | + +--- + +## Identified Inconsistencies + +### 1. Header Implementation (CRITICAL) +**Problem:** Forms, Layouts, and Spacing pages implement duplicate custom sticky headers instead of using `DevLayout`. + +**Current Pattern (Forms/Layouts/Spacing):** +```typescript +
+
+ + + +
+

{title}

+

{subtitle}

+
+
+
+``` + +**Problem:** +- Duplicated across 3 pages (DRY violation) +- DevLayout is ignored on these pages +- Breaking point: Sticky headers override global nav + +**Expected:** Should use a shared pattern or component + +--- + +### 2. Page Title/Breadcrumbs (CRITICAL) +**Problem:** No consistent pattern for breadcrumbs or page titles. + +- Hub, Docs: Hero section titles +- Components: No title at all +- Forms, Layouts, Spacing: Header titles only +- Docs Dynamic: Frontmatter (if present) + +**Missing:** True breadcrumb navigation for nested routes + +--- + +### 3. Footer Implementation (INCONSISTENT) +**Problem:** Some pages have footers, others don't. + +**Pages with footers:** +- Forms: `