write-stories

name	write-stories
description	Write Storybook stories and MDX docs for BEEQ web components. Use for: adding or updating Storybook stories, writing MDX documentation pages, adding argTypes and controls for component props/events, creating story variants for all component states. Uses @storybook/web-components-vite and lit-html templates. Files live at packages/beeq/src/components/<name>/_storybook/.
argument-hint	Component name (e.g. "bq-button") or path to the component tsx file

Write BEEQ Storybook Stories

When to Use

• Adding stories for a new bq-* component
• Adding missing story variants for component states
• Updating stories after a component API change
• Writing or updating the MDX documentation page

File Locations

packages/beeq/src/components/<name>/_storybook/
├── bq-<name>.stories.tsx   # Story definitions
└── bq-<name>.mdx           # Documentation page

Stories File Structure

Always import from @storybook/web-components-vite (not @storybook/web-components):

import type { Args, Meta, StoryObj } from '@storybook/web-components-vite';
import { html, nothing } from 'lit-html';
import { unsafeHTML } from 'lit-html/directives/unsafe-html.js'; // only if dynamic HTML needed

import { isChromatic, skipSnapshotParameters } from '../../../../.storybook/chromatic-parameters';
import { BQ_COMPONENT_PROP_CONST } from '../bq-<name>.types';
import mdx from './bq-<name>.mdx';

const meta: Meta = {
  title: 'Components/<ComponentName>',
  component: 'bq-<name>',
  parameters: {
    docs: { page: mdx },
  },
  argTypes: {
    // @Prop() controls — use const arrays from types file for selects
    size: { control: 'select', options: [...BQ_COMPONENT_SIZE] },
    disabled: { control: 'boolean' },
    value: { control: 'text' },
    // @Event() actions
    bqChange: { action: 'bqChange' },
    bqFocus:  { action: 'bqFocus' },
    bqBlur:   { action: 'bqBlur' },
    // Slot / story-only controls (hide from docs table)
    slotContent: { control: 'text', table: { disable: true } },
  },
  args: {
    size: 'medium',
    disabled: false,
    value: undefined,
  },
};
export default meta;

type Story = StoryObj;

Template Pattern

Use lit-html tagged template literals. Handle boolean attributes with ?:

const Template = (args: Args) => html`
  <bq-<name>
    size=${args.size}
    ?disabled=${args.disabled}
    value=${args.value ?? nothing}
    @bqChange=${args.bqChange}
    @bqFocus=${args.bqFocus}
    @bqBlur=${args.bqBlur}
  >
    ${args.slotContent}
  </bq-<name>>
`;

export const Default: Story = {
  render: Template,
  args: {},
};

Required Story Variants

At minimum, provide stories for:

Story	Purpose
Default	Component in its default state
Disabled	disabled prop set
WithPrefix / WithSuffix	Slot usage where applicable
One story per primary variant/appearance	e.g. Primary, Secondary, Ghost

Chromatic / Snapshot Handling

For animated or stateful components, opt out of Chromatic snapshots:

import { skipSnapshotParameters } from '../../../../.storybook/chromatic-parameters';

export const WithAnimation: Story = {
  render: Template,
  parameters: { ...skipSnapshotParameters },
};

For loading states, guard against Chromatic environment:

const Template = (args: Args) => {
  const loading = isChromatic() ? false : args.loading;
  return html`<bq-button ?loading=${loading}>...</bq-button>`;
};

MDX Documentation Page

The .mdx file should import and use <Stories /> and <ArgTypes /> from @storybook/blocks. Reference the component's design documentation link if available from https://www.beeq.design/.

Running Storybook

# Run Storybook locally
pnpm start

# Build Storybook for production
pnpm build