{
  "name": "HeroBillboardCarousel",
  "description": "Full-width hero section with centered text, configurable background, and 5+ auto-scrolling images in carousel layout.",
  "details": "Use for showcasing large collections or portfolios. Features centered title and description with TextBox animations, required background variant (choose from animated grids, gradient effects, or 'plain' for no background), optional tag with icon, up to 2 CTA buttons. Displays 5 or more images in auto-scrolling carousel on both mobile and desktop. Full viewport height with vertical centering on desktop. Background variants include preset options for zero-config usage.",
  "constraints": {
    "textRules": {
      "title": {
        "required": true,
        "example": "Our Portfolio",
        "minChars": 2,
        "maxChars": 40
      },
      "description": {
        "required": true,
        "example": "Browse through our collection of projects",
        "minChars": 5,
        "maxChars": 200
      },
      "tag": {
        "required": false,
        "example": "Portfolio",
        "minChars": 2,
        "maxChars": 30
      }
    },
    "mediaRules": {
      "mediaItems": {
        "required": true,
        "example": "[{ imageSrc: '/img1.jpg', imageAlt: 'Product 1' }, { imageSrc: '/img2.jpg', imageAlt: 'Product 2' }, { imageSrc: '/img3.jpg', imageAlt: 'Product 3' }, { imageSrc: '/img4.jpg', imageAlt: 'Product 4' }, { imageSrc: '/img5.jpg', imageAlt: 'Product 5' }]",
        "note": "Array of 5+ MediaItem objects. Each item can have imageSrc, videoSrc, imageAlt, videoAriaLabel. Requires minimum 5 images."
      }
    },
    "buttonRules": {
      "maxButtons": 2,
      "structure": {
        "text": "string - Button label (required)",
        "href": "string - Link destination (optional). External URLs (https://, http://, www.) open in new tab. Internal values (e.g., 'about', 'contact') scroll to #about, #contact sections",
        "onClick": "() => void - Additional click handler (optional)",
        "props": "Partial<ButtonPropsForVariant> - Additional button props like className, textClassName (optional)"
      },
      "examples": [
        "{ text: 'View Portfolio', href: 'https://example.com' }",
        "{ text: 'Contact Us', href: 'contact' }"
      ],
      "note": "Button variant is controlled by ThemeProvider's defaultButtonVariant. Border radius is controlled by ThemeProvider's borderRadius (options: 'sharp', 'rounded', 'soft', 'pill'). All sections should be wrapped in a single ThemeProvider at the app/page level to maintain consistent styling across the entire site."
    }
  },
  "propsSchema": {
    "title": "string",
    "description": "string",
    "background": "{ variant: 'plain' | 'animated-grid' | 'canvas-reveal' | 'cell-wave' | 'downward-rays-animated' | 'downward-rays-animated-grid' | 'downward-rays-static' | 'downward-rays-static-grid' | 'gradient-bars' | 'radial-gradient' | 'rotated-rays-animated' | 'rotated-rays-animated-grid' | 'rotated-rays-static' | 'rotated-rays-static-grid' | 'sparkles-gradient' }",
    "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'",
    "mediaItems": "Array<{ imageSrc?: string, videoSrc?: string, imageAlt?: string, videoAriaLabel?: string }> - Each item requires either imageSrc or videoSrc",
    "ariaLabel?": "string (default: 'Hero section')",
    "className?": "string",
    "containerClassName?": "string",
    "textBoxClassName?": "string",
    "titleClassName?": "string",
    "descriptionClassName?": "string",
    "tagClassName?": "string",
    "buttonContainerClassName?": "string",
    "buttonClassName?": "string",
    "buttonTextClassName?": "string",
    "mediaWrapperClassName?": "string"
  },
  "usageExample": "<ThemeProvider defaultButtonVariant=\"text-stagger\" defaultTextAnimation=\"entrance-slide\" borderRadius=\"rounded\">\n  <HeroBillboardCarousel \n    background={{ variant: 'sparkles-gradient' }}\n    title=\"Our Portfolio\" \n    description=\"Browse through our collection of projects\" \n    tag=\"Portfolio\" \n    mediaItems={[\n      { imageSrc: '/img1.jpg', imageAlt: 'Product 1' },\n      { imageSrc: '/img2.jpg', imageAlt: 'Product 2' },\n      { imageSrc: '/img3.jpg', imageAlt: 'Product 3' },\n      { imageSrc: '/img4.jpg', imageAlt: 'Product 4' },\n      { imageSrc: '/img5.jpg', imageAlt: 'Product 5' },\n      { imageSrc: '/img6.jpg', imageAlt: 'Product 6' },\n      { imageSrc: '/img7.jpg', imageAlt: 'Product 7' }\n    ]}\n    buttons={[{ text: 'View Portfolio', href: 'https://example.com' }, { text: 'Contact Us', href: 'contact' }]} \n  />\n</ThemeProvider>",
  "do": [
    "Use for landing pages",
    "Use for feature showcases",
    "Use for capability displays",
    "Use for portfolios",
    "Use for image galleries",
    "Requires buttons?[]",
    "Requires mediaItems[]"
  ],
  "dont": [
    "Do not use less than 5 items"
  ],
  "editRules": {
    "textOnly": true,
    "layoutLocked": true,
    "styleLocked": true
  }
}
