Skip to content
This repository was archived by the owner on Mar 7, 2026. It is now read-only.

Commit 55f4f71

Browse files
christoph2806Developer
christoph2806
and
Developer
authored
feat: reorganize Storybook documentation with hierarchical component categorization (#34)
* feat: reorganize Storybook documentation with hierarchical component categorization * fix: resolve NumberInput accessibility violations --------- Co-authored-by: Developer <developer@example.com>
1 parent 70562d3 commit 55f4f71

File tree

57 files changed

+2561
-1103
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

57 files changed

+2561
-1103
lines changed

‎docs/project_plan.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -84,8 +84,8 @@ A pragmatic breakdown into **four one‑week sprints** plus a preparatory **Spri
8484
| 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. | ✓ |
8585
| 5.3 | **Remaining layouts** – ErrorShell, MainFixedLayout, DataDenseLayout, Footer slot in MainLayout | Storybook snapshots approved in light/dark; axe-core passes. | ✓ |
8686
| 5.4 | **Showcase routes extension** – `/settings` (MainFixedLayout), `/components` gallery, wildcard 404 page | Playwright E2E navigates: login → settings → gallery → invalid URL → 404; no console errors. | ✓ |
87-
| 5.5 | Add **Reset‑Password page** (AuthShell variant) | Route `/reset-password` renders form; Vitest form validation passes. | PR |
88-
| 5.6 | Update documentation index & Storybook sidebar grouping | `npm run build-storybook` completes; new components appear under correct groups. | |
87+
| 5.5 | Add **Reset‑Password page** (AuthShell variant) | Route `/reset-password` renders form; Vitest form validation passes. | ✓ |
88+
| 5.6 | Update documentation index & Storybook sidebar grouping **PR** | `npm run build-storybook` completes; new components appear under correct groups. | PR |
8989

9090
---
9191

‎docs/task-planning/task-5.6-storybook-documentation-organization.md‎

Lines changed: 167 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,167 @@
1+
# Task 5.6: Update documentation index & Storybook sidebar grouping
2+
3+
## Overview
4+
5+
Organize and improve the Storybook documentation structure by implementing proper sidebar grouping, creating documentation indexes, and ensuring all components appear in logical categories.
6+
7+
## Current State Analysis
8+
9+
### Current Storybook Structure Issues
10+
11+
1. **Inconsistent grouping**: Some stories use different title patterns
12+
2. **Missing organization**: No clear hierarchy for complex components
13+
3. **Legacy stories**: Old stories from `/stories` folder mixed with new component stories
14+
4. **Documentation scattered**: MDX files exist but aren't properly indexed
15+
16+
### Audit Results - Current Story Title Patterns Found
17+
18+
**Inconsistent Patterns Identified:**
19+
20+
- `Primitives/*` (Button, ComboBox, CodeEditor, etc.)
21+
- `Components/Form/*` (Checkbox, NumberInput, RadioGroup, Select)
22+
- `Components/Primitives/*` (DatePicker, DateRangePicker, ThemeToggle)
23+
- `Components/Feedback/*` (StatusBadge, Toast)
24+
- `Components/TextInput` (no category)
25+
- `Layout/*` (AuthShell, DataDenseLayout, etc.)
26+
- `Layout/AppShell/*` (AppShell, ContentWrapper, SideNav, TopBar)
27+
- `Brand/*` (EtheriscLogo)
28+
- `Data Display/*` (DataTable)
29+
- `Form/*` (FormExample, AccessibleExamples)
30+
- `Examples/*` (A11yButton, FormExample)
31+
- `Providers/*` (ErrorBoundary, ThemeProvider)
32+
- `Example/*` (Legacy stories: Button, Header, Page)
33+
34+
**Problems:**
35+
36+
- 13 different top-level categories with inconsistent naming
37+
- Same component types scattered across different categories
38+
- Form components split between "Components/Form", "Primitives", and "Form"
39+
- Legacy stories using "Example/" instead of "Examples/"
40+
- AppShell components nested under "Layout/AppShell" while others are flat
41+
42+
## Tasks
43+
44+
| Task Description | DoD | Status |
45+
| ------------------------------------------ | ----------------------------------------------------------------------------- | -------- |
46+
| 1. Audit current story organization | Complete inventory of all story files and their current titles | Complete |
47+
| 2. Define new Storybook grouping structure | Create standardized story title hierarchy and document conventions | Complete |
48+
| 3. Update all story titles for consistency | All stories follow new standardized title structure | Complete |
49+
| 4. Create Welcome/Introduction page | Replace default Welcome.mdx with comprehensive UI-Kit introduction | Complete |
50+
| 5. Create Documentation index pages | Add index MDX pages for each major category (Primitives, Layout, etc.) | Complete |
51+
| 6. Configure Storybook sidebar ordering | Implement custom sidebar ordering in .storybook configuration | Complete |
52+
| 7. Clean up legacy stories | Remove or migrate legacy stories from /stories folder | Complete |
53+
| 8. Add component group documentation | Create overview documentation for each component category | Complete |
54+
| 9. Verify build and organization | Ensure `pnpm run build-storybook` completes and sidebar is properly organized | Complete |
55+
| 10. Add missing component stories | Ensure all UI-Kit components have proper stories with correct grouping | Complete |
56+
57+
## Proposed Storybook Organization Structure
58+
59+
**New Standardized Title Hierarchy:**
60+
61+
```
62+
📚 Welcome
63+
├── Getting Started
64+
65+
🧱 Form Controls
66+
├── Button
67+
├── TextInput
68+
├── NumberInput
69+
├── TextArea
70+
├── Select
71+
├── ComboBox
72+
├── Checkbox
73+
├── RadioGroup
74+
├── SliderInput
75+
├── SpinnerInput
76+
├── DatePicker
77+
└── DateRangePicker
78+
79+
✏️ Editors
80+
├── CodeEditor
81+
└── MarkdownEditor
82+
83+
🏗️ Layout
84+
├── Shells
85+
│ ├── AuthShell
86+
│ ├── AppShell
87+
│ ├── WizardShell
88+
│ ├── MinimalShell
89+
│ └── ErrorShell
90+
├── Content Layouts
91+
│ ├── MainFixedLayout
92+
│ ├── DataDenseLayout
93+
│ └── ContentWrapper
94+
└── Navigation
95+
├── TopBar
96+
├── SideNav
97+
├── NavItem
98+
├── Breadcrumbs
99+
└── HeaderActionIcon
100+
101+
🎨 Feedback
102+
├── Toast
103+
└── StatusBadge
104+
105+
📊 Data Display
106+
└── DataTable
107+
108+
🔧 Form Components
109+
├── Form Examples
110+
├── FormGrid
111+
├── FormGroup
112+
└── A11y Examples
113+
114+
🛡️ Providers
115+
├── ErrorBoundary
116+
├── ThemeProvider
117+
└── ThemeToggle
118+
119+
🎯 Brand
120+
├── Logo
121+
└── EtheriscLogo
122+
123+
📝 Examples
124+
└── Component Gallery
125+
```
126+
127+
**Title Mapping (Old → New):**
128+
129+
- `Primitives/Button` → `Form Controls/Button`
130+
- `Components/Form/Checkbox` → `Form Controls/Checkbox`
131+
- `Components/Primitives/DatePicker` → `Form Controls/DatePicker`
132+
- `Primitives/CodeEditor` → `Editors/CodeEditor`
133+
- `Layout/AppShell/TopBar` → `Layout/Navigation/TopBar`
134+
- `Components/Feedback/Toast` → `Feedback/Toast`
135+
- `Components/Primitives/ThemeToggle` → `Providers/ThemeToggle`
136+
- `Example/*` → DELETE (legacy stories)
137+
- `Form/FormExample` → `Form Components/Form Examples`
138+
139+
## Implementation Details
140+
141+
### 1. Story Title Conventions
142+
143+
- Use descriptive category names: `Form Controls/Button` instead of `Primitives/Button`
144+
- Group related components: All form inputs under `Form Controls`
145+
- Separate complex layouts: Different shell types under `Layout/Shells`
146+
147+
### 2. Documentation Structure
148+
149+
- Create index MDX files for each major category
150+
- Include component overview, usage guidelines, and links
151+
- Add getting started documentation
152+
153+
### 3. Build Verification
154+
155+
- Ensure no broken links or imports
156+
- Verify all components appear in correct categories
157+
- Confirm build completes without errors
158+
159+
## Success Criteria (DoD)
160+
161+
- ✅ `npm run build-storybook` completes successfully
162+
- ✅ New components appear under correct groups in sidebar
163+
- ✅ All story titles follow consistent naming conventions
164+
- ✅ Documentation index pages exist for major categories
165+
- ✅ Sidebar is logically organized and easy to navigate
166+
- ✅ No broken stories or missing imports
167+
- ✅ Component categories are clearly separated and labeled

‎packages/ui-kit/.storybook/preview.tsx‎

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -50,6 +50,30 @@ const preview: Preview = {
5050
light: { ...themes.light },
5151
current: 'light',
5252
},
53+
options: {
54+
storySort: {
55+
order: [
56+
'Welcome',
57+
'Form Controls',
58+
['Overview', 'Button', 'TextInput', 'NumberInput', 'TextArea', 'Select', 'ComboBox', 'Checkbox', 'RadioGroup', 'SliderInput', 'SpinnerInput', 'DatePicker', 'DateRangePicker'],
59+
'Editors',
60+
['Overview', 'CodeEditor', 'MarkdownEditor'],
61+
'Layout',
62+
['Overview', 'Shells', 'Content Layouts', 'Navigation'],
63+
'Feedback',
64+
['Overview', 'Toast', 'StatusBadge'],
65+
'Data Display',
66+
'Form Components',
67+
['Overview', 'Form Examples', 'A11y Examples'],
68+
'Providers',
69+
['Overview', 'ErrorBoundary', 'ThemeProvider', 'ThemeToggle'],
70+
'Brand',
71+
['Overview', 'Logo', 'EtheriscLogo'],
72+
'Examples',
73+
'*' // Everything else at the end
74+
],
75+
},
76+
},
5377
},
5478
decorators: [
5579
(Story, context) => (

‎packages/ui-kit/src/Welcome.mdx‎

Lines changed: 63 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -49,49 +49,95 @@ function App() {
4949

5050
## 🧩 Component Categories
5151

52-
### 🎨 **Primitives**
52+
### 🧱 **Form Controls**
5353

54-
Basic building blocks for your application:
54+
Essential form input components:
5555

5656
- **Button** - Various button styles and states
57-
- **Input** - Text, number, and form inputs
57+
- **TextInput** - Text input with validation
58+
- **NumberInput** - Numeric input with constraints
59+
- **TextArea** - Multi-line text input
60+
- **Select** - Dropdown selection component
61+
- **ComboBox** - Searchable dropdown with autocomplete
5862
- **Checkbox** - Accessible checkbox components
59-
- **ThemeToggle** - Dark/light mode switcher
63+
- **RadioGroup** - Radio button groups
64+
- **SliderInput** - Range slider input
65+
- **SpinnerInput** - Numeric spinner input
66+
- **DatePicker** - Date selection component
67+
- **DateRangePicker** - Date range selection
6068

61-
### 📋 **Form Components**
69+
### ✏️ **Editors**
6270

63-
Complete form building blocks:
71+
Advanced text editing components:
6472

65-
- **TextInput** - Enhanced text input with validation
66-
- **NumberInput** - Numeric input with min/max constraints
67-
- **Form Examples** - Accessible form patterns
73+
- **CodeEditor** - Syntax-highlighted code editor
74+
- **MarkdownEditor** - WYSIWYG markdown editor
6875

69-
### 🏗️ **Layout Components**
76+
### 🏗️ **Layout**
7077

71-
Structure your application:
78+
Structure your application with organized layout components:
7279

80+
#### **Shells**
7381
- **AppShell** - Complete application layout
7482
- **AuthShell** - Authentication page layouts
83+
- **WizardShell** - Multi-step wizard layouts
7584
- **MinimalShell** - Minimal page layouts
85+
- **ErrorShell** - Error page layouts
86+
87+
#### **Content Layouts**
88+
- **MainFixedLayout** - Fixed-width main content layout
89+
- **DataDenseLayout** - Dense data presentation layout
7690
- **ContentWrapper** - Content area management
91+
92+
#### **Navigation**
93+
- **TopBar** - Application top navigation
94+
- **SideNav** - Sidebar navigation
95+
- **NavItem** - Individual navigation items
7796
- **Breadcrumbs** - Navigation breadcrumbs
78-
- **Logo** - Brand logo component
79-
- **NavItem** - Navigation items
97+
- **HeaderActionIcon** - Header action buttons
98+
99+
### 🎨 **Feedback**
100+
101+
User feedback and status components:
102+
103+
- **Toast** - Notification toast messages
104+
- **StatusBadge** - Status indicator badges
105+
106+
### 📊 **Data Display**
107+
108+
Components for displaying structured data:
109+
110+
- **DataTable** - Feature-rich data tables
80111

81-
### 🔧 **Providers**
112+
### 🔧 **Form Components**
113+
114+
Complete form building patterns:
115+
116+
- **Form Examples** - Comprehensive form patterns
117+
- **A11y Examples** - Accessibility-focused examples
118+
119+
### 🛡️ **Providers**
82120

83121
Context providers for global functionality:
84122

85-
- **ThemeProvider** - Theme and dark mode management
86-
- **ToastProvider** - Toast notification system
87123
- **ErrorBoundary** - Error handling and recovery
124+
- **ThemeProvider** - Theme and dark mode management
125+
- **ThemeToggle** - Dark/light mode switcher
88126

89-
### 🎨 **Brand Components**
127+
### 🎯 **Brand**
90128

91129
Official Etherisc branding elements:
92130

131+
- **Logo** - Generic logo component
93132
- **EtheriscLogo** - Official Etherisc logo with multiple variants
94133

134+
### 📝 **Examples**
135+
136+
Demonstration and example components:
137+
138+
- **A11yButton** - Accessibility demonstration
139+
- **Component Gallery** - Showcase of all components
140+
95141
## ✨ Key Features
96142

97143
- **🎨 Modern Design System** - Built with Tailwind CSS and DaisyUI

0 commit comments

Comments
 (0)