chore: integrate Storybook into the project (#124)

Author: nickytonline

.continue/rules/file-structure-frameworks.md

@@ -114,6 +114,7 @@ export const Route = createFileRoute('/users/$id')({
 • Use Shadcn components as building blocks rather than reinventing UI
 • Create compound components for related UI elements
 • Export components with descriptive names
+• See the standards rule (`mcp-app-demo-standards.md`) for requirements on colocated Storybook stories for all new components.
 
 ## Code Organization
 
@@ -158,3 +159,7 @@ import { userSchema } from '../../lib/schemas'
 • Use kebab-case for route files when appropriate
 • Use descriptive names that clearly indicate the file's purpose
 • Include the file type in the name when it adds clarity
+
+```
+
+```

.continue/rules/mcp-app-demo-standards.md

@@ -110,3 +110,38 @@ function useToggle(initialValue = false) {
   return [value, toggle] as const
 }
 ```
+
+## Storybook Stories for Components
+
+- All new components **must** have a colocated Storybook story for visual documentation, testing, and design review.
+- The story file should be named `SomeComponent.stories.tsx` and placed in the same directory as `SomeComponent.tsx`.
+- Example file structure:
+
+  ```
+  src/components/
+    MyComponent.tsx
+    MyComponent.stories.tsx
+  ```
+
+- See `src/components/ui/button.stories.tsx` for a full example. Minimal example:
+
+  ```typescript
+  // MyComponent.stories.tsx
+  import type { Meta, StoryObj } from '@storybook/react'
+  import { MyComponent } from './MyComponent'
+
+  const meta: Meta<typeof MyComponent> = {
+    title: 'UI/MyComponent',
+    component: MyComponent,
+    tags: ['autodocs'],
+  }
+  export default meta
+
+  type Story = StoryObj<typeof MyComponent>
+
+  export const Default: Story = {
+    args: {
+      /* props */
+    },
+  }
+  ```

.continue/rules/styling-ui-guidelines.md

@@ -14,6 +14,7 @@ You are an expert in Tailwind CSS and Shadcn/ui component development.
 • Compose existing Shadcn components rather than creating new ones from scratch
 • Follow Shadcn's composition patterns for building complex UI
 • Customize Shadcn components through their built-in variant system
+• See the standards rule (`mcp-app-demo-standards.md`) for requirements on colocated Storybook stories for all new components.
 
 ## Tailwind CSS Best Practices
 

.cursorrules

@@ -404,6 +404,39 @@ npx shadcn@latest add <component-name>
 <div className={cn("base-classes", isActive && "active-classes")}>
 ```
 
+## Component Storybook Stories
+- All new components **must** have a colocated Storybook story for visual documentation, testing, and design review.
+- The story file should be named `SomeComponent.stories.tsx` and placed in the same directory as `SomeComponent.tsx`.
+- Example file structure:
+
+  ```
+  src/components/
+    MyComponent.tsx
+    MyComponent.stories.tsx
+  ```
+- See [`src/components/ui/button.stories.tsx`](src/components/ui/button.stories.tsx) for a full example. Minimal example:
+
+  ```typescript
+  // MyComponent.stories.tsx
+  import type { Meta, StoryObj } from '@storybook/react'
+  import { MyComponent } from './MyComponent'
+
+  const meta: Meta<typeof MyComponent> = {
+    title: 'UI/MyComponent',
+    component: MyComponent,
+    tags: ['autodocs'],
+  }
+  export default meta
+
+  type Story = StoryObj<typeof MyComponent>
+
+  export const Default: Story = {
+    args: {
+      /* props */
+    },
+  }
+  ```
+
 ## State Management Patterns
 
 **Loader-first approach - avoid redundant React Query:**

.github/copilot-instructions.md

@@ -369,6 +369,41 @@ import { Card, CardContent, CardHeader, CardTitle } from '@/components/ui/card';
 <div className={cn("base-classes", isActive && "active-classes")}>
 ```
 
+## Component Storybook Stories
+
+- All new components **must** have a colocated Storybook story for visual documentation, testing, and design review.
+- The story file should be named `SomeComponent.stories.tsx` and placed in the same directory as `SomeComponent.tsx`.
+- Example file structure:
+
+  ```
+  src/components/
+    MyComponent.tsx
+    MyComponent.stories.tsx
+  ```
+
+- See [`src/components/ui/button.stories.tsx`](src/components/ui/button.stories.tsx) for a full example. Minimal example:
+
+  ```typescript
+  // MyComponent.stories.tsx
+  import type { Meta, StoryObj } from '@storybook/react'
+  import { MyComponent } from './MyComponent'
+
+  const meta: Meta<typeof MyComponent> = {
+    title: 'UI/MyComponent',
+    component: MyComponent,
+    tags: ['autodocs'],
+  }
+  export default meta
+
+  type Story = StoryObj<typeof MyComponent>
+
+  export const Default: Story = {
+    args: {
+      /* props */
+    },
+  }
+  ```
+
 ## Accessibility Best Practices
 
 ### Semantic HTML and ARIA Attributes

.github/workflows/test.yaml

@@ -26,6 +26,9 @@ jobs:
 
       - name: Run tests
         run: npm run test:ci
+      # This can be removed one we deploy to Netlify and Storybook deploying is a check for PRs. See https://github.com/pomerium/mcp-app-demo/issues/123
+      - name: Build Storybook
+        run: npm run build-storybook
 
       - name: Set up QEMU
         uses: docker/setup-qemu-action@29109295f81e9208d7d86ff1c6c12d2833863392

.gitignore

@@ -145,3 +145,6 @@ dist
 # Tanstack Start specific files
 .tanstack
 .nitro
+
+*storybook.log
+storybook-static

.storybook/main.ts

@@ -0,0 +1,21 @@
+import type { StorybookConfig } from '@storybook/react-vite'
+
+const config: StorybookConfig = {
+  stories: [
+    '../src/components/**/*.stories.@(js|jsx|mjs|ts|tsx)',
+    '../src/components/**/*.mdx',
+  ],
+  addons: [
+    '@chromatic-com/storybook',
+    '@storybook/addon-docs',
+    '@storybook/addon-onboarding',
+    '@storybook/addon-a11y',
+    '@storybook/addon-vitest',
+    'storybook-dark-mode',
+  ],
+  framework: {
+    name: '@storybook/react-vite',
+    options: {},
+  },
+}
+export default config

.storybook/preview.tsx

@@ -0,0 +1,32 @@
+import React from 'react'
+import type { Preview } from '@storybook/react-vite'
+import '../src/styles.css'
+
+const preview: Preview = {
+  parameters: {
+    darkMode: {
+      classTarget: 'html',
+      darkClass: 'dark',
+      lightClass: '',
+      stylePreview: true,
+    },
+    controls: {
+      matchers: {
+        color: /(background|color)$/i,
+        date: /Date$/i,
+      },
+    },
+    a11y: {
+      test: 'todo',
+    },
+  },
+  decorators: [
+    (Story) => (
+      <div className="p-4">
+        <Story />
+      </div>
+    ),
+  ],
+}
+
+export default preview

.storybook/vitest.setup.ts

@@ -0,0 +1,7 @@
+import * as a11yAddonAnnotations from "@storybook/addon-a11y/preview";
+import { setProjectAnnotations } from '@storybook/react-vite';
+import * as projectAnnotations from './preview';
+
+// This is an important step to apply the right configuration when testing your stories.
+// More info at: https://storybook.js.org/docs/api/portable-stories/portable-stories-vitest#setprojectannotations
+setProjectAnnotations([a11yAddonAnnotations, projectAnnotations]);