Storybook Story Conventions

Canonical source: docs/coding-guidebook.md §12 (product-area grouping, FE-275).

Stack

• Framework: @storybook/nextjs-vite (Storybook 10)
• Discovery: ../src/**/*.mdx and ../src/**/*.stories.@(js|jsx|mjs|ts|tsx)
• Global decorators: .storybook/preview.tsx (Chakra provider, theme, sidebar storySort)
• Story tests: npx vitest run --project storybook [paths] (each story renders as a test; play functions run)

Titles (by product area)

Rules

• Colocate <Component>.stories.tsx next to every component that renders visible UI.
• One named story per situation the component can be in (data states, viewer roles, loading / empty / error, open / closed, phone vs desktop), each with a one-line JSDoc saying which situation it shows. Phone layouts: globals: { viewport: { value: 'mobile1' } }.
• No stories for hooks, providers, GraphQL, analytics view capture, trackers, URL sync, or anything else that renders nothing visible.
• Components that read a route context get a story-only decorator that seeds the real provider with fixtures and a story-only Apollo client (a link that never resolves, plus a seeded cache), e.g. withTaskDetailStory in src/app/(task)/tasks/[slug]/helpers/. Stories must never reach the network (.env points at production).
• Story tests: npx vitest run --project storybook [paths] renders every story and runs play functions (e.g. UI/Dropdown "Mobile Item Opens Dialog").
• The sidebar order lives in .storybook/preview.tsx (storySort); add new areas there.
• Don't add non-story helper files under auto-generated barrel folders (src/ui, src/app/(task)/components); keep src/ui story helpers inside the story file.
• Inside src/ui/**, import siblings relatively, not through the @ui barrel.
• Dual theme: semantic tokens only; no hardcoded dark canvas wrappers.

Skeleton

import type { Meta, StoryObj } from '@storybook/nextjs-vite'

import { ComponentName } from './ComponentName'

const meta = {
  title: 'Area/ComponentName',
  component: ComponentName,
  parameters: { layout: 'padded' },
  args: {},
} satisfies Meta<typeof ComponentName>

export default meta
type Story = StoryObj<typeof meta>

/** Populated: what most people see. */
export const Default: Story = {}

/** Loading: skeleton while the data is fetched. */
export const Loading: Story = { args: { loading: true } }

Layout and args

• fullscreen for page-like or full-width components, padded for contained ones; match siblings when unsure.
• Realistic, production-like args with complete object shapes; reuse the area's story fixtures.

Checklist

• Story file is colocated, titled by product area, and listed in the right storySort group
• One story per situation, each with a one-line JSDoc
• Route contexts come from a story-only decorator; nothing reaches the network
• npx vitest run --project storybook <file> passes; no Biome or tsc errors

Examples

See references/EXAMPLE.md.