Vue 3 Modern Standards

Use Vue 3.5 features supported by the repository. Inspect package.json, nearby components, ESLint, Prettier, Stylelint, and project instructions before editing; treat them as authoritative when they are stricter than this skill.

Structure every SFC consistently

1. Order blocks as <template>, <script lang="ts" setup>, <style lang="scss" scoped>.
2. Omit an unused style block. Keep styles scoped unless a global style is explicitly required.
3. Use Composition API and <script setup> for new code. Do not add Options API, mixins, this, or a second <script> block when a compiler macro expresses the same behavior.
4. Use PascalCase component imports and tags. Follow the repository's existing file naming convention.

<template>
  <ResultPanel :userName :normalizedQuery @retry-request="handleRetryRequest" />
  <input ref="searchInput" v-model="query" />
</template>

<script lang="ts" setup>
import { computed, onMounted, ref, useTemplateRef } from "vue";

type SearchPanelProps = {
  userName: string;
};

const { userName } = defineProps<SearchPanelProps>();
const query = defineModel<string>({ required: true });
const searchInput = useTemplateRef<HTMLInputElement>("searchInput");
const pending = ref<boolean>(false);
const normalizedQuery = computed<string>(() => query.value.trim());

function handleRetryRequest(): void {
  pending.value = true;
}

onMounted(() => searchInput.value?.focus());
</script>

<style lang="scss" scoped>
.search-panel {
  display: grid;
}
</style>

Declare component contracts with compiler macros

• Declare props with defineProps<Props>(); use a type, not an interface, under this repository's TypeScript rules. Do not import compiler macros.
• On Vue 3.5, prefer reactive props destructuring with native defaults when only selected props are needed: const { title, pageSize = 20 } = defineProps<Props>(). The destructured bindings remain reactive inside the same <script setup> block.
• Keep const props = defineProps<Props>() when the whole read-only props object must be forwarded or inspected. Use props.foo in script, while templates may reference declared props directly.
• When watching a destructured prop, pass a getter: watch(() => pageSize, callback). Do not pass its current primitive value as the source.
• Declare emits with typed named tuples, for example defineEmits<{ saveSuccess: [recordId: number]; close: [] }>().
• Declare typed slots with defineSlots<{ default(props: SlotProps): unknown }>() when slot props form a public contract. Prefer it to useSlots() for TypeScript-based slot declarations.
• Use defineOptions() for inheritAttrs, component names, or custom options. Use defineExpose() only for the smallest parent-facing imperative API; <script setup> components are closed by default.
• Use <script lang="ts" setup generic="T extends ..."> for truly reusable generic components instead of weakening types with unknown or any.

Use modern model APIs correctly

• In an SFC using <script setup>, prefer defineModel<T>() over manually pairing modelValue with update:modelValue, or building a writable computed() proxy.
• Use named models for multiple bindings: defineModel<string>("firstName", { required: true }), consumed as v-model:firstName by the parent.
• Specify value and modifier types when modifiers are supported: defineModel<string, "trim" | "uppercase">().
• Prefer { required: true } when the parent must own the value. Be cautious with model defaults: a child default can desynchronize from an omitted, undefined parent ref.
• Use the runtime useModel(props, key) helper only in non-SFC components or raw setup() implementations. useModel() is the lower-level helper behind defineModel() and requires explicit props and emits declarations.

Type reactivity explicitly

• Write explicit generic contracts for component state and derived business values: ref<T>(), shallowRef<T>(), and computed<T>(). Include null or undefined in the type when it is a real lifecycle state.
• Type writable computed values with computed<T>({ get, set }).
• Let reactive() infer from its initializer. Do not pass reactive<T>(): Vue's deep ref-unwrapped return type can differ from T. Add a variable annotation only when a wider contract is needed.
• Do not destructure ordinary reactive objects because that disconnects primitive properties from reactivity. Use toRef() / toRefs() when independent refs are required. Vue 3.5 reactive props destructuring is the compiler- supported exception.
• Type native DOM event parameters, such as function handleInput(event: Event): void, and narrow event.target before reading element-specific fields.
• Use import type for types. Preserve precise unions and avoid any, non-null assertions, and type assertions when narrowing or a generic can express the contract.

Prefer useTemplateRef() for template refs

• Use useTemplateRef<T>("key") with a matching ref="key"; do not create template element refs with ref<T | null>(null) and name matching.
• Type DOM refs with the exact element type, such as HTMLInputElement. For component refs use InstanceType<typeof ChildComponent> when inference is insufficient, or ComponentPublicInstance when only common instance members are needed.
• Access a template ref only after mount and account for null, including unmounts caused by v-if.
• Prefer declarative rendering to direct DOM mutation. Use a template ref only for focus, measurement, integration with imperative libraries, or a deliberately exposed child method.

Keep naming consistent across script and template

• Declare multi-word props, models, variables, and event identifiers in camelCase: userName, modelValue, saveSuccess.
• Bind multi-word component props and named model arguments in SFC templates with the same camelCase spelling as their declarations: :userName, :modelValue, v-model:firstName. Do not convert them to kebab-case.
• Listen to multi-word component events in templates with kebab-case: @save-success. Use PascalCase for component tags.
• Prefer : and @ directive shorthands. When a bound prop/attribute and its in-scope value have the same name, use Vue 3.4+ same-name shorthand:

<!-- Avoid -->
<UserCard :userName="props.userName" :loading="loading" />

<!-- Prefer; declared props are directly visible to the template -->
<UserCard :userName :loading />

• Keep an explicit expression when names differ, a transformation is required, or the value is not directly in template scope: :userName="owner.displayName".
• Use method handlers for non-trivial behavior: @save-success="handleSaveSuccess". Keep inline handlers limited to short assignments or direct calls.

Apply modern reactivity and rendering patterns

• Use computed() for pure derived state and watch() / watchEffect() only for side effects.
• Register cleanup for stale async watcher work. On Vue 3.5, call onWatcherCleanup() synchronously before any await; otherwise use the callback-provided onCleanup function.
• Create watchers synchronously during setup so Vue stops them automatically. If a watcher must be created later, retain and call its stop handle.
• In composables that accept values, refs, or getters, use MaybeRefOrGetter<T> with toValue() at the tracking point instead of manually branching on input kinds.
• Use useId() for SSR-stable, per-application form and accessibility IDs. Call it during setup, not inside a computed() getter.
• Treat props as read-only. Request changes with an emit or model instead of mutating nested parent state.
• Use a stable domain key for v-for; do not use an array index when list identity can change. Do not put v-if and v-for on the same element; filter through computed() or move the condition to a wrapper.
• Choose v-show for frequently toggled content and v-if for lazy or infrequent branches.
• Avoid legacy .sync, filters, event buses, $refs, Reactivity Transform macros, and broad getCurrentInstance() access. Modernize them only within the requested scope.

Validate the result

1. Run pnpm lint-vue for Vue and TypeScript type safety.
2. Run pnpm lint:code for script and template conventions.
3. Run pnpm lint:style when Vue styles changed.
4. Inspect the final diff and preserve unrelated user changes.

Official references

• Script setup and compiler macros
• Composition API helpers
• TypeScript with Composition API
• Template refs
• Component v-model
• Props naming and passing
• Component events
• Watchers and cleanup