ARCHIVED: This plan was not delivered. Preserved for context.
Implementation Plan: Storybook Integration for Component Documentation¶
Overview¶
Integrate Storybook 10.1.x into the Vue 3 + Quasar application to document and test components. This implementation will create a comprehensive component library similar to the EPFL Elements example, with full support for Quasar framework, custom SCSS architecture, i18n and Pinia stores.
Architecture¶
Storybook will be organized within the frontend/ directory with the following structure:
frontend/
├── src/
│ └── components/
│ └── **/*.stories.ts (co-located with components)
├── storybook/
│ ├── .storybook/ (Storybook configuration)
│ └── stories/ (additional stories if needed)
├── Dockerfile (existing frontend app)
└── Dockerfile.storybook (Storybook Docker image)
The CI/CD pipeline will build both Docker images: the main frontend app and the Storybook static site.
Requirements¶
- Install Storybook 10.1.x with Vue 3 + Vite support
- Configure Quasar framework integration (plugins, styles, components)
- Setup custom decorators for i18n, Pinia, and Vue Router
- Configure SVG icon plugin in Storybook preview
- Import SCSS architecture with CSS Cascade Layers
- Create stories for components across atoms, molecules, charts, and layout categories
- Create documentation for writing stories
- Create Dockerfile.storybook for containerized Storybook deployment
- Update CI/CD pipeline to build Storybook Docker image
- Add Storybook command line helpers to frontend Makefile
Implementation Steps¶
Phase 1: Installation & Configuration (3 files)¶
1. Install Dependencies¶
Add to package.json:
Dev Dependencies:
npm install --save-dev \
@storybook/vue3-vite@=10.1.8 \
@storybook/addon-a11y@=10.1.8 \
@storybook/test@=10.1.8 \
@storybook/test-runner@=0.24.2 \
storybook@=10.1.8 \
concurrently@=9.2.1 \
wait-on@=9.0.1
Note: In Storybook 10.x, @storybook/addon-essentials, @storybook/addon-interactions, and @storybook/addon-links have been deprecated and integrated into Storybook's core. They should not be installed as separate packages.
NPM Scripts:
{
"storybook": "storybook dev -p 6006 --config-dir storybook/.storybook",
"storybook:build": "storybook build --config-dir storybook/.storybook",
"storybook:test": "test-storybook --config-dir storybook/.storybook",
"storybook:test-ci": "concurrently -k -s first -n \"SB,TEST\" -c \"magenta,blue\" \"npm run storybook -- --no-open --quiet --ci\" \"wait-on tcp:127.0.0.1:6006 && npm run storybook:test\""
}
Note: All Storybook commands are run from the frontend/ directory. The --config-dir flag is required since the Storybook configuration is located in the non-standard storybook/.storybook/ directory.
2. Storybook Main Configuration¶
File: storybook/.storybook/main.ts (create new)
- Configure stories glob pattern:
../../src/components/**/*.stories.@(js|jsx|mjs|ts|tsx) - Configure optional stories directory:
../stories/**/*.stories.@(js|jsx|mjs|ts|tsx)(for additional standalone stories) - Set
storiesarray in StorybookConfig to include both patterns - Register addons:
@storybook/addon-a11y(essentials, interactions, and links are now built into Storybook core) - Configure Vite integration with:
- Path aliases matching Quasar config (src, components, layouts, pages, assets)
- SCSS preprocessorOptions with additionalData for quasar-bridge
- Modern compiler API for Sass 1.93.3
3. Storybook Preview Configuration¶
File: storybook/.storybook/preview.ts (create new)
- Import ../../src/css/app.scss for CSS Cascade Layers
- Import Quasar icon libraries (Material Icons)
- Setup global app configuration:
- Pinia: Fresh instance per story
- Vue I18n: Composition API with messages from ../../src/i18n
- Vue Router: Memory history with basic routes
- Quasar: Install plugins (Dialog, Loading, Notify)
- Icon Plugin: Register custom SVG icons from ../../src/plugin/module-icon.ts
- Configure locale switcher in toolbar (EN/FR)
- Add i18n decorator for global locale switching
- Configure backgrounds and viewport presets
Phase 2: Decorators & Fixtures (4 files)¶
4. Pinia Store Utilities¶
File: storybook/.storybook/decorators/pinia.ts (create new)
- Create
withPiniadecorator for fresh store instances - Create
withMockStorehelper for overriding initial state - Prevent state leakage between stories
5. Timeline Mock Data¶
File: storybook/.storybook/fixtures/timeline.ts (create new)
- Export
defaultTimelineStatewith module states - Reference MODULE_STATES and MODULES constants from
../../src
File: storybook/.storybook/fixtures/timelineItems.ts (create new)
- Re-export timelineItems from ../../src/constant/timelineItems
- Export
mockTimelineItemfor stories
Phase 3: Atom Stories (3 files)¶
6. ModuleIcon Stories¶
File: src/components/atoms/ModuleIcon.stories.ts (create new)
- Stories: Default, Small, Large, AllIcons, ColorVariants
- argTypes: name (select), size (select), color (text)
- Description: Custom SVG icon component with size/color variants
- Features: Dynamic SVG injection, Vite glob imports
7. CO2Container Stories¶
File: src/components/atoms/CO2Container.stories.ts (create new)
- Stories: Default, WithMultipleElements
- Description: Simple slot wrapper with container styling
- Features: Single slot, layout styles
8. CO2LanguageSelector Stories¶
File: src/components/atoms/CO2LanguageSelector.stories.ts (create new)
- Stories: Default, WithMockRoute
- Description: Language switcher using Vue Router
- Features: Router-link integration, active state styling
Phase 4: Molecule Stories (3 files)¶
9. BigNumber Stories¶
File: src/components/molecules/BigNumber.stories.ts (create new)
- Stories: Default, WithComparison, WithColor, WithTooltip, LargeNumber
- argTypes: title, number, unit, comparison, comparisonHighlight, color
- Description: Q-Card component for displaying large metrics
- Features: i18n fallback, slot support, comparison highlighting
- Interaction Test: Add play function for tooltip interaction
10. ChartContainer Stories¶
File: src/components/molecules/ChartContainer.stories.ts (create new)
- Stories: Default, WithTooltip, MultipleCharts
- argTypes: title
- Description: Q-Card wrapper for charts with title and tooltip
- Features: Flat styling, centered content area
11. Co2TimelineItem Stories¶
File: src/components/molecules/Co2TimelineItem.stories.ts (create new)
- Stories: Default, InProgress, Validated, Selected, AllStates, Timeline
- argTypes: currentState (select), selected (boolean)
- Description: Timeline navigation item with state indicator
- Features: ModuleIcon integration, router navigation, state-based coloring
- Mock Data: Use mockTimelineItem from fixtures
Phase 4b: Chart Stories (1 file for now)¶
12. Chart Component Stories¶
Files: Create stories for chart components in src/components/charts/results/ (create new)
- Components to document:
-
ModuleCarbonFootprintChart.stories.ts -
Stories pattern: Default, WithData, WithLoading, WithEmptyState
- argTypes: data, loading, error states
- Description: ECharts-based visualization components
- Features: ECharts integration, data transformations, responsive sizing
- Mock Data: Create chart data fixtures for different scenarios
Note: During implementation, determine if charts should remain a separate category or be consolidated into molecules.
Phase 4c: Layout Stories (2 files)¶
13. Layout Component Stories¶
File: src/components/layout/Co2Header.stories.ts (create new)
- Stories: Default, WithNavigation, WithUser, MobileView
- Description: Main application header component
- Features: Navigation links, user menu, responsive layout
File: src/components/layout/Co2Sidebar.stories.ts (create new)
- Stories: Default, Collapsed, WithActiveRoute, MobileView
- Description: Application sidebar navigation
- Features: Route highlighting, collapse state, mobile responsiveness
Phase 5: Component Architecture Review (documentation task)¶
14. Review Organisms Category¶
Task: During Storybook implementation, review the organisms/ directory .
- Create a review document:
storybook/.storybook/ARCHITECTURE_REVIEW.md - Evaluate each organism component:
- Should it be in molecules instead?
- Should it be in layouts?
- Should it be split into smaller components?
- Is the current categorization appropriate?
Phase 6: Documentation (1 file)¶
15. Storybook Documentation¶
File: storybook/.storybook/README.md (create new)
- Running Storybook: npm scripts reference
- Project Structure: File organization diagram
- Writing Stories: Basic story structure, TypeScript types
- Using i18n: Locale switching, translation keys
- Using Pinia: Store initialization, mock state
- Using Router: Memory history, navigation
- Custom Icons: SVG icon plugin usage
- Interaction Testing: play function examples
- Best Practices: Co-location, autodocs, multiple variants
- Troubleshooting: Common issues (CSS loading, icons, store state, router errors)
Phase 7: Docker Configuration (1 file)¶
16. Create Dockerfile.storybook¶
File: Dockerfile.storybook (create new)
- Multi-stage build similar to main Dockerfile
- Use
node:24-alpineas builder - Run
npm run storybook:buildto generate static site - Use
nginx:stable-alpine-slimfor production - Copy built files from
storybook-static/to nginx html directory - Expose port 8080 (or 6006 for consistency)
- Include healthcheck
Example structure:
FROM node:24-alpine AS builder
WORKDIR /app
COPY package.json package-lock.json ./
RUN npm ci
COPY . .
RUN npm run storybook:build
FROM nginx:stable-alpine-slim
COPY --from=builder /app/storybook-static /usr/share/nginx/html
EXPOSE 8080
CMD ["nginx", "-g", "daemon off;"]
Phase 8: CI/CD Integration (modify existing workflow)¶
17. Update CI/CD Pipeline¶
File: .github/workflows/deploy.yml (modify)
- Update
build_contextto include Storybook Docker build - Add Storybook image build step
- Ensure
Dockerfile.storybookis built alongside main frontend Dockerfile - Tag Storybook image appropriately (e.g.,
-storybooksuffix)
Note: The epfl-enac-build-push-deploy-action may need to be configured to recognize Dockerfile.storybook or a separate workflow step may be needed.
Phase 9: Makefile Helpers (modify existing)¶
18. Add Storybook Commands to Makefile¶
File: Makefile (modify)
Add the following commands:
.PHONY: storybook
storybook: ## Start Storybook development server
npm run storybook
.PHONY: storybook-build
storybook-build: ## Build Storybook static site
npm run storybook:build
.PHONY: storybook-test
storybook-test: ## Run Storybook interaction tests
npm run storybook:test
.PHONY: storybook-docker-build
storybook-docker-build: ## Build Storybook Docker image
docker build -f Dockerfile.storybook -t co2-calculator-storybook .
.PHONY: storybook-docker-run
storybook-docker-run: ## Run Storybook Docker container
docker run -p 8080:8080 co2-calculator-storybook
Phase 10: Git Configuration (1 file)¶
19. Update .gitignore¶
File: .gitignore (modify)
Add:
# Storybook
storybook-static/
Data Flow¶
Component Story Rendering¶
User opens Storybook → storybook/.storybook/main.ts loads config → storybook/.storybook/preview.ts runs setup()
→ Creates Pinia, i18n, router, Quasar → Story file loads from src/components/**/*.stories.ts
→ Component renders with args → User changes controls → Component re-renders
Docker Build Flow¶
CI/CD Pipeline → Build frontend Dockerfile (main app)
→ Build Dockerfile.storybook (static Storybook site)
→ Push both images to registry
→ Deploy both services (optional)
Critical Files (18-20 total)¶
Create (15-17 story files + config)¶
Configuration Files:
- storybook/.storybook/main.ts - Core configuration
- storybook/.storybook/preview.ts - Global setup
- storybook/.storybook/test-runner.ts - Test config
- storybook/.storybook/decorators/pinia.ts - Store utilities
- storybook/.storybook/fixtures/timeline.ts - Mock data
- storybook/.storybook/fixtures/timelineItems.ts - Mock data
Atom Stories: 7. src/components/atoms/ModuleIcon.stories.ts 8. src/components/atoms/CO2Container.stories.ts 9. src/components/atoms/CO2LanguageSelector.stories.ts
Molecule Stories: 10. src/components/molecules/BigNumber.stories.ts 11. src/components/molecules/ChartContainer.stories.ts 12. src/components/molecules/Co2TimelineItem.stories.ts
Chart Stories (to be determined during implementation): 13. src/components/charts/results/ModuleCarbonFootprintChart.stories.ts (required) 14. Additional chart stories as needed (optional)
Layout Stories: 15. src/components/layout/Co2Header.stories.ts 16. src/components/layout/Co2Sidebar.stories.ts
Documentation: 17. storybook/.storybook/README.md - User documentation 18. storybook/.storybook/ARCHITECTURE_REVIEW.md - Architecture review findings
Docker: 19. Dockerfile.storybook - Storybook Docker image
Modify (3 files)¶
- package.json - Add dependencies and scripts
- .gitignore - Add storybook-static/
- Makefile - Add Storybook command helpers
- .github/workflows/deploy.yml - Add Storybook Docker build (or separate workflow)
Architecture Decisions (To Be Determined During Implementation)¶
1. Charts Category Structure¶
Question: Should charts/ remain a separate category or be consolidated into molecules/?
Considerations:
- Keep separate if:
- Charts have distinct complexity/patterns (ECharts integration, data transformations)
- Charts are domain-specific (results charts vs general charts)
-
Team prefers clear separation of visualization components
-
Consolidate into molecules if:
- Charts are essentially complex molecules (composed of atoms, reusable)
- No significant architectural difference from other molecule components
- Simplifies navigation and reduces category overhead
Default recommendation: Start by documenting charts as separate category. Revisit after creating initial stories to assess if consolidation makes sense.¶
Edge Cases¶
1. Quasar CSS Auto-Injection Conflict¶
- Issue: Quasar auto-injects CSS, but app uses manual SCSS with cascade layers
- Solution: Import app.scss directly in preview.ts, use SCSS additionalData in main.ts
- Gotcha: Ensure app.scss loads before Quasar components
2. Vite Glob Import for SVG Icons¶
- Issue: Icon plugin uses import.meta.glob requiring special Vite handling
- Solution: Proper alias resolution in main.ts, icons loaded eagerly as raw strings
- Gotcha: Icon names must match SVG filenames exactly
3. CSS Cascade Layers Specificity¶
- Issue: Layers change CSS specificity, may conflict with Storybook styles
- Solution: Full layer structure imported via app.scss
- Gotcha: Custom story styles may need higher specificity
4. Pinia Store State Persistence¶
- Issue: Stores may persist state between stories
- Solution: Fresh Pinia instance per story via preview.ts setup
- Gotcha: Disable pinia-plugin-persistedstate in Storybook
5. Vue Router Memory History¶
- Issue: Components using useRoute() or router-link need router
- Solution: Memory history router in preview.ts with basic routes
- Gotcha: Console warnings about missing routes are safe to ignore
6. i18n Message Loading¶
- Issue: Messages loaded via Vite glob imports
- Solution: Import messages directly in preview.ts
- Gotcha: New translation keys require Storybook restart
7. TypeScript Path Aliases¶
- Issue: Project uses src/* aliases from Quasar tsconfig
- Solution: Match aliases exactly in main.ts viteFinal()
- Gotcha: "Cannot find module" errors indicate alias misconfiguration
Success Criteria¶
Functional¶
✅ Storybook runs on npm run storybook or make storybook
✅ Storybook Docker image builds successfully with make storybook-docker-build
✅ CI/CD pipeline builds Storybook Docker image
✅ Storybook static site is served correctly in Docker container
✅ All component categories have stories (atoms, molecules, charts, layout)
✅ Components have multiple story variants demonstrating different states and use cases
✅ i18n locale switcher works in toolbar
✅ Quasar components render correctly
✅ ModuleIcon displays all SVG icons
✅ CSS Cascade Layers apply correct styling
✅ Pinia stores available in stories
✅ Vue Router works without console errors
✅ Controls addon allows interactive prop editing
✅ Interaction tests run successfully
✅ Test runner executes all stories
✅ Static build produces deployable artifact
Documentation¶
✅ storybook/.storybook/README.md exists with complete guide ✅ Each story has component description and argTypes ✅ README includes troubleshooting and best practices
Implementation Order¶
- Phase 1: Install dependencies and create configuration files
- Phase 2: Create decorators and fixtures
- Phase 3: Create atom stories (ModuleIcon → CO2Container → CO2LanguageSelector)
- Phase 4: Create molecule stories (BigNumber → ChartContainer → Co2TimelineItem)
- Phase 4b: Create chart stories (ModuleCarbonFootprintChart, others as needed)
- Decision point: Determine if charts category should remain separate or be consolidated into molecules
- Phase 4c: Create layout stories (Co2Header → Co2Sidebar)
- Phase 5: Review organisms architecture and document findings (parallel to story creation)
- Phase 6: Create documentation (README.md and ARCHITECTURE_REVIEW.md)
- Phase 7: Create Dockerfile.storybook
- Phase 8: Update CI/CD pipeline for Storybook build
- Phase 9: Add Makefile helpers for Storybook commands
- Phase 10: Update .gitignore
- Phase 11: Verify all success criteria