diff --git a/docs/REGISTRY_FOLDER_STRUCTURE.md b/docs/REGISTRY_FOLDER_STRUCTURE.md deleted file mode 100644 index 1003662..0000000 --- a/docs/REGISTRY_FOLDER_STRUCTURE.md +++ /dev/null @@ -1,299 +0,0 @@ -# Registry Folder Structure - -This document explains the new folder-based registry structure in `/registry/` and how to work with it. - -## Folder Overview - -``` -registry/ -├── index.json # Quick lookup index for all components -├── intents.json # Intent-based component grouping -├── components/ # Full component documentation -│ ├── HeroBillboard.json -│ ├── FeatureCardOne.json -│ └── ... -└── schemas/ # Simplified prop schemas - ├── HeroBillboard.schema.json - ├── FeatureCardOne.schema.json - └── ... -``` - -## File Purposes - -### index.json - -**Quick lookup index** for component discovery and selection. - -**Use case:** AI builders use this to find the right component for a given intent. - -```json -{ - "HeroBillboard": { - "category": "hero", - "intent": "hero with media", - "bestFor": ["landing pages", "feature showcases", "capability displays"], - "avoidWhen": ["multiple items"], - "requires": ["buttons?[]"], - "import": "@/components/sections/hero/HeroBillboard" - } -} -``` - -**Fields:** -- `category` - Component category (hero, feature, pricing, team, etc.) -- `intent` - Primary use case -- `bestFor` - Ideal scenarios for this component -- `avoidWhen` - When NOT to use this component -- `requires` - Required prop arrays (use `?[]` for optional) -- `import` - Import path for the component - ---- - -### intents.json - -**Intent-based grouping** for semantic component discovery. - -**Use case:** AI builders use this to find all components that match a specific intent. - -```json -{ - "hero with media": [ - "HeroBillboard", - "HeroBillboardCarousel", - "HeroSplit", - "HeroOverlay" - ], - "feature showcase": [ - "FeatureCardOne", - "FeatureCardThree", - "FeatureBento" - ], - "testimonials": [ - "TestimonialCardOne", - "TestimonialCardTwo" - ] -} -``` - -**Common intents:** -- `hero with media` - Hero sections with images/videos -- `feature showcase` - Feature display sections -- `testimonials` - Customer testimonial sections -- `sequential process` - Step-by-step or timeline sections -- `metrics display` - Statistics and KPI sections -- `contact form` - Contact and CTA sections -- `pricing plans` - Pricing tier sections - ---- - -### components/*.json - -**Full component documentation** with constraints, examples, and rules. - -**Use case:** AI builders use this for detailed implementation guidance. - -```json -{ - "name": "HeroBillboard", - "description": "Full-width hero section with centered text content...", - "constraints": { - "textRules": { - "title": { - "required": true, - "example": "Welcome to Our Platform", - "minChars": 2, - "maxChars": 36 - } - }, - "mediaRules": {...}, - "buttonRules": {...} - }, - "propsSchema": { - "title": "string", - "description": "string", - "tag?": "string", - "tagAnimation?": "'none' | 'opacity' | 'slide-up' | 'blur-reveal'", - "buttons?": "Array<{text: string, onClick?: () => void, href?: string}>", - "buttonAnimation?": "'none' | 'opacity' | 'slide-up' | 'blur-reveal'", - "mediaAnimation?": "'none' | 'opacity' | 'slide-up' | 'blur-reveal'" - }, - "usageExample": "", - "do": ["Use for landing pages", "Use for feature showcases"], - "dont": ["Do not use multiple items"], - "editRules": { - "textOnly": true, - "layoutLocked": true, - "styleLocked": true - } -} -``` - -**Sections:** -- `name` - Component name -- `description` - Brief component description -- `constraints` - Text length limits, media rules, button rules -- `propsSchema` - All props with types and defaults -- `usageExample` - Complete usage example with ThemeProvider -- `do` - Recommended use cases -- `dont` - Anti-patterns to avoid -- `editRules` - What can/cannot be customized - ---- - -### schemas/*.schema.json - -**Simplified prop schemas** for quick reference. - -**Use case:** AI builders use this for prop validation and code generation. - -```json -{ - "name": "HeroBillboard", - "propsSchema": { - "title": "string", - "description": "string", - "background": "{ variant: 'plain' | 'animated-grid' | ... } (required)", - "tag?": "string", - "tagIcon?": "LucideIcon", - "tagAnimation?": "'none' | 'opacity' | 'slide-up' | 'blur-reveal'", - "buttons?": "Array<{text: string, onClick?: () => void, href?: string}>", - "buttonAnimation?": "'none' | 'opacity' | 'slide-up' | 'blur-reveal'", - "mediaAnimation?": "'none' | 'opacity' | 'slide-up' | 'blur-reveal'", - "className?": "string", - "containerClassName?": "string", - "titleClassName?": "string" - } -} -``` - -**Note:** Schema files include ALL className props while component files may omit them for brevity. - ---- - -## When to Update Each File - -### Adding a New Component - -1. Add entry to `index.json` with category, intent, bestFor, avoidWhen, requires, import -2. Add component name to appropriate intent(s) in `intents.json` -3. Create `components/ComponentName.json` with full documentation -4. Create `schemas/ComponentName.schema.json` with prop schema - -### Adding a New Prop - -1. Update `components/ComponentName.json` propsSchema -2. Update `schemas/ComponentName.schema.json` propsSchema -3. If prop affects usage, update `usageExample` in component file - -### Modifying Constraints - -1. Only update `components/ComponentName.json` constraints section - -### Changing Component Intent/Category - -1. Update `index.json` entry -2. Move component name between arrays in `intents.json` - ---- - -## Common Prop Patterns - -### Animation Props - -All animation props follow the same pattern: - -```json -"tagAnimation?": "'none' | 'opacity' | 'slide-up' | 'blur-reveal'", -"buttonAnimation?": "'none' | 'opacity' | 'slide-up' | 'blur-reveal'", -"mediaAnimation?": "'none' | 'opacity' | 'slide-up' | 'blur-reveal'" -``` - -### Background Props - -Hero sections use background variant: - -```json -"background": "{ variant: 'plain' | 'animated-grid' | 'canvas-reveal' | 'cell-wave' | 'downward-rays-animated' | ... } (required)" -``` - -### Button Config - -Standard button array structure: - -```json -"buttons?": "Array<{text: string, onClick?: () => void, href?: string}>" -``` - -### ClassName Props - -Always include standard className props in schema files: - -```json -"className?": "string", -"containerClassName?": "string", -"textBoxClassName?": "string", -"titleClassName?": "string", -"descriptionClassName?": "string", -"tagClassName?": "string", -"buttonContainerClassName?": "string", -"buttonClassName?": "string", -"buttonTextClassName?": "string", -"mediaWrapperClassName?": "string", -"imageClassName?": "string" -``` - ---- - -## Validation Checklist - -When updating registry files: - -### index.json -- [ ] Category matches component type -- [ ] Intent matches primary use case -- [ ] bestFor list is comprehensive -- [ ] avoidWhen captures real limitations -- [ ] requires uses `?[]` for optional arrays -- [ ] import path is correct - -### intents.json -- [ ] Component is listed under correct intent(s) -- [ ] No duplicate entries -- [ ] Intent names are consistent - -### components/*.json -- [ ] name matches filename -- [ ] description is concise -- [ ] constraints have realistic examples -- [ ] propsSchema matches component interface -- [ ] usageExample is valid JSX -- [ ] do/dont provide useful guidance -- [ ] editRules are accurate - -### schemas/*.schema.json -- [ ] name matches filename -- [ ] propsSchema matches component file -- [ ] All className props included -- [ ] Optional props use `?` suffix -- [ ] Defaults noted with `(default: value)` - ---- - -## Quick Reference: File Relationships - -``` -Component: HeroBillboard - -registry/ -├── index.json -│ └── "HeroBillboard": { category, intent, bestFor, ... } -│ -├── intents.json -│ └── "hero with media": ["HeroBillboard", ...] -│ -├── components/HeroBillboard.json -│ └── Full documentation with constraints, examples, rules -│ -└── schemas/HeroBillboard.schema.json - └── Simplified propsSchema for code generation -```