Components

A structured component library designed for AI-assisted development.

How It Works

Components are organised into four folders by purpose. This makes it clear where to find components and where to add new ones. AI agents can quickly locate the right component for any task.

Component Types

UI (Shadcn)

components/ui/

Primitive components from shadcn/ui. Easy to upgrade, minimal customisation.

Examples: Button, Input, Dialog, Card, Table

Shared

components/shared/

Project-specific components composed from primitives. Reusable across pages.

Examples: LabelValue, StatCard

Structure

components/structure/

Content-level layout helpers for in-page structure. Gap scale and alignment.

Examples: Stack, Row, Grid, Container, Section

Vendors

components/vendors/

External packages wrapped and styled to match the design system.

Examples: Calendar, DataTable, RichTextEditor

Layout

components/layout/

Layout components for page structure. Shell, Sidebar, Header, and page-level patterns.

Examples: Shell, Sidebar, Header, Logo

Where to Put Components

1
Need a UI primitive?
Check components/ui/ first. If missing, install from shadcn: npx shadcn@latest add [component]
2
Need an external package?
Wrap it in components/vendors/ and style to match the design system.
3
Building a reusable project component?
Create in components/shared/. Compose from UI primitives.
4
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
 */

@customised No

Safe to overwrite with new version from shadcn.

@customised Yes

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.