Vue Conventions

Vue Conventions

Component Structure

Always: <script setup lang="ts"> — no Options API, no class components, no mixins.

Props

// Library components (ui-vue): export interface for reuse
export interface BaseInputProps {
  modelValue: string | number;
  type?: "text" | "email" | "number";
  disabled?: boolean;
}
const props = withDefaults(defineProps<BaseInputProps>(), {
  type: "text",
});

// App components: local interface
interface Props {
  status: string;
  variant?: "solid" | "outline";
}
const props = withDefaults(defineProps<Props>(), {
  variant: "solid",
});

Emits

// Typed tuple syntax
const emit = defineEmits<{
  "update:modelValue": [value: string];
  focus: [];
}>();

// v-model via defineModel
const open = defineModel<boolean>("open", { required: true });

File Organization

Components high-level directory (atomic design)

• atoms/ → Base* prefix (BaseButton, BaseInput, BaseCard)
• molecules/ → Descriptive (FormControl, TabsGroup)
• organisms/ → Complex (DataTable)
• layouts/ → FlexLayout, ModalContainer, SlideOut

Domain high-level directory

• domain/​common/ → Shared
• domain/​{feature}/ → Feature-specific, ie: domain/​radar/

Other high-level directories

• composables/ → Feature hooks
• stores/ → Pinia
• services/ → API layer
• types/ → TypeScript definitions

Composables

Naming: use* prefix — useModal, useAirportAutocomplete

Return pattern: Object with refs, computed, methods

export const useAirportAutocomplete = () => {
  const results = ref<Airport[]>([])
  const loading = ref(false)
  const error = ref<string | null>(null)

  const search = async (term: string) => { ... }

  return { results, loading, error, search }
}

Options for complex composables:

interface UseModalSubmissionOptions<T, R> {
  defaultFormData: T;
  submitAction: (data: T) => Promise<R>;
  onSuccess?: (result: R) => void;
}

Pinia Stores

Options API style (not setup stores):

export const useSessionStore = defineStore('session', {
  state: (): SessionState => ({
    user: null,
    isLoading: false,
    error: null
  }),
  actions: {
    async checkSession() { ... },
  }
})

• Explicit state interfaces
• All API calls in actions
• URL as source of truth for query state

Styling

See conventions-css skill. Key points:

• <style scoped> for domain components, unscoped for atomic design components
• Design tokens via CSS custom properties exclusively
• No Tailwind, utility classes, or CSS-in-JS

Common Patterns

Loading/​error states:

<FlexLayout v-if="isLoading" align="center">
  <BaseIcon id="spinner" inline /> Loading...
</​FlexLayout>
<AlertMessage v-else-if="error" :message="error" type="error" />
<template v-else>
  <!-- Content -->
</​template>

Forms: FormControl molecule wrapping atoms

<FormControl v-model="formData.reason" :error="error" label="Reason" type="textarea" />

Modals: ModalContainer + useModalSubmission

<ModalContainer :is-open="open" title="Suspend" @close="open = false">
  <FormControl v-model="formData.reason" />
  <template #footer>
    <BaseButton :loading="isLoading" @click="submitForm">Submit</​BaseButton>
  </​template>
</​ModalContainer>

Layout: FlexLayout/​FlexItem, not raw flexbox

<FlexLayout direction="column" gap="xs">
  <FlexItem :span="6">Label</​FlexItem>
  <FlexItem :span="6">Value</​FlexItem>
</​FlexLayout>

TypeScript

• Strict mode
• type for object shapes (props, state)
• type for unions and aliases

Never Do

• Options API
• Mixins
• Global components (always explicit imports)
• Vuex
• Inline styles (except dynamic values)
• Magic strings for events
• CSS-in-JS or Tailwind