14 KiB
14 KiB
| 1 | No | Category | Guideline | Description | Do | Don't | Code Good | Code Bad | Severity | Docs URL |
|---|---|---|---|---|---|---|---|---|---|---|
| 2 | 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 |
| 3 | 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 |
| 4 | 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 |
| 5 | 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 |
| 6 | 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 |
| 7 | 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 |
| 8 | 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 |
| 9 | 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 |
| 10 | 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 |
| 11 | 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 |
| 12 | 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 |
| 13 | 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 |
| 14 | 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 |
| 15 | 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 |
| 16 | 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 |
| 17 | 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 |
| 18 | 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 |
| 19 | 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 |
| 20 | 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 |
| 21 | 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 |
| 22 | 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 |
| 23 | 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 |
| 24 | 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 |
| 25 | 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 |
| 26 | 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 |
| 27 | 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 |
| 28 | 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 |
| 29 | 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 |
| 30 | 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 |
| 31 | 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 |