Felipe Cardoso
68e28e4c76
- Remove persist middleware from authStore (causing hooks timing issues) - Restore original AuthInitializer component pattern - Keep good Phase 3 optimizations: - Theme FOUC fix (inline script) - React Query refetchOnWindowFocus disabled - Code splitting for dev/auth components - Shared form components (FormField, useFormError) - Store location in lib/stores
353 lines
12 KiB
Markdown
353 lines
12 KiB
Markdown
# 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
|
||
|