Why Storybook?

Storybook is a development environment for UI components that helps catch UI changes and provides integrations for various testing types. For testing, Storybook offers:

• Accessibility tests - Built-in a11y checks
• Visual tests - Compare JPG screenshots
• Vitest tests - Use stories directly in the unit tests

Component Categories

The plan is to organize components into 3 categories.

UI Library Components

Generic and reusable components used throughout the application.

• Examples: Button, Input, Modal, Card
• Testing focus: Props, variants, accessibility
• Coverage: All variants and states

Composite Components

Single-use components that encapsulate one feature.

• Examples: UserProfile, WeeklyDownloadStats
• Testing focus: Integration patterns, user interactions
• Coverage: Common usage scenarios

Page Components

Full-page layouts should match what the users see.

• Examples: HomePage, Dashboard, CheckoutPage
• Testing focus: Layout, responsive behavior, integration testing
• Coverage: Critical user flows and breakpoints

Coverage Guidelines

Which Components Need Stories?

TBD

Project Conventions

Place .stories.ts files next to the component

components/
├── Button.vue
└── Button.stories.ts

Story Template

// *.stories.ts
import type { Meta, StoryObj } from '@nuxtjs/storybook'
import Component from './Button.vue'

const meta = {
  component: Component,
  // component scope configuration goes here
} satisfies Meta<typeof Component>

export default meta
type Story = StoryObj<typeof meta>

export const Default: Story = {
  // story scope configuration goes here
}

JSDocs Annotation

The component should include descriptive comments.

// Button.vue
<script setup lang="ts">
const props = withDefaults(
  defineProps<{
    /** Whether the button is disabled */
    disabled?: boolean
    /**
     * HTML button type attribute
     * @default "button"
    type?: 'button' | 'submit'
    // ...
  }>)
</script>

Configuration

Stories can be configured at three levels:

• Global scope (.storybook/preview.ts) - Applies to all stories
• Component scope - Applies to all stories for a specific component
• Story scope - Applies to individual stories only

Global App Settings

Global application settings are added to the Storybook toolbar for easy testing and viewing. Configure these in .storybook/preview.ts under the globalTypes and decorators properties.

Known Limitations

• Changing i18n in the toolbar doesn't update the language. A manual story reload is required.
• autodocs currently is non-functional due bugs, its usage is discouraged at this time.
• pnpm build-storybook currently fails, use pnpm storybook to view the stories for the time being.
• pnpm storybook may log warnings or non-breaking errors for Nuxt modules due to the lack of mocks. If the UI renders correctly, these can be safely ignored.