UI Framework Build Brief

Build brief for the first epic of the Application UI Framework: Layout and Navigation. This is the starting point for all Application Architecture work.

---

Overview

Epic: Layout and Navigation Estimated effort: ~1 week Depends on: Nothing (this is the foundation) Enables: Component Library, Design System, all Application pages

Build the foundational layout with a collapsible dark sidebar, React Router navigation, and responsive collapse behavior.

---

Acceptance Criteria

1. Project Setup

• ☐ Initialize marchay-application repo with Vite + React 19 + TypeScript
• ☐ Set up Tailwind CSS 4 with oklch color space
• ☐ Configure ESLint and Prettier
• ☐ Configure Vitest for testing
• ☐ Create basic folder structure (pages/, components/, hooks/, libs/, styles/)

2. Layout Structure

• ☐ Create main layout with sidebar and content area
• ☐ Implement dark sidebar theme (#111C33)
• ☐ Add Marchay logo in sidebar header
• ☐ Build responsive sidebar collapse (full → icons on smaller screens)
• ☐ Implement smooth transition animations

3. Navigation

• ☐ Set up React Router with route definitions:

  const routes = [
    { path: '/', element: <Dashboard /> },
    { path: '/members', element: <Members /> },
    { path: '/members/:id', element: <MemberDetail /> },
    { path: '/trips', element: <Trips /> },
    { path: '/trips/:id', element: <TripDetail /> },
    { path: '/chat', element: <Chat /> },
    { path: '/inbox', element: <Inbox /> },
    { path: '/settings', element: <Settings /> },
  ];

• ☐ Build navigation items with icons
• ☐ Implement active route highlighting
• ☐ Add breadcrumb navigation

4. Responsive Behavior

• ☐ Sidebar collapses to icons on screens < 1024px
• ☐ Content area expands to full width when collapsed
• ☐ Mobile-friendly hamburger menu
• ☐ Touch-friendly sidebar toggle

5. Tests

• ☐ Unit tests for sidebar component
• ☐ Unit tests for navigation items
• ☐ Unit tests for route matching
• ☐ Integration test: navigation changes route
• ☐ Integration test: sidebar collapse works

---

File Structure (created by this brief)

marchay-application/
├── src/
│   ├── App.tsx
│   ├── main.tsx
│   ├── routes/
│   │   ├── index.tsx
│   │   └── routes.tsx
│   ├── layouts/
│   │   ├── MainLayout.tsx
│   │   └── __tests__/
│   │       └── MainLayout.test.tsx
│   ├── components/
│   │   ├── sidebar/
│   │   │   ├── Sidebar.tsx
│   │   │   ├── SidebarHeader.tsx
│   │   │   ├── SidebarNav.tsx
│   │   │   ├── SidebarItem.tsx
│   │   │   └── __tests__/
│   │   │       └── Sidebar.test.tsx
│   │   └── breadcrumb/
│   │       ├── Breadcrumb.tsx
│   │       └── __tests__/
│   │           └── Breadcrumb.test.tsx
│   ├── pages/
│   │   ├── Dashboard.tsx
│   │   ├── Members.tsx
│   │   ├── MemberDetail.tsx
│   │   ├── Trips.tsx
│   │   ├── TripDetail.tsx
│   │   ├── Chat.tsx
│   │   ├── Inbox.tsx
│   │   └── Settings.tsx
│   ├── hooks/
│   │   └── useSidebar.ts
│   └── styles/
│       └── globals.css
├── public/
├── package.json
├── tsconfig.json
├── vite.config.ts
├── tailwind.config.ts
├── Dockerfile
└── README.md

---

Implementation Phases

Phase 1: Project Scaffolding (Day 1)

1. Initialize Vite + React + TypeScript
2. Set up Tailwind CSS 4
3. Create folder structure
4. Verify npm run dev works

Phase 2: Sidebar (Day 2-3)

1. Build sidebar component with dark theme
2. Add logo and navigation items
3. Implement collapse behavior
4. Write tests

Phase 3: Navigation (Day 3-4)

1. Set up React Router
2. Create route definitions
3. Build breadcrumb navigation
4. Implement active route highlighting
5. Write tests

Phase 4: Responsive (Day 4-5)

1. Add responsive breakpoints
2. Implement collapse on small screens
3. Add mobile hamburger menu
4. Write integration tests

Phase 5: Polish (Day 5)

1. Add transition animations
2. Run all tests
3. Fix lint and type errors
4. Create README.md

---

Dependencies

Dependency	Version	Purpose
react	^19.0.0	UI framework
react-dom	^19.0.0	DOM rendering
react-router-dom	^7.0.0	Routing
tailwindcss	^4.0.0	Styling
@tailwindcss/vite	^4.0.0	Vite integration
class-variance-authority	^0.7.0	Component variants
clsx	^2.1.0	Class merging
tailwind-merge	^2.3.0	Tailwind class merging
lucide-react	^0.378.0	Icons
vitest	^2.0.0	Testing
@testing-library/react	^15.0.0	React testing
eslint	^9.0.0	Linting
prettier	^3.3.0	Formatting
typescript	^5.4.0	Type checking