Skip to main content

ADR-0018: Shadcn UI for Component Library

Status​

Accepted - 2025-01-26

Context​

TVL Platform needs reusable UI components (forms, dialogs, dropdowns) with consistent design and accessibility.

Decision​

Shadcn UI (Radix primitives + Tailwind CSS) as the component library.

Rationale​

  1. Copy-Paste Components: Own the code (no npm dependency)
  2. Radix Primitives: Accessible, unstyled components
  3. Tailwind Styled: Consistent with our design system
  4. TypeScript: Fully typed components
  5. Customizable: Easy to modify (it's your code)

Alternatives Considered​

Alternative 1: Material UI (MUI)​

Rejected - Opinionated design, large bundle, difficult customization

Alternative 2: Chakra UI​

Rejected - Runtime CSS-in-JS, performance overhead

Alternative 3: Headless UI​

Rejected - Unstyled only (must style everything manually)

Installation​

# Install Shadcn CLI
npx shadcn-ui@latest init

# Add components as needed
npx shadcn-ui@latest add button
npx shadcn-ui@latest add dialog
npx shadcn-ui@latest add form

Usage Examples​

import { Button } from '@/components/ui/button';
import { Dialog, DialogContent, DialogTitle } from '@/components/ui/dialog';

export function BookingDialog({ open, onClose }) {
  return (
    <Dialog open={open} onOpenChange={onClose}>
      <DialogContent>
        <DialogTitle>Create Booking</DialogTitle>
        <BookingForm />
        <Button onClick={onClose}>Cancel</Button>
      </DialogContent>
    </Dialog>
  );
}

Benefits​

  • ✅ Accessible: ARIA attributes, keyboard navigation
  • ✅ Customizable: Modify components directly (no overrides)
  • ✅ Small Bundle: Only include components you use
  • ✅ TypeScript: Fully typed

References​