Remove analysis documents (ANALYSIS_SUMMARY.md, COMPONENT_IMPLEMENTATION_GUIDE.md, DEV_PAGES_QUICK_REFERENCE.md) for /dev/ pages refactor. Content has been fully implemented in codebase.
This commit is contained in:
@@ -1,346 +0,0 @@
|
||||
# /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
|
||||
@@ -1,629 +0,0 @@
|
||||
# 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
|
||||
* <DevPageHeader
|
||||
* title="Form Patterns"
|
||||
* subtitle="react-hook-form + Zod examples"
|
||||
* showBackButton
|
||||
* backHref="/dev"
|
||||
* />
|
||||
*/
|
||||
export function DevPageHeader({
|
||||
title,
|
||||
subtitle,
|
||||
showBackButton = false,
|
||||
backHref = '/dev',
|
||||
}: DevPageHeaderProps) {
|
||||
return (
|
||||
<header className="sticky top-0 z-50 w-full border-b bg-background/95 backdrop-blur supports-[backdrop-filter]:bg-background/60">
|
||||
<div className="container mx-auto flex h-16 items-center gap-4 px-4">
|
||||
{showBackButton && (
|
||||
<Link href={backHref}>
|
||||
<Button
|
||||
variant="ghost"
|
||||
size="icon"
|
||||
aria-label="Back to previous page"
|
||||
>
|
||||
<ArrowLeft className="h-5 w-5" />
|
||||
</Button>
|
||||
</Link>
|
||||
)}
|
||||
<div className="flex-1">
|
||||
<h1 className="text-xl font-bold">{title}</h1>
|
||||
{subtitle && (
|
||||
<p className="text-sm text-muted-foreground">{subtitle}</p>
|
||||
)}
|
||||
</div>
|
||||
</div>
|
||||
</header>
|
||||
);
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 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
|
||||
* <DevBreadcrumbs
|
||||
* items={[
|
||||
* { label: 'Hub', href: '/dev' },
|
||||
* { label: 'Forms' }
|
||||
* ]}
|
||||
* />
|
||||
*/
|
||||
export function DevBreadcrumbs({ items, className }: DevBreadcrumbsProps) {
|
||||
return (
|
||||
<nav
|
||||
className={cn('bg-muted/30 border-b px-4 py-2', className)}
|
||||
aria-label="Breadcrumb"
|
||||
>
|
||||
<ol className="container mx-auto flex items-center gap-2 text-sm">
|
||||
{/* Home link */}
|
||||
<li>
|
||||
<Link
|
||||
href="/dev"
|
||||
className="inline-flex items-center gap-1 text-muted-foreground hover:text-foreground transition-colors"
|
||||
>
|
||||
<Home className="h-4 w-4" />
|
||||
<span className="sr-only">Home</span>
|
||||
</Link>
|
||||
</li>
|
||||
|
||||
{/* Breadcrumb items */}
|
||||
{items.map((item, index) => (
|
||||
<li key={index} className="flex items-center gap-2">
|
||||
<ChevronRight className="h-4 w-4 text-muted-foreground" />
|
||||
{item.href ? (
|
||||
<Link
|
||||
href={item.href}
|
||||
className="text-muted-foreground hover:text-foreground transition-colors"
|
||||
>
|
||||
{item.label}
|
||||
</Link>
|
||||
) : (
|
||||
<span className="text-foreground font-medium">{item.label}</span>
|
||||
)}
|
||||
</li>
|
||||
))}
|
||||
</ol>
|
||||
</nav>
|
||||
);
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 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
|
||||
* <DevPageFooter
|
||||
* documentationLink={{
|
||||
* label: 'Forms Documentation',
|
||||
* href: '/dev/docs/design-system/06-forms'
|
||||
* }}
|
||||
* />
|
||||
*/
|
||||
export function DevPageFooter({ documentationLink }: DevPageFooterProps) {
|
||||
return (
|
||||
<footer className="mt-16 border-t py-6">
|
||||
<div className="container mx-auto px-4">
|
||||
{documentationLink ? (
|
||||
<p className="text-center text-sm text-muted-foreground">
|
||||
Learn more:{' '}
|
||||
<Link
|
||||
href={documentationLink.href}
|
||||
className="font-medium hover:text-foreground transition-colors"
|
||||
>
|
||||
{documentationLink.label}
|
||||
</Link>
|
||||
</p>
|
||||
) : (
|
||||
<p className="text-center text-sm text-muted-foreground">
|
||||
Part of the FastNext Design System
|
||||
</p>
|
||||
)}
|
||||
</div>
|
||||
</footer>
|
||||
);
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 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
|
||||
* <DevPageLayout
|
||||
* title="Form Patterns"
|
||||
* subtitle="Complete form examples"
|
||||
* breadcrumbs={[
|
||||
* { label: 'Hub', href: '/dev' },
|
||||
* { label: 'Forms' }
|
||||
* ]}
|
||||
* footer={{
|
||||
* label: 'Forms Documentation',
|
||||
* href: '/dev/docs/design-system/06-forms'
|
||||
* }}
|
||||
* showBackButton
|
||||
* >
|
||||
* {/* Page content */}
|
||||
* </DevPageLayout>
|
||||
*/
|
||||
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 (
|
||||
<div className="min-h-screen bg-background">
|
||||
{/* Breadcrumbs (optional) */}
|
||||
{breadcrumbs && breadcrumbs.length > 0 && (
|
||||
<DevBreadcrumbs items={breadcrumbs} />
|
||||
)}
|
||||
|
||||
{/* Page Header (optional) */}
|
||||
{title && (
|
||||
<DevPageHeader
|
||||
title={title}
|
||||
subtitle={subtitle}
|
||||
showBackButton={showBackButton}
|
||||
backHref={backHref}
|
||||
/>
|
||||
)}
|
||||
|
||||
{/* Main Content */}
|
||||
<main className={cn('container mx-auto px-4 py-8', className)}>
|
||||
{children}
|
||||
</main>
|
||||
|
||||
{/* Footer */}
|
||||
{footer !== false && <DevPageFooter documentationLink={footerLink} />}
|
||||
</div>
|
||||
);
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 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: () => <ExampleLoadingSkeleton />,
|
||||
* });
|
||||
*/
|
||||
export function ExampleLoadingSkeleton({
|
||||
count = 1,
|
||||
className,
|
||||
}: ExampleLoadingSkeletonProps) {
|
||||
return (
|
||||
<div className={cn('space-y-4', className)}>
|
||||
{Array.from({ length: count }).map((_, i) => (
|
||||
<div
|
||||
key={i}
|
||||
className="animate-pulse space-y-4 rounded-lg border p-6"
|
||||
>
|
||||
{/* Title skeleton */}
|
||||
<div className="h-6 w-48 rounded bg-muted" />
|
||||
|
||||
{/* Description skeleton */}
|
||||
<div className="space-y-2">
|
||||
<div className="h-4 w-full rounded bg-muted" />
|
||||
<div className="h-4 w-3/4 rounded bg-muted" />
|
||||
</div>
|
||||
|
||||
{/* Content skeleton */}
|
||||
<div className="h-32 rounded bg-muted" />
|
||||
</div>
|
||||
))}
|
||||
</div>
|
||||
);
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 6. Example Page Refactoring
|
||||
|
||||
### Forms Page (BEFORE)
|
||||
|
||||
```typescript
|
||||
export default function FormsPage() {
|
||||
const [isSubmitting, setIsSubmitting] = useState(false);
|
||||
// ... rest of state
|
||||
|
||||
return (
|
||||
<div className="min-h-screen bg-background">
|
||||
<header className="sticky top-0 z-50 w-full border-b bg-background/95 backdrop-blur supports-[backdrop-filter]:bg-background/60">
|
||||
<div className="container mx-auto flex h-16 items-center gap-4 px-4">
|
||||
<Link href="/dev">
|
||||
<Button variant="ghost" size="icon" aria-label="Back to hub">
|
||||
<ArrowLeft className="h-5 w-5" />
|
||||
</Button>
|
||||
</Link>
|
||||
<div>
|
||||
<h1 className="text-xl font-bold">Form Patterns</h1>
|
||||
<p className="text-sm text-muted-foreground">
|
||||
react-hook-form + Zod validation examples
|
||||
</p>
|
||||
</div>
|
||||
</div>
|
||||
</header>
|
||||
|
||||
<main className="container mx-auto px-4 py-8">
|
||||
{/* Content sections */}
|
||||
</main>
|
||||
|
||||
<footer className="mt-16 border-t py-6">
|
||||
<div className="container mx-auto px-4 text-center">
|
||||
<p className="text-sm text-muted-foreground">
|
||||
Learn more:{' '}
|
||||
<Link
|
||||
href="/dev/docs/design-system/06-forms"
|
||||
className="font-medium hover:text-foreground"
|
||||
>
|
||||
Forms Documentation
|
||||
</Link>
|
||||
</p>
|
||||
</div>
|
||||
</footer>
|
||||
</div>
|
||||
);
|
||||
}
|
||||
```
|
||||
|
||||
### 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 (
|
||||
<DevPageLayout
|
||||
title="Form Patterns"
|
||||
subtitle="react-hook-form + Zod validation 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">
|
||||
{/* Content sections remain the same */}
|
||||
</div>
|
||||
</DevPageLayout>
|
||||
);
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 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: () => <ExampleLoadingSkeleton /> }
|
||||
);
|
||||
|
||||
const ExampleSection = dynamic(
|
||||
() => import('@/components/dev/Example').then((mod) => ({
|
||||
default: mod.ExampleSection
|
||||
})),
|
||||
{ loading: () => <ExampleLoadingSkeleton /> }
|
||||
);
|
||||
|
||||
const BeforeAfter = dynamic(
|
||||
() => import('@/components/dev/BeforeAfter').then((mod) => ({
|
||||
default: mod.BeforeAfter
|
||||
})),
|
||||
{ loading: () => <ExampleLoadingSkeleton /> }
|
||||
);
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 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
|
||||
<DevPageLayout
|
||||
title="Form Patterns"
|
||||
subtitle="Complete form 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">
|
||||
{/* Your content */}
|
||||
</div>
|
||||
</DevPageLayout>
|
||||
```
|
||||
|
||||
### Hub Page (with footer only)
|
||||
|
||||
```typescript
|
||||
<DevPageLayout footer={false}>
|
||||
{/* Hero section */}
|
||||
{/* Content sections */}
|
||||
</DevPageLayout>
|
||||
```
|
||||
|
||||
### With Breadcrumbs Only
|
||||
|
||||
```typescript
|
||||
<DevPageLayout
|
||||
breadcrumbs={[
|
||||
{ label: 'Docs', href: '/dev/docs' },
|
||||
{ label: 'Forms' }
|
||||
]}
|
||||
>
|
||||
{/* Content */}
|
||||
</DevPageLayout>
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 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
|
||||
```
|
||||
|
||||
@@ -1,352 +0,0 @@
|
||||
# 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 (
|
||||
<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)
|
||||
```typescript
|
||||
// /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
|
||||
|
||||
@@ -1,758 +0,0 @@
|
||||
# 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 `<Separator />`
|
||||
- 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 `<ComponentShowcase />`
|
||||
|
||||
**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
|
||||
<header className="sticky top-0 z-50 w-full border-b bg-background/95 backdrop-blur">
|
||||
<div className="container mx-auto flex h-16 items-center gap-4 px-4">
|
||||
<Link href="/dev">
|
||||
<Button variant="ghost" size="icon" aria-label="Back to hub">
|
||||
<ArrowLeft className="h-5 w-5" />
|
||||
</Button>
|
||||
</Link>
|
||||
<div>
|
||||
<h1 className="text-xl font-bold">{title}</h1>
|
||||
<p className="text-sm text-muted-foreground">{subtitle}</p>
|
||||
</div>
|
||||
</div>
|
||||
</header>
|
||||
```
|
||||
|
||||
**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: `<footer className="mt-16 border-t py-6">`
|
||||
- Layouts: `<footer className="mt-16 border-t py-6">`
|
||||
- Spacing: `<footer className="mt-16 border-t py-6">`
|
||||
|
||||
**Pages without footers:**
|
||||
- Hub: None
|
||||
- Components: None
|
||||
- Docs: None
|
||||
- Docs Dynamic: None
|
||||
|
||||
**Issue:** Documentation link footers only on 3 pages creates inconsistent UX
|
||||
|
||||
---
|
||||
|
||||
### 4. Page Layout Wrapper (INCONSISTENT)
|
||||
**Problem:** Inconsistent use of wrapper divs.
|
||||
|
||||
**Forms/Layouts/Spacing:**
|
||||
```typescript
|
||||
<div className="min-h-screen bg-background">
|
||||
<header>...</header>
|
||||
<main>...</main>
|
||||
<footer>...</footer>
|
||||
</div>
|
||||
```
|
||||
|
||||
**Hub/Docs:**
|
||||
```typescript
|
||||
<div className="bg-background">
|
||||
{/* Hero Section */}
|
||||
<section>...</section>
|
||||
<main>...</main>
|
||||
</div>
|
||||
```
|
||||
|
||||
**Components:**
|
||||
No wrapper at all - just `<ComponentShowcase />`
|
||||
|
||||
---
|
||||
|
||||
### 5. Content Container Padding (MINOR)
|
||||
**Problem:** Inconsistent container and padding patterns.
|
||||
|
||||
```
|
||||
Hub/Docs: container mx-auto px-4 py-12
|
||||
Forms/Layouts/Spacing: container mx-auto px-4 py-8
|
||||
Docs Dynamic: container mx-auto px-4 py-8
|
||||
```
|
||||
|
||||
**Expected:** Standardized to `py-8` or `py-12` across all
|
||||
|
||||
---
|
||||
|
||||
### 6. 'use client' Directive (INCONSISTENT)
|
||||
**Problem:** Inconsistent use of client vs server components.
|
||||
|
||||
- Forms: `'use client'` (needs interactivity)
|
||||
- Others: Server components (except those with dynamic imports)
|
||||
- Spacing: Server component with dynamic client imports
|
||||
|
||||
**Question:** Should all pages be consistent?
|
||||
|
||||
---
|
||||
|
||||
### 7. Component Loading/Code Splitting (INCONSISTENT)
|
||||
**Problem:** Inconsistent approach to component loading.
|
||||
|
||||
**Components Page:**
|
||||
- Uses dynamic imports with loading state
|
||||
|
||||
**Spacing Page:**
|
||||
- Uses dynamic imports with skeleton loading
|
||||
|
||||
**Forms/Layouts Pages:**
|
||||
- No dynamic imports, inline all components
|
||||
|
||||
**Expected:** Consistent strategy across demo pages
|
||||
|
||||
---
|
||||
|
||||
### 8. ExampleSection Organization (INCONSISTENT)
|
||||
**Problem:** Not all pages use `ExampleSection`.
|
||||
|
||||
- Hub: No ExampleSection (custom layout)
|
||||
- Components: No ExampleSection (uses ComponentShowcase)
|
||||
- Forms/Layouts/Spacing: All use ExampleSection
|
||||
- Docs: No ExampleSection
|
||||
- Docs Dynamic: No ExampleSection
|
||||
|
||||
---
|
||||
|
||||
## Common Patterns Found
|
||||
|
||||
### Pattern 1: Hero Section + Grid Layout (Hub, Docs)
|
||||
```typescript
|
||||
<section className="border-b bg-gradient-to-b from-background to-muted/20 py-12">
|
||||
<div className="container mx-auto px-4">
|
||||
{/* Content */}
|
||||
</div>
|
||||
</section>
|
||||
<main className="container mx-auto px-4 py-12">
|
||||
<div className="space-y-12">
|
||||
{/* Multiple sections with grids */}
|
||||
</div>
|
||||
</main>
|
||||
```
|
||||
|
||||
### Pattern 2: Sticky Header + Sections (Forms, Layouts, Spacing)
|
||||
```typescript
|
||||
<header className="sticky top-0 z-50...">
|
||||
{/* Custom header with back button */}
|
||||
</header>
|
||||
<main className="container mx-auto px-4 py-8">
|
||||
<div className="space-y-12">
|
||||
<ExampleSection>{...}</ExampleSection>
|
||||
</div>
|
||||
</main>
|
||||
<footer className="mt-16 border-t py-6">{...}</footer>
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Recommendations
|
||||
|
||||
### 1. CREATE SHARED HEADER COMPONENT (HIGH PRIORITY)
|
||||
Create `/src/components/dev/DevPageHeader.tsx`:
|
||||
|
||||
```typescript
|
||||
interface DevPageHeaderProps {
|
||||
title: string;
|
||||
subtitle?: string;
|
||||
showBackButton?: boolean;
|
||||
breadcrumbs?: Array<{ label: string; href: string }>;
|
||||
}
|
||||
|
||||
export function DevPageHeader({ title, subtitle, showBackButton, breadcrumbs }: DevPageHeaderProps) {
|
||||
// Replaces duplicated headers in forms, layouts, spacing pages
|
||||
}
|
||||
```
|
||||
|
||||
**Impact:** Reduces code duplication, standardizes header UX
|
||||
|
||||
---
|
||||
|
||||
### 2. ADD BREADCRUMBS COMPONENT (MEDIUM PRIORITY)
|
||||
Create `/src/components/dev/DevBreadcrumbs.tsx`:
|
||||
|
||||
```typescript
|
||||
interface Breadcrumb {
|
||||
label: string;
|
||||
href: string;
|
||||
}
|
||||
|
||||
export function DevBreadcrumbs({ items }: { items: Breadcrumb[] }) {
|
||||
// Renders: Home > Section > Current Page
|
||||
}
|
||||
```
|
||||
|
||||
**Usage:**
|
||||
- Hub: None
|
||||
- Components: `[{ label: 'Hub', href: '/dev' }, { label: 'Components' }]`
|
||||
- Forms: `[{ label: 'Hub', href: '/dev' }, { label: 'Forms' }]`
|
||||
- Layouts: `[{ label: 'Hub', href: '/dev' }, { label: 'Layouts' }]`
|
||||
- Spacing: `[{ label: 'Hub', href: '/dev' }, { label: 'Spacing' }]`
|
||||
- Docs: `[{ label: 'Hub', href: '/dev' }, { label: 'Docs' }]`
|
||||
- Docs Dynamic: `[{ label: 'Docs', href: '/dev/docs' }, { label: currentTitle }]`
|
||||
|
||||
---
|
||||
|
||||
### 3. STANDARDIZE FOOTER (MEDIUM PRIORITY)
|
||||
Create `/src/components/dev/DevPageFooter.tsx`:
|
||||
|
||||
```typescript
|
||||
interface DevPageFooterProps {
|
||||
documentationLink?: {
|
||||
label: string;
|
||||
href: string;
|
||||
};
|
||||
}
|
||||
|
||||
export function DevPageFooter({ documentationLink }: DevPageFooterProps) {
|
||||
return (
|
||||
<footer className="mt-16 border-t py-6">
|
||||
{documentationLink && (
|
||||
<div className="container mx-auto px-4 text-center">
|
||||
<p className="text-sm text-muted-foreground">
|
||||
Learn more:{' '}
|
||||
<Link href={documentationLink.href} className="font-medium hover:text-foreground">
|
||||
{documentationLink.label}
|
||||
</Link>
|
||||
</p>
|
||||
</div>
|
||||
)}
|
||||
</footer>
|
||||
);
|
||||
}
|
||||
```
|
||||
|
||||
**Add to ALL pages:** Hub, Components, Forms, Layouts, Spacing, Docs
|
||||
|
||||
---
|
||||
|
||||
### 4. CREATE DEVPAGE LAYOUT WRAPPER (HIGH PRIORITY)
|
||||
Create `/src/components/dev/DevPageLayout.tsx`:
|
||||
|
||||
```typescript
|
||||
interface DevPageLayoutProps {
|
||||
title?: string;
|
||||
subtitle?: string;
|
||||
breadcrumbs?: Breadcrumb[];
|
||||
showBackButton?: boolean;
|
||||
footer?: { label: string; href: string };
|
||||
children: React.ReactNode;
|
||||
}
|
||||
|
||||
export function DevPageLayout({
|
||||
title,
|
||||
subtitle,
|
||||
breadcrumbs,
|
||||
showBackButton,
|
||||
footer,
|
||||
children,
|
||||
}: DevPageLayoutProps) {
|
||||
return (
|
||||
<div className="min-h-screen bg-background">
|
||||
{breadcrumbs && <DevBreadcrumbs items={breadcrumbs} />}
|
||||
{title && (
|
||||
<DevPageHeader
|
||||
title={title}
|
||||
subtitle={subtitle}
|
||||
showBackButton={showBackButton}
|
||||
breadcrumbs={breadcrumbs}
|
||||
/>
|
||||
)}
|
||||
<main className="container mx-auto px-4 py-8">{children}</main>
|
||||
{footer && <DevPageFooter documentationLink={footer} />}
|
||||
</div>
|
||||
);
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 5. STANDARDIZE COMPONENT LOADING (MEDIUM PRIORITY)
|
||||
Use consistent pattern for code-splitting:
|
||||
|
||||
**Create loading skeleton component:**
|
||||
```typescript
|
||||
export function ExampleLoadingSkeleton() {
|
||||
return <div className="animate-pulse h-64 bg-muted rounded-lg" />;
|
||||
}
|
||||
```
|
||||
|
||||
**Use in all heavy components:**
|
||||
```typescript
|
||||
const ComponentShowcase = dynamic(() => import('@/components/dev/ComponentShowcase'), {
|
||||
loading: () => <ExampleLoadingSkeleton />,
|
||||
});
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 6. UPDATE DevLayout TO NOT OVERRIDE (MEDIUM PRIORITY)
|
||||
Current issue: Forms, Layouts, Spacing pages implement custom headers that hide global nav.
|
||||
|
||||
**Solution:** Update those pages to use DevLayout properly OR explicitly extend it:
|
||||
|
||||
```typescript
|
||||
// Option A: Remove custom headers and use DevLayout's nav + page title
|
||||
// Option B: Make DevLayout flexible to show page-specific titles
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 7. AUDIT Components PAGE (LOW PRIORITY)
|
||||
The Components page is minimal - just a wrapper around ComponentShowcase.
|
||||
|
||||
**Consider:**
|
||||
- Add breadcrumbs
|
||||
- Add footer
|
||||
- Add page title/subtitle
|
||||
- Show 787-line warning or lazy load sections
|
||||
|
||||
---
|
||||
|
||||
### 8. ADD TABLE OF CONTENTS (LOW PRIORITY)
|
||||
For longer pages (Layouts, Spacing), add sidebar with section navigation:
|
||||
|
||||
```typescript
|
||||
const sections = [
|
||||
{ id: 'spacing-scale', label: 'Spacing Scale' },
|
||||
{ id: 'gap', label: 'Gap for Flex/Grid' },
|
||||
// ...
|
||||
];
|
||||
|
||||
<TableOfContents sections={sections} />
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Implementation Priority
|
||||
|
||||
**Phase 1 (Critical - Fixes inconsistencies):**
|
||||
1. Create `DevPageHeader` component
|
||||
2. Create `DevPageLayout` wrapper
|
||||
3. Update Forms/Layouts/Spacing pages to use new components
|
||||
|
||||
**Phase 2 (Important - UX improvements):**
|
||||
1. Create `DevBreadcrumbs` component
|
||||
2. Create `DevPageFooter` component
|
||||
3. Add breadcrumbs to all pages
|
||||
4. Standardize footers
|
||||
|
||||
**Phase 3 (Nice to have - Polish):**
|
||||
1. Add Table of Contents to long pages
|
||||
2. Audit Components page structure
|
||||
3. Standardize dynamic imports
|
||||
4. Add loading states to all dynamic components
|
||||
|
||||
---
|
||||
|
||||
## Code Duplication Analysis
|
||||
|
||||
### Header Duplication (3 pages - 40 lines × 3)
|
||||
```
|
||||
/dev/forms/page.tsx: Lines 99-113
|
||||
/dev/layouts/page.tsx: Lines 31-45
|
||||
/dev/spacing/page.tsx: Lines 46-60
|
||||
|
||||
Total duplicated: ~40 lines × 3 = 120 lines of nearly identical code
|
||||
```
|
||||
|
||||
### Footer Duplication (3 pages - 8 lines × 3)
|
||||
```
|
||||
/dev/forms/page.tsx: Lines 572-584
|
||||
/dev/layouts/page.tsx: Lines 507-519
|
||||
/dev/spacing/page.tsx: Lines 520-532
|
||||
|
||||
Total duplicated: ~8 lines × 3 = 24 lines of identical code
|
||||
```
|
||||
|
||||
**Total Duplication:** 144 lines of code that could be extracted into components
|
||||
|
||||
---
|
||||
|
||||
## File Structure Refactor Proposal
|
||||
|
||||
```
|
||||
frontend/src/components/dev/
|
||||
├── DevLayout.tsx (current - global layout)
|
||||
├── DevPageHeader.tsx (NEW - shared page header)
|
||||
├── DevBreadcrumbs.tsx (NEW - breadcrumb navigation)
|
||||
├── DevPageFooter.tsx (NEW - shared page footer)
|
||||
├── DevPageLayout.tsx (NEW - complete page wrapper)
|
||||
├── Example.tsx (current - example container)
|
||||
├── ExampleSection.tsx (extracted from Example.tsx)
|
||||
├── ExampleGrid.tsx (extracted from Example.tsx)
|
||||
├── BeforeAfter.tsx (current)
|
||||
├── CodeSnippet.tsx (current)
|
||||
└── ComponentShowcase.tsx (current)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Summary Table: What Each Page Should Have
|
||||
|
||||
| Element | Hub | Components | Forms | Layouts | Spacing | Docs | Docs Dyn |
|
||||
|---------|-----|-----------|-------|---------|---------|------|----------|
|
||||
| Breadcrumbs | ✗ | ✓ | ✓ | ✓ | ✓ | ✗ | ✓ |
|
||||
| Page Title | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
|
||||
| Hero Section | ✓ | ✗ | ✗ | ✗ | ✗ | ✓ | ✗ |
|
||||
| Sticky Header | ✗ | ✗ | ✓ | ✓ | ✓ | ✗ | ✗ |
|
||||
| Footer | ✗ | ✗ | ✓ | ✓ | ✓ | ✗ | ✗ |
|
||||
| Back Button | ✗ | ✓ | ✓ | ✓ | ✓ | ✗ | ✓ |
|
||||
| Content Sections | 3 | 1 | 6 | 7 | 7 | 3 | 1 |
|
||||
|
||||
**Proposed Target:**
|
||||
|
||||
| Element | Hub | Components | Forms | Layouts | Spacing | Docs | Docs Dyn |
|
||||
|---------|-----|-----------|-------|---------|---------|------|----------|
|
||||
| Breadcrumbs | ✗ | ✓ | ✓ | ✓ | ✓ | ✗ | ✓ |
|
||||
| Page Title | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
|
||||
| Hero Section | ✓ | ✗ | ✗ | ✗ | ✗ | ✓ | ✗ |
|
||||
| Sticky Header | ✗ | ✗ | REMOVE | REMOVE | REMOVE | ✗ | ✗ |
|
||||
| Footer | UPGRADE | UPGRADE | ✓ | ✓ | ✓ | UPGRADE | UPGRADE |
|
||||
| Back Button | ✗ | ✓ | ✓ | ✓ | ✓ | ✗ | ✓ |
|
||||
|
||||
260
README.md
260
README.md
@@ -1,260 +0,0 @@
|
||||
# FastNext Stack
|
||||
|
||||
A modern, Docker-ready full-stack template combining FastAPI, Next.js, and PostgreSQL. Built for developers who need a robust starting point for web applications with TypeScript frontend and Python backend.
|
||||
|
||||
## Features
|
||||
|
||||
- 🐍 **FastAPI Backend**
|
||||
- Python 3.12 with modern async support
|
||||
- SQLAlchemy ORM with async capabilities
|
||||
- Alembic migrations
|
||||
- JWT authentication ready
|
||||
- Pydantic data validation
|
||||
- Comprehensive testing setup
|
||||
|
||||
- ⚛️ **Next.js Frontend**
|
||||
- React 19 with TypeScript
|
||||
- Tailwind CSS for styling
|
||||
- Modern app router architecture
|
||||
- Built-in API route support
|
||||
- SEO-friendly by default
|
||||
|
||||
- 🛠️ **Development Experience**
|
||||
- Docker-based development environment
|
||||
- Hot-reloading for both frontend and backend
|
||||
- Unified development workflow
|
||||
- Comprehensive testing setup
|
||||
- Type safety across the stack
|
||||
|
||||
- 🚀 **Production Ready**
|
||||
- Multi-stage Docker builds
|
||||
- Production-optimized configurations
|
||||
- Environment-based settings
|
||||
- Health checks and container orchestration
|
||||
- CORS security configured
|
||||
|
||||
## Quick Start
|
||||
|
||||
1. Clone the template:
|
||||
```bash
|
||||
git clone https://github.com/yourusername/fastnext-stack myproject
|
||||
cd myproject
|
||||
```
|
||||
|
||||
2. Create environment files:
|
||||
```bash
|
||||
cp .env.template .env
|
||||
```
|
||||
|
||||
3. Start development environment:
|
||||
```bash
|
||||
make dev
|
||||
```
|
||||
|
||||
4. Access the applications:
|
||||
- Frontend: http://localhost:3000
|
||||
- Backend: http://localhost:8000
|
||||
- API Docs: http://localhost:8000/docs
|
||||
|
||||
## Project Structure
|
||||
|
||||
```
|
||||
fast-next-template/
|
||||
├── backend/ # FastAPI backend
|
||||
│ ├── app/
|
||||
│ │ ├── alembic/ # Database migrations
|
||||
│ │ ├── api/ # API routes and dependencies
|
||||
│ │ ├── core/ # Core functionality (auth, config, db)
|
||||
│ │ ├── crud/ # Database CRUD operations
|
||||
│ │ ├── models/ # SQLAlchemy models
|
||||
│ │ ├── schemas/ # Pydantic schemas
|
||||
│ │ ├── services/ # Business logic services
|
||||
│ │ ├── utils/ # Utility functions
|
||||
│ │ ├── init_db.py # Database initialization script
|
||||
│ │ └── main.py # FastAPI application entry
|
||||
│ ├── tests/ # Comprehensive test suite
|
||||
│ ├── migrate.py # Migration helper CLI
|
||||
│ ├── requirements.txt # Python dependencies
|
||||
│ └── Dockerfile # Multi-stage container build
|
||||
├── frontend/ # Next.js frontend
|
||||
│ ├── src/
|
||||
│ │ ├── app/ # Next.js app router
|
||||
│ │ └── components/ # React components
|
||||
│ ├── public/ # Static assets
|
||||
│ └── Dockerfile # Next.js container build
|
||||
├── docker-compose.yml # Production compose configuration
|
||||
├── docker-compose.dev.yml # Development compose configuration
|
||||
├── docker-compose.deploy.yml # Deployment with pre-built images
|
||||
└── .env.template # Environment variables template
|
||||
```
|
||||
|
||||
## Backend Features
|
||||
|
||||
### Authentication System
|
||||
- **JWT-based authentication** with access and refresh tokens
|
||||
- **User management** with email/password authentication
|
||||
- **Password hashing** using bcrypt
|
||||
- **Token expiration** handling (access: 1 day, refresh: 60 days)
|
||||
- **Optional authentication** support for public/private endpoints
|
||||
- **Superuser** authorization support
|
||||
|
||||
### Database Management
|
||||
- **PostgreSQL** with optimized connection pooling
|
||||
- **Alembic migrations** with auto-generation support
|
||||
- **Migration CLI helper** (`migrate.py`) for easy database management:
|
||||
```bash
|
||||
python migrate.py generate "add users table" # Generate migration
|
||||
python migrate.py apply # Apply migrations
|
||||
python migrate.py list # List all migrations
|
||||
python migrate.py current # Show current revision
|
||||
python migrate.py check # Check DB connection
|
||||
python migrate.py auto "message" # Generate and apply
|
||||
```
|
||||
- **Automatic database initialization** with first superuser creation
|
||||
|
||||
### Testing Infrastructure
|
||||
- **92 comprehensive tests** covering all core functionality
|
||||
- **SQLite in-memory** database for fast test execution
|
||||
- **Auth test utilities** for easy endpoint testing
|
||||
- **Mocking support** for external dependencies
|
||||
- **Test fixtures** for common scenarios
|
||||
|
||||
### Security Utilities
|
||||
- **Upload token system** for secure file operations
|
||||
- **HMAC-based signing** for token validation
|
||||
- **Time-limited tokens** with expiration
|
||||
- **Nonce support** to prevent token reuse
|
||||
|
||||
## Development
|
||||
|
||||
### Running Tests
|
||||
|
||||
```bash
|
||||
# Backend tests
|
||||
cd backend
|
||||
source .venv/bin/activate
|
||||
pytest tests/ -v
|
||||
|
||||
# With coverage
|
||||
pytest tests/ --cov=app --cov-report=html
|
||||
```
|
||||
|
||||
### Database Migrations
|
||||
|
||||
```bash
|
||||
# Using the migration helper
|
||||
python migrate.py generate "your migration message"
|
||||
python migrate.py apply
|
||||
|
||||
# Or using alembic directly
|
||||
alembic revision --autogenerate -m "your message"
|
||||
alembic upgrade head
|
||||
```
|
||||
|
||||
### First Superuser
|
||||
|
||||
The backend automatically creates a superuser on initialization. Configure via environment variables:
|
||||
|
||||
```bash
|
||||
FIRST_SUPERUSER_EMAIL=admin@example.com
|
||||
FIRST_SUPERUSER_PASSWORD=admin123
|
||||
```
|
||||
|
||||
If not configured, defaults to `admin@example.com` / `admin123`.
|
||||
|
||||
## Deployment
|
||||
|
||||
### Option 1: Build and Deploy Locally
|
||||
|
||||
For production with local builds:
|
||||
|
||||
```bash
|
||||
docker-compose up -d
|
||||
```
|
||||
|
||||
### Option 2: Deploy with Pre-built Images
|
||||
|
||||
For deployment using images from a container registry:
|
||||
|
||||
1. Build and push your images:
|
||||
```bash
|
||||
# Build images
|
||||
docker-compose build
|
||||
|
||||
# Tag for your registry
|
||||
docker tag fast-next-template-backend:latest your-registry/your-project-backend:latest
|
||||
docker tag fast-next-template-frontend:latest your-registry/your-project-frontend:latest
|
||||
|
||||
# Push to registry
|
||||
docker push your-registry/your-project-backend:latest
|
||||
docker push your-registry/your-project-frontend:latest
|
||||
```
|
||||
|
||||
2. Update `docker-compose.deploy.yml` with your image references:
|
||||
```yaml
|
||||
services:
|
||||
backend:
|
||||
image: your-registry/your-project-backend:latest
|
||||
frontend:
|
||||
image: your-registry/your-project-frontend:latest
|
||||
```
|
||||
|
||||
3. Deploy:
|
||||
```bash
|
||||
docker-compose -f docker-compose.deploy.yml up -d
|
||||
```
|
||||
|
||||
### Environment Variables
|
||||
|
||||
Create a `.env` file based on `.env.template`:
|
||||
|
||||
```bash
|
||||
# Project
|
||||
PROJECT_NAME=MyApp
|
||||
VERSION=1.0.0
|
||||
|
||||
# Database
|
||||
POSTGRES_USER=postgres
|
||||
POSTGRES_PASSWORD=your-secure-password
|
||||
POSTGRES_DB=app
|
||||
POSTGRES_HOST=db
|
||||
POSTGRES_PORT=5432
|
||||
|
||||
# Backend
|
||||
BACKEND_PORT=8000
|
||||
SECRET_KEY=your-secret-key-change-this-in-production
|
||||
ENVIRONMENT=production
|
||||
DEBUG=false
|
||||
BACKEND_CORS_ORIGINS=["http://localhost:3000"]
|
||||
|
||||
# First Superuser
|
||||
FIRST_SUPERUSER_EMAIL=admin@example.com
|
||||
FIRST_SUPERUSER_PASSWORD=admin123
|
||||
|
||||
# Frontend
|
||||
NEXT_PUBLIC_API_URL=http://localhost:8000/api/v1
|
||||
```
|
||||
|
||||
## API Documentation
|
||||
|
||||
Once the backend is running, visit:
|
||||
- Swagger UI: http://localhost:8000/docs
|
||||
- ReDoc: http://localhost:8000/redoc
|
||||
|
||||
## Available Endpoints
|
||||
|
||||
### Authentication
|
||||
- `POST /api/v1/auth/register` - User registration
|
||||
- `POST /api/v1/auth/login` - User login (JSON)
|
||||
- `POST /api/v1/auth/login/oauth` - OAuth2-compatible login
|
||||
- `POST /api/v1/auth/refresh` - Refresh access token
|
||||
- `POST /api/v1/auth/change-password` - Change password
|
||||
- `GET /api/v1/auth/me` - Get current user info
|
||||
|
||||
## Contributing
|
||||
|
||||
This is a template project. Feel free to fork and customize for your needs.
|
||||
|
||||
## License
|
||||
|
||||
MIT License - feel free to use this template for your projects.
|
||||
@@ -1,401 +0,0 @@
|
||||
# Dev Pages Analysis - Complete Documentation Index
|
||||
|
||||
## Overview
|
||||
|
||||
This analysis provides a thorough examination of all pages under `/frontend/src/app/dev/` and their imported components, identifying structural inconsistencies and providing a complete implementation roadmap.
|
||||
|
||||
**Analysis Date:** November 2, 2025
|
||||
**Scope:** 7 pages, 6 components, 2,500+ lines of code
|
||||
**Total Documentation:** 2,085 lines across 4 files
|
||||
|
||||
---
|
||||
|
||||
## Quick Start
|
||||
|
||||
### For Managers/Decision Makers
|
||||
Read: **ANALYSIS_SUMMARY.md** (5-10 min read)
|
||||
- Problem statement
|
||||
- Key findings
|
||||
- Implementation effort estimate
|
||||
- Success criteria
|
||||
|
||||
### For Developers (Implementation)
|
||||
Read in order:
|
||||
1. **DEV_PAGES_QUICK_REFERENCE.md** (10 min) - Overview and visual diagrams
|
||||
2. **COMPONENT_IMPLEMENTATION_GUIDE.md** (20 min) - Code to implement
|
||||
3. **DEV_PAGES_STRUCTURE_ANALYSIS.md** (reference) - Detailed analysis
|
||||
|
||||
### For Code Reviewers
|
||||
Read: **DEV_PAGES_STRUCTURE_ANALYSIS.md** (30 min)
|
||||
- Detailed before/after comparison
|
||||
- All inconsistencies documented
|
||||
- Rationale for each recommendation
|
||||
|
||||
---
|
||||
|
||||
## Document Breakdown
|
||||
|
||||
### 1. ANALYSIS_SUMMARY.md (346 lines)
|
||||
**Purpose:** Executive summary and quick reference
|
||||
|
||||
**Contains:**
|
||||
- Problem statement
|
||||
- Key findings (8 inconsistencies)
|
||||
- Proposed solution overview
|
||||
- Implementation plan (4 phases)
|
||||
- Page comparison matrix
|
||||
- Code metrics
|
||||
- File changes summary
|
||||
- Success criteria
|
||||
|
||||
**Best for:** Quick understanding of the issues and proposed solution
|
||||
|
||||
---
|
||||
|
||||
### 2. DEV_PAGES_STRUCTURE_ANALYSIS.md (758 lines)
|
||||
**Purpose:** Complete technical analysis with detailed structure
|
||||
|
||||
**Contains:**
|
||||
- Detailed analysis of all 7 pages:
|
||||
- `/dev/page.tsx` (Design System Hub)
|
||||
- `/dev/components/page.tsx` (Component Showcase)
|
||||
- `/dev/forms/page.tsx` (Form Patterns)
|
||||
- `/dev/layouts/page.tsx` (Layout Patterns)
|
||||
- `/dev/spacing/page.tsx` (Spacing Patterns)
|
||||
- `/dev/docs/page.tsx` (Documentation Hub)
|
||||
- `/dev/docs/design-system/[...slug]/page.tsx` (Dynamic Docs)
|
||||
|
||||
- For each page:
|
||||
- File path
|
||||
- Structure breakdown
|
||||
- Breadcrumbs/titles/footers
|
||||
- Components used
|
||||
- Layout pattern (ASCII diagram)
|
||||
|
||||
- Comparison tables showing:
|
||||
- What each page has
|
||||
- What's inconsistent
|
||||
- What's missing
|
||||
|
||||
- 8 Identified inconsistencies with details:
|
||||
1. Header Implementation (CRITICAL)
|
||||
2. Page Title/Breadcrumbs (CRITICAL)
|
||||
3. Footer Implementation (INCONSISTENT)
|
||||
4. Page Layout Wrapper (INCONSISTENT)
|
||||
5. Content Container Padding (MINOR)
|
||||
6. 'use client' Directive (INCONSISTENT)
|
||||
7. Component Loading/Code Splitting (INCONSISTENT)
|
||||
8. ExampleSection Organization (INCONSISTENT)
|
||||
|
||||
- 8 Specific recommendations
|
||||
- Code duplication analysis (144 lines identified)
|
||||
- File structure refactor proposal
|
||||
- Target state comparison table
|
||||
|
||||
**Best for:** Understanding the complete picture and rationale
|
||||
|
||||
---
|
||||
|
||||
### 3. DEV_PAGES_QUICK_REFERENCE.md (352 lines)
|
||||
**Purpose:** Quick lookup guide with visual diagrams and matrices
|
||||
|
||||
**Contains:**
|
||||
- Visual ASCII diagrams of page structures
|
||||
- Page inventory
|
||||
- Key findings summary
|
||||
- Component architecture
|
||||
- Page usage matrix (current vs target)
|
||||
- Implementation roadmap (4 phases)
|
||||
- Before/after code examples
|
||||
- Testing checklist
|
||||
- File modification guide
|
||||
- Metrics summary
|
||||
|
||||
**Best for:** Quick visual reference during implementation
|
||||
|
||||
---
|
||||
|
||||
### 4. COMPONENT_IMPLEMENTATION_GUIDE.md (629 lines)
|
||||
**Purpose:** Ready-to-implement code and step-by-step instructions
|
||||
|
||||
**Contains:**
|
||||
- Complete code for 5 new components:
|
||||
1. `DevPageHeader.tsx` - Shared page header
|
||||
2. `DevBreadcrumbs.tsx` - Breadcrumb navigation
|
||||
3. `DevPageFooter.tsx` - Shared footer
|
||||
4. `DevPageLayout.tsx` - Complete wrapper
|
||||
5. `ExampleLoadingSkeleton.tsx` - Loading placeholder
|
||||
|
||||
- For each component:
|
||||
- Full TypeScript code
|
||||
- JSDoc documentation
|
||||
- Usage examples
|
||||
- Type definitions
|
||||
|
||||
- Page refactoring examples:
|
||||
- Forms page (before/after)
|
||||
- Usage patterns
|
||||
- Migration instructions
|
||||
|
||||
- Step-by-step implementation checklist
|
||||
- Testing commands
|
||||
- Usage examples for different page types
|
||||
|
||||
**Best for:** Actual implementation work
|
||||
|
||||
---
|
||||
|
||||
## Key Findings Summary
|
||||
|
||||
### Problems Identified
|
||||
|
||||
1. **144 lines of duplicated code**
|
||||
- 120 lines: Duplicated headers (3 pages × 40 lines)
|
||||
- 24 lines: Duplicated footers (3 pages × 8 lines)
|
||||
|
||||
2. **Inconsistent header implementations**
|
||||
- 3 pages (Forms, Layouts, Spacing) implement custom sticky headers
|
||||
- 4 pages (Hub, Components, Docs, Dynamic) use or don't use DevLayout
|
||||
|
||||
3. **No breadcrumb navigation**
|
||||
- All 7 pages missing breadcrumbs
|
||||
- Only Back buttons on detail pages (4 pages)
|
||||
|
||||
4. **Inconsistent footer usage**
|
||||
- 3 pages have footers with doc links
|
||||
- 4 pages have no footers
|
||||
|
||||
5. **8 structural inconsistencies** in total
|
||||
|
||||
### Proposed Solution
|
||||
|
||||
Create 4 reusable components to:
|
||||
- Eliminate 144 lines of duplication
|
||||
- Add breadcrumb navigation
|
||||
- Standardize page structure
|
||||
- Improve maintainability
|
||||
|
||||
**Estimated effort:** 4-8 hours
|
||||
**Code savings:** 6 KB (after removing duplication)
|
||||
**New bundle:** +2-3 KB (net savings: 3-4 KB)
|
||||
|
||||
---
|
||||
|
||||
## Implementation Timeline
|
||||
|
||||
### Phase 1: Extract Components (1-2 hours)
|
||||
- Create 5 new reusable components
|
||||
- Full TypeScript types
|
||||
- Documentation
|
||||
|
||||
### Phase 2: Refactor Pages (2-3 hours)
|
||||
- Update 7 pages to use new components
|
||||
- Remove 144 lines of duplicated code
|
||||
- Add breadcrumbs and footers
|
||||
|
||||
### Phase 3: Enhance (1-2 hours)
|
||||
- Standardize dynamic imports
|
||||
- Add consistent loading states
|
||||
- Update all loading skeletons
|
||||
|
||||
### Phase 4: Polish (30-60 min)
|
||||
- Test navigation flows
|
||||
- Verify mobile responsiveness
|
||||
- Check accessibility
|
||||
- Run full test suite
|
||||
|
||||
**Total: 4-8 hours of implementation work**
|
||||
|
||||
---
|
||||
|
||||
## File Changes Required
|
||||
|
||||
### Create (5 files)
|
||||
```
|
||||
src/components/dev/
|
||||
├── DevPageHeader.tsx (NEW)
|
||||
├── DevBreadcrumbs.tsx (NEW)
|
||||
├── DevPageFooter.tsx (NEW)
|
||||
├── DevPageLayout.tsx (NEW)
|
||||
└── ExampleLoadingSkeleton.tsx (NEW)
|
||||
```
|
||||
|
||||
### Modify (7 files)
|
||||
```
|
||||
src/app/dev/
|
||||
├── page.tsx (add footer)
|
||||
├── components/page.tsx (add breadcrumbs/footer)
|
||||
├── forms/page.tsx (refactor with DevPageLayout)
|
||||
├── layouts/page.tsx (refactor with DevPageLayout)
|
||||
├── spacing/page.tsx (refactor with DevPageLayout)
|
||||
├── docs/page.tsx (add footer)
|
||||
└── docs/design-system/[...slug]/page.tsx (add breadcrumbs/footer)
|
||||
```
|
||||
|
||||
### Keep As-Is (6 files)
|
||||
- Layout wrapper
|
||||
- DevLayout.tsx
|
||||
- Example components
|
||||
- CodeSnippet
|
||||
- ComponentShowcase
|
||||
|
||||
---
|
||||
|
||||
## How to Use This Analysis
|
||||
|
||||
### Step 1: Review
|
||||
1. Read ANALYSIS_SUMMARY.md to understand the issues
|
||||
2. Review DEV_PAGES_QUICK_REFERENCE.md for visual overview
|
||||
3. Get buy-in from team
|
||||
|
||||
### Step 2: Plan
|
||||
1. Prioritize based on your schedule
|
||||
2. Allocate 4-8 hours for implementation
|
||||
3. Assign team members
|
||||
|
||||
### Step 3: Implement
|
||||
1. Follow COMPONENT_IMPLEMENTATION_GUIDE.md
|
||||
2. Create new components (Phase 1)
|
||||
3. Refactor pages (Phase 2)
|
||||
4. Enhance and test (Phases 3-4)
|
||||
|
||||
### Step 4: Review
|
||||
1. Run full test suite
|
||||
2. Check mobile responsiveness
|
||||
3. Verify accessibility
|
||||
4. Commit with detailed message
|
||||
|
||||
---
|
||||
|
||||
## Success Criteria
|
||||
|
||||
After implementation, verify:
|
||||
- [ ] 144 lines of duplicated code removed
|
||||
- [ ] All pages have consistent header styling
|
||||
- [ ] Breadcrumbs visible on all detail pages
|
||||
- [ ] Page titles visible on all pages
|
||||
- [ ] Footers with doc links on all pages
|
||||
- [ ] Back buttons work on detail pages
|
||||
- [ ] Global navigation accessible
|
||||
- [ ] Mobile layout responsive
|
||||
- [ ] No console errors
|
||||
- [ ] Build passes without warnings
|
||||
- [ ] E2E tests pass
|
||||
- [ ] Code follows project conventions
|
||||
|
||||
---
|
||||
|
||||
## Project Context
|
||||
|
||||
This analysis is part of the **FastNext** project:
|
||||
- Full-stack FastAPI + Next.js 15 application
|
||||
- Comprehensive design system documentation
|
||||
- Interactive demo pages under `/dev/`
|
||||
- Production-ready code with high test coverage
|
||||
|
||||
### Related Documentation
|
||||
- `/CLAUDE.md` - Project guidelines and conventions
|
||||
- `/frontend/docs/design-system/` - Design system documentation
|
||||
- `/frontend/src/components/` - All component definitions
|
||||
|
||||
---
|
||||
|
||||
## Questions & Answers
|
||||
|
||||
**Q: Why create new components instead of just fixing the existing code?**
|
||||
A: DRY principle - 144 lines of identical code should be extracted to reusable components
|
||||
|
||||
**Q: Will this refactoring break anything?**
|
||||
A: No. We're only extracting and reorganizing existing code, not changing functionality
|
||||
|
||||
**Q: Should I do all pages at once?**
|
||||
A: Recommended approach: Create components first (Phase 1), then refactor all pages (Phase 2)
|
||||
|
||||
**Q: How do I prioritize if I have limited time?**
|
||||
A: Phase 1 (extract components) is highest priority as it unblocks all page refactoring
|
||||
|
||||
**Q: What if I have concerns about the approach?**
|
||||
A: See DEV_PAGES_STRUCTURE_ANALYSIS.md for detailed rationale behind each recommendation
|
||||
|
||||
---
|
||||
|
||||
## Navigation Guide
|
||||
|
||||
### If you want to...
|
||||
|
||||
**Understand the problem quickly**
|
||||
→ Read: ANALYSIS_SUMMARY.md (page 1-2)
|
||||
|
||||
**See visual diagrams of page structures**
|
||||
→ Read: DEV_PAGES_QUICK_REFERENCE.md (page 1-2)
|
||||
|
||||
**Understand why these changes matter**
|
||||
→ Read: DEV_PAGES_STRUCTURE_ANALYSIS.md (page 1-3, 22-25)
|
||||
|
||||
**Get started implementing**
|
||||
→ Read: COMPONENT_IMPLEMENTATION_GUIDE.md (page 1-2)
|
||||
|
||||
**See before/after code examples**
|
||||
→ Read: DEV_PAGES_QUICK_REFERENCE.md (page 12) or COMPONENT_IMPLEMENTATION_GUIDE.md (page 14)
|
||||
|
||||
**Understand all the inconsistencies**
|
||||
→ Read: DEV_PAGES_STRUCTURE_ANALYSIS.md (page 18-27)
|
||||
|
||||
**Get a step-by-step checklist**
|
||||
→ Read: COMPONENT_IMPLEMENTATION_GUIDE.md (page 20-21)
|
||||
|
||||
**Verify success after implementation**
|
||||
→ Read: ANALYSIS_SUMMARY.md (page 18) or DEV_PAGES_QUICK_REFERENCE.md (page 13)
|
||||
|
||||
---
|
||||
|
||||
## File Locations
|
||||
|
||||
All analysis documents are in the project root:
|
||||
|
||||
```
|
||||
/workdrive/workspace/Projects/HomeLab/fast-next-template/
|
||||
├── README_ANALYSIS.md (this file)
|
||||
├── ANALYSIS_SUMMARY.md
|
||||
├── DEV_PAGES_STRUCTURE_ANALYSIS.md
|
||||
├── DEV_PAGES_QUICK_REFERENCE.md
|
||||
├── COMPONENT_IMPLEMENTATION_GUIDE.md
|
||||
└── frontend/
|
||||
├── src/app/dev/ (pages to refactor)
|
||||
├── src/components/dev/ (components to create)
|
||||
└── docs/design-system/ (related documentation)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Contact & Support
|
||||
|
||||
For questions about this analysis:
|
||||
1. Review the relevant document linked above
|
||||
2. Check the "Questions & Answers" section
|
||||
3. Refer to CLAUDE.md for project conventions
|
||||
|
||||
For implementation issues:
|
||||
1. Consult COMPONENT_IMPLEMENTATION_GUIDE.md
|
||||
2. Check DEV_PAGES_QUICK_REFERENCE.md for quick answers
|
||||
3. Review existing dev components for patterns
|
||||
|
||||
---
|
||||
|
||||
## Document Statistics
|
||||
|
||||
| Document | Lines | Size | Focus |
|
||||
|----------|-------|------|-------|
|
||||
| ANALYSIS_SUMMARY.md | 346 | 10K | Overview |
|
||||
| DEV_PAGES_STRUCTURE_ANALYSIS.md | 758 | 22K | Deep dive |
|
||||
| DEV_PAGES_QUICK_REFERENCE.md | 352 | 13K | Quick lookup |
|
||||
| COMPONENT_IMPLEMENTATION_GUIDE.md | 629 | 15K | Implementation |
|
||||
| **Total** | **2,085** | **60K** | Complete analysis |
|
||||
|
||||
---
|
||||
|
||||
Generated: November 2, 2025
|
||||
Analysis Type: Very Thorough (Complete structure & component analysis)
|
||||
Analyzed Pages: 7 (all /dev/ routes)
|
||||
Analyzed Components: 6 (all dev components)
|
||||
|
||||
Reference in New Issue
Block a user