6c4bf59b-39cf-423b-a293-20f9469ff1e1/docs/REGISTRY_STANDARDS.md

Registry Documentation Standards

This document outlines how to document components in registry.json for AI website builders.

Registry Structure

The registry is organized into two main sections:

{
  "componentRegistry": {
    "button": [...],
    "text": [...],
    "navbar": [...],
    "layout": [...]
  },
  "sectionRegistry": {
    "hero": [...],
    "about": [...],
    "feature": [...],
    "testimonial": [...],
    "pricing": [...],
    "team": [...],
    "product": [...],
    "metrics": [...],
    "blog": [...],
    "footer": [...],
    "contact": [...],
    "faq": [...],
    "socialProof": [...]
  }
}

componentRegistry - Base/utility components (buttons, text, navbar, CardStack, etc.) sectionRegistry - Section components (hero, about, feature, etc.)

Component Entry Format

Every component entry must follow this structure:

{
  "import": "import ComponentName from '@/components/category/ComponentName';",
  "name": "ComponentName",
  "path": "@/components/category/ComponentName",
  "description": "Brief one-line description of what the component is.",
  "details": "Longer description of when to use it, behavior, and constraints.",
  "constraints": {
    "textRules": {
      "text": {
        "required": true,
        "example": "Example text",
        "minChars": 2,
        "maxChars": 15
      }
    }
  },
  "propsSchema": {
    "text": "string",
    "onClick?": "() => void",
    "className?": "string",
    "disabled?": "boolean (default: false)",
    "ariaLabel?": "string",
    "type?": "'button' | 'submit' | 'reset' (default: 'button')"
  },
  "usage": "<ComponentName text=\"Example\" onClick={() => console.log('clicked')} />"
}

Field Descriptions

import

The exact import statement AI should use.

Format:

"import": "import ComponentName from '@/components/category/ComponentName';"

Examples:

"import": "import HeroBillboard from '@/components/sections/hero/HeroBillboard';"
"import": "import ButtonTextStagger from '@/components/button/text-stagger/ButtonTextStagger';"
"import": "import CardStack from '@/components/cardStack/CardStack';"

name

Component name exactly as exported.

Format:

"name": "ComponentName"

path

File path without extension.

Format:

"path": "@/components/category/ComponentName"

description

One-line summary of what the component is. Focus on visual/behavioral characteristics.

Format: 1 sentence, under 100 characters

Good Examples:

"description": "CTA button with character stagger animation on hover."
"description": "Full-width hero section with centered text and billboard layout."
"description": "Feature section with grid or carousel layout for feature cards."

Bad Examples:

"description": "A really cool button component with lots of features and animations that can be used anywhere."  // Too verbose
"description": "Button"  // Too vague

details

Longer description covering:

• When to use it
• Key behavior notes
• Important constraints

Format: 2-4 sentences

Good Example:

"details": "Use for primary or secondary CTAs where subtle text motion adds emphasis. On hover, the label's characters animate in sequence (stagger). Includes background styling and supports all standard button props."

Bad Example:

"details": "This is a button that you can click and it will do something when you click it. It has animations."  // Too obvious, not helpful

constraints

Defines text length constraints for string props.

Format:

"constraints": {
  "textRules": {
    "propName": {
      "required": true,
      "example": "Example value",
      "minChars": 2,
      "maxChars": 15
    }
  }
}

Common Patterns:

Button text:

"constraints": {
  "textRules": {
    "text": {
      "required": true,
      "example": "Get Started",
      "minChars": 2,
      "maxChars": 15
    }
  }
}

Section titles and descriptions:

"constraints": {
  "textRules": {
    "title": {
      "required": true,
      "example": "Welcome to Our Platform",
      "minChars": 5,
      "maxChars": 60
    },
    "description": {
      "required": true,
      "example": "Build amazing websites with our component library",
      "minChars": 10,
      "maxChars": 200
    }
  }
}

propsSchema

Documents all component props with types and defaults.

Format Rules:

Required props:

"propName": "type"

Optional props:

"propName?": "type"

Optional props with defaults:

"propName?": "type (default: value)"

Examples:

Simple types:

"text": "string",
"count": "number",
"enabled": "boolean"

Functions:

"onClick?": "() => void",
"onChange?": "(value: string) => void",
"onSubmit?": "(data: FormData) => Promise<void>"

Union types:

"type?": "'button' | 'submit' | 'reset' (default: 'button')",
"variant?": "'primary' | 'secondary' | 'ghost'",
"size?": "'sm' | 'md' | 'lg' (default: 'md')"

Array types:

"items": "Array<{ title: string; description: string }>",
"buttons?": "ButtonConfig[]",
"features": "Feature[]"

Complex types:

"gridVariant": "'uniform-all-items-equal' | 'two-columns-alternating-heights' | 'asymmetric-60-wide-40-narrow' | ...",
"icon?": "LucideIcon",
"image?": "string (URL or path)"

With defaults:

"className?": "string",
"disabled?": "boolean (default: false)",
"carouselMode?": "'auto' | 'buttons' (default: 'buttons')",
"uniformGridCustomHeightClasses?": "string (default: 'min-h-80 2xl:min-h-90')"

usage

Single-line example showing typical implementation.

Format: One line, realistic props, valid JSX

Good Examples:

Button:

"usage": "<ButtonTextStagger text=\"Get Started\" onClick={() => console.log('clicked')} />"

Section with minimal props:

"usage": "<HeroBillboard title=\"Welcome\" description=\"Start building today\" buttons={[{ text: 'Get Started', href: '/signup' }]} />"

CardStack section:

"usage": "<FeatureCardOne features={featuresData} gridVariant=\"uniform-all-items-equal\" textboxLayout=\"default\" title=\"Features\" description=\"Our key features\" />"

Bad Examples:

"usage": "<Component />"  // Missing required props
"usage": "<Component\n  prop1=\"value\"\n  prop2=\"value\"\n/>"  // Multi-line, hard to read
"usage": "Component({ text: 'Hi' })"  // Not JSX

What to Include

✅ DO Include:

Default values in propsSchema - Critical for AI to generate correct code

"disabled?": "boolean (default: false)",
"type?": "'button' | 'submit' | 'reset' (default: 'button')"

Usage examples - Helps AI understand context

"usage": "<ButtonTextStagger text=\"Click me\" onClick={() => alert('Hi')} />"

Text constraints - Min/max character limits

"constraints": {
  "textRules": {
    "text": {
      "required": true,
      "example": "Get Started",
      "minChars": 2,
      "maxChars": 15
    }
  }
}

Accurate descriptions - Ensure description matches actual behavior

"description": "CTA button with character stagger animation on hover.",
"details": "Use for primary or secondary CTAs where subtle text motion adds emphasis."

Use case guidance - When to use this vs alternatives

"details": "Use for hero sections with centered content and billboard layout. Best for landing pages and marketing sites."

What NOT to Include

❌ DO NOT Include:

Metadata field - Unnecessary complexity

// Don't do this:
"metadata": {
  "category": "button",
  "version": "1.0.0",
  "author": "..."
}

Verbose descriptions - Keep concise and obvious

// Don't do this:
"description": "This is an amazing button component that you can use to create buttons with stagger animations that look really cool and modern and will make your website stand out from the competition."

Dependencies - AI builders can infer from imports

// Don't do this:
"dependencies": ["lucide-react", "framer-motion"]

Over-documentation - If it's obvious from the name, skip it

// Don't do this:
"details": "This is a button. You can click it. It accepts text to display on the button."

Implementation details - Focus on usage, not internals

// Don't do this:
"details": "Uses GSAP ScrollTrigger with stagger: 0.1 and uses React.memo for performance and has displayName set to ButtonTextStagger."

Complete Examples

Button Component

{
  "import": "import ButtonTextStagger from '@/components/button/text-stagger/ButtonTextStagger';",
  "name": "ButtonTextStagger",
  "path": "@/components/button/text-stagger/ButtonTextStagger",
  "description": "CTA button with character stagger animation on hover.",
  "details": "Use for primary or secondary CTAs where subtle text motion adds emphasis. On hover, the label's characters animate in sequence (stagger). Includes background styling.",
  "constraints": {
    "textRules": {
      "text": {
        "required": true,
        "example": "Get Started",
        "minChars": 2,
        "maxChars": 15
      }
    }
  },
  "propsSchema": {
    "text": "string",
    "onClick?": "() => void",
    "href?": "string",
    "className?": "string",
    "textClassName?": "string",
    "disabled?": "boolean (default: false)",
    "ariaLabel?": "string",
    "type?": "'button' | 'submit' | 'reset' (default: 'button')"
  },
  "usage": "<ButtonTextStagger text=\"Get Started\" onClick={() => console.log('clicked')} />"
}

Section Component (CardStack-based)

{
  "import": "import FeatureCardOne from '@/components/sections/feature/FeatureCardOne';",
  "name": "FeatureCardOne",
  "path": "@/components/sections/feature/FeatureCardOne",
  "description": "Feature section with grid or carousel layout for feature cards.",
  "details": "Displays feature cards in a responsive grid (1-4 items) or carousel (5+ items). Supports TextBox header with multiple layout options. Each card includes icon, title, and description.",
  "constraints": {
    "textRules": {
      "title": {
        "required": true,
        "example": "Our Features",
        "minChars": 5,
        "maxChars": 60
      },
      "description": {
        "required": true,
        "example": "Discover what makes us unique",
        "minChars": 10,
        "maxChars": 200
      }
    }
  },
  "propsSchema": {
    "features": "Array<{ icon: LucideIcon; title: string; description: string }>",
    "gridVariant": "'uniform-all-items-equal' | 'two-columns-alternating-heights' | 'asymmetric-60-wide-40-narrow' | ...",
    "title": "string",
    "description": "string",
    "tag?": "string",
    "tagIcon?": "LucideIcon",
    "buttons?": "ButtonConfig[]",
    "textboxLayout": "'default' | 'split' | 'split-actions' | 'split-description'",
    "carouselMode?": "'auto' | 'buttons' (default: 'buttons')",
    "uniformGridCustomHeightClasses?": "string (default: 'min-h-80 2xl:min-h-90')",
    "ariaLabel?": "string",
    "className?": "string"
  },
  "usage": "<FeatureCardOne features={featuresData} gridVariant=\"uniform-all-items-equal\" textboxLayout=\"default\" title=\"Features\" description=\"Our key features\" />"
}

Registry Validation Checklist

When adding a new component to the registry:

Required Fields

• import - Exact import statement
• name - Component name
• path - File path without extension
• description - One-line summary
• details - When to use, behavior, constraints
• propsSchema - All props documented
• usage - Single-line example

Constraints (if applicable)

• Add textRules for text props
• Set minChars and maxChars
• Provide realistic example values
• Mark required: true for required props

propsSchema Format

• Required props: "prop": "type"
• Optional props: "prop?": "type"
• Defaults: "prop?": "type (default: value)"
• All types match component implementation
• Union types use single quotes inside double quotes

Quality Checks

• Description is concise (under 100 chars)
• Details provide use case guidance
• Usage example is valid JSX
• Usage example shows realistic props
• Default values documented in propsSchema
• No over-documentation or verbose descriptions
• No unnecessary metadata or dependencies

Consistency Checks

• Component name matches file name
• Path matches actual file location
• Import statement is correct
• Props match actual component interface
• Defaults in registry match component defaults
• Naming follows conventions (title/description for sections, text for buttons)