{
  "feature": "accessible-component-library",
  "version": "1.0.0",
  "description": "Accessible, composable UI component library built on accessible component primitives with variant system, Tailwind CSS styling, and a multi-style design system",
  "category": "ui",
  "tags": [
    "components",
    "design-system",
    "accessible-primitives",
    "tailwind",
    "accessibility",
    "react"
  ],
  "actors": [
    {
      "id": "developer",
      "name": "Developer",
      "type": "human",
      "description": "Consumes components in their application"
    },
    {
      "id": "end_user",
      "name": "End User",
      "type": "human",
      "description": "Interacts with the rendered UI components"
    },
    {
      "id": "design_system",
      "name": "Design System",
      "type": "system",
      "description": "CSS custom properties, style presets, and theme configuration"
    },
    {
      "id": "accessible_primitives",
      "name": "Accessible Component Primitives",
      "type": "external",
      "description": "Unstyled, accessible component primitives providing ARIA compliance"
    },
    {
      "id": "alternative_primitives",
      "name": "Alternative Accessible Primitives",
      "type": "external",
      "description": "Alternative unstyled component primitives"
    }
  ],
  "fields": [
    {
      "name": "primitive_library",
      "label": "Primitive Library",
      "type": "select",
      "required": true,
      "options": [
        {
          "value": "library-a",
          "label": "Library A"
        },
        {
          "value": "library-b",
          "label": "Library B"
        }
      ]
    },
    {
      "name": "style",
      "label": "Design Style",
      "type": "select",
      "required": true,
      "options": [
        {
          "value": "vega",
          "label": "Vega"
        },
        {
          "value": "nova",
          "label": "Nova"
        },
        {
          "value": "lyra",
          "label": "Lyra"
        },
        {
          "value": "maia",
          "label": "Maia"
        },
        {
          "value": "mira",
          "label": "Mira"
        },
        {
          "value": "luma",
          "label": "Luma"
        }
      ]
    },
    {
      "name": "icon_library",
      "label": "Icon Library",
      "type": "select",
      "required": false,
      "options": [
        {
          "value": "lucide",
          "label": "Lucide"
        },
        {
          "value": "hugeicons",
          "label": "Hugeicons"
        },
        {
          "value": "tabler",
          "label": "Tabler"
        },
        {
          "value": "phosphor",
          "label": "Phosphor"
        },
        {
          "value": "remixicon",
          "label": "Remix Icon"
        }
      ]
    },
    {
      "name": "border_radius",
      "label": "Border Radius",
      "type": "number",
      "required": false
    },
    {
      "name": "font_family",
      "label": "Font Family",
      "type": "text",
      "required": false
    },
    {
      "name": "variant",
      "label": "Component Variant",
      "type": "text",
      "required": false
    },
    {
      "name": "size",
      "label": "Component Size",
      "type": "select",
      "required": false,
      "options": [
        {
          "value": "default",
          "label": "Default"
        },
        {
          "value": "sm",
          "label": "Small"
        },
        {
          "value": "lg",
          "label": "Large"
        },
        {
          "value": "icon",
          "label": "Icon"
        }
      ]
    },
    {
      "name": "as_child",
      "label": "Render as Child",
      "type": "boolean",
      "required": false
    },
    {
      "name": "form_field_name",
      "label": "Form Field Name",
      "type": "text",
      "required": true
    },
    {
      "name": "form_field_error",
      "label": "Field Error Message",
      "type": "text",
      "required": false
    },
    {
      "name": "sidebar_state",
      "label": "Sidebar State",
      "type": "select",
      "required": false,
      "options": [
        {
          "value": "expanded",
          "label": "Expanded"
        },
        {
          "value": "collapsed",
          "label": "Collapsed"
        }
      ]
    },
    {
      "name": "sidebar_open",
      "label": "Sidebar Mobile Open",
      "type": "boolean",
      "required": false
    }
  ],
  "rules": {
    "accessibility": {
      "aria_compliance": true,
      "keyboard_navigation": true,
      "focus_management": true,
      "screen_reader_labels": true
    },
    "composition": {
      "slot_pattern": true,
      "data_slot_attributes": true,
      "context_based_state": true,
      "compound_components": true
    },
    "styling": {
      "cva_variants": true,
      "cn_utility": true,
      "css_custom_properties": true,
      "tailwind_v4": true,
      "multi_theme": true
    },
    "state_management": {
      "sidebar_cookie_persistence": true,
      "jotai_atoms": true,
      "url_state": true
    },
    "dependencies": {
      "react_hook_form": true,
      "tanstack_table": true,
      "recharts": true,
      "embla_carousel": true
    }
  },
  "outcomes": {
    "component_renders_with_variants": {
      "priority": 1,
      "given": [
        "Developer passes variant and size props to a component",
        {
          "field": "variant",
          "source": "input",
          "operator": "exists"
        }
      ],
      "then": [
        {
          "action": "call_service",
          "target": "cva.resolve_classname",
          "description": "CVA resolves variant+size to Tailwind className string"
        },
        {
          "action": "call_service",
          "target": "cn.merge",
          "description": "cn() merges variant classes with any custom className prop"
        }
      ],
      "result": "Component renders with correct visual variant and allows className overrides"
    },
    "component_renders_as_child": {
      "priority": 2,
      "given": [
        "Developer passes asChild=true to a component",
        {
          "field": "as_child",
          "source": "input",
          "operator": "eq",
          "value": true
        }
      ],
      "then": [
        {
          "action": "call_service",
          "target": "radix.slot",
          "description": "Radix Slot merges props onto child element instead of rendering wrapper"
        }
      ],
      "result": "Component behaviour applied to child element without extra DOM node"
    },
    "form_field_validates": {
      "priority": 3,
      "given": [
        "Form is wrapped in FormProvider with react-hook-form",
        "FormField is configured with validation rules"
      ],
      "then": [
        {
          "action": "call_service",
          "target": "react_hook_form.validate",
          "description": "react-hook-form validates field against schema (Zod resolver)"
        },
        {
          "action": "set_field",
          "target": "form_field_error",
          "value": "validation error message"
        }
      ],
      "result": "FormMessage displays error, FormControl gets aria-invalid=true and aria-describedby linking to error"
    },
    "form_submits_successfully": {
      "priority": 4,
      "given": [
        "All form fields pass validation",
        "User submits the form"
      ],
      "then": [
        {
          "action": "call_service",
          "target": "react_hook_form.handle_submit",
          "description": "Form handler receives validated, typed data"
        }
      ],
      "result": "Developer's onSubmit callback receives strongly-typed form values"
    },
    "dialog_opens_with_focus_trap": {
      "priority": 5,
      "given": [
        "User clicks DialogTrigger or sheet/drawer trigger"
      ],
      "then": [
        {
          "action": "call_service",
          "target": "radix.portal",
          "description": "Overlay content rendered in React Portal"
        },
        {
          "action": "call_service",
          "target": "radix.focus_trap",
          "description": "Focus trapped inside dialog, Tab cycles within content"
        }
      ],
      "result": "Dialog is visible with backdrop overlay, focus trapped, ESC to close"
    },
    "dialog_closes": {
      "priority": 6,
      "given": [
        {
          "any": [
            "User presses Escape key",
            "User clicks overlay backdrop",
            "User clicks close button (if showCloseButton=true)"
          ]
        }
      ],
      "then": [
        {
          "action": "call_service",
          "target": "radix.restore_focus",
          "description": "Focus returned to trigger element"
        }
      ],
      "result": "Dialog closes and focus returns to the element that opened it"
    },
    "sidebar_toggles": {
      "priority": 7,
      "given": [
        {
          "any": [
            "User clicks SidebarTrigger button",
            "User presses keyboard shortcut"
          ]
        }
      ],
      "then": [
        {
          "action": "set_field",
          "target": "sidebar_state",
          "value": "toggled value"
        },
        {
          "action": "call_service",
          "target": "cookie.persist",
          "description": "Persist sidebar state in cookie for next page load"
        }
      ],
      "result": "Sidebar expands or collapses with animation, state persisted across sessions"
    },
    "sidebar_mobile_responsive": {
      "priority": 8,
      "given": [
        "Viewport width is below mobile breakpoint"
      ],
      "then": [
        {
          "action": "call_service",
          "target": "sheet.render",
          "description": "Sidebar renders as a Sheet (slide-in overlay) on mobile"
        }
      ],
      "result": "Sidebar adapts to mobile as a dismissible sheet overlay"
    },
    "table_renders_with_sorting": {
      "priority": 9,
      "given": [
        "Developer provides column definitions with sorting enabled",
        "Data array is passed to useReactTable hook"
      ],
      "then": [
        {
          "action": "call_service",
          "target": "tanstack.create_table",
          "description": "@tanstack/react-table creates headless table instance"
        }
      ],
      "result": "Table renders with sortable columns, click headers to sort"
    },
    "theme_switches_light_dark": {
      "priority": 10,
      "given": [
        "User changes system colour scheme preference or developer toggles theme"
      ],
      "then": [
        {
          "action": "set_field",
          "target": "css_custom_properties",
          "value": "light or dark theme values"
        }
      ],
      "result": "All components update to light/dark theme via CSS variable cascade"
    },
    "style_preset_applied": {
      "priority": 11,
      "given": [
        "Design system config has a style value (vega, nova, lyra, maia, mira, luma)"
      ],
      "then": [
        {
          "action": "set_field",
          "target": "css_custom_properties",
          "value": "style-specific CSS variable overrides"
        }
      ],
      "result": "Components render with chosen design style's spacing, radius, typography"
    },
    "toast_displays": {
      "priority": 12,
      "given": [
        "Developer calls toast() or sonner function"
      ],
      "then": [
        {
          "action": "call_service",
          "target": "sonner.show",
          "description": "Toast appears in configured position with auto-dismiss timer"
        }
      ],
      "result": "Non-intrusive notification shown to user, auto-dismisses after timeout"
    },
    "component_import_missing": {
      "priority": 13,
      "error": "COMPONENT_NOT_INSTALLED",
      "given": [
        "Developer imports a component that hasn't been added via CLI"
      ],
      "then": [
        {
          "action": "notify",
          "channel": "build",
          "target": "developer",
          "description": "Build error or module not found error"
        }
      ],
      "result": "Developer must run 'shadcn add <component>' to install it"
    }
  },
  "errors": [
    {
      "code": "COMPONENT_NOT_INSTALLED",
      "status": 404,
      "message": "Component not found. Run 'npx shadcn add <component>' to install it."
    },
    {
      "code": "FORM_VALIDATION_FAILED",
      "status": 422,
      "message": "One or more form fields contain invalid values."
    },
    {
      "code": "INVALID_VARIANT",
      "status": 400,
      "message": "Unknown variant or size value passed to component."
    },
    {
      "code": "MISSING_FORM_CONTEXT",
      "status": 500,
      "message": "useFormField must be used within a FormField component."
    },
    {
      "code": "MISSING_SIDEBAR_CONTEXT",
      "status": 500,
      "message": "useSidebar must be used within a SidebarProvider."
    }
  ],
  "events": [
    {
      "name": "form.submit.success",
      "description": "Form submitted with valid data",
      "payload": [
        "form_values",
        "form_name"
      ]
    },
    {
      "name": "form.validation.error",
      "description": "Form validation failed",
      "payload": [
        "field_name",
        "error_message"
      ]
    },
    {
      "name": "sidebar.toggle",
      "description": "Sidebar expanded or collapsed",
      "payload": [
        "new_state",
        "is_mobile"
      ]
    },
    {
      "name": "dialog.open",
      "description": "Dialog or sheet opened",
      "payload": [
        "dialog_id"
      ]
    },
    {
      "name": "dialog.close",
      "description": "Dialog or sheet closed",
      "payload": [
        "dialog_id",
        "close_reason"
      ]
    },
    {
      "name": "toast.show",
      "description": "Toast notification displayed",
      "payload": [
        "message",
        "type",
        "duration"
      ]
    },
    {
      "name": "theme.change",
      "description": "Theme switched between light and dark",
      "payload": [
        "new_theme"
      ]
    }
  ],
  "related": [
    {
      "feature": "shadcn-cli",
      "type": "required",
      "reason": "The CLI tool that installs and manages these components in developer projects"
    }
  ],
  "agi": {
    "goals": [
      {
        "id": "reliable_accessible_component_library",
        "description": "Accessible, composable UI component library built on accessible component primitives with variant system, Tailwind CSS styling, and a multi-style design system",
        "success_metrics": [
          {
            "metric": "success_rate",
            "target": ">= 99%",
            "measurement": "Successful operations divided by total attempts"
          },
          {
            "metric": "error_rate",
            "target": "< 1%",
            "measurement": "Failed operations divided by total attempts"
          }
        ],
        "constraints": []
      }
    ],
    "autonomy": {
      "level": "semi_autonomous",
      "human_checkpoints": [
        "before making irreversible changes"
      ],
      "escalation_triggers": [
        "error_rate > 5"
      ]
    },
    "safety": {
      "action_permissions": [
        {
          "action": "component_renders_with_variants",
          "permission": "autonomous"
        },
        {
          "action": "component_renders_as_child",
          "permission": "autonomous"
        },
        {
          "action": "form_field_validates",
          "permission": "autonomous"
        },
        {
          "action": "form_submits_successfully",
          "permission": "autonomous"
        },
        {
          "action": "dialog_opens_with_focus_trap",
          "permission": "autonomous"
        },
        {
          "action": "dialog_closes",
          "permission": "autonomous"
        },
        {
          "action": "sidebar_toggles",
          "permission": "autonomous"
        },
        {
          "action": "sidebar_mobile_responsive",
          "permission": "autonomous"
        },
        {
          "action": "table_renders_with_sorting",
          "permission": "autonomous"
        },
        {
          "action": "theme_switches_light_dark",
          "permission": "autonomous"
        },
        {
          "action": "style_preset_applied",
          "permission": "autonomous"
        },
        {
          "action": "toast_displays",
          "permission": "autonomous"
        },
        {
          "action": "component_import_missing",
          "permission": "autonomous"
        }
      ]
    },
    "tradeoffs": [
      {
        "prefer": "accessibility",
        "over": "aesthetics",
        "reason": "UI must be usable by all users including those with disabilities"
      }
    ],
    "coordination": {
      "protocol": "orchestrated",
      "consumes": [
        {
          "capability": "shadcn_cli",
          "from": "shadcn-cli",
          "fallback": "degrade"
        }
      ]
    }
  },
  "extensions": {
    "tech_stack": {
      "language": "TypeScript",
      "framework": "React 19 + Next.js 16",
      "styling": "Tailwind CSS v4",
      "primitives": "Radix UI / Base UI",
      "build": "Turborepo + pnpm"
    },
    "components": {
      "count": 56,
      "list": [
        "accordion",
        "alert",
        "alert-dialog",
        "aspect-ratio",
        "avatar",
        "badge",
        "breadcrumb",
        "button",
        "button-group",
        "calendar",
        "card",
        "carousel",
        "chart",
        "checkbox",
        "collapsible",
        "combobox",
        "command",
        "context-menu",
        "dialog",
        "direction",
        "drawer",
        "dropdown-menu",
        "empty",
        "field",
        "form",
        "hover-card",
        "input",
        "input-group",
        "input-otp",
        "kbd",
        "label",
        "menubar",
        "native-select",
        "navigation-menu",
        "pagination",
        "popover",
        "progress",
        "radio-group",
        "resizable",
        "scroll-area",
        "select",
        "separator",
        "sheet",
        "sidebar",
        "skeleton",
        "slider",
        "sonner",
        "spinner",
        "switch",
        "table",
        "tabs",
        "textarea",
        "toggle",
        "toggle-group",
        "tooltip"
      ]
    },
    "design_styles": [
      "vega",
      "nova",
      "lyra",
      "maia",
      "mira",
      "luma"
    ],
    "component_bases": [
      "radix",
      "base"
    ]
  },
  "ui_hints": {
    "component_pattern": "Compound components with subcomponent exports (e.g., Dialog.Trigger, Dialog.Content)",
    "styling_approach": "CVA variants + cn() utility + data-slot attributes + Tailwind CSS v4",
    "form_library": "react-hook-form with Zod resolver",
    "state_management": "React Context for compound components, Jotai atoms for global config"
  }
}