docs(storybooks): implement ADR-013 documentation guidelines (#635)

Copilot · SebastianSchuetze · web-flow · commit 7a1b6ece7d60 · 2026-02-03T22:51:41.000Z
Co-authored-by: Sebastian Schütze &lt;sebastian.schuetze@razorspoint.com&gt;
diff --git a/.github/instructions/stories.instructions.md b/.github/instructions/stories.instructions.md
@@ -14,11 +14,42 @@ These rules apply to all Storybook stories (`*.stories.tsx`) and ensure they are
 
 ## Implementation Rules
 
-### Documentation Location
+### Documentation Location (ADR-013)
+
+This repository follows **ADR-013: Storybook Documentation Location** (see `docs/adrs/013-adr-storybook-documentation-location.md`).
+
+**Autodocs-First Approach:**
+
+- **Primary documentation** lives in story files via Autodocs. Stories must include the `autodocs` tag in their `tags` array (for example, `tags: ['autodocs']`).
+- All stories **must** include the `autodocs` tag in their `tags` array to enable automatic documentation generation.
+- Add a short component description via `parameters.docs.description.component` when it helps clarify the component's purpose or key behaviors.
+- Keep descriptions concise (1-3 sentences). Example:
+  ```tsx
+  const meta = {
+    title: 'Atoms/Button',
+    component: Button,
+    tags: ['autodocs'],
+    parameters: {
+      docs: {
+        description: {
+          component:
+            'Primary interactive element for user actions. Supports multiple variants and sizes for different contexts.',
+        },
+      },
+    },
+  } satisfies Meta<typeof Button>
+  ```
+
+**When to Use MDX:**
 
-- **Primary documentation** lives in story files via Autodocs (`tags: ['autodocs']`) and short component descriptions in story metadata.
 - **Use Storybook MDX docs** only for cross-cutting guidance, complex workflows, or narrative explanations that do not fit inside Autodocs.
-- **Use repository docs** (like ADRs) only for system-wide decisions or infra-level guidance; do not duplicate component documentation there.
+- Examples: design system patterns, compound component usage guides, accessibility best practices across multiple components.
+- Do **NOT** create MDX files for individual component documentation—use story metadata instead.
+
+**Repository Docs:**
+
+- **Use repository docs** (like ADRs in `docs/adrs/`) only for system-wide decisions or infra-level guidance.
+- Do **NOT** duplicate component documentation in repository markdown files.
 
 ### 0. Images / Assets (Required)
 
@@ -68,3 +99,19 @@ These rules apply to all Storybook stories (`*.stories.tsx`) and ensure they are
 - Stories are run as tests via `pnpm tests`.
 - Any story that crashes because of missing providers (Router, QueryClient) is considered a **failed test**.
 - Fix failures by mocking the missing dependency in the story, NOT by adding the provider to the global test setup.
+
+## Contributor Checklist (PR Reviews)
+
+When creating or updating stories, ensure:
+
+- [ ] Story includes `autodocs` tag in the tags array for automatic documentation
+- [ ] Story metadata includes a concise description via `parameters.docs.description.component` (1-3 sentences) when it clarifies component purpose
+- [ ] Story title follows atomic structure: `Atoms/`, `Molecules/`, `Organisms/`, `Templates/`
+- [ ] Stories are isolated—no real API calls, navigation, or external dependencies
+- [ ] Images/assets are committed to `src/stories/assets/` (no hotlinked URLs except `placehold.co` for ephemeral placeholders)
+- [ ] Interactive behaviors are covered by `play()` functions with assertions
+- [ ] Mock decorators are used for routing, auth, and fetch when needed
+- [ ] Component business logic and visuals remain unchanged (stories only document existing behavior)
+- [ ] Tests pass: `pnpm tests` (stories run as Vitest tests)
+
+**Reference**: See [ADR-013](../../docs/adrs/013-adr-storybook-documentation-location.md) for full documentation location guidelines.
diff --git a/.storybook/main.ts b/.storybook/main.ts
@@ -3,7 +3,7 @@ import { createRequire } from 'node:module'
 import tsconfigPaths from 'vite-tsconfig-paths'
 
 const config: StorybookConfig = {
-  stories: ['../src/stories/**/*.stories.@(js|jsx|mjs|ts|tsx)'],
+  stories: ['../src/stories/**/*.stories.@(js|jsx|mjs|ts|tsx)', '../src/stories/**/*.mdx'],
   addons: [
     '@chromatic-com/storybook',
     '@storybook/addon-vitest',
diff --git a/eslint.config.mjs b/eslint.config.mjs
@@ -42,7 +42,7 @@ const eslintConfig = [
     },
   },
   {
-    files: ['src/stories/**/*.{ts,tsx,mdx}'],
+    files: ['src/stories/**/*.{ts,tsx}'],
     // Enforce correct Storybook framework imports to avoid mixing Next.js/React renderers
     rules: {
       'no-restricted-imports': [
@@ -119,6 +119,7 @@ const eslintConfig = [
       'src/payload-types.ts',
       'src/app/(payload)/**',
       'next-env.d.ts',
+      'src/stories/**/*.mdx',
     ],
   },
   ...storybook.configs['flat/recommended'],
diff --git a/public/stories/flower.mp4 b/public/stories/flower.mp4
diff --git a/src/stories/atoms/Button.stories.tsx b/src/stories/atoms/Button.stories.tsx
@@ -6,6 +6,14 @@ const meta = {
   title: 'Atoms/Button',
   component: Button,
   tags: ['autodocs'],
+  parameters: {
+    docs: {
+      description: {
+        component:
+          'Primary interactive element for user actions. Supports multiple variants (primary, secondary, destructive, etc.) and sizes for different contexts.',
+      },
+    },
+  },
   argTypes: {
     variant: {
       control: 'select',
diff --git a/src/stories/atoms/Dialog.stories.tsx b/src/stories/atoms/Dialog.stories.tsx
@@ -16,6 +16,14 @@ const meta = {
   title: 'Atoms/Dialog',
   component: Dialog,
   tags: ['autodocs'],
+  parameters: {
+    docs: {
+      description: {
+        component:
+          'Modal dialog compound component for critical user interactions. Built with a Dialog root component and DialogTrigger, DialogContent, DialogHeader, DialogFooter, DialogTitle, DialogDescription, and DialogClose sub-components for composable layouts.',
+      },
+    },
+  },
 } satisfies Meta<typeof Dialog>
 
 export default meta
diff --git a/src/stories/atoms/Heading.stories.tsx b/src/stories/atoms/Heading.stories.tsx
@@ -8,6 +8,12 @@ const meta = {
   tags: ['autodocs'],
   parameters: {
     layout: 'padded',
+    docs: {
+      description: {
+        component:
+          'Semantic heading component with controlled typography hierarchy (h1-h6). Requires explicit alignment prop to ensure consistent text positioning.',
+      },
+    },
   },
   args: {
     as: 'h2',
diff --git a/src/stories/atoms/Input.stories.tsx b/src/stories/atoms/Input.stories.tsx
@@ -7,6 +7,14 @@ const meta = {
   title: 'Atoms/Input',
   component: Input,
   tags: ['autodocs'],
+  parameters: {
+    docs: {
+      description: {
+        component:
+          'Text input field for user data entry. Supports various types (text, email, password) and validation states.',
+      },
+    },
+  },
   argTypes: {
     type: {
       control: 'select',
diff --git a/src/stories/atoms/Slider.stories.tsx b/src/stories/atoms/Slider.stories.tsx
@@ -6,6 +6,7 @@ import { Slider } from '@/components/atoms/slider'
 const meta: Meta<typeof Slider> = {
   title: 'Atoms/Slider',
   component: Slider,
+  tags: ['autodocs'],
 }
 
 export default meta
diff --git a/src/stories/atoms/VerificationBadge.stories.tsx b/src/stories/atoms/VerificationBadge.stories.tsx
@@ -5,6 +5,7 @@ import { VerificationBadge } from '@/components/atoms/verification-badge'
 const meta = {
   title: 'Atoms/VerificationBadge',
   component: VerificationBadge,
+  tags: ['autodocs'],
 } satisfies Meta<typeof VerificationBadge>
 
 export default meta
diff --git a/src/stories/molecules/CheckboxGroup.stories.tsx b/src/stories/molecules/CheckboxGroup.stories.tsx
@@ -7,6 +7,7 @@ import { CheckboxGroup } from '@/components/molecules/CheckboxGroup'
 const meta: Meta<typeof CheckboxGroup> = {
   title: 'Molecules/CheckboxGroup',
   component: CheckboxGroup,
+  tags: ['autodocs'],
 }
 
 export default meta
diff --git a/src/stories/molecules/CheckboxWithLabel.stories.tsx b/src/stories/molecules/CheckboxWithLabel.stories.tsx
@@ -7,6 +7,7 @@ import { CheckboxWithLabel } from '@/components/molecules/CheckboxWithLabel'
 const meta: Meta<typeof CheckboxWithLabel> = {
   title: 'Molecules/CheckboxWithLabel',
   component: CheckboxWithLabel,
+  tags: ['autodocs'],
 }
 
 export default meta
diff --git a/src/stories/molecules/ClinicSearchBar.stories.tsx b/src/stories/molecules/ClinicSearchBar.stories.tsx
@@ -26,6 +26,14 @@ const meta: Meta<typeof ControlledClinicSearchBar> = {
   title: 'Molecules/ClinicSearchBar',
   component: ControlledClinicSearchBar,
   tags: ['autodocs'],
+  parameters: {
+    docs: {
+      description: {
+        component:
+          'Compound search interface for finding clinics by service, location, and budget. Parent-controlled component with three combobox inputs and submit handler.',
+      },
+    },
+  },
   argTypes: {
     onSearch: { action: 'onSearch' },
   },
diff --git a/src/stories/molecules/Container.stories.tsx b/src/stories/molecules/Container.stories.tsx
@@ -6,6 +6,12 @@ const meta = {
   component: Container,
   parameters: {
     demoFrame: false,
+    docs: {
+      description: {
+        component:
+          'Layout wrapper that constrains content width to design system max-width with responsive padding. Base variant removes max-width constraint.',
+      },
+    },
   },
   tags: ['autodocs'],
 } satisfies Meta<typeof Container>
diff --git a/src/stories/molecules/LocationLine.stories.tsx b/src/stories/molecules/LocationLine.stories.tsx
@@ -6,6 +6,7 @@ import { sampleClinicLocation } from '@/stories/fixtures'
 const meta = {
   title: 'Molecules/LocationLine',
   component: LocationLine,
+  tags: ['autodocs'],
 } satisfies Meta<typeof LocationLine>
 
 export default meta
diff --git a/src/stories/molecules/Logo.stories.tsx b/src/stories/molecules/Logo.stories.tsx
@@ -5,6 +5,13 @@ const meta = {
   title: 'Molecules/Logo',
   component: Logo,
   tags: ['autodocs'],
+  parameters: {
+    docs: {
+      description: {
+        component: 'Brand logo component with dark and white variants for different background contexts.',
+      },
+    },
+  },
   argTypes: {
     variant: {
       control: 'select',
diff --git a/src/stories/molecules/Media.stories.tsx b/src/stories/molecules/Media.stories.tsx
@@ -51,8 +51,7 @@ const sampleVideo: PlatformContentMedia = {
   storagePath: 'public/stories/flower.mp4',
   updatedAt: '2024-01-01T00:00:00.000Z',
   createdAt: '2024-01-01T00:00:00.000Z',
-  // Use a public MP4 URL so Storybook can load it without the Payload /media route.
-  url: 'https://interactive-examples.mdn.mozilla.net/media/cc0-videos/flower.mp4',
+  url: '/stories/flower.mp4',
   filename: 'flower.mp4',
   mimeType: 'video/mp4',
   filesize: 12345,
diff --git a/src/stories/molecules/Pagination.stories.tsx b/src/stories/molecules/Pagination.stories.tsx
@@ -6,6 +6,14 @@ const meta = {
   title: 'Molecules/Pagination',
   component: Pagination,
   tags: ['autodocs'],
+  parameters: {
+    docs: {
+      description: {
+        component:
+          'Navigation component for paginated content lists. Displays page numbers with ellipsis for long ranges and handles edge cases (first/last page).',
+      },
+    },
+  },
 } satisfies Meta<typeof Pagination>
 
 export default meta
diff --git a/src/stories/molecules/RatingFilter.stories.tsx b/src/stories/molecules/RatingFilter.stories.tsx
@@ -6,6 +6,7 @@ import { sampleClinicRating } from '@/stories/fixtures'
 const meta: Meta<typeof RatingFilter> = {
   title: 'Molecules/RatingFilter',
   component: RatingFilter,
+  tags: ['autodocs'],
 }
 
 export default meta
diff --git a/src/stories/molecules/RatingSummary.stories.tsx b/src/stories/molecules/RatingSummary.stories.tsx
@@ -6,6 +6,7 @@ import { makeClinic, sampleClinicRating } from '@/stories/fixtures'
 const meta = {
   title: 'Molecules/RatingSummary',
   component: RatingSummary,
+  tags: ['autodocs'],
 } satisfies Meta<typeof RatingSummary>
 
 export default meta
diff --git a/src/stories/molecules/TagList.stories.tsx b/src/stories/molecules/TagList.stories.tsx
@@ -6,6 +6,7 @@ import { sampleClinicTags } from '@/stories/fixtures'
 const meta = {
   title: 'Molecules/TagList',
   component: TagList,
+  tags: ['autodocs'],
 } satisfies Meta<typeof TagList>
 
 export default meta
diff --git a/src/stories/molecules/WaitTime.stories.tsx b/src/stories/molecules/WaitTime.stories.tsx
@@ -6,6 +6,7 @@ import { sampleClinicWaitTime } from '@/stories/fixtures'
 const meta = {
   title: 'Molecules/WaitTime',
   component: WaitTime,
+  tags: ['autodocs'],
 } satisfies Meta<typeof WaitTime>
 
 export default meta
diff --git a/src/stories/organisms/BlogCard.stories.tsx b/src/stories/organisms/BlogCard.stories.tsx
@@ -7,6 +7,14 @@ const meta = {
   title: 'Organisms/BlogCard',
   component: BlogCard,
   tags: ['autodocs'],
+  parameters: {
+    docs: {
+      description: {
+        component:
+          'Content card displaying blog post preview with image, title, excerpt, and date. Supports default and inverted color variants.',
+      },
+    },
+  },
 } satisfies Meta<typeof BlogCard>
 
 export default meta
diff --git a/src/stories/organisms/CallToAction.stories.tsx b/src/stories/organisms/CallToAction.stories.tsx
@@ -8,6 +8,12 @@ const meta = {
   decorators: [withMockRouter],
   parameters: {
     layout: 'fullscreen',
+    docs: {
+      description: {
+        component:
+          'Full-width promotional section with rich text content and up to two action links. Commonly used at page endings to drive conversions.',
+      },
+    },
   },
   tags: ['autodocs'],
 } satisfies Meta<typeof CallToAction>
diff --git a/src/stories/organisms/FAQSection.stories.tsx b/src/stories/organisms/FAQSection.stories.tsx
@@ -10,6 +10,12 @@ const meta: Meta<typeof FAQSection> = {
   tags: ['autodocs'],
   parameters: {
     layout: 'fullscreen',
+    docs: {
+      description: {
+        component:
+          'Collapsible accordion section for frequently asked questions. Supports an optional default open item to control which question is expanded initially.',
+      },
+    },
   },
 }
 
diff --git a/src/stories/organisms/Form.stories.tsx b/src/stories/organisms/Form.stories.tsx
@@ -9,6 +9,12 @@ const meta = {
   decorators: [withMockRouter],
   parameters: {
     layout: 'fullscreen',
+    docs: {
+      description: {
+        component:
+          'Dynamic form builder that renders fields from configuration object. Supports text, email, textarea, select, and checkbox fields with validation and submission handling.',
+      },
+    },
   },
   tags: ['autodocs'],
 } satisfies Meta<typeof Form>
diff --git a/src/stories/organisms/ListingCard.stories.tsx b/src/stories/organisms/ListingCard.stories.tsx
@@ -7,6 +7,7 @@ import { clinicMedia, makeClinic } from '@/stories/fixtures/listings'
 const meta: Meta<typeof ListingCard> = {
   title: 'Organisms/ListingCard',
   component: ListingCard,
+  tags: ['autodocs'],
   parameters: {
     layout: 'centered',
   },
diff --git a/src/stories/organisms/MediaBlock.stories.tsx b/src/stories/organisms/MediaBlock.stories.tsx
@@ -25,7 +25,7 @@ const mediaWithCaption = {
 }
 
 const mediaVideo = {
-  src: 'https://interactive-examples.mdn.mozilla.net/media/cc0-videos/flower.mp4',
+  src: '/stories/flower.mp4',
   alt: 'Sample looping video',
   type: 'video' as const,
 }
diff --git a/src/stories/pages/storybook/assets-and-media.mdx b/src/stories/pages/storybook/assets-and-media.mdx
diff --git a/src/stories/pages/storybook/mocking-and-isolation.mdx b/src/stories/pages/storybook/mocking-and-isolation.mdx
diff --git a/src/stories/pages/storybook/play-and-vitest.mdx b/src/stories/pages/storybook/play-and-vitest.mdx
diff --git a/src/stories/pages/storybook/runtime-and-layout.mdx b/src/stories/pages/storybook/runtime-and-layout.mdx
diff --git a/src/stories/pages/storybook/ui-payload-boundary.mdx b/src/stories/pages/storybook/ui-payload-boundary.mdx
diff --git a/src/stories/templates/Landing.stories.tsx b/src/stories/templates/Landing.stories.tsx

Original file line number	Diff line number	Diff line change
`@@ -6,6 +6,7 @@ import { Slider } from '@/components/atoms/slider'`
`6`	`6`	`const meta: Meta<typeof Slider> = {`
`7`	`7`	`title: 'Atoms/Slider',`
`8`	`8`	`component: Slider,`
	`9`	`+ tags: ['autodocs'],`
`9`	`10`	`}`
`10`	`11`
`11`	`12`	`export default meta`