From e862a9b0fefa570952aed47a3fd4033a66612fb1 Mon Sep 17 00:00:00 2001 From: bender Date: Fri, 17 Apr 2026 21:17:50 +0000 Subject: [PATCH] Switch to version 2: added docs/REGISTRY_FOLDER_STRUCTURE.md --- docs/REGISTRY_FOLDER_STRUCTURE.md | 299 ++++++++++++++++++++++++++++++ 1 file changed, 299 insertions(+) create mode 100644 docs/REGISTRY_FOLDER_STRUCTURE.md diff --git a/docs/REGISTRY_FOLDER_STRUCTURE.md b/docs/REGISTRY_FOLDER_STRUCTURE.md new file mode 100644 index 0000000..1003662 --- /dev/null +++ b/docs/REGISTRY_FOLDER_STRUCTURE.md @@ -0,0 +1,299 @@ +# 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 +```