08 — Storybook-First Development

Develop a standalone UI component entirely in Storybook before integrating with the app.
For modules, use template 01 — Module Development which already follows a Storybook-first approach.
This template is for UI components in packages/ui/ or adding stories to existing components.

Context Loading

Read these files before executing the prompt:

docs/dev-frontend-guides/04_STORYBOOK_FIRST_DEVELOPMENT.md
docs/dev-frontend-guides/03_MODULE_DEVELOPMENT_LIFECYCLE.md
packages/modules/src/m04-page-hero/           # existing module example — read stories file
apps/storybook/.storybook/main.ts
apps/storybook/.storybook/preview.ts          # theme decorator setup
packages/themes/src/                          # scan for available themes

Prompt Template

Read the following context files first:
- docs/dev-frontend-guides/04_STORYBOOK_FIRST_DEVELOPMENT.md
- docs/dev-frontend-guides/03_MODULE_DEVELOPMENT_LIFECYCLE.md
- apps/storybook/.storybook/main.ts
- apps/storybook/.storybook/preview.ts
- packages/themes/src/ (scan for all theme names)
- {EXISTING_STORIES_FILE} (use as pattern reference)

Now create comprehensive Storybook stories for the following component
using a Storybook-first development approach:

**Component Name:** {COMPONENT_NAME}
**Package:** {PACKAGE — ui | modules}
**Module ID:** {MODULE_ID — e.g., M10}
**Component Path:** packages/{PACKAGE}/src/{COMPONENT_PATH}/
**Figma Reference:** {FIGMA_URL}

**Props Interface:**
{LIST_EACH_PROP_WITH_TYPE_AND_DESCRIPTION}

**Story Variants Needed:**
- Default — standard usage with all typical props populated
- Minimal — only required props, all optional props omitted
- Empty — edge case with empty arrays, empty strings where allowed
- LongContent — stress test with maximum-length text, many items
- AllOptions — every optional prop provided
{ADDITIONAL_VARIANTS — e.g., WithCTA, WithoutImage, SingleItem, ManyItems}

**Theme Decorator:** {YES_OR_NO — almost always Yes}
**Needs Interaction Tests:** {YES_OR_NO — Yes for interactive components like accordions, sliders, tabs}

**Interaction Test Scenarios (if applicable):**
{LIST_INTERACTIONS — e.g., click accordion header toggles panel, swipe carousel advances slide}

Create the stories file at:
packages/{PACKAGE}/src/{COMPONENT_PATH}/{COMPONENT_NAME}.stories.tsx

Follow these conventions:
- Use CSF3 (Component Story Format 3) with `satisfies Meta<typeof Component>`
- Include `tags: ['autodocs']` in the meta for automatic documentation
- Add Figma link in `parameters.design` using the Figma addon format
- Use realistic mock data drawn from hotel context (room names, restaurant descriptions, spa treatments — not lorem ipsum)
- Each story must render correctly in all 8 themes via the theme switcher decorator
- Test all breakpoints: 375px (mobile), 768px (tablet), 1024px (small desktop), 1440px (full desktop)
- For interactive components, add `play` functions using @storybook/test for interaction tests
- Mock data should be exported from a separate `{COMPONENT_NAME}.mocks.ts` file if complex
- Args table should have descriptions and default values for all props

Acceptance Criteria

Common Pitfalls

Using lorem ipsum instead of hotel context data — Mock data should reference real hotel concepts: “Deluxe River Suite”, “The Savoy Grill”, “Guerlain Spa Treatment” — not placeholder text.
Forgetting tags: ['autodocs'] — Without this, the component will not get an auto-generated docs page in Storybook.
Missing Figma link in parameters — The parameters.design field connects the story to the Figma source. Without it, designers cannot cross-reference.
Not testing all 8 themes — Each theme has different color palettes, fonts, and spacing. A story that looks correct in one theme may break in another.
Hardcoded viewport in stories — Do not set a fixed viewport. Let the theme decorator and Storybook viewport controls handle responsive testing.
Interaction tests without await — Every userEvent and expect call inside a play function must be awaited.
Importing from wrong path — Stories should import the component from the same package, not cross-package.
Missing args on stories — Every story should define args so that the Controls panel works and the story is self-documenting.

Example

Filled-in prompt for M10 Testimonials:

Read the following context files first:
- docs/dev-frontend-guides/04_STORYBOOK_FIRST_DEVELOPMENT.md
- docs/dev-frontend-guides/03_MODULE_DEVELOPMENT_LIFECYCLE.md
- apps/storybook/.storybook/main.ts
- apps/storybook/.storybook/preview.ts
- packages/themes/src/ (scan for all theme names)
- packages/modules/src/m04-page-hero/m04-page-hero.stories.tsx (use as pattern reference)

Now create comprehensive Storybook stories for the following component
using a Storybook-first development approach:

**Component Name:** Testimonials
**Package:** modules
**Module ID:** M10
**Component Path:** packages/modules/src/m10-testimonials/
**Figma Reference:** https://www.figma.com/design/abc123/Savoy-Design-System?node-id=2100-890

**Props Interface:**
- heading: string — Section heading (e.g., "Guest Experiences")
- testimonials: Testimonial[] — Array of testimonial objects:
  - quote: string — The guest's testimonial text
  - guestName: string — Name of the guest
  - guestTitle?: string — Optional title/location (e.g., "London, UK")
  - rating?: number — Optional star rating 1-5
  - imageDesktop?: ImageData — Optional guest portrait for desktop
  - imageMobile?: ImageData — Optional guest portrait for mobile
- layout?: 'carousel' | 'grid' — Display mode (default: 'carousel')
- showRatings?: boolean — Whether to display star ratings (default: true)

**Story Variants Needed:**
- Default — 4 testimonials with carousel layout, ratings visible
- Minimal — 1 testimonial, no optional props
- Empty — heading only, empty testimonials array
- LongContent — 12 testimonials with very long quotes (300+ chars)
- AllOptions — every prop filled, grid layout, all ratings, all images
- CarouselLayout — explicit carousel with 6 items
- GridLayout — grid layout with 3 items
- WithoutRatings — showRatings false, no rating data
- WithImages — all testimonials have guest portraits

**Theme Decorator:** Yes
**Needs Interaction Tests:** Yes

**Interaction Test Scenarios:**
- Click next/prev buttons on carousel to navigate between testimonials
- Swipe gesture advances to next testimonial on mobile
- Keyboard arrow keys navigate carousel
- Focus is visible on interactive carousel controls
- Grid layout has no interactive controls (static)

Create the stories file at:
packages/modules/src/m10-testimonials/Testimonials.stories.tsx

Follow these conventions:
- Use CSF3 (Component Story Format 3) with `satisfies Meta<typeof Testimonials>`
- Include `tags: ['autodocs']` in the meta for automatic documentation
- Add Figma link in `parameters.design` using the Figma addon format
- Use realistic mock data drawn from hotel context (real guest names, authentic-sounding quotes about hotel experiences)
- Each story must render correctly in all 8 themes via the theme switcher decorator
- Test all breakpoints: 375px (mobile), 768px (tablet), 1024px (small desktop), 1440px (full desktop)
- For the carousel, add `play` functions testing navigation via click, keyboard, and swipe
- Mock data should be exported from a separate `Testimonials.mocks.ts` file
- Args table should have descriptions and default values for all props