diff --git a/docs/PREVIEW_PAGE_STANDARDS.md b/docs/PREVIEW_PAGE_STANDARDS.md new file mode 100644 index 0000000..7ed66ef --- /dev/null +++ b/docs/PREVIEW_PAGE_STANDARDS.md @@ -0,0 +1,499 @@ +# Preview Page Standards + +This document outlines how to create preview pages for components in `/app/components/`. + +## Purpose + +Preview pages allow developers and AI builders to: +- See components in isolation +- Test component behavior and styling +- Verify responsive design +- Experiment with different prop configurations +- Ensure smooth scrolling and theme integration + +## File Structure + +### Location Pattern + +``` +/app/components/ + ├── sections/ + │ ├── hero/ + │ │ ├── billboard/ + │ │ │ └── page.tsx // Preview for HeroBillboard + │ │ ├── split/ + │ │ │ └── page.tsx // Preview for HeroSplit + │ ├── feature/ + │ │ ├── card-one/ + │ │ │ └── page.tsx // Preview for FeatureCardOne + ├── buttons/ + │ ├── text-stagger/ + │ │ └── page.tsx // Preview for ButtonTextStagger + └── page.tsx // Main components index +``` + +**Pattern:** `/app/components/[category]/[component-name]/page.tsx` + +**Component name formatting:** +- Use kebab-case for folder names +- `HeroBillboard` → `hero/billboard/` +- `FeatureCardOne` → `feature/card-one/` +- `ButtonTextStagger` → `buttons/text-stagger/` + +## Preview Page Template + +### Basic Template (Non-Section Components) + +```tsx +"use client"; + +import React from "react"; +import ReactLenis from "lenis/react"; +import { ThemeProvider } from "@/providers/themeProvider/ThemeProvider"; +import ComponentName from "@/components/category/ComponentName"; + +export default function ComponentPreviewPage() { + return ( + + + console.log("clicked")} + /> + + + ); +} +``` + +### Section Component Template + +```tsx +"use client"; + +import React from "react"; +import ReactLenis from "lenis/react"; +import { ThemeProvider } from "@/providers/themeProvider/ThemeProvider"; +import SectionName from "@/components/sections/category/SectionName"; + +export default function SectionPreviewPage() { + return ( + + + console.log("Learn more") } + ]} + // Add section-specific props + /> + + + ); +} +``` + +### CardStack Section Template + +```tsx +"use client"; + +import React from "react"; +import ReactLenis from "lenis/react"; +import { ThemeProvider } from "@/providers/themeProvider/ThemeProvider"; +import { Package, Zap, Shield, Sparkles } from "lucide-react"; +import FeatureCardOne from "@/components/sections/feature/FeatureCardOne"; + +export default function FeatureCardOnePreviewPage() { + const features = [ + { + icon: Package, + title: "Feature One", + description: "Lorem ipsum dolor sit amet, consectetur adipiscing elit." + }, + { + icon: Zap, + title: "Feature Two", + description: "Sed do eiusmod tempor incididunt ut labore et dolore." + }, + { + icon: Shield, + title: "Feature Three", + description: "Ut enim ad minim veniam, quis nostrud exercitation." + }, + { + icon: Sparkles, + title: "Feature Four", + description: "Duis aute irure dolor in reprehenderit in voluptate." + } + ]; + + return ( + + + + + + ); +} +``` + +## Critical Requirements + +### Wrapper Order + +**MUST follow this order:** + +```tsx + + + + + +``` + +**❌ WRONG:** +```tsx + + + + + +``` + +ReactLenis must be **inside** ThemeProvider, not outside. + +### "use client" Directive + +All preview pages must include `"use client"` at the top: + +```tsx +"use client"; + +import React from "react"; +// ... +``` + +This is required because: +- ReactLenis uses client-side hooks +- ThemeProvider uses React Context +- Components may use interactive features + +### ReactLenis Root Prop + +Always include the `root` prop: + +```tsx + + {/* components */} + +``` + +This enables page-wide smooth scrolling. + +## Theme Configuration + +### Recommended Defaults + +**For most previews:** +```tsx + +``` + +**For button previews:** +```tsx + +``` + +**For hero previews:** +```tsx + +``` + +### When to Customize + +Customize theme settings when: +- Testing different button variants +- Showcasing card styles +- Demonstrating responsive behavior +- Highlighting specific theme features + +## Realistic Props + +### Use Realistic Content + +**✅ GOOD:** +```tsx + window.open("/demo") } + ]} +/> +``` + +**❌ BAD:** +```tsx + +``` + +### Sample Data Patterns + +**Features:** +```tsx +const features = [ + { + icon: Package, + title: "Fast Shipping", + description: "Get your order delivered within 2-3 business days." + }, + // ... more features +]; +``` + +**Products:** +```tsx +const products = [ + { + title: "Premium Headphones", + description: "Wireless noise-cancelling headphones with 30-hour battery life.", + price: "$299", + image: "/images/headphones.jpg" + }, + // ... more products +]; +``` + +**Testimonials:** +```tsx +const testimonials = [ + { + name: "Sarah Johnson", + role: "CEO, TechCorp", + content: "This component library transformed our development workflow. Highly recommend!", + image: "/images/avatar-1.jpg", + rating: 5 + }, + // ... more testimonials +]; +``` + +## Multiple Sections Example + +Preview pages can show multiple components together: + +```tsx +"use client"; + +import React from "react"; +import ReactLenis from "lenis/react"; +import { ThemeProvider } from "@/providers/themeProvider/ThemeProvider"; +import HeroBillboard from "@/components/sections/hero/HeroBillboard"; +import FeatureCardOne from "@/components/sections/feature/FeatureCardOne"; +import Footer from "@/components/sections/footer/FooterBase"; + +export default function FullPagePreview() { + return ( + + + + +