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