Vue Component Architect

When to use this skill

• User asks to create a new Vue component
• User wants component scaffolding with tests and stories
• User mentions Nuxt component creation
• User asks for TypeScript props definitions
• User wants CSS modules or scoped styles setup

Workflow

• [ ] Determine component name and location
• [ ] Detect project conventions (Nuxt vs Vue, styling approach)
• [ ] Generate component file with Composition API
• [ ] Create CSS module or scoped styles
• [ ] Generate Vitest test file
• [ ] Create Storybook story
• [ ] Export from index if barrel pattern used

Instructions

Step 1: Determine Component Details

Gather from user:

• Component name (PascalCase)
• Location: src/components/, components/, or feature folder
• Type: presentational, container, layout, or page component

Derive file paths:

src/components/Button/
├── Button.vue
├── Button.test.ts
├── Button.stories.ts
└── index.ts

Step 2: Detect Project Conventions

Vue vs Nuxt:

ls nuxt.config.* 2>/dev/null && echo "Nuxt project"
ls vite.config.* vue.config.* 2>/dev/null && echo "Vue project"

Styling approach:

grep -l "module.css\|module.scss" src/**/*.vue 2>/dev/null | head -1 && echo "CSS Modules"
grep -l "<style scoped" src/**/*.vue 2>/dev/null | head -1 && echo "Scoped styles"
npm ls tailwindcss 2>/dev/null && echo "Tailwind CSS"

State management:

npm ls pinia vuex 2>/dev/null

Test framework:

npm ls vitest @vue/test-utils 2>/dev/null

Step 3: Generate Component File

Use the standard Composition API structure:

• <script setup lang="ts"> with typed props and emits
• withDefaults(defineProps<Props>(), { ... }) for defaults
• defineEmits<{ event: [payload] }>() for typed events
• <style module> with design tokens

See component-templates.md for full templates including:

• Standard component with variants
• Component with composables
• Pinia store integration

Step 4: Generate Test File

Use Vitest with Vue Test Utils:

import { describe, it, expect } from "vitest";
import { mount } from "@vue/test-utils";
import ComponentName from "./ComponentName.vue";

describe("ComponentName", () => {
  it("renders slot content", () => {
    const wrapper = mount(ComponentName, {
      slots: { default: "Hello" },
    });
    expect(wrapper.text()).toContain("Hello");
  });

  it("emits click when not disabled", async () => {
    const wrapper = mount(ComponentName);
    await wrapper.trigger("click");
    expect(wrapper.emitted("click")).toHaveLength(1);
  });
});

See testing.md for more patterns including Pinia testing and async components.

Step 5: Create Storybook Story

Use CSF3 format for Storybook 7+:

import type { Meta, StoryObj } from "@storybook/vue3";
import ComponentName from "./ComponentName.vue";

const meta: Meta<typeof ComponentName> = {
  title: "Components/ComponentName",
  component: ComponentName,
  tags: ["autodocs"],
  argTypes: {
    variant: { control: "select", options: ["primary", "secondary"] },
  },
};

export default meta;
type Story = StoryObj<typeof meta>;

export const Primary: Story = {
  args: { label: "Primary Button", variant: "primary" },
};

See storybook.md for slot stories, decorators, and interactions.

Step 6: Create Barrel Export

index.ts:

export { default as ComponentName } from "./ComponentName.vue";

Common Patterns

v-model support (Vue 3.4+):

<script setup lang="ts">
  const modelValue = defineModel<string>({ default: "" });
</script>

Expose methods:

<script setup lang="ts">
  const focus = () => inputRef.value?.focus();
  defineExpose({ focus });
</script>

Provide/Inject:

// Parent
provide("state", reactive({ active: 0 }));

// Child
const state = inject<{ active: number }>("state");

See advanced-patterns.md for compound components, generics, and Nuxt patterns.

Validation

Before completing:

• [ ] Component renders without errors
• [ ] TypeScript has no errors
• [ ] Props interface uses defineProps with types
• [ ] Emits are properly typed
• [ ] Tests pass
• [ ] Story renders in Storybook

Error Handling

• Module not found: Check import paths and file extensions (.vue).
• CSS module not applying: Ensure using $style in template and <style module>.
• Test setup missing: Install @vue/test-utils and configure Vitest for Vue.
• Storybook not rendering: Check .storybook/main.js uses @storybook/vue3.
• Pinia not available in tests: Call setActivePinia(createPinia()) in beforeEach.
• Unsure about conventions: Check existing components in project for patterns.

Resources

• Vue 3 Documentation
• Vue Test Utils
• Storybook for Vue
• Pinia Documentation

Examples

• Component Templates — Full component code examples
• Testing — Vitest patterns and Pinia testing
• Storybook — Story formats and interactions
• Advanced Patterns — Generics, Suspense, Nuxt