---
trigger: glob
glob: app/*.vue
---

| No | Category | Guideline | Description | Do | Don't | Code Good | Code Bad | Severity | Docs URL |
|----|----------|-----------|-------------|----|-------|-----------|----------|----------|----------|
| 1 | Installation | Add Nuxt UI module | Install and configure Nuxt UI in your Nuxt project | pnpm add @nuxt/ui and add to modules | Manual component imports | modules: ['@nuxt/ui'] | import { UButton } from '@nuxt/ui' | High | https://ui.nuxt.com/docs/getting-started/installation/nuxt |
| 2 | Installation | Import Tailwind and Nuxt UI CSS | Required CSS imports in main.css file | @import tailwindcss and @import @nuxt/ui | Skip CSS imports | @import "tailwindcss"; @import "@nuxt/ui"; | No CSS imports | High | https://ui.nuxt.com/docs/getting-started/installation/nuxt |
| 3 | Installation | Wrap app with UApp component | UApp provides global configs for Toast Tooltip and overlays | <UApp> wrapper in app.vue | Skip UApp wrapper | <UApp><NuxtPage/></UApp> | <NuxtPage/> without wrapper | High | https://ui.nuxt.com/docs/components/app |
| 4 | Components | Use U prefix for components | All Nuxt UI components use U prefix by default | UButton UInput UModal | Button Input Modal | <UButton>Click</UButton> | <Button>Click</Button> | Medium | https://ui.nuxt.com/docs/getting-started/installation/nuxt |
| 5 | Components | Use semantic color props | Use semantic colors like primary secondary error | color="primary" color="error" | Hardcoded colors | <UButton color="primary"> | <UButton class="bg-green-500"> | Medium | https://ui.nuxt.com/docs/getting-started/theme/design-system |
| 6 | Components | Use variant prop for styling | Nuxt UI provides solid outline soft subtle ghost link variants | variant="soft" variant="outline" | Custom button classes | <UButton variant="soft"> | <UButton class="border bg-transparent"> | Medium | https://ui.nuxt.com/docs/components/button |
| 7 | Components | Use size prop consistently | Components support xs sm md lg xl sizes | size="sm" size="lg" | Arbitrary sizing classes | <UButton size="lg"> | <UButton class="text-xl px-6"> | Low | https://ui.nuxt.com/docs/components/button |
| 8 | Icons | Use icon prop with Iconify format | Nuxt UI supports Iconify icons via icon prop | icon="lucide:home" icon="heroicons:user" | i-lucide-home format | <UButton icon="lucide:home"> | <UButton icon="i-lucide-home"> | Medium | https://ui.nuxt.com/docs/getting-started/integrations/icons/nuxt |
| 9 | Icons | Use leadingIcon and trailingIcon | Position icons with dedicated props for clarity | leadingIcon="lucide:plus" trailingIcon="lucide:arrow-right" | Manual icon positioning | <UButton leadingIcon="lucide:plus"> | <UButton><Icon name="lucide:plus"/>Add</UButton> | Low | https://ui.nuxt.com/docs/components/button |
| 10 | Theming | Configure colors in app.config.ts | Runtime color configuration without restart | ui.colors.primary in app.config.ts | Hardcoded colors in components | defineAppConfig({ ui: { colors: { primary: 'blue' } } }) | <UButton class="bg-blue-500"> | High | https://ui.nuxt.com/docs/getting-started/theme/design-system |
| 11 | Theming | Use @theme directive for custom colors | Define design tokens in CSS with Tailwind @theme | @theme { --color-brand-500: #xxx } | Inline color definitions | @theme { --color-brand-500: #ef4444; } | :style="{ color: '#ef4444' }" | Medium | https://ui.nuxt.com/docs/getting-started/theme/design-system |
| 12 | Theming | Extend semantic colors in nuxt.config | Register new colors like tertiary in theme.colors | theme.colors array in ui config | Use undefined colors | ui: { theme: { colors: ['primary', 'tertiary'] } } | <UButton color="tertiary"> without config | Medium | https://ui.nuxt.com/docs/getting-started/theme/design-system |
| 13 | Forms | Use UForm with schema validation | UForm supports Zod Yup Joi Valibot schemas | :schema prop with validation schema | Manual form validation | <UForm :schema="schema" :state="state"> | Manual @blur validation | High | https://ui.nuxt.com/docs/components/form |
| 14 | Forms | Use UFormField for field wrapper | Provides label error message and validation display | UFormField with name prop | Manual error handling | <UFormField name="email" label="Email"> | <div><label>Email</label><UInput/><span>error</span></div> | Medium | https://ui.nuxt.com/docs/components/form-field |
| 15 | Forms | Handle form submit with @submit | UForm emits submit event with validated data | @submit handler on UForm | @click on submit button | <UForm @submit="onSubmit"> | <UButton @click="onSubmit"> | Medium | https://ui.nuxt.com/docs/components/form |
| 16 | Forms | Use validateOn prop for validation timing | Control when validation triggers (blur change input) | validateOn="['blur']" for performance | Always validate on input | <UForm :validateOn="['blur', 'change']"> | <UForm> (validates on every keystroke) | Low | https://ui.nuxt.com/docs/components/form |
| 17 | Overlays | Use v-model:open for overlay control | Modal Slideover Drawer use v-model:open | v-model:open for controlled state | Manual show/hide logic | <UModal v-model:open="isOpen"> | <UModal v-if="isOpen"> | Medium | https://ui.nuxt.com/docs/components/modal |
| 18 | Overlays | Use useOverlay composable for programmatic overlays | Open overlays programmatically without template refs | useOverlay().open(MyModal) | Template ref and manual control | const overlay = useOverlay(); overlay.open(MyModal, { props }) | const modal = ref(); modal.value.open() | Medium | https://ui.nuxt.com/docs/components/modal |
| 19 | Overlays | Use title and description props | Built-in header support for overlays | title="Confirm" description="Are you sure?" | Manual header content | <UModal title="Confirm" description="Are you sure?"> | <UModal><template #header><h2>Confirm</h2></template> | Low | https://ui.nuxt.com/docs/components/modal |
| 20 | Dashboard | Use UDashboardSidebar for navigation | Provides collapsible resizable sidebar with mobile support | UDashboardSidebar with header default footer slots | Custom sidebar implementation | <UDashboardSidebar><template #header>...</template></UDashboardSidebar> | <aside class="w-64 border-r"> | Medium | https://ui.nuxt.com/docs/components/dashboard-sidebar |
| 21 | Dashboard | Use UDashboardGroup for layout | Wraps dashboard components with sidebar state management | UDashboardGroup > UDashboardSidebar + UDashboardPanel | Manual layout flex containers | <UDashboardGroup><UDashboardSidebar/><UDashboardPanel/></UDashboardGroup> | <div class="flex"><aside/><main/></div> | Medium | https://ui.nuxt.com/docs/components/dashboard-group |
| 22 | Dashboard | Use UDashboardNavbar for top navigation | Responsive navbar with mobile menu support | UDashboardNavbar in dashboard layout | Custom navbar implementation | <UDashboardNavbar :links="navLinks"/> | <nav class="border-b"> | Low | https://ui.nuxt.com/docs/components/dashboard-navbar |
| 23 | Tables | Use UTable with data and columns props | Powered by TanStack Table with built-in features | :data and :columns props | Manual table markup | <UTable :data="users" :columns="columns"/> | <table><tr v-for="user in users"> | High | https://ui.nuxt.com/docs/components/table |
| 24 | Tables | Define columns with accessorKey | Column definitions use accessorKey for data binding | accessorKey: 'email' in column def | String column names only | { accessorKey: 'email', header: 'Email' } | ['name', 'email'] | Medium | https://ui.nuxt.com/docs/components/table |
| 25 | Tables | Use cell slot for custom rendering | Customize cell content with scoped slots | #cell-columnName slot | Override entire table | <template #cell-status="{ row }"> | Manual column render function | Medium | https://ui.nuxt.com/docs/components/table |
| 26 | Tables | Enable sorting with sortable column option | Add sortable: true to column definition | sortable: true in column | Manual sort implementation | { accessorKey: 'name', sortable: true } | @click="sortBy('name')" | Low | https://ui.nuxt.com/docs/components/table |
| 27 | Navigation | Use UNavigationMenu for nav links | Horizontal or vertical navigation with dropdown support | UNavigationMenu with items array | Manual nav with v-for | <UNavigationMenu :items="navItems"/> | <nav><a v-for="item in items"> | Medium | https://ui.nuxt.com/docs/components/navigation-menu |
| 28 | Navigation | Use UBreadcrumb for page hierarchy | Automatic breadcrumb with NuxtLink support | :items array with label and to | Manual breadcrumb links | <UBreadcrumb :items="breadcrumbs"/> | <nav><span v-for="crumb in crumbs"> | Low | https://ui.nuxt.com/docs/components/breadcrumb |
| 29 | Navigation | Use UTabs for tabbed content | Tab navigation with content panels | UTabs with items containing slot content | Manual tab state | <UTabs :items="tabs"/> | <div><button @click="tab=1"> | Medium | https://ui.nuxt.com/docs/components/tabs |
| 30 | Feedback | Use useToast for notifications | Composable for toast notifications | useToast().add({ title description }) | Alert components for toasts | const toast = useToast(); toast.add({ title: 'Saved' }) | <UAlert v-if="showSuccess"> | High | https://ui.nuxt.com/docs/components/toast |
| 31 | Feedback | Use UAlert for inline messages | Static alert messages with icon and actions | UAlert with title description color | Toast for static messages | <UAlert title="Warning" color="warning"/> | useToast for inline alerts | Medium | https://ui.nuxt.com/docs/components/alert |
| 32 | Feedback | Use USkeleton for loading states | Placeholder content during data loading | USkeleton with appropriate size | Spinner for content loading | <USkeleton class="h-4 w-32"/> | <UIcon name="lucide:loader" class="animate-spin"/> | Low | https://ui.nuxt.com/docs/components/skeleton |
| 33 | Color Mode | Use UColorModeButton for theme toggle | Built-in light/dark mode toggle button | UColorModeButton component | Manual color mode logic | <UColorModeButton/> | <button @click="toggleColorMode"> | Low | https://ui.nuxt.com/docs/components/color-mode-button |
| 34 | Color Mode | Use UColorModeSelect for theme picker | Dropdown to select system light or dark mode | UColorModeSelect component | Custom select for theme | <UColorModeSelect/> | <USelect v-model="colorMode" :items="modes"/> | Low | https://ui.nuxt.com/docs/components/color-mode-select |
| 35 | Customization | Use ui prop for component styling | Override component styles via ui prop | ui prop with slot class overrides | Global CSS overrides | <UButton :ui="{ base: 'rounded-full' }"/> | <UButton class="!rounded-full"/> | Medium | https://ui.nuxt.com/docs/getting-started/theme/components |
| 36 | Customization | Configure default variants in nuxt.config | Set default color and size for all components | theme.defaultVariants in ui config | Repeat props on every component | ui: { theme: { defaultVariants: { color: 'neutral' } } } | <UButton color="neutral"> everywhere | Medium | https://ui.nuxt.com/docs/getting-started/installation/nuxt |
| 37 | Customization | Use app.config.ts for theme overrides | Runtime theme customization | defineAppConfig with ui key | nuxt.config for runtime values | defineAppConfig({ ui: { button: { defaultVariants: { size: 'sm' } } } }) | nuxt.config ui.button.size: 'sm' | Medium | https://ui.nuxt.com/docs/getting-started/theme/components |
| 38 | Performance | Enable component detection | Tree-shake unused component CSS | experimental.componentDetection: true | Include all component CSS | ui: { experimental: { componentDetection: true } } | ui: {} (includes all CSS) | Low | https://ui.nuxt.com/docs/getting-started/installation/nuxt |
| 39 | Performance | Use UTable virtualize for large data | Enable virtualization for 1000+ rows | :virtualize prop on UTable | Render all rows | <UTable :data="largeData" virtualize/> | <UTable :data="largeData"/> | Medium | https://ui.nuxt.com/docs/components/table |
| 40 | Accessibility | Use semantic component props | Components have built-in ARIA support | Use title description label props | Skip accessibility props | <UModal title="Settings"> | <UModal><h2>Settings</h2> | Medium | https://ui.nuxt.com/docs/components/modal |
| 41 | Accessibility | Use UFormField for form accessibility | Automatic label-input association | UFormField wraps inputs | Manual id and for attributes | <UFormField label="Email"><UInput/></UFormField> | <label for="email">Email</label><UInput id="email"/> | High | https://ui.nuxt.com/docs/components/form-field |
| 42 | Content | Use UContentToc for table of contents | Automatic TOC with active heading highlight | UContentToc with :links | Manual TOC implementation | <UContentToc :links="toc"/> | <nav><a v-for="heading in headings"> | Low | https://ui.nuxt.com/docs/components/content-toc |
| 43 | Content | Use UContentSearch for docs search | Command palette for documentation search | UContentSearch with Nuxt Content | Custom search implementation | <UContentSearch/> | <UCommandPalette :groups="searchResults"/> | Low | https://ui.nuxt.com/docs/components/content-search |
| 44 | AI/Chat | Use UChatMessages for chat UI | Designed for Vercel AI SDK integration | UChatMessages with messages array | Custom chat message list | <UChatMessages :messages="messages"/> | <div v-for="msg in messages"> | Medium | https://ui.nuxt.com/docs/components/chat-messages |
| 45 | AI/Chat | Use UChatPrompt for input | Enhanced textarea for AI prompts | UChatPrompt with v-model | Basic textarea | <UChatPrompt v-model="prompt"/> | <UTextarea v-model="prompt"/> | Medium | https://ui.nuxt.com/docs/components/chat-prompt |
| 46 | Editor | Use UEditor for rich text | TipTap-based editor with toolbar support | UEditor with v-model:content | Custom TipTap setup | <UEditor v-model:content="content"/> | Manual TipTap initialization | Medium | https://ui.nuxt.com/docs/components/editor |
| 47 | Links | Use to prop for navigation | UButton and ULink support NuxtLink to prop | to="/dashboard" for internal links | href for internal navigation | <UButton to="/dashboard"> | <UButton href="/dashboard"> | Medium | https://ui.nuxt.com/docs/components/button |
| 48 | Links | Use external prop for outside links | Explicitly mark external links | target="_blank" with external URLs | Forget rel="noopener" | <UButton to="https://example.com" target="_blank"> | <UButton href="https://..."> | Low | https://ui.nuxt.com/docs/components/link |
| 49 | Loading | Use loadingAuto on buttons | Automatic loading state from @click promise | loadingAuto prop on UButton | Manual loading state | <UButton loadingAuto @click="async () => await save()"> | <UButton :loading="isLoading" @click="save"> | Low | https://ui.nuxt.com/docs/components/button |
| 50 | Loading | Use UForm loadingAuto | Auto-disable form during submit | loadingAuto on UForm (default true) | Manual form disabled state | <UForm @submit="handleSubmit"> | <UForm :disabled="isSubmitting"> | Low | https://ui.nuxt.com/docs/components/form |