Initial commit
This commit is contained in:
299
docs/REGISTRY_FOLDER_STRUCTURE.md
Normal file
299
docs/REGISTRY_FOLDER_STRUCTURE.md
Normal file
@@ -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": "<HeroBillboard title=\"...\" ... />",
|
||||
"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
|
||||
```
|
||||
Reference in New Issue
Block a user