README

Author: sacrosanctic

.storybook/README.md

@@ -0,0 +1,135 @@
+# Why are we using Storybook?
+
+Storybook is a development environment for UI components that helps catch changes in UI while also having integrations for different kinds of tests. For testing, Storybook provides:
+
+- **Accessibility tests** - Built-in a11y checks (link to example)
+- **Visual tests** - Compare JPG screenshots (link to example)
+- **Snapshot tests** - Compare HTML output (link to example)
+- **Vitest tests** - Use stories directly in your unit tests (link to example)
+
+## Component Categories
+
+We organize components into 3 categories.
+
+### UI Library Components
+
+**Generic, reusable components** used throughout your application.
+
+- Examples: Button, Input, Modal, Card
+- **Testing focus:** Props, variants, accessibility
+- **Coverage:** All variants and states
+
+### Composite Components
+
+**Domain-specific components** built from UI library components.
+
+- Examples: UserProfile, ProductCard, SearchForm
+- **Testing focus:** Integration patterns, user interactions
+- **Coverage:** Common usage scenarios
+
+### Page Components
+
+**Full-page layouts** shown to end users.
+
+- Examples: HomePage, Dashboard, CheckoutPage
+- **Testing focus:** Layout, responsive behavior, integration testing
+- **Coverage:** Critical user flows and breakpoints
+
+## Coverage Guidelines
+
+### Which Components Need Stories?
+
+TBD
+
+### Convention
+
+- An edge case per story
+- Do not use `autodocs`
+
+# How to Use
+
+## Writing Stories
+
+1. **Create your first story** - Place a `.stories.ts` file next to your component:
+
+   ```
+   components/
+   ├── Button.vue
+   └── Button.stories.ts
+   ```
+
+2. **Add the story code** - Each story file follows this pattern:
+
+```ts
+// Button.stories.ts
+import type { Meta, StoryObj } from '@nuxtjs/storybook'
+import Component from './Button.vue'
+
+const meta = {
+  component: Component,
+  // component configuration goes here
+} satisfies Meta<typeof Component>
+
+export default meta
+type Story = StoryObj<typeof meta>
+
+export const Default: Story = {
+  // story configuration goes here
+}
+```
+
+3. **Run Storybook locally:**
+
+   ```sh
+   pnpm storybook
+   ```
+
+4. **Find your story** - Storybook URLs mirror your project structure.
+
+For a component at `app/components/Button/Button.stories.ts`, the story will be available at `http://localhost:6006/?path=/story/components-button--default`
+
+## Configuration
+
+### Global Configuration (`.storybook/preview.ts`)
+
+Affects all stories across the project:
+
+```ts
+export default {
+  globals: {
+    locale: 'en-US',
+  },
+}
+```
+
+### Component Configuration (meta)
+
+Overrides settings for a specific component:
+
+```ts
+const meta = {
+  component: Button,
+  parameters: {
+    layout: 'centered',
+  },
+  globals: {
+    locale: 'ja-JP',
+  },
+}
+```
+
+### Story Configuration
+
+Overrides settings for individual stories:
+
+```ts
+export const SpecialCase: Story = {
+  globals: {
+    locale: 'fr-FR',
+  },
+}
+```
+
+## Global App Settings
+
+Global application settings are added to the Storybook toolbar for easy testing and viewing. Configure these in `.storybook/preview.ts` using the `globals` property with toolbar definitions.