Skill Storybook Stories: Создание Storybook историй для компонентов

--- name: storybook-stories description: Create, update, or refactor Storybook stories following the project's standard patterns. Use this skill when adding stories for new components, updating existing stories, or fixing Storybook-related issues. --- # Storybook Stories This skill enforces consistent Storybook story creation patterns across the application. It ensures that all components have proper documentation, interactive examples, and follow the established project structure. <critical_component_usage> **MANDATORY: Always Use Base UI Components from @compozy/ui** **CRITICAL REQUIREMENTS:** - ✅ **ALWAYS** import components from `@compozy/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 `@compozy/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 `@compozy/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. </critical_component_usage> ## 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`. 2. **Component Imports** - **MANDATORY**: Import base UI components from `@compozy/ui` - Use: `import { Button, Card, Dialog } from "@compozy/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> = { ... }` 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. 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 @compozy/ui ```tsx import type { Meta, StoryObj } from "@storybook/react"; import { Button, Card, CardHeader, CardTitle, CardContent } from "@compozy/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 @compozy/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 @compozy/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 @compozy/ui) ```tsx import type { Meta, StoryObj } from "@storybook/react"; import { Button } from "@compozy/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 ### Conciseness & Simplicity <critical> **MANDATORY: Keep Stories Concise and Focused** - ✅ **DO**: Create only essential stories that demonstrate core functionality - ✅ **DO**: Use minimal, realistic examples that show the component's purpose - ✅ **DO**: Focus on one concept per story - ❌ **DON'T**: Create excessive variations that don't add value - ❌ **DON'T**: Over-engineer with complex mock data or elaborate scenarios - ❌ **DON'T**: Create stories for every possible prop combination - ❌ **DON'T**: Add unnecessary decorators or wrappers unless required **Story Count Guidelines:** - Simple components (Button, Badge): 2-3 stories max (Default + 1-2 key variations) - Medium components (Card, Dialog): 3-4 stories max (Default + key use cases) - Complex components: 4-5 stories max (Default + essential scenarios) - **Never create more than 5 stories per component** unless absolutely necessary </critical> ### Component Usage - **Base Components First**: Always check `@compozy/ui` for existing components before creating new ones - **Composition Over Creation**: Compose complex components from base UI components - **Compound Components**: Always demonstrate the full structure (Parent + Children) when using compound components from `@compozy/ui` - **Design Tokens**: Always use design tokens (`bg-background`, `text-foreground`, etc.) instead of explicit colors ### Story Structure - **Mock Data**: Keep mock data minimal and realistic - only include what's necessary to demonstrate the component - **Interactivity**: For components like Accordion or Dialog, ensure the `render` function sets up the component in a way that allows interaction (e.g., not force-controlled unless necessary) - **Cleanliness**: Remove unused imports and generic "template" comments - **Type Safety**: Always use explicit type annotation for `meta`: `const meta: Meta<typeof Component>` - **Args Property**: Always include `args: {}` in all stories, even when using custom `render` functions - **One Story Per Concept**: Each story should demonstrate one clear use case or variation, not multiple concepts ### Design System Compliance - **Follow React Rules**: Adhere to patterns in `@.cursor/rules/react.mdc` - **Follow Shadcn Rules**: Adhere to patterns in `@.cursor/rules/shadcn.mdc` - **Accessibility**: Use semantic HTML and proper ARIA attributes - **Theme Support**: All stories should work in both light and dark themes using design tokens ## Common Mistakes to Avoid ❌ **Creating components from scratch when base components exist:** ```tsx // ❌ 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 @compozy/ui import { Button } from "@compozy/ui"; export const Good: Story = { args: {}, render: () => <Button variant="default">Click me</Button>, }; ``` ❌ **Using explicit colors instead of design tokens:** ```tsx // ❌ 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"> ``` ❌ **Missing args property:** ```tsx // ❌ 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>, }; ``` ❌ **Missing explicit type annotation:** ```tsx // ❌ 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, }; ``` ❌ **Over-engineering stories with unnecessary examples:** ```tsx // ❌ 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 ``` ❌ **Over-complicated mock data or scenarios:** ```tsx // ❌ 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" }, ]; ```