795bf9bf-81ed-43a1-9214-e3e49c8acf19/docs/REGISTRY_FOLDER_STRUCTURE.md

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.

{
  "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.

{
  "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.

{
  "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.

{
  "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:

"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:

"background": "{ variant: 'plain' | 'animated-grid' | 'canvas-reveal' | 'cell-wave' | 'downward-rays-animated' | ... } (required)"

Button Config

Standard button array structure:

"buttons?": "Array<{text: string, onClick?: () => void, href?: string}>"

ClassName Props

Always include standard className props in schema files:

"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