Components
A structured component library designed for AI-assisted development.
Read this when choosing where to find or add components.
For developers and AI agents working with the codebase.
How It Works
Components are organised into five folders by purpose. This makes it clear where to find components and where to add new ones.
UI (Shadcn)
Primitive components from shadcn/ui. Easy to upgrade, minimal customisation. 34 components.
Core
Building blocks for layout and typography. Stack, Row, Text, Title, and more. 10 components.
Shared
Project-specific components composed from primitives. Reusable across pages.
Vendor
External packages wrapped and styled to match the design system.
Layout
Page structure components. Shell, Sidebar, Header, and layout patterns. 5 components.
Where to Put Components
Follow this decision tree when adding new components:
Need a UI primitive?
Check components/ui/ first. If missing, install from shadcn: npx shadcn@latest add [component]
Need an external package?
Wrap it in components/vendor/ and style to match the design system.
Building a reusable project component?
Create in components/shared/. Compose from UI primitives.
One-off component for a single page?
Inline it in the page file. Keep it simple (<50 lines).
Component Headers
Every component has a metadata header for upgrade tracking:
/** * CATALYST - Button Component * * @source shadcn/ui + @base-ui/react * @customised No — stock component */
Safe to overwrite with new version from shadcn.
Review changes before upgrading. Preserve customisations.
AI Reference
For a machine-readable component list, see components/COMPONENTS.md. This file is optimised for AI agents to quickly understand available components.
Next Steps
Explore specific component categories: