Vue Story Development Skill

Vue Story Development

Create and maintain Histoire stories for Vue 3 components, focusing on visual and behavioral contracts rather than parameter demonstrations.

Prerequisites

Histoire for visual stories
Vue 3 with <script setup> syntax
TypeScript
Existing Vue component to create stories for

Story File

Each component can optionally have a compName.story.vue file that contains Histoire stories.

Requirements:

Component must have compName.story.md documentation file (not just compName.md)
Stories are optional but recommended for visual regression prevention
Follow the Story Guide for best practices

Core Principle

A Story represents ONE of the following:

Canonical semantic state - A stable, long-term design commitment
State transition boundary - Critical boundaries between internal states
Edge case likely to regress - Scenarios most likely to break
Design-forbidden state - Invalid states that must not be relied upon

Stories must be readable without explanatory text. If a Story needs explanation, it likely belongs in the documentation instead.

Story Categories

Canonical (Required)

Stable, long-term design commitments.

<Story title="Primary Button" :layout="{ type: 'single' }">
  <InkButton text="Save Changes" variant="primary" />
</Story>

State (Recommended)

Critical boundaries between internal states.

<Story title="Loading State">
  <InkButton text="Saving..." :loading="true" />
</Story>

Edge (Recommended)

Scenarios most likely to break layout or behavior.

<Story title="Long Text Wrapping">
  <InkButton text="This is a very long button text that should wrap properly" />
</Story>

Invalid (Optional)

States that must not be relied upon.

<Story title="❌ Both Loading and Disabled (Undefined)">
  <InkButton text="Invalid" :loading="true" :disabled="true" />
</Story>

What Stories Are NOT

❌ NOT for exhaustive prop combinations ❌ NOT a playground or sandbox ❌ NOT for replacing documentation

✅ YES for semantic state contracts

Development Workflow

Creating Stories for a Component

Ensure component has compName.story.md (not just compName.md)
Create compName.story.vue in the component folder
Import the component
Create at least one canonical story
Add state and edge stories as needed
Verify stories are readable without explanation

Story Template

<script setup lang="ts">
import { CompName } from './compName';
</script>

<template>
  <Story
    group="canonical"
    title="Primary State"
    :layout="{ type: 'single', width: '200px' }"
  >
    <CompName prop="value" />
  </Story>

  <Story group="state" title="Loading State">
    <CompName :loading="true" />
  </Story>

  <Story group="edge" title="Edge Case">
    <CompName extreme="scenario" />
  </Story>
</template>

Best Practices

Story Creation:

Focus on semantic states, not prop variations
Use clear, descriptive titles
Group related stories with the group attribute
Keep stories simple and self-explanatory

Layout:

Use appropriate Histoire layout options
Consider container constraints for edge cases
Test dark mode/theme variations when relevant

Quality:

Stories represent meaningful states
No exhaustive prop combinations
All critical states are covered
Stories are stable over time

Minimal Checklist

Before committing a *.story.vue:

[ ] At least one canonical variant exists
[ ] At least one state or edge variant exists
[ ] No exhaustive prop combinations are present
[ ] All Story titles communicate semantic intent
[ ] Stories are readable without needing explanation

Success Criteria

A well-implemented story file has:

✅ Clear category grouping (canonical, state, edge)
✅ Semantic, descriptive titles
✅ Coverage of critical states and boundaries
✅ No exhaustive prop matrices
✅ Stories that are self-explanatory
✅ Focused on long-term semantic contracts
❌ No redundant similar stories
❌ No stories that just demonstrate parameters
❌ No stories requiring extensive explanation

Related Skills

vue-component-development - Main Vue component development skill

References

Story Guide - Comprehensive guide to creating stories
Histoire Documentation

Agent Skills: Vue Story Development

Install this agent skill to your local

Skill Files