Initial commit

docs/README.md

@@ -0,0 +1,145 @@
+# Component Library Documentation
+
+This directory contains focused documentation for building components in this AI-optimized component library.
+
+## Documentation Files
+
+### 📋 [COMPONENT_IMPLEMENTATION.md](./COMPONENT_IMPLEMENTATION.md)
+**Core component implementation patterns**
+
+Load when: Creating or modifying component code
+
+Covers:
+- Component structure template
+- Prop structure & defaults
+- Naming conventions
+- Component customizability
+- Type safety
+- Responsive design
+- Content width pattern
+- Implementation checklist
+
+---
+
+### 🎴 [CARDSTACK_SECTIONS.md](./CARDSTACK_SECTIONS.md)
+**CardStack-based section components**
+
+Load when: Creating Feature, Product, Pricing, Testimonial, Team, Blog, or Metrics sections
+
+Covers:
+- CardStack pattern overview
+- Grid variants (10+ layouts)
+- Height control (`uniformGridCustomHeightClasses`)
+- Carousel modes
+- TextBox integration
+- Button system
+- Animation types
+- Complete examples & checklist
+
+---
+
+### 🎨 [THEME_AND_STYLING.md](./THEME_AND_STYLING.md)
+**Theme system and styling patterns**
+
+Load when: Setting up themes, working with colors, or styling components
+
+Covers:
+- Theme Provider configuration
+- Color theming (CSS variables)
+- Inverted background pattern
+- Content width pattern
+- Card styling
+- Border radius patterns
+- Button styling classes
+- Styling checklist
+
+---
+
+### ♿ [ACCESSIBILITY.md](./ACCESSIBILITY.md)
+**Accessibility (a11y) standards**
+
+Load when: Adding interactive elements, media, or sections
+
+Covers:
+- Interactive components (buttons, links)
+- Media components (images, videos)
+- Section components (semantic HTML)
+- Form components
+- Focus management
+- Keyboard navigation
+- ARIA roles
+- Accessibility checklist
+
+---
+
+### 📚 [REGISTRY_STANDARDS.md](./REGISTRY_STANDARDS.md)
+**Registry documentation rules**
+
+Load when: Adding or updating component entries in `registry.json`
+
+Covers:
+- Registry structure
+- Component entry format
+- Field descriptions
+- propsSchema rules
+- Constraints format
+- Usage examples
+- What to include/exclude
+- Validation checklist
+
+---
+
+### 📄 [PREVIEW_PAGE_STANDARDS.md](./PREVIEW_PAGE_STANDARDS.md)
+**Preview page setup and patterns**
+
+Load when: Creating preview pages in `/app/components/`
+
+Covers:
+- File structure & location
+- Preview page templates
+- Wrapper order (ThemeProvider > ReactLenis)
+- Theme configuration
+- Realistic props
+- Multiple sections example
+- Preview page checklist
+
+---
+
+## Quick Reference
+
+### When creating a new component:
+1. Load `COMPONENT_IMPLEMENTATION.md` for structure
+2. Load `ACCESSIBILITY.md` for a11y requirements
+3. Load `THEME_AND_STYLING.md` for styling patterns
+4. Load `CARDSTACK_SECTIONS.md` if using CardStack
+
+### When updating the registry:
+1. Load `REGISTRY_STANDARDS.md` only
+
+### When creating a preview page:
+1. Load `PREVIEW_PAGE_STANDARDS.md` only
+
+### When modifying themes:
+1. Load `THEME_AND_STYLING.md` only
+
+---
+
+## Documentation Principles
+
+These docs are optimized for:
+- **AI builders** (Lovable, V0, Claude Code)
+- **Focused context** (load only what you need)
+- **Quick reference** (checklists and examples)
+- **Consistency** (standardized patterns across all components)
+
+Each file is:
+- **Single-purpose** - covers one concern thoroughly
+- **Self-contained** - minimal cross-references
+- **Example-driven** - shows good/bad patterns
+- **Checklist-equipped** - actionable validation steps
+
+---
+
+## Legacy Documentation
+
+The original `COMPONENT_STANDARDS.md` file has been split into these focused documents. Refer to these new files for all component development.