300 lines
7.8 KiB
Markdown
300 lines
7.8 KiB
Markdown
# 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
|
|
```
|