feat: Replace AppShell custom components with UI-Kit components (#55)

docs/project_plan.md

@@ -125,9 +125,12 @@ A pragmatic breakdown into **four one‑week sprints** plus a preparatory **Spri
 | #    | Task                                                              | DoD                                                                                    | Status |
 | ---- | ----------------------------------------------------------------- | -------------------------------------------------------------------------------------- | ------ |
 | BF.1 | **Issue #46**: Fix TypeScript module resolution for pnpm projects | pnpm users can compile TypeScript without module resolution errors; peer deps resolved | ✓      |
+| BF.2 | **Issues #50-53**: Fix critical toast system and theming issues   | Toast notifications work correctly, API consistency, proper DaisyUI theme integration  | ✓      |
 
 **BF.1 Details**: Moved all Radix UI packages from dependencies to peerDependencies to fix TypeScript compilation failures in pnpm projects due to symlink structure conflicts. Released as v0.4.4.
 
+**BF.2 Details**: Fixed critical toast system rendering issues, unified toast API under useToast hook, replaced hardcoded colors with CSS variables for proper theme integration, and updated showcase to demonstrate best practices. Released as v0.4.6. See [PR #54](https://github.com/etherisc/ui-kit/pull/54) for full details.
+
 ---
 
 ## Post‑MVP backlog (icebox)

docs/task-planning/appshell-analysis.md

@@ -0,0 +1,222 @@
+# AppShell Component Analysis & UI-Kit Replacement Opportunities
+
+## Executive Summary
+
+The current AppShell component uses **5 custom components** that can be replaced with existing ui-kit components, plus several **inline implementations** that should use proper ui-kit components. This analysis identifies **8 major replacement opportunities** that will improve consistency, functionality, and maintainability.
+
+## Current Structure Analysis
+
+### Dependencies & Imports
+
+```typescript
+// Current AppShell imports
+import { TopBar } from "./TopBar"; // ❌ Custom - Replace with UI components
+import { SideNav } from "./SideNav"; // ❌ Custom - Replace with UI/Sidebar
+import { ContentWrapper } from "./ContentWrapper"; // ⚠️ Wrapper - Update to use UI components
+import { cn } from "../../utils/cn"; // ✅ Keep
+import type { NavItem } from "./SideNav"; // ❌ Custom type
+import type { BreadcrumbItem } from "./Breadcrumbs"; // ❌ Custom type
+```
+
+### Component Hierarchy
+
+```
+AppShell
+├── TopBar (Custom)
+│   ├── Logo slot
+│   ├── Navigation items (ReactNode - no structure)
+│   └── User actions (ReactNode - no structure)
+├── Main Layout Container
+│   ├── SideNav (Custom)
+│   │   ├── NavItem components (Custom)
+│   │   ├── Collapse toggle (Custom button)
+│   │   └── Nested navigation (Custom logic)
+│   └── ContentWrapper (Custom)
+│       ├── Breadcrumbs (Custom)
+│       ├── Header slot
+│       ├── Main content
+│       └── Footer slot
+└── Footer (Inline div with hard-coded styling)
+```
+
+## Critical Issues Identified
+
+### 🔴 Major Issues (High Priority)
+
+1. **Custom Breadcrumb Implementation**
+
+   - **Problem**: Uses custom separator logic, prone to ">/" rendering bug
+   - **Impact**: Inconsistent separators, missing accessibility features
+   - **Solution**: Replace with `UI/Breadcrumb` components
+
+2. **Custom SideNav Implementation**
+
+   - **Problem**: Duplicates functionality available in `UI/Sidebar`
+   - **Impact**: Missing provider pattern, inconsistent styling, no mobile support
+   - **Solution**: Replace with `UI/Sidebar` + `SidebarProvider`
+
+3. **Limited TopBar Functionality**
+   - **Problem**: Only accepts ReactNode for navigation - no dropdown support
+   - **Impact**: Cannot create rich navigation menus with dropdowns
+   - **Solution**: Integrate `UI/NavigationMenu` + `UI/DropdownMenu`
+
+### 🟡 Medium Issues (Medium Priority)
+
+4. **Hard-coded Footer Styling**
+
+   ```typescript
+   // Current implementation
+   <div className="mt-auto p-4 bg-background border-t border-gray-200">
+   ```
+
+   - **Problem**: Hard-coded `border-gray-200` instead of using design tokens
+   - **Solution**: Use `UI/Separator` component
+
+5. **No Proper Scroll Management**
+
+   - **Problem**: Uses basic `overflow-auto` without proper scroll area components
+   - **Impact**: Inconsistent scrolling behavior across browsers
+   - **Solution**: Integrate `UI/ScrollArea` for content areas
+
+6. **Manual State Management**
+   - **Problem**: Uses local `useState` for sidebar collapse instead of provider pattern
+   - **Impact**: No persistence, no global state management
+   - **Solution**: Use `SidebarProvider` from `UI/Sidebar`
+
+### 🟢 Minor Issues (Low Priority)
+
+7. **Missing Component Composition**
+
+   - **Problem**: ContentWrapper could be more modular
+   - **Solution**: Allow header/footer to use specific ui-kit components
+
+8. **No Responsive Breakpoint Management**
+   - **Problem**: Hard-coded responsive classes
+   - **Solution**: Use consistent breakpoint system from ui-kit
+
+## Replacement Mapping
+
+| Current Component | Replace With                      | Benefits                                                     |
+| ----------------- | --------------------------------- | ------------------------------------------------------------ |
+| `Breadcrumbs`     | `UI/Breadcrumb` + subcomponents   | Proper separators, accessibility, ellipsis support           |
+| `SideNav`         | `UI/Sidebar` + `SidebarProvider`  | Mobile support, provider pattern, better responsive behavior |
+| `TopBar`          | Enhanced with `UI/NavigationMenu` | Dropdown menus, better navigation structure                  |
+| Footer div        | `UI/Separator` for border         | Design token consistency                                     |
+| Manual state      | `SidebarProvider`                 | Proper state management, persistence                         |
+| Overflow areas    | `UI/ScrollArea`                   | Better cross-browser scrolling                               |
+| `NavItem`         | `UI/SidebarNavItem`               | Consistent styling, accessibility                            |
+
+## Available UI-Kit Components for Integration
+
+### ✅ Ready to Use
+
+- `UI/Breadcrumb` - Complete breadcrumb system
+- `UI/Sidebar` - Complete sidebar with provider
+- `UI/NavigationMenu` - Rich navigation with dropdowns
+- `UI/DropdownMenu` - Dropdown functionality
+- `UI/Separator` - Consistent borders/dividers
+- `UI/ScrollArea` - Better scrolling
+- `UI/Collapsible` - For expandable nav sections
+
+### 🔍 Components Not Yet Analyzed
+
+- `UI/Sheet` - Could be useful for mobile navigation
+- `UI/Command` - Could enhance navigation search
+- `UI/Popover` - Alternative to dropdowns
+
+## Functional Gaps Analysis
+
+### What AppShell Currently Provides ✅
+
+- Fixed header layout
+- Collapsible sidebar
+- Breadcrumb navigation
+- Content wrapper with fixed width option
+- Footer support
+- Responsive behavior (basic)
+
+### What's Missing that UI-Kit Could Add 🚀
+
+- **Dropdown navigation menus** (NavigationMenu)
+- **Mobile-optimized sidebar** (Sidebar mobile support)
+- **Proper scroll areas** (ScrollArea)
+- **Search in navigation** (Command component)
+- **Better accessibility** (All ui-kit components are WCAG compliant)
+- **Advanced breadcrumb features** (Ellipsis, truncation)
+- **Consistent design tokens** (All styling through CSS variables)
+
+### Backward Compatibility Requirements 🔒
+
+- All current AppShell props must continue to work
+- No breaking changes to public API
+- Existing stories and tests must pass
+- Performance must not degrade
+
+## Implementation Strategy
+
+### Phase 1: Direct Replacements (High Impact, Low Risk)
+
+1. Replace `Breadcrumbs` with `UI/Breadcrumb`
+2. Replace footer border with `UI/Separator`
+3. Add `UI/ScrollArea` to content areas
+
+### Phase 2: Enhanced Components (High Impact, Medium Risk)
+
+1. Replace `SideNav` with `UI/Sidebar` system
+2. Enhance `TopBar` with `UI/NavigationMenu`
+3. Integrate `SidebarProvider` for state management
+
+### Phase 3: Advanced Features (Medium Impact, Low Risk)
+
+1. Add dropdown menu support to navigation
+2. Add mobile-specific navigation behaviors
+3. Enhance responsive breakpoint handling
+
+## Success Metrics
+
+### Code Quality
+
+- ✅ Reduce custom component count from 5 to 0
+- ✅ Eliminate hard-coded styling
+- ✅ Improve TypeScript type safety
+
+### User Experience
+
+- ✅ Fix breadcrumb separator rendering
+- ✅ Add dropdown navigation functionality
+- ✅ Improve mobile navigation experience
+- ✅ Better accessibility compliance
+
+### Developer Experience
+
+- ✅ Consistent component usage patterns
+- ✅ Better Storybook documentation
+- ✅ Easier testing and maintenance
+
+## Risk Assessment
+
+### Low Risk ✅
+
+- Breadcrumb replacement (well-defined interface)
+- Separator usage (simple styling fix)
+- ScrollArea integration (additive enhancement)
+
+### Medium Risk ⚠️
+
+- Sidebar replacement (complex state management)
+- NavigationMenu integration (API design needed)
+
+### High Risk 🚨
+
+- None identified - all changes maintain backward compatibility
+
+## Conclusion
+
+The AppShell component has **significant opportunities** for improvement through ui-kit integration. The analysis reveals that **all 5 custom components** can be replaced with existing ui-kit components, providing:
+
+1. **Better functionality** (dropdowns, mobile support, accessibility)
+2. **Consistent design system** usage
+3. **Reduced maintenance overhead**
+4. **Enhanced user experience**
+
+**Recommendation**: Proceed with the comprehensive refactoring plan outlined in this analysis.