diff --git a/CLAUDE.md b/CLAUDE.md
index 837d01e0..f679d0be 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -80,6 +80,36 @@ Configure three frontend origins in both Laravel (`config/cors.php` via env) and
 
 ## Frontend rules (strict)
 
+### Vuexy-first strategy
+
+Before writing ANY frontend component, consult `/dev-docs/VUEXY_COMPONENTS.md` and follow this decision tree:
+
+1. **Can a standard Vuetify component do this?** → Use it with default props.
+   Do not wrap it in a custom component.
+2. **Does Vuexy provide an @core component for this?** → Use it. Check
+   `/dev-docs/VUEXY_COMPONENTS.md` section 1 for the full registry.
+3. **Does an existing Crewli page already solve a similar UI pattern?** →
+   Copy that pattern exactly. Check `/dev-docs/VUEXY_COMPONENTS.md` section 3
+   for established patterns and their reference implementations.
+4. **None of the above?** → Only then write custom code. Add `<style scoped>`
+   with a comment explaining why Vuexy/Vuetify couldn't handle it.
+
+Concrete component rules:
+- Tables: `v-data-table-server` with server-side pagination — never client-side for API data
+- Cards: `v-card` directly, or `AppCardActions` when collapse/refresh/remove is needed
+- Forms in dialogs: `v-dialog` + `v-card` + `v-form` — follow the established dialog pattern
+- Detail panels: `v-navigation-drawer` with `temporary` and `location="end"` — follow ShiftDetailPanel pattern
+- Date/time pickers: `AppDateTimePicker` from @core — never raw input[type=date]
+- Status indicators: `v-chip` with color prop — never custom styled spans
+- Loading states: `v-skeleton-loader` — never custom spinners
+- Error states: `v-alert` with retry button — never custom error divs
+- Empty states: `v-card` with icon + message + action button
+- Notifications: `v-snackbar` — never custom toast components
+- Page layout: `v-row` + `v-col` with Vuetify breakpoint props — never CSS grid or custom flexbox
+
+**Before ANY frontend task:** read `/dev-docs/VUEXY_COMPONENTS.md` to verify
+you are using available components rather than building custom ones.
+
 ### Vue components
 
 - Always `<script setup lang="ts">` — never the Options API