storybook-stories

CRITICAL REQUIREMENTS:

• ✅ ALWAYS import components from @agh/ui package (packages/ui)
• ✅ ALWAYS use existing base UI components instead of creating new ones from scratch
• ✅ ALWAYS follow design system rules from @.cursor/rules/react.mdc and @.cursor/rules/shadcn.mdc
• ✅ ALWAYS use design tokens (e.g., bg-background, text-foreground, border-border) instead of explicit colors
• ❌ NEVER create components from scratch when a base component exists in @agh/ui
• ❌ NEVER use explicit color values (e.g., bg-white, text-black) - always use design tokens
• ❌ NEVER duplicate component logic - compose from base components

Available Base Components: All components from packages/ui/src/components are available via @agh/ui:

• Button, Card, Dialog, Input, Select, Badge, Avatar, Accordion, Alert, etc.
• See packages/ui/src/index.ts for complete list of exports

Design System Rules:

• Follow React best practices: @.cursor/rules/react.mdc
• Follow Shadcn UI patterns: @.cursor/rules/shadcn.mdc
• Use design tokens for theming: bg-background, text-foreground, border-border, etc.

Instructions

1. File Location & Naming

   • Place story files in a stories/ folder within the same category folder as the component.
   • Example: src/components/base/accordion.tsx -> src/components/base/stories/accordion.stories.tsx.
   • Use the Storybook instance that matches the layer:
     • packages/ui/.storybook for packages/ui/src/components/*.stories.tsx
     • web/.storybook for web/src/components/ui/**/*.stories.tsx and web/src/systems/**/components/stories/*.stories.tsx

2. Component Imports

   • MANDATORY: Import base UI components from @agh/ui
   • Use: import { Button, Card, Dialog } from "@agh/ui";
   • Only import custom/domain-specific components from local files
   • Check packages/ui/src/index.ts to see available components before creating new ones

3. Meta Configuration

   • Title should follow the directory structure: components/custom/ComponentName or components/ui/ComponentName.
   • Include component in the meta object.
   • Set parameters.layout to "centered" by default.
   • Add parameters.docs.description.component to describe the component.
   • Use decorators if the component requires a specific container width or context.
   • MANDATORY: Use explicit type annotation: const meta: Meta<typeof Component> = { ... }
   • web system stories may rely on the shared QueryClient + router + MSW decorators from web/.storybook/preview.ts; prefer those global decorators over per-story provider duplication.

4. Story Definition

   • Define a helper type: type Story = StoryObj<typeof meta>;.
   • Export stories as named constants (PascalCase).
   • Always add JSDoc comments above each story export; these appear in the Storybook UI.
   • Use the Default story as the primary example.
   • MANDATORY: All stories must include args property, even if empty: args: {}
   • Keep it concise: Create only essential stories (2-5 max per component). Avoid over-engineering with excessive variations or complex scenarios.
   • For system stories, keep titles aligned to the domain surface: systems/<name>/<ComponentName>.

5. Render vs Args

   • Use render functions for compound components (like Accordion, Dialog, Select) that require children composition.
   • Use args for simple components (like Button, Badge) where props define the variation.
   • MANDATORY: Even when using render, include args: {} property

6. Design System Compliance

   • ALWAYS use design tokens for colors: bg-background, text-foreground, border-border
   • NEVER use explicit colors: bg-white, text-black, border-gray-200
   • Follow accessibility guidelines from @.cursor/rules/shadcn.mdc
   • Use semantic HTML elements and proper ARIA attributes

Example Template

Using Base UI Components from @agh/ui

import type { Meta, StoryObj } from "@storybook/react";
import { Button, Card, CardHeader, CardTitle, CardContent } from "@agh/ui";
import { MyCustomComponent } from "./my-custom-component";

const meta: Meta<typeof MyCustomComponent> = {
  title: "components/custom/MyCustomComponent",
  component: MyCustomComponent,
  parameters: {
    layout: "centered",
    docs: {
      description: {
        component: "A custom component that composes base UI components from @agh/ui.",
      },
    },
  },
  // Optional decorator using design tokens
  decorators: [
    Story => (
      <div className="w-[400px] p-4 bg-background border border-border rounded-lg">
        <Story />
      </div>
    ),
  ],
};

export default meta;
type Story = StoryObj<typeof meta>;

/**
 * Default usage showing the standard behavior
 * Uses base Button and Card components from @agh/ui
 */
export const Default: Story = {
  args: {},
  render: () => (
    <Card>
      <CardHeader>
        <CardTitle>My Custom Component</CardTitle>
      </CardHeader>
      <CardContent>
        <MyCustomComponent>
          <Button variant="default">Action</Button>
        </MyCustomComponent>
      </CardContent>
    </Card>
  ),
};

/**
 * Variation with specific props
 * All styling uses design tokens (bg-background, text-foreground, etc.)
 */
export const WithVariant: Story = {
  args: {},
  render: () => (
    <div className="bg-card border border-border rounded-lg p-4">
      <MyCustomComponent variant="secondary">
        <Button variant="outline">Secondary Action</Button>
      </MyCustomComponent>
    </div>
  ),
};

Story for Base UI Component (from @agh/ui)

import type { Meta, StoryObj } from "@storybook/react";
import { Button } from "@agh/ui";

const meta: Meta<typeof Button> = {
  title: "components/ui/Button",
  component: Button,
  parameters: {
    layout: "centered",
    docs: {
      description: {
        component: "A button component with multiple variants and sizes.",
      },
    },
  },
};

export default meta;
type Story = StoryObj<typeof meta>;

/**
 * Default button with standard styling
 */
export const Default: Story = {
  args: {
    children: "Button",
    variant: "default",
    size: "default",
  },
};

/**
 * All variants using design tokens
 */
export const AllVariants: Story = {
  args: {},
  render: () => (
    <div className="flex flex-wrap gap-4 bg-background p-4 rounded-lg">
      <Button variant="default">Default</Button>
      <Button variant="secondary">Secondary</Button>
      <Button variant="outline">Outline</Button>
      <Button variant="ghost">Ghost</Button>
      <Button variant="muted">Muted</Button>
    </div>
  ),
};

Best Practices

Autodocs Policy

Use tags: ["autodocs"] only for public packages/ui primitives or stories that intentionally document configuration-heavy public APIs. Do not add it by default to web/src/components/ui or web/src/systems/** stories; that policy comes from ADR-003 and keeps domain-story docs noise low.

Conciseness & Simplicity

// ❌ BAD: Creating a button from scratch
export const Bad: Story = {
  render: () => <button className="bg-blue-500 text-white px-4 py-2 rounded">Click me</button>,
};

// ✅ GOOD: Using base Button from @agh/ui
import { Button } from "@agh/ui";
export const Good: Story = {
  args: {},
  render: () => <Button variant="default">Click me</Button>,
};

// ❌ BAD: Using explicit colors
<div className="bg-white text-black border-gray-200">

// ✅ GOOD: Using design tokens
<div className="bg-background text-foreground border-border">

// ❌ BAD: Missing args property
export const Bad: Story = {
  render: () => <Button>Click</Button>,
};

// ✅ GOOD: Including args property
export const Good: Story = {
  args: {},
  render: () => <Button>Click</Button>,
};

// ❌ BAD: Type inference
const meta = {
  title: "Components/Button",
  component: Button,
} satisfies Meta<typeof Button>;

// ✅ GOOD: Explicit type annotation
const meta: Meta<typeof Button> = {
  title: "Components/Button",
  component: Button,
};

// ❌ BAD: Too many stories with similar variations
export const Default: Story = { ... };
export const WithIcon: Story = { ... };
export const WithIconLeft: Story = { ... };
export const WithIconRight: Story = { ... };
export const WithLongText: Story = { ... };
export const WithShortText: Story = { ... };
export const Disabled: Story = { ... };
export const Loading: Story = { ... };
export const WithTooltip: Story = { ... };
export const InCard: Story = { ... };
export const InDialog: Story = { ... };
// ... 10+ stories for a simple button

// ✅ GOOD: Concise, focused stories
export const Default: Story = {
  args: {
    children: "Button",
    variant: "default",
  },
};

export const Variants: Story = {
  args: {},
  render: () => (
    <div className="flex gap-2">
      <Button variant="default">Default</Button>
      <Button variant="secondary">Secondary</Button>
      <Button variant="outline">Outline</Button>
    </div>
  ),
};

export const Disabled: Story = {
  args: {
    children: "Disabled",
    disabled: true,
  },
};
// Only 3 stories covering essential use cases

// ❌ BAD: Unnecessarily complex mock data
const mockUsers = [
  { id: "1", name: "John Doe", email: "john@example.com", role: "admin", avatar: "...", lastLogin: "...", permissions: [...], metadata: {...} },
  { id: "2", name: "Jane Smith", email: "jane@example.com", role: "user", avatar: "...", lastLogin: "...", permissions: [...], metadata: {...} },
  // ... 10 more users with full data
];

// ✅ GOOD: Minimal, realistic data
const mockUsers = [
  { id: "1", name: "John Doe", email: "john@example.com" },
  { id: "2", name: "Jane Smith", email: "jane@example.com" },
];