Developing Vue Components

When to use this skill

Use this skill when you need to:

• Create new Vue 3 components from scratch
• Modify existing Vue components (template, logic, or styles)
• Define or update component props, emits, and TypeScript types
• Write or update component SCSS styles
• Document component APIs and usage
• Refactor components for better type safety or structure
• Review components for best practices compliance

Component File Structure

• compName.vue

  : Template and component logic , read more invue-guide.md

• compName.ts

  : Props, emits, types, constants (public API) read more in typescript-guide.md

• compName.scss

  : Component styles, read more in scss-guide.md

• compName.md

  : Component documentation, read more in documentation-guide.md

Instructions

Creating a New Component

Follow these steps to create a new Vue component:

1. Create component folder:

   compName/

2. Document the component (spec-first):

   • Create

     compName.story.md

     if using Histoire, otherwise create

     compName.md

   • Document intended props, emits, slots, and usage
   • Define component behavior and user interaction patterns
   • See documentation-guide.md for format

3. Define types and API (

   compName.ts

   ):
   • Define props interface with JSDoc comments
   • Define emits interface
   • Export types, constants, and utilities
   • See typescript-guide.md for patterns

4. Implement component logic (

   compName.vue

   ):
   • Import types from

     compName.ts

   • Use

     <script setup>

     with TypeScript
   • Implement component logic based on documented behavior
   • See vue-guide.md for structure

5. Build template and styling (

   compName.vue

   +

   compName.scss

   ):
   • Implement template structure in

     compName.vue

   • Style the component in

     compName.scss

     using BEM or scoped styles
   • Avoid magic values, use CSS variables
   • See scss-guide.md for guidelines

Modifying an Existing Component

1. Understand current state:

   • Read

     compName.md

     for component intent
   • Review existing implementation files

2. Make changes:

   • Update

     compName.ts

     if props/emits/types change
   • Update

     compName.vue

     for template or logic changes
   • Update

     compName.scss

     for styling changes
   • Consult reference docs as needed

3. Update documentation:

   • Update component documentation to reflect changes
   • Update tests if behavior changed (if tests exist)
   • Update stories if using Histoire (see vue-story skill)

4. Verify consistency:

   • Ensure all files are aligned
   • Check type safety (no

     any

     or

     unknown

     )
   • Verify tests pass (if tests exist)

Quality Checklist

Before completing work on any component, verify:

• Type-safe props and emits with JSDoc documentation
• Component documentation is current and accurate
• Styles follow project patterns (no magic values)
• No hard-coded strings (use i18n if available)
• Tests updated and passing (if tests exist)
• Stories updated (if using Histoire - see vue-story skill)
• Code follows naming conventions (camelCase for JS, kebab-case for CSS/events)
• Error handling with graceful degradation

Best Practices

Follow these principles for maintainable, high-quality components:

Architecture:

• Single Responsibility Principle - each component does one thing well
• High cohesion, low coupling - minimize dependencies
• Clear and consistent API design
• Avoid prop drilling - use provide/inject or composables for deep data
• Design for testability and maintainability

Naming:

• camelCase

  for component names, variables, functions, TypeScript interfaces

• kebab-case

  for CSS class names and event names
• Descriptive names that convey purpose

Type Safety:

• Always define props and emits interfaces
• Avoid

  any

  and

  unknown

  types
• Use JSDoc comments for props and emits
• Leverage TypeScript's inference when possible

Error Handling:

• Implement graceful degradation
• Provide user-friendly error messages
• Add appropriate console warnings/errors for developers
• Handle edge cases explicitly

---

Note:

• For detailed patterns and examples, consult the reference documentation in the

  references/

  directory.
• Starter templates are available in the

  assets/

  directory.