Build Brief: Component Library

Epic: Component Library Project: Application UI Framework Status: Ready for implementation Depends on: Layout and Navigation ✓

---

Context

Build 25 reusable shadcn/ui components (New York variant) with a co-location structure. This provides the building blocks for all UI in the Advisor Console.

Tech Stack:

• React 19
• TypeScript 5.4+
• Tailwind CSS 4
• shadcn/ui (New York variant)
• Vitest + @testing-library/react (testing)
• ESLint (linting)

Project Root: marchay-application/

Directory Layout:

marchay-application/
├── src/
│   ├── components/
│   │   ├── ui/                    # shadcn/ui components
│   │   │   ├── alert.tsx
│   │   │   ├── avatar.tsx
│   │   │   ├── badge.tsx
│   │   │   ├── breadcrumb.tsx
│   │   │   ├── button.tsx
│   │   │   ├── calendar.tsx
│   │   │   ├── card.tsx
│   │   │   ├── checkbox.tsx
│   │   │   ├── collapsible.tsx
│   │   │   ├── datepicker.tsx
│   │   │   ├── dialog.tsx
│   │   │   ├── dropdown-menu.tsx
│   │   │   ├── field.tsx
│   │   │   ├── input.tsx
│   │   │   ├── label.tsx
│   │   │   ├── pagination.tsx
│   │   │   ├── popover.tsx
│   │   │   ├── select.tsx
│   │   │   ├── separator.tsx
│   │   │   ├── skeleton.tsx
│   │   │   ├── sonner.tsx
│   │   │   ├── spinner.tsx
│   │   │   ├── table.tsx
│   │   │   └── tabs.tsx
│   │   └── layouts/              # Layout components
│   │       └── card-layout.tsx
│   ├── hooks/                     # Custom React hooks
│   ├── libs/                      # Utility functions
│   └── styles/                    # Global styles
├── tests/
│   └── components/
│       └── ui/                    # Component tests
├── package.json
├── tsconfig.json
└── README.md

---

Acceptance Criteria

1. Project Setup

• [ ] Initialize component library with shadcn/ui
• [ ] Set up co-location structure (components/, hooks/, libs/, styles/)
• [ ] Configure Vitest + @testing-library/react
• [ ] Set up ESLint with React rules

2. Core Components

• [ ] Button - Primary, secondary, ghost, link variants with loading state
• [ ] Input - Text input with label, error state, helper text
• [ ] Label - Form field labels
• [ ] Card - Container with header, content, footer sections
• [ ] Badge - Status indicators (default, success, warning, error)
• [ ] Separator - Horizontal/vertical dividers

3. Form Components

• [ ] Checkbox - Boolean toggle with label
• [ ] Select - Dropdown selection with search
• [ ] Field - Form field wrapper with label, input, error
• [ ] Calendar - Date picker calendar
• [ ] DatePicker - Combined input + calendar picker

4. Overlay Components

• [ ] Dialog - Modal dialogs with focus trap
• [ ] Popover - Floating content panels
• [ ] DropdownMenu - Action menus with icons

5. Data Display

• [ ] Table - Data tables with sorting, pagination
• [ ] Tabs - Tabbed content panels
• [ ] Collapsible - Expandable/collapsible sections

6. Feedback Components

• [ ] Alert - Inline notifications (info, success, warning, error)
• [ ] Sonner - Toast notifications
• [ ] Spinner - Loading indicators
• [ ] Skeleton - Content placeholders while loading

7. Navigation Components

• [ ] Breadcrumb - Navigation breadcrumbs
• [ ] Pagination - Page navigation controls
• [ ] Avatar - User profile images/initials

8. Tests

• [ ] Unit tests for each component
• [ ] Accessibility tests (ARIA attributes, keyboard navigation)
• [ ] Integration tests for form components
• [ ] Visual regression tests (optional)

---

File Structure

marchay-application/
├── src/
│   ├── components/
│   │   └── ui/
│   │       ├── alert.tsx
│   │       ├── avatar.tsx
│   │       ├── badge.tsx
│   │       ├── breadcrumb.tsx
│   │       ├── button.tsx
│   │       ├── calendar.tsx
│   │       ├── card.tsx
│   │       ├── checkbox.tsx
│   │       ├── collapsible.tsx
│   │       ├── datepicker.tsx
│   │       ├── dialog.tsx
│   │       ├── dropdown-menu.tsx
│   │       ├── field.tsx
│   │       ├── input.tsx
│   │       ├── label.tsx
│   │       ├── pagination.tsx
│   │       ├── popover.tsx
│   │       ├── select.tsx
│   │       ├── separator.tsx
│   │       ├── skeleton.tsx
│   │       ├── sonner.tsx
│   │       ├── spinner.tsx
│   │       ├── table.tsx
│   │       └── tabs.tsx
│   ├── hooks/
│   ├── libs/
│   └── styles/
├── tests/
│   └── components/
│       └── ui/
├── package.json
├── tsconfig.json
└── README.md

---

Implementation Phases

Phase 1: Project Scaffolding (Day 1)

1. Initialize shadcn/ui with New York variant
2. Set up co-location structure
3. Configure testing framework
4. Set up ESLint rules

Phase 2: Core Components (Day 1-2)

1. Button component with variants
2. Input, Label, Field components
3. Card component
4. Badge and Separator components
5. Write tests for core components

Phase 3: Form Components (Day 2-3)

1. Checkbox component
2. Select component with search
3. Calendar and DatePicker components
4. Write tests for form components

Phase 4: Overlay Components (Day 3-4)

1. Dialog component with focus trap
2. Popover component
3. DropdownMenu component
4. Write tests for overlay components

Phase 5: Data Display (Day 4)

1. Table component
2. Tabs component
3. Collapsible component
4. Write tests for data display

Phase 6: Feedback & Navigation (Day 5)

1. Alert and Sonner components
2. Spinner and Skeleton components
3. Breadcrumb and Pagination
4. Avatar component
5. Write tests for all remaining components

---

Dependencies

Dependency	Version	Purpose
react	^19.0.0	UI framework
react-dom	^19.0.0	DOM rendering
tailwindcss	^4.0.0	Styling
class-variance-authority	^0.7.0	Component variants
clsx	^2.1.0	Class merging
tailwind-merge	^2.3.0	Tailwind class merging
@radix-ui/react-*	latest	Accessible primitives
lucide-react	^0.378.0	Icons
vitest	^2.0.0	Testing
@testing-library/react	^15.0.0	React testing
eslint	^9.0.0	Linting
typescript	^5.4.0	Type checking