shadcn/ui Component Collection - Quick Start Guide

You can add ALL 50+ shadcn/ui components to your monorepo in ~10 hours.

The NavigationMenu you already have proves your architecture works. Now scale it!

📋 Prerequisites Checklist

Radix UI understanding (it’s the foundation - not optional!)
NavigationMenu successfully integrated
Storybook running and configured
CSS variables setup complete
Tailwind config extended for shadcn/ui
Decision: Want ALL components or curated set?
Decision: Flat structure or categorized?

🚀 Quick Start: Add All Components (Recommended)

Step 1: Prepare Workspace

cd /Users/work-station/company/cloudalt-frontend

Step 2: Choose Your Approach

Option A: CLI Bulk Install (Fastest)

cd packages/ui-web

# Install ALL components at once
npx shadcn@latest add --all

# This installs:
# - 50+ component files
# - All Radix UI dependencies
# - All helper utilities
# - CSS variable updates

Time: 5-10 minutes Result: All components in packages/ui-web/src/components/ui/

Option B: Selective Install (Strategic)

cd packages/ui-web

# Core essentials (15 components)
npx shadcn@latest add button input textarea select checkbox radio-group switch label form badge avatar card alert dialog toast

# Navigation (5 components)
npx shadcn@latest add breadcrumb sidebar dropdown-menu

# Advanced (as needed)
npx shadcn@latest add table calendar chart carousel data-table

Time: 15-20 minutes Result: Curated set based on immediate needs

Step 3: Organize Components (Optional but Recommended)

# Run organization script
node scripts/organize-shadcn-components.js

# OR manually organize:
mkdir -p packages/ui-web/src/components/{forms,layout,feedback,data,navigation}

# Move components to categories
mv packages/ui-web/src/components/ui/button* packages/ui-web/src/components/forms/
mv packages/ui-web/src/components/ui/card* packages/ui-web/src/components/layout/
# ... etc

Step 4: Generate Storybook Stories

# Auto-generate stories for all components
node scripts/generate-shadcn-stories.js

# Result: 50+ .stories.tsx files in packages/storybook/stories/

Step 5: Update Package Exports

export * from './components/forms';
export * from './components/layout';
export * from './components/feedback';
export * from './components/data';
export * from './components/navigation';
export * from './lib/utils';

// OR if using flat structure:
export * from './components/ui';

Step 6: Test in Storybook

# Restart Storybook
pkill -f storybook && yarn storybook

# Navigate to http://localhost:6006
# Look for new components in sidebar

📊 What You Get

Complete Component Library

✅ 50+ Production-Ready Components
✅ Full Accessibility (WCAG 2.1 AA compliant)
✅ Keyboard Navigation (built-in)
✅ Dark Mode Support (via CSS variables)
✅ Responsive Design (mobile-first)
✅ TypeScript Types (full type safety)
✅ Customizable (own the code, modify anything)
✅ Storybook Docs (interactive examples)

Dependencies Added (~35 packages)

{
  "@radix-ui/react-*": "~40 packages (primitives)",
  "date-fns": "^4.1.0",
  "react-day-picker": "^9.4.3",
  "embla-carousel-react": "^8.5.2",
  "recharts": "^2.15.0",
  "sonner": "^1.7.3",
  "vaul": "^1.1.2"
}

Bundle Impact: ~500KB gzipped (tree-shakeable)

🎨 Component Categories

Breadcrumb, Navigation Menu, Menubar, Command
Context Menu, Dropdown Menu, Pagination

2. Forms (13 components)

Button, Input, Textarea, Select, Checkbox
Radio Group, Switch, Form, Label, Button Group
Toggle, Toggle Group, Slider

3. Layout (10 components)

Card, Separator, Sheet, Drawer, Sidebar
Resizable, Scroll Area, Tabs, Collapsible, Aspect Ratio

4. Feedback (11 components)

Alert, Alert Dialog, Dialog, Toast, Sonner
Tooltip, Hover Card, Popover, Progress
Skeleton, Spinner

5. Data (9 components)

Table, Badge, Avatar, Calendar, Chart
Carousel, Accordion, Date Picker, Input OTP

🛠️ Advanced Usage

Create Division-Specific Wrappers

import { Button } from '@cloudalt-frontend/ui-web';

export function StayMatchButton(props: ButtonProps) {
  return (
    <Button
      className="stay-match-brand"
      variant="default"
      {...props}
    />
  );
}

Extend Components

import { Button } from '../button';
import { LucideIcon } from 'lucide-react';

interface IconButtonProps extends ButtonProps {
  icon: LucideIcon;
  label?: string;
}

export function IconButton({ icon: Icon, label, ...props }: IconButtonProps) {
  return (
    <Button {...props}>
      <Icon className="mr-2 h-4 w-4" />
      {label}
    </Button>
  );
}

Create Composite Components

import { Card, CardHeader, CardContent } from '../../layout/card';
import { Avatar, AvatarImage, AvatarFallback } from '../avatar';
import { Badge } from '../badge';

export function UserCard({ user }: { user: User }) {
  return (
    <Card>
      <CardHeader>
        <Avatar>
          <AvatarImage src={user.avatar} />
          <AvatarFallback>{user.initials}</AvatarFallback>
        </Avatar>
      </CardHeader>
      <CardContent>
        <h3>{user.name}</h3>
        <Badge>{user.role}</Badge>
      </CardContent>
    </Card>
  );
}

🧪 Testing Strategy

Unit Tests (Vitest)

import { describe, it, expect } from 'vitest';
import { render, screen } from '@testing-library/react';
import { Button } from './Button';

describe('Button', () => {
  it('renders with text', () => {
    render(<Button>Click me</Button>);
    expect(screen.getByRole('button')).toHaveTextContent('Click me');
  });

  it('calls onClick handler', async () => {
    const handleClick = vi.fn();
    render(<Button onClick={handleClick}>Click me</Button>);
    await userEvent.click(screen.getByRole('button'));
    expect(handleClick).toHaveBeenCalledOnce();
  });
});

Accessibility Tests (Axe)

import { axe } from 'jest-axe';

it('has no accessibility violations', async () => {
  const { container } = render(<Button>Accessible</Button>);
  const results = await axe(container);
  expect(results).toHaveNoViolations();
});

Visual Regression Tests (Chromatic)

# Already configured in Storybook
yarn chromatic --project-token=<YOUR_TOKEN>

📚 Documentation

Auto-Generate Component Docs

# Create docs in Astro site
node scripts/generate-component-docs.js

Example Doc Structure

---
title: Button
description: A clickable button component with multiple variants
category: Forms
---

## Installation
\`\`\`bash
npx shadcn@latest add button
\`\`\`

## Usage
\`\`\`tsx
import { Button } from '@cloudalt-frontend/ui-web';

<Button variant="default">Click me</Button>
\`\`\`

## API Reference
...

🔄 Maintenance

Update Components

# Check for updates
npx shadcn@latest diff

# Update specific component
npx shadcn@latest add button --overwrite

# Update all components
npx shadcn@latest add --all --overwrite

Monitor Bundle Size

# Analyze bundle
yarn nx build ui-web --with-deps
yarn bundle-analyzer

# Check specific component impact
yarn bundle-buddy

❓ FAQ

Q: Do I need to install ALL components?

A: No! Start with core set (20-25 components), add more as needed.

Q: Can I customize component styles?

A: Yes! You own the code. Modify directly in packages/ui-web/src/.

Q: How do I handle updates?

A: Use npx shadcn@latest diff to see changes, manually merge updates.

Q: What about bundle size?

A: Tree-shaking eliminates unused code. Only imported components are bundled.

Q: Can I use these in React Native?

A: No, shadcn/ui is web-only. Consider NativeWind for similar approach.

Q: Do I need to understand Radix UI?

A: Basic understanding helps, but not required. shadcn/ui abstracts complexity.

🎯 Next Steps

Decision Time: All components or selective?
Run Installation: Choose approach (CLI bulk or selective)
Generate Stories: Auto-create Storybook documentation
Test in App: Import into one app (homestay) to verify
Roll Out: Make available to all app divisions
Document: Update Astro docs with usage examples
Train Team: Show developers how to use component library

🚨 Important Reminders

✅ Radix UI is NOT optional - it’s the foundation
✅ CSS variables must be configured - already done!
✅ Tailwind config must extend shadcn theme - already done!
✅ React 18+ required - you have it!
⚠️ Test each component before production use
⚠️ Commit working state before bulk changes
⚠️ Update dependencies regularly for security patches

📞 Support

Official Docs: https://ui.shadcn.com/docs
GitHub Issues: https://github.com/shadcn-ui/ui/issues
Discord: https://discord.gg/shadcn-ui
Your Docs: apps/docs/src/content/reference/components/

Ready to proceed? Let’s add all the components! 🚀