Writing Storybook Stories

• Copy the closest neighboring story instead of forcing one universal template.
• Most repo stories use @storybook/vue3-vite. Some stories under apps/desktop-ui still use @storybook/vue3; keep the local convention for that area.
• Add tags: ['autodocs'] unless the surrounding stories in that area intentionally omit it.
• Use ComponentPropsAndSlots<typeof Component> when it helps with prop and slot typing.
• Keep render functions stateful when needed. Use ref(), computed(), and toRefs(args) instead of mutating Storybook args directly.
• Use args.default or other slot-shaped args when the component content is provided through slots.
• Use ComponentExposed only when a component's exposed API breaks the normal Storybook typing.
• Add decorators for realistic width or background context when the component needs it.

Title Patterns

Do not invent titles from scratch when a close sibling story already exists. Match the nearest domain pattern.

If multiple patterns seem plausible, follow the closest sibling story in the same folder tree.

Common Story Shapes

Stateful input or v-model

export const Default: Story = {
  render: (args) => ({
    components: { MyComponent },
    setup() {
      const { disabled, size } = toRefs(args)
      const value = ref('Hello world')
      return { value, disabled, size }
    },
    template:
      '<MyComponent v-model="value" :disabled="disabled" :size="size" />'
  })
}

Slot-driven content

const meta: Meta<ComponentPropsAndSlots<typeof Button>> = {
  argTypes: {
    default: { control: 'text' }
  },
  args: {
    default: 'Button'
  }
}

export const SingleButton: Story = {
  render: (args) => ({
    components: { Button },
    setup() {
      return { args }
    },
    template: '<Button v-bind="args">{{ args.default }}</Button>'
  })
}

Variants or edge cases grid

export const AllVariants: Story = {
  render: () => ({
    components: { MyComponent },
    template: `
      <div class="grid gap-4 sm:grid-cols-2">
        <MyComponent />
        <MyComponent disabled />
        <MyComponent loading />
        <MyComponent invalid />
      </div>
    `
  })
}

Figma Mapping

• Extract the named states from the design first.
• Prefer explicit prop-driven stories such as Disabled, Loading, Invalid, WithPlaceholder, AllSizes, or EdgeCases.
• Add an aggregate story such as AllVariants, AllSizes, or EdgeCases when side-by-side comparison is useful.
• Use pseudo-state parameters only if the addon is already configured in this repo.
• If a Figma state cannot be represented exactly, capture the closest prop-driven version and explain the gap in the story docs.

Component-Specific Notes

• Widget components often need a minimal SimplifiedWidget object. Build it in setup() and use computed() when args change widget.options.
• Input and search components often need a width-constrained wrapper so they render at realistic sizes.
• Asset and platform cards often need background decorators such as bg-base-background and fixed-width containers.
• Desktop installer stories may need custom backgrounds parameters and may intentionally keep the older Storybook import style used by neighboring files.
• Use semantic tokens such as bg-base-background and bg-node-component-surface instead of dark: variants or hardcoded theme assumptions.

Checklist

• Read the component source and any supporting types or composables
• Match the nearest local title pattern and story style
• Include a baseline story; name it Default only when that matches nearby conventions
• Add focused stories for meaningful states
• Add tags: ['autodocs']
• Keep the story co-located with the component
• Run pnpm storybook
• Run pnpm typecheck
• Run pnpm lint

Avoid

• Do not guess props, emits, slots, or exposed methods.
• Do not force one generic title convention across the repo.
• Do not mutate Storybook args directly for v-model components.
• Do not introduce dark: Tailwind variants in story wrappers.
• Do not create barrel files.
• Do not assume every story needs layout: 'centered' or a Default export; follow the nearest existing pattern.