etherisc · christoph2806 · May 29, 2025 · May 29, 2025 · May 29, 2025
diff --git a/docs/project_plan.md b/docs/project_plan.md
@@ -84,8 +84,8 @@ A pragmatic breakdown into **four one‑week sprints** plus a preparatory **Spri
 | 5.2 | **Editor widgets** – MarkdownEditor (already complete) & CodeEditor (CodeMirror 6)                      | MarkdownEditor verified complete with security & a11y. CodeEditor implemented with syntax highlighting, themes, mobile support; bundle size increase ≤ 500 KB gzip total. | ✓      |
 | 5.3 | **Remaining layouts** – ErrorShell, MainFixedLayout, DataDenseLayout, Footer slot in MainLayout         | Storybook snapshots approved in light/dark; axe-core passes.                                                                                                              | ✓      |
 | 5.4 | **Showcase routes extension** – `/settings` (MainFixedLayout), `/components` gallery, wildcard 404 page | Playwright E2E navigates: login → settings → gallery → invalid URL → 404; no console errors.                                                                              | ✓      |
-| 5.5 | Add **Reset‑Password page** (AuthShell variant)                                                         | Route `/reset-password` renders form; Vitest form validation passes.                                                                                                      | PR     |
-| 5.6 | Update documentation index & Storybook sidebar grouping                                                 | `npm run build-storybook` completes; new components appear under correct groups.                                                                                          |        |
+| 5.5 | Add **Reset‑Password page** (AuthShell variant)                                                         | Route `/reset-password` renders form; Vitest form validation passes.                                                                                                      | ✓      |
+| 5.6 | Update documentation index & Storybook sidebar grouping **PR**                                          | `npm run build-storybook` completes; new components appear under correct groups.                                                                                          | PR     |
 
 ---
 

diff --git a/docs/task-planning/task-5.6-storybook-documentation-organization.md b/docs/task-planning/task-5.6-storybook-documentation-organization.md
@@ -0,0 +1,167 @@
+# Task 5.6: Update documentation index & Storybook sidebar grouping
+
+## Overview
+
+Organize and improve the Storybook documentation structure by implementing proper sidebar grouping, creating documentation indexes, and ensuring all components appear in logical categories.
+
+## Current State Analysis
+
+### Current Storybook Structure Issues
+
+1. **Inconsistent grouping**: Some stories use different title patterns
+2. **Missing organization**: No clear hierarchy for complex components
+3. **Legacy stories**: Old stories from `/stories` folder mixed with new component stories
+4. **Documentation scattered**: MDX files exist but aren't properly indexed
+
+### Audit Results - Current Story Title Patterns Found
+
+**Inconsistent Patterns Identified:**
+
+- `Primitives/*` (Button, ComboBox, CodeEditor, etc.)
+- `Components/Form/*` (Checkbox, NumberInput, RadioGroup, Select)
+- `Components/Primitives/*` (DatePicker, DateRangePicker, ThemeToggle)
+- `Components/Feedback/*` (StatusBadge, Toast)
+- `Components/TextInput` (no category)
+- `Layout/*` (AuthShell, DataDenseLayout, etc.)
+- `Layout/AppShell/*` (AppShell, ContentWrapper, SideNav, TopBar)
+- `Brand/*` (EtheriscLogo)
+- `Data Display/*` (DataTable)
+- `Form/*` (FormExample, AccessibleExamples)
+- `Examples/*` (A11yButton, FormExample)
+- `Providers/*` (ErrorBoundary, ThemeProvider)
+- `Example/*` (Legacy stories: Button, Header, Page)
+
+**Problems:**
+
+- 13 different top-level categories with inconsistent naming
+- Same component types scattered across different categories
+- Form components split between "Components/Form", "Primitives", and "Form"
+- Legacy stories using "Example/" instead of "Examples/"
+- AppShell components nested under "Layout/AppShell" while others are flat
+
+## Tasks
+
+| Task Description                           | DoD                                                                           | Status   |
+| ------------------------------------------ | ----------------------------------------------------------------------------- | -------- |
+| 1. Audit current story organization        | Complete inventory of all story files and their current titles                | Complete |
+| 2. Define new Storybook grouping structure | Create standardized story title hierarchy and document conventions            | Complete |
+| 3. Update all story titles for consistency | All stories follow new standardized title structure                           | Complete |
+| 4. Create Welcome/Introduction page        | Replace default Welcome.mdx with comprehensive UI-Kit introduction            | Complete |
+| 5. Create Documentation index pages        | Add index MDX pages for each major category (Primitives, Layout, etc.)        | Complete |
+| 6. Configure Storybook sidebar ordering    | Implement custom sidebar ordering in .storybook configuration                 | Complete |
+| 7. Clean up legacy stories                 | Remove or migrate legacy stories from /stories folder                         | Complete |
+| 8. Add component group documentation       | Create overview documentation for each component category                     | Complete |
+| 9. Verify build and organization           | Ensure `pnpm run build-storybook` completes and sidebar is properly organized | Complete |
+| 10. Add missing component stories          | Ensure all UI-Kit components have proper stories with correct grouping        | Complete |
+
+## Proposed Storybook Organization Structure
+
+**New Standardized Title Hierarchy:**
+
+```
+📚 Welcome
+├── Getting Started
+
+🧱 Form Controls
+├── Button
+├── TextInput
+├── NumberInput
+├── TextArea
+├── Select
+├── ComboBox
+├── Checkbox
+├── RadioGroup
+├── SliderInput
+├── SpinnerInput
+├── DatePicker
+└── DateRangePicker
+
+✏️ Editors
+├── CodeEditor
+└── MarkdownEditor
+
+🏗️ Layout
+├── Shells
+│   ├── AuthShell
+│   ├── AppShell
+│   ├── WizardShell
+│   ├── MinimalShell
+│   └── ErrorShell
+├── Content Layouts
+│   ├── MainFixedLayout
+│   ├── DataDenseLayout
+│   └── ContentWrapper
+└── Navigation
+    ├── TopBar
+    ├── SideNav
+    ├── NavItem
+    ├── Breadcrumbs
+    └── HeaderActionIcon
+
+🎨 Feedback
+├── Toast
+└── StatusBadge
+
+📊 Data Display
+└── DataTable
+
+🔧 Form Components
+├── Form Examples
+├── FormGrid
+├── FormGroup
+└── A11y Examples
+
+🛡️ Providers
+├── ErrorBoundary
+├── ThemeProvider
+└── ThemeToggle
+
+🎯 Brand
+├── Logo
+└── EtheriscLogo
+
+📝 Examples
+└── Component Gallery
+```
+
+**Title Mapping (Old → New):**
+
+- `Primitives/Button` → `Form Controls/Button`
+- `Components/Form/Checkbox` → `Form Controls/Checkbox`
+- `Components/Primitives/DatePicker` → `Form Controls/DatePicker`
+- `Primitives/CodeEditor` → `Editors/CodeEditor`
+- `Layout/AppShell/TopBar` → `Layout/Navigation/TopBar`
+- `Components/Feedback/Toast` → `Feedback/Toast`
+- `Components/Primitives/ThemeToggle` → `Providers/ThemeToggle`
+- `Example/*` → DELETE (legacy stories)
+- `Form/FormExample` → `Form Components/Form Examples`
+
+## Implementation Details
+
+### 1. Story Title Conventions
+
+- Use descriptive category names: `Form Controls/Button` instead of `Primitives/Button`
+- Group related components: All form inputs under `Form Controls`
+- Separate complex layouts: Different shell types under `Layout/Shells`
+
+### 2. Documentation Structure
+
+- Create index MDX files for each major category
+- Include component overview, usage guidelines, and links
+- Add getting started documentation
+
+### 3. Build Verification
+
+- Ensure no broken links or imports
+- Verify all components appear in correct categories
+- Confirm build completes without errors
+
+## Success Criteria (DoD)
+
+- ✅ `npm run build-storybook` completes successfully
+- ✅ New components appear under correct groups in sidebar
+- ✅ All story titles follow consistent naming conventions
+- ✅ Documentation index pages exist for major categories
+- ✅ Sidebar is logically organized and easy to navigate
+- ✅ No broken stories or missing imports
+- ✅ Component categories are clearly separated and labeled
diff --git a/packages/ui-kit/.storybook/preview.tsx b/packages/ui-kit/.storybook/preview.tsx
@@ -50,6 +50,30 @@ const preview: Preview = {
             light: { ...themes.light },
             current: 'light',
         },
+        options: {
+            storySort: {
+                order: [
+                    'Welcome',
+                    'Form Controls',
+                    ['Overview', 'Button', 'TextInput', 'NumberInput', 'TextArea', 'Select', 'ComboBox', 'Checkbox', 'RadioGroup', 'SliderInput', 'SpinnerInput', 'DatePicker', 'DateRangePicker'],
+                    'Editors', 
+                    ['Overview', 'CodeEditor', 'MarkdownEditor'],
+                    'Layout',
+                    ['Overview', 'Shells', 'Content Layouts', 'Navigation'],
+                    'Feedback',
+                    ['Overview', 'Toast', 'StatusBadge'],
+                    'Data Display',
+                    'Form Components',
+                    ['Overview', 'Form Examples', 'A11y Examples'],
+                    'Providers',
+                    ['Overview', 'ErrorBoundary', 'ThemeProvider', 'ThemeToggle'],
+                    'Brand',
+                    ['Overview', 'Logo', 'EtheriscLogo'],
+                    'Examples',
+                    '*' // Everything else at the end
+                ],
+            },
+        },
     },
     decorators: [
         (Story, context) => (

diff --git a/packages/ui-kit/src/Welcome.mdx b/packages/ui-kit/src/Welcome.mdx
@@ -49,49 +49,95 @@ function App() {
 
 ## 🧩 Component Categories
 
-### 🎨 **Primitives**
+### 🧱 **Form Controls**
 
-Basic building blocks for your application:
+Essential form input components:
 
 - **Button** - Various button styles and states
-- **Input** - Text, number, and form inputs
+- **TextInput** - Text input with validation
+- **NumberInput** - Numeric input with constraints
+- **TextArea** - Multi-line text input
+- **Select** - Dropdown selection component
+- **ComboBox** - Searchable dropdown with autocomplete
 - **Checkbox** - Accessible checkbox components
-- **ThemeToggle** - Dark/light mode switcher
+- **RadioGroup** - Radio button groups
+- **SliderInput** - Range slider input
+- **SpinnerInput** - Numeric spinner input
+- **DatePicker** - Date selection component
+- **DateRangePicker** - Date range selection
 
-### 📋 **Form Components**
+### ✏️ **Editors**
 
-Complete form building blocks:
+Advanced text editing components:
 
-- **TextInput** - Enhanced text input with validation
-- **NumberInput** - Numeric input with min/max constraints
-- **Form Examples** - Accessible form patterns
+- **CodeEditor** - Syntax-highlighted code editor
+- **MarkdownEditor** - WYSIWYG markdown editor
 
-### 🏗️ **Layout Components**
+### 🏗️ **Layout**
 
-Structure your application:
+Structure your application with organized layout components:
 
+#### **Shells**
 - **AppShell** - Complete application layout
 - **AuthShell** - Authentication page layouts
+- **WizardShell** - Multi-step wizard layouts
 - **MinimalShell** - Minimal page layouts
+- **ErrorShell** - Error page layouts
+
+#### **Content Layouts**
+- **MainFixedLayout** - Fixed-width main content layout
+- **DataDenseLayout** - Dense data presentation layout
 - **ContentWrapper** - Content area management
+
+#### **Navigation**
+- **TopBar** - Application top navigation
+- **SideNav** - Sidebar navigation
+- **NavItem** - Individual navigation items
 - **Breadcrumbs** - Navigation breadcrumbs
-- **Logo** - Brand logo component
-- **NavItem** - Navigation items
+- **HeaderActionIcon** - Header action buttons
+
+### 🎨 **Feedback**
+
+User feedback and status components:
+
+- **Toast** - Notification toast messages
+- **StatusBadge** - Status indicator badges
+
+### 📊 **Data Display**
+
+Components for displaying structured data:
+
+- **DataTable** - Feature-rich data tables
 
-### 🔧 **Providers**
+### 🔧 **Form Components**
+
+Complete form building patterns:
+
+- **Form Examples** - Comprehensive form patterns
+- **A11y Examples** - Accessibility-focused examples
+
+### 🛡️ **Providers**
 
 Context providers for global functionality:
 
-- **ThemeProvider** - Theme and dark mode management
-- **ToastProvider** - Toast notification system
 - **ErrorBoundary** - Error handling and recovery
+- **ThemeProvider** - Theme and dark mode management
+- **ThemeToggle** - Dark/light mode switcher
 
-### 🎨 **Brand Components**
+### 🎯 **Brand**
 
 Official Etherisc branding elements:
 
+- **Logo** - Generic logo component
 - **EtheriscLogo** - Official Etherisc logo with multiple variants
 
+### 📝 **Examples**
+
+Demonstration and example components:
+
+- **A11yButton** - Accessibility demonstration
+- **Component Gallery** - Showcase of all components
+
 ## ✨ Key Features
 
 - **🎨 Modern Design System** - Built with Tailwind CSS and DaisyUI