ProjectAGiPrompt/1-AgentSkills/coding-vue3-vuetify/SKILL.md

name, description

name	description
coding-vue3-vuetify	Build production-grade Vue 3 + TypeScript + Vuetify 3 interfaces with architectural rigor. Use when creating Vue components, pages, layouts, Pinia stores, or API modules. Enforces strict typing, Composition API patterns, Material Design 3 aesthetics, and bulletproof data handling.

This skill crafts Vue 3 + Vuetify 3 code that is architecturally sound, type-safe to the bone, and visually polished. Every component should feel like it belongs in a production codebase that senior engineers would be proud to maintain.

The user provides: $ARGUMENTS (component specs, page requirements, feature requests, or architectural questions).

Architectural Thinking

Before writing a single line, establish clarity:

• Component Identity: Is this a Page, Layout, Reusable Component, Composable, Store, or API Module? Each has distinct patterns.
• Data Gravity: Where does state live? Props flow down, events bubble up. Pinia for cross-component state. provide/inject for deep hierarchies.
• Scroll Strategy: Which container owns the scroll? Never the body. Always explicit. Always controlled.
• Failure Modes: What happens when data is null? Empty array? Network timeout? Design for the unhappy path first.

CRITICAL: Production code anticipates chaos. Type everything. Guard everything. Gracefully degrade everything.

Core Dogma

TypeScript Absolutism

• <script setup lang="ts"> — the ONLY acceptable incantation
• any is forbidden — use unknown + type guards, generics, utility types
• Every prop, emit, ref, and API response wears its type proudly
• Types live in @/types/, organized by domain: user.d.ts, order.d.ts

Composition API Purity

• ref, reactive, computed, watchEffect — master these four
• shallowRef, readonly, toRaw — know when to reach for optimization
• Lifecycle via onMounted, onUnmounted — never mix Options API
• Pinia stores: typed state, typed getters, typed actions — no exceptions

Vuetify 3 + Material Design 3

• ALL UI through Vuetify components — no raw HTML for UI elements
• Theme-aware always — rgb(var(--v-theme-surface)), never #ffffff
• useDisplay() for responsive logic — breakpoints are first-class citizens
• Density matters — density="compact" for data-heavy interfaces

Layout Philosophy

┌─────────────────────────────────┐
│  Toolbar (flex-shrink-0)        │
├─────────────────────────────────┤
│                                 │
│  Content Area                   │
│  (flex-grow-1, overflow-y-auto) │
│  (min-height: 0) ← CRITICAL     │
│                                 │
├─────────────────────────────────┤
│  Footer (flex-shrink-0)         │
└─────────────────────────────────┘

• No body scroll — viewport locked, content scrolls in containers
• Flexbox trap: flex-grow-1 children MUST have min-height: 0
• Sticky elements: filters, table headers — always visible during scroll

Data Robustness Patterns

Treat all external data as hostile:

// Defensive access
const userName = user?.profile?.name ?? 'Unknown'

// Array safety
const items = Array.isArray(response.data) ? response.data : []

// Existence guards in templates
<template v-if="user">{{ user.name }}</template>
<v-empty-state v-else />

UI State Trinity

Every data-driven view handles THREE states:

State	Component	Never Do
Loading	v-skeleton-loader	Show stale data or blank screen
Empty	v-empty-state with action	Leave white void
Error	Snackbar + retry option	Silent failure

Table & List Commandments

• fixed-header on every v-data-table — non-negotiable
• Truncated text gets v-tooltip — users deserve full content on hover
• 100+ items? v-virtual-scroll — DOM nodes stay constant
• Column widths explicit — no layout lottery

Anti-Patterns (NEVER)

• .js files in a TypeScript project
• any without a blood oath and written justification
• Hardcoded colors: color="#1976d2" → color="primary"
• Body-level scrolling in SPA layouts
• Tables without fixed headers
• Truncated text without tooltips
• Empty states that are literally empty
• Loading states that freeze the UI
• API calls without error handling

Reference Files

Consult these for implementation details:

Need	Read
Advanced TypeScript patterns	reference/typescript-rules.md
Complex layout structures	reference/layout-patterns.md
API client architecture	reference/api-patterns.md
Tables, lists, forms, feedback	reference/ui-interaction.md

Project Anatomy

src/
├── api/          # Axios instance + modules
├── components/   # Shared components
├── composables/  # Reusable hooks
├── layouts/      # Page shells
├── pages/        # Route views
├── plugins/      # Vuetify, Pinia, Router
├── store/        # Pinia stores
├── styles/       # Global SCSS
├── types/        # Type definitions
└── utils/        # Pure functions

Output Protocol

1. State the architectural approach (2-3 sentences)
2. List files to create with their purposes
3. Implement each file completely — no placeholders, no TODOs
4. Verify against the anti-patterns list
5. Call out any assumptions or trade-offs made

---

Remember: You're not writing code that works. You're writing code that works, scales, maintains, and delights. Every ref is typed. Every edge case is handled. Every loading state is beautiful. This is what production-grade means.