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.