Initial commit
This commit is contained in:
499
docs/PREVIEW_PAGE_STANDARDS.md
Normal file
499
docs/PREVIEW_PAGE_STANDARDS.md
Normal file
@@ -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 (
|
||||
<ThemeProvider
|
||||
defaultButtonVariant="text-stagger"
|
||||
defaultTextAnimation="entrance-slide"
|
||||
borderRadius="rounded"
|
||||
contentWidth="medium"
|
||||
sizing="medium"
|
||||
background="plain"
|
||||
cardStyle="glass-flat"
|
||||
primaryButtonStyle="gradient"
|
||||
secondaryButtonStyle="glass"
|
||||
headingFontWeight="medium"
|
||||
>
|
||||
<ReactLenis root>
|
||||
<ComponentName
|
||||
// Add realistic props here
|
||||
text="Example"
|
||||
onClick={() => console.log("clicked")}
|
||||
/>
|
||||
</ReactLenis>
|
||||
</ThemeProvider>
|
||||
);
|
||||
}
|
||||
```
|
||||
|
||||
### 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 (
|
||||
<ThemeProvider
|
||||
defaultButtonVariant="icon-arrow"
|
||||
defaultTextAnimation="entrance-slide"
|
||||
borderRadius="pill"
|
||||
contentWidth="medium"
|
||||
sizing="medium"
|
||||
background="animatedGrid"
|
||||
cardStyle="glass-flat"
|
||||
primaryButtonStyle="gradient"
|
||||
secondaryButtonStyle="glass"
|
||||
headingFontWeight="medium"
|
||||
>
|
||||
<ReactLenis root>
|
||||
<SectionName
|
||||
title="Preview Section Title"
|
||||
description="This is a preview of the section component with example content."
|
||||
buttons={[
|
||||
{ text: "Get Started", href: "#" },
|
||||
{ text: "Learn More", onClick: () => console.log("Learn more") }
|
||||
]}
|
||||
// Add section-specific props
|
||||
/>
|
||||
</ReactLenis>
|
||||
</ThemeProvider>
|
||||
);
|
||||
}
|
||||
```
|
||||
|
||||
### 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 (
|
||||
<ThemeProvider
|
||||
defaultButtonVariant="icon-arrow"
|
||||
defaultTextAnimation="entrance-slide"
|
||||
borderRadius="rounded"
|
||||
contentWidth="medium"
|
||||
sizing="medium"
|
||||
background="animatedGrid"
|
||||
cardStyle="glass-flat"
|
||||
primaryButtonStyle="gradient"
|
||||
secondaryButtonStyle="glass"
|
||||
headingFontWeight="medium"
|
||||
>
|
||||
<ReactLenis root>
|
||||
<FeatureCardOne
|
||||
features={features}
|
||||
gridVariant="uniform-all-items-equal"
|
||||
textboxLayout="default"
|
||||
title="Our Features"
|
||||
description="Discover what makes us unique"
|
||||
tag="Features"
|
||||
tagIcon={Sparkles}
|
||||
buttons={[
|
||||
{ text: "View All", href: "#" }
|
||||
]}
|
||||
/>
|
||||
</ReactLenis>
|
||||
</ThemeProvider>
|
||||
);
|
||||
}
|
||||
```
|
||||
|
||||
## Critical Requirements
|
||||
|
||||
### Wrapper Order
|
||||
|
||||
**MUST follow this order:**
|
||||
|
||||
```tsx
|
||||
<ThemeProvider>
|
||||
<ReactLenis root>
|
||||
<Component />
|
||||
</ReactLenis>
|
||||
</ThemeProvider>
|
||||
```
|
||||
|
||||
**❌ WRONG:**
|
||||
```tsx
|
||||
<ReactLenis root>
|
||||
<ThemeProvider>
|
||||
<Component />
|
||||
</ThemeProvider>
|
||||
</ReactLenis>
|
||||
```
|
||||
|
||||
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
|
||||
<ReactLenis root>
|
||||
{/* components */}
|
||||
</ReactLenis>
|
||||
```
|
||||
|
||||
This enables page-wide smooth scrolling.
|
||||
|
||||
## Theme Configuration
|
||||
|
||||
### Recommended Defaults
|
||||
|
||||
**For most previews:**
|
||||
```tsx
|
||||
<ThemeProvider
|
||||
defaultButtonVariant="icon-arrow"
|
||||
defaultTextAnimation="entrance-slide"
|
||||
borderRadius="rounded"
|
||||
contentWidth="medium"
|
||||
sizing="medium"
|
||||
background="animatedGrid"
|
||||
cardStyle="glass-flat"
|
||||
primaryButtonStyle="gradient"
|
||||
secondaryButtonStyle="glass"
|
||||
headingFontWeight="medium"
|
||||
>
|
||||
```
|
||||
|
||||
**For button previews:**
|
||||
```tsx
|
||||
<ThemeProvider
|
||||
defaultButtonVariant="text-stagger" // Match button being previewed
|
||||
defaultTextAnimation="entrance-slide"
|
||||
borderRadius="pill"
|
||||
contentWidth="medium"
|
||||
sizing="medium"
|
||||
background="plain"
|
||||
cardStyle="glass-flat"
|
||||
primaryButtonStyle="gradient"
|
||||
secondaryButtonStyle="glass"
|
||||
headingFontWeight="medium"
|
||||
>
|
||||
```
|
||||
|
||||
**For hero previews:**
|
||||
```tsx
|
||||
<ThemeProvider
|
||||
defaultButtonVariant="icon-arrow"
|
||||
defaultTextAnimation="entrance-slide"
|
||||
borderRadius="rounded"
|
||||
contentWidth="large" // Wider for heroes
|
||||
sizing="large" // Larger sizing for heroes
|
||||
background="aurora" // Visual background
|
||||
cardStyle="glass-flat"
|
||||
primaryButtonStyle="gradient"
|
||||
secondaryButtonStyle="glass"
|
||||
headingFontWeight="semibold" // Bolder for heroes
|
||||
>
|
||||
```
|
||||
|
||||
### 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
|
||||
<HeroBillboard
|
||||
title="Build Amazing Websites Faster"
|
||||
description="Create stunning, responsive websites with our modern component library. Ship faster, iterate quicker."
|
||||
buttons={[
|
||||
{ text: "Get Started", href: "/signup" },
|
||||
{ text: "View Demo", onClick: () => window.open("/demo") }
|
||||
]}
|
||||
/>
|
||||
```
|
||||
|
||||
**❌ BAD:**
|
||||
```tsx
|
||||
<HeroBillboard
|
||||
title="Test"
|
||||
description="Test description"
|
||||
buttons={[
|
||||
{ text: "Click", href: "#" }
|
||||
]}
|
||||
/>
|
||||
```
|
||||
|
||||
### 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 (
|
||||
<ThemeProvider
|
||||
defaultButtonVariant="icon-arrow"
|
||||
defaultTextAnimation="entrance-slide"
|
||||
borderRadius="rounded"
|
||||
contentWidth="medium"
|
||||
sizing="medium"
|
||||
background="animatedGrid"
|
||||
cardStyle="glass-flat"
|
||||
primaryButtonStyle="gradient"
|
||||
secondaryButtonStyle="glass"
|
||||
headingFontWeight="medium"
|
||||
>
|
||||
<ReactLenis root>
|
||||
<HeroBillboard {...heroProps} />
|
||||
<FeatureCardOne {...featureProps} />
|
||||
<Footer {...footerProps} />
|
||||
</ReactLenis>
|
||||
</ThemeProvider>
|
||||
);
|
||||
}
|
||||
```
|
||||
|
||||
## Preview Page Checklist
|
||||
|
||||
### File Setup
|
||||
- [ ] Create in correct location: `/app/components/[category]/[component-name]/page.tsx`
|
||||
- [ ] Use kebab-case for folder names
|
||||
- [ ] Add `"use client"` directive at top
|
||||
- [ ] Export default function with descriptive name
|
||||
|
||||
### Wrapper Configuration
|
||||
- [ ] Wrap in ThemeProvider (outer)
|
||||
- [ ] Wrap in ReactLenis with `root` prop (inner)
|
||||
- [ ] Correct order: ThemeProvider > ReactLenis > Component
|
||||
- [ ] Import both wrappers
|
||||
|
||||
### Component Props
|
||||
- [ ] Use realistic, representative content
|
||||
- [ ] Include all required props
|
||||
- [ ] Test with typical prop combinations
|
||||
- [ ] Use proper TypeScript types (no `any`)
|
||||
|
||||
### Theme Settings
|
||||
- [ ] Configure appropriate theme settings for component type
|
||||
- [ ] Use sensible defaults that showcase the component well
|
||||
- [ ] Test with different theme configurations if needed
|
||||
|
||||
### Quality Checks
|
||||
- [ ] Component renders without errors
|
||||
- [ ] Smooth scrolling works
|
||||
- [ ] Responsive design functions correctly
|
||||
- [ ] Animations trigger properly
|
||||
- [ ] No console warnings or errors
|
||||
|
||||
## Common Patterns
|
||||
|
||||
### Background for Preview
|
||||
|
||||
If the component needs a background color to be visible:
|
||||
|
||||
```tsx
|
||||
<ReactLenis root>
|
||||
<div className="min-h-screen bg-background">
|
||||
<Component {...props} />
|
||||
</div>
|
||||
</ReactLenis>
|
||||
```
|
||||
|
||||
### Centered Preview
|
||||
|
||||
For small components that need centering:
|
||||
|
||||
```tsx
|
||||
<ReactLenis root>
|
||||
<div className="min-h-screen flex items-center justify-center bg-background">
|
||||
<Component {...props} />
|
||||
</div>
|
||||
</ReactLenis>
|
||||
```
|
||||
|
||||
### Multiple Variants
|
||||
|
||||
Show multiple variants of the same component:
|
||||
|
||||
```tsx
|
||||
<ReactLenis root>
|
||||
<div className="min-h-screen bg-background py-20 space-y-20">
|
||||
<ComponentName variant="primary" {...props} />
|
||||
<ComponentName variant="secondary" {...props} />
|
||||
<ComponentName variant="ghost" {...props} />
|
||||
</div>
|
||||
</ReactLenis>
|
||||
```
|
||||
|
||||
## Best Practices
|
||||
|
||||
### ✅ DO:
|
||||
|
||||
- Use realistic, production-quality content
|
||||
- Test responsive behavior
|
||||
- Include all ThemeProvider configuration
|
||||
- Use ReactLenis for smooth scrolling
|
||||
- Follow naming conventions (kebab-case folders)
|
||||
- Include required props only (let optional props use defaults)
|
||||
- Test with different theme settings
|
||||
|
||||
### ❌ DO NOT:
|
||||
|
||||
- Use placeholder text like "Lorem ipsum" (use realistic content)
|
||||
- Skip ThemeProvider or ReactLenis
|
||||
- Put ReactLenis outside ThemeProvider
|
||||
- Use hardcoded colors that break theming
|
||||
- Create overly complex multi-component demos (keep focused)
|
||||
- Forget "use client" directive
|
||||
- Use incorrect folder structure
|
||||
Reference in New Issue
Block a user