# Vue 3 — Claude Code rules

You are working in a Vue 3 codebase using the Composition API with `<script setup>`
Single-File Components. Follow the official Vue Style Guide conventions below.

## Components

- Component names are **multi-word** (`TodoItem`, not `Item`) — the only exception is the root `App`. This avoids clashing with current and future HTML elements.
- One component per file when a build system is available.
- Filenames are either **always PascalCase** (`TodoItem.vue`) or always kebab-case (`todo-item.vue`) — pick one and never mix.
- In SFC and string templates, reference components in **PascalCase** (`<TodoItem/>`); in JS/JSX, component names are always PascalCase.
- Components with no content are **self-closing** in SFCs (`<TodoItem/>`, not `<TodoItem></TodoItem>`).
- Prefer **full words** over abbreviations (`UserProfileOptions`, not `UProfOpts`).
- Name from most-general to most-specific (`SearchButtonClear`, not `ClearSearchButton`), and prefix tightly-coupled children with the parent (`TodoListItem`).
- Base/presentational components start with `Base`, `App`, or `V` (`BaseButton`, `VIcon`).

## Props

- Always write **detailed prop definitions** — at minimum the type. Never use the bare-array form. This documents the API and lets Vue warn on bad input in dev.
- Declare prop names in **camelCase** (`greetingText`). In SFC templates either casing is acceptable, but stay consistent across the project.

## Templates

- `v-for` always carries a `:key` — required on components, expected on elements.
- **Never** put `v-if` and `v-for` on the same element. Filter with a computed property, or move `v-if` to a wrapper / inner element.
- Keep template expressions **simple** — push anything non-trivial into a computed property or method.
- Quote all non-empty attribute values.
- Spread elements with multiple attributes over multiple lines, one attribute per line.
- Use directive shorthands (`:`, `@`, `#`) **always or never** — be consistent across the project.

## Reactivity & computed

- Split complex computed properties into smaller, single-purpose ones (`basePrice`, `discount`, `finalPrice` rather than one mega `price`).
- For large, effectively-immutable data structures, reach for `shallowRef()` / `shallowReactive()` to skip deep-reactivity overhead.

## Styling

- All component styles are **scoped** (`<style scoped>`, CSS Modules, or a BEM/class strategy). Only top-level `App` and layout components may use global styles.

## Performance

- Keep props passed to children **stable** to avoid needless re-renders.
- Use `v-once` for content that renders once and never updates; use `v-memo` to skip updates of large sub-trees or `v-for` lists.
- Virtualize very large lists instead of rendering every row.
- In hot lists (100+ items), avoid extra renderless / HOC abstractions — component instances cost far more than plain DOM nodes.

## Don't

- Don't use single-word user component names.
- Don't combine `v-if` and `v-for` on one element.
- Don't omit `:key` on `v-for`.
- Don't declare props without a type.
- Don't leave non-App component styles global.
- Don't bury complex logic inside template expressions.