ui-ux-consultant-cli 1.0.0

package/assets/ui-ux-consultant/references/stacks/nextjs.md

@@ -0,0 +1,275 @@
+# Next.js UI/UX Guidelines
+
+## When to read this
+Read this file when building with Next.js 14+ App Router. Covers server vs client components, data fetching patterns, routing, images, metadata, and performance for production Next.js apps.
+
+## Recommended UI Libraries
+
+| Library | Best for | Install |
+|---|---|---|
+| shadcn/ui | UI components | `npx shadcn@latest init` |
+| next-auth v5 | Authentication | `npm install next-auth@beta` |
+| TanStack Query | Client-side caching | `npm install @tanstack/react-query` |
+| Prisma | Database ORM | `npm install prisma` |
+| Zod | Schema validation | `npm install zod` |
+| nuqs | URL search params state | `npm install nuqs` |
+
+## Style Recommendations by App Type
+
+- **SaaS product:** shadcn/ui + custom color tokens in `globals.css`
+- **Marketing site:** shadcn/ui + Tailwind animations + dark mode
+- **Dashboard/admin:** shadcn/ui data table + sidebar layout
+- **E-commerce:** Custom product cards, cart drawer, optimistic updates
+
+## Top UX Patterns
+
+### 1. Streaming Loading UI with loading.tsx
+```tsx
+// app/dashboard/loading.tsx
+export default function Loading() {
+  return <DashboardSkeleton />;
+}
+// Automatically shown while page.tsx's async data resolves
+// No extra code needed in page.tsx
+```
+
+### 2. Server Action with Error Handling
+```tsx
+'use server';
+import { revalidatePath } from 'next/cache';
+
+export async function createItem(formData: FormData) {
+  const title = formData.get('title') as string;
+  try {
+    await db.item.create({ data: { title } });
+    revalidatePath('/items');
+    return { success: true };
+  } catch {
+    return { error: 'Failed to create item' };
+  }
+}
+
+// Client component usage
+function ItemForm() {
+  const [state, formAction] = useFormState(createItem, null);
+  return (
+    <form action={formAction}>
+      <input name="title" required />
+      {state?.error && <p className="text-red-500">{state.error}</p>}
+      <button type="submit">Create</button>
+    </form>
+  );
+}
+```
+
+### 3. Route-Level Data Fetching (Server Component)
+```tsx
+// app/users/[id]/page.tsx
+import { notFound } from 'next/navigation';
+
+export default async function UserPage({ params }: { params: { id: string } }) {
+  const user = await db.user.findUnique({ where: { id: params.id } });
+  if (!user) notFound();
+  return <UserProfile user={user} />;
+}
+```
+
+### 4. Parallel Data Fetching
+```tsx
+// BAD: sequential — each awaits the previous (slow)
+const user = await getUser(id);
+const posts = await getPosts(id);
+
+// GOOD: parallel — both fire simultaneously
+const [user, posts] = await Promise.all([getUser(id), getPosts(id)]);
+```
+
+### 5. Intercepting Route Modal Pattern
+```
+app/
+  photos/
+    page.tsx                  ← gallery page
+    [id]/
+      page.tsx                ← full photo page (direct navigation)
+    @modal/
+      (.)photos/[id]/
+        page.tsx              ← modal (shown when navigating from gallery)
+  layout.tsx                  ← renders both {children} and {modal}
+```
+
+### 6. Dynamic Metadata for SEO
+```tsx
+// app/blog/[slug]/page.tsx
+export async function generateMetadata({ params }: { params: { slug: string } }) {
+  const post = await getPost(params.slug);
+  return {
+    title: post.title,
+    description: post.excerpt,
+    openGraph: {
+      title: post.title,
+      images: [{ url: post.coverImage }],
+    },
+  };
+}
+```
+
+### 7. Suspense Boundary for Slow Component
+```tsx
+// app/dashboard/page.tsx
+import { Suspense } from 'react';
+
+export default function DashboardPage() {
+  return (
+    <div>
+      <StaticHeader />
+      <Suspense fallback={<ChartSkeleton />}>
+        <SlowAnalyticsChart />  {/* streams in separately */}
+      </Suspense>
+    </div>
+  );
+}
+```
+
+### 8. Optimistic UI with useOptimistic (React 19 / Next.js 14+)
+```tsx
+'use client';
+import { useOptimistic } from 'react';
+
+function LikeButton({ post }) {
+  const [optimisticPost, addOptimisticLike] = useOptimistic(
+    post,
+    (state) => ({ ...state, likes: state.likes + 1 })
+  );
+  return (
+    <form action={async () => {
+      addOptimisticLike(null);
+      await likePost(post.id);
+    }}>
+      <button type="submit">Like ({optimisticPost.likes})</button>
+    </form>
+  );
+}
+```
+
+### 9. next/image with Priority and Sizes
+```tsx
+import Image from 'next/image';
+
+// Hero image (LCP) — always use priority
+<Image
+  src="/hero.jpg"
+  alt="Hero"
+  width={1200}
+  height={600}
+  priority
+/>
+
+// Responsive fill image
+<div className="relative h-64 w-full">
+  <Image
+    src={product.image}
+    alt={product.name}
+    fill
+    sizes="(max-width: 768px) 100vw, (max-width: 1200px) 50vw, 33vw"
+    className="object-cover"
+  />
+</div>
+```
+
+### 10. URL State with nuqs
+```tsx
+'use client';
+import { useQueryState } from 'nuqs';
+
+function ProductFilter() {
+  const [category, setCategory] = useQueryState('category');
+  const [sort, setSort] = useQueryState('sort', { defaultValue: 'popular' });
+
+  return (
+    <div>
+      <select value={category ?? ''} onChange={e => setCategory(e.target.value)}>
+        <option value="">All</option>
+        <option value="shoes">Shoes</option>
+      </select>
+    </div>
+  );
+}
+// URL: /products?category=shoes&sort=popular — shareable, bookmarkable
+```
+
+## Best Practices by Category
+
+### Rendering
+- Server Components by default — no `'use client'` unless you need browser APIs, event handlers, or hooks
+- Push `'use client'` to leaf nodes — not layouts or high-level wrappers
+- Use Suspense for progressive streaming of slow data sections
+- Static generation (`cache: 'force-cache'`) where data does not change per request
+
+### Data Fetching
+- Fetch in Server Components — no `useEffect` for initial data load
+- `cache: 'force-cache'` for static data, `cache: 'no-store'` for always-fresh data
+- Server Actions for all mutations (create, update, delete)
+- `revalidatePath` or `revalidateTag` for ISR cache invalidation after mutations
+- `Promise.all` for all parallel fetches — never sequential `await` for independent calls
+
+### Routing
+- App Router as default for all new Next.js projects
+- File-based routing: `page.tsx`, `layout.tsx`, `loading.tsx`, `error.tsx` per segment
+- Parallel routes (`@slot`) for split views and modal overlays
+- Intercepting routes for modal patterns without losing deep-link capability
+
+### Images
+- `next/image` on every `<img>` — automatic format optimization and lazy loading
+- `priority` prop on the LCP (largest contentful paint) image
+- Explicit `width`/`height` or `fill` + `sizes` — prevents layout shift
+- `next/font` for all custom fonts — zero layout shift, self-hosted automatically
+
+### Performance
+- `next/dynamic` for client-heavy third-party components (maps, editors, charts)
+- Bundle analyzer: `ANALYZE=true npm run build` with `@next/bundle-analyzer`
+- Avoid large `'use client'` subtrees — keep server boundary as low as possible
+- Cache expensive DB queries with `unstable_cache` or React `cache()`
+
+### Forms
+- Server Actions as form `action` prop — no API route needed
+- `useFormState` for server action response feedback
+- `useFormStatus` for pending state on submit button
+- Zod for schema validation in Server Actions before DB writes
+
+### Accessibility
+- Semantic HTML in all Server Components
+- `loading.tsx` skeleton should mirror the layout of real content — reduces layout shift
+- Focus management after navigation — Next.js handles this automatically
+- Error pages (`error.tsx`) must have a recovery action (retry button)
+
+### State
+- URL state (`nuqs`) for filters, pagination, search — shareable and bookmarkable
+- `useState`/`useReducer` for ephemeral UI state (modals, toggles)
+- TanStack Query for client-side caching of server data after initial load
+- Avoid `localStorage` for critical state — use cookies or DB for SSR compatibility
+
+## Common Anti-Patterns
+
+1. `'use client'` on a layout or high-level wrapper — makes the entire subtree client-side, losing all Server Component benefits
+2. `useEffect` for data that could be fetched in a Server Component — unnecessary client waterfall
+3. Fetching in client components without caching — re-fetches on every mount
+4. Missing `loading.tsx` — no streaming feedback during server data loading
+5. `<img>` instead of `next/image` — no optimization, causes layout shift
+6. Sequential `await` for independent data fetches — use `Promise.all`
+7. No `generateMetadata` on dynamic pages — poor SEO, missing OG tags
+8. Putting secrets in client components — environment variables without `NEXT_PUBLIC_` are server-only
+9. Mutating data without `revalidatePath` — stale cache shown to users after update
+10. Not using `notFound()` — returning null causes blank pages instead of proper 404
+
+## Performance Checklist
+
+- [ ] Server Components used for all non-interactive UI
+- [ ] `next/image` on every image, with `priority` on LCP image
+- [ ] `next/font` for all custom fonts — no `@font-face` in CSS
+- [ ] `loading.tsx` on every dynamic route segment
+- [ ] `Promise.all` for all parallel data fetches in Server Components
+- [ ] Bundle analyzer run: `ANALYZE=true npm run build`
+- [ ] Suspense boundaries around individually-slow components
+- [ ] `generateStaticParams` for known dynamic routes (static generation)
+- [ ] No large third-party libraries in Server Components (they ship to client via `'use client'` boundary)
+- [ ] `revalidateTag` strategy defined for all cached data

package/assets/ui-ux-consultant/references/stacks/nuxt-ui.md

@@ -0,0 +1,384 @@
+# Nuxt UI (nuxt/ui) UI/UX Guidelines
+
+## When to read this
+Read this file when building UI with the `@nuxt/ui` component library in a Nuxt 3 project. Covers component usage, theming, form patterns, toast notifications, modals, and accessibility built into the library.
+
+## Setup
+```bash
+npx nuxi module add ui
+# Automatically installs and configures:
+# - Tailwind CSS
+# - Headless UI (accessibility primitives)
+# - Heroicons (default icon set)
+# - Color mode support
+# - All components are auto-imported
+```
+
+## Core Components Reference
+
+| Component | Selector | Best for |
+|---|---|---|
+| UButton | `<UButton>` | Actions — color, variant, icon, size, loading props |
+| UInput | `<UInput>` | Text fields — placeholder, icon, trailing, disabled |
+| UTextarea | `<UTextarea>` | Multi-line text input |
+| USelect | `<USelect>` | Dropdown select with options array |
+| UCard | `<UCard>` | Content containers with header/footer slots |
+| UModal | `<UModal>` | Dialogs — v-model for open/close, accessible by default |
+| USlideover | `<USlideover>` | Side panels / drawers |
+| UDropdown | `<UDropdown>` | Menus — :items array prop |
+| UTable | `<UTable>` | Data tables — :rows, :columns, sorting, pagination |
+| UBadge | `<UBadge>` | Status indicators — color, variant, size |
+| UAlert | `<UAlert>` | Feedback messages — icon, color, description |
+| UCommandPalette | `<UCommandPalette>` | Search / command palette with built-in filtering |
+| UNotifications | `<UNotifications>` | Toast notification stack — pair with useToast() |
+| UFormGroup | `<UFormGroup>` | Form field wrapper with label, hint, and error |
+| UForm | `<UForm>` | Form with schema validation (Zod or Yup) |
+| UTabs | `<UTabs>` | Tab navigation — :items array |
+| UAccordion | `<UAccordion>` | Collapsible sections |
+| UAvatar | `<UAvatar>` | User avatars with fallback initials |
+| UProgress | `<UProgress>` | Progress bar with value and animation |
+| UTooltip | `<UTooltip>` | Hover tooltips with text prop |
+| UPopover | `<UPopover>` | Click-triggered overlay panels |
+| UPagination | `<UPagination>` | Page navigation — v-model, :total, :page-count |
+| URange | `<URange>` | Slider input |
+| UToggle | `<UToggle>` | Boolean on/off switch |
+| UCheckbox | `<UCheckbox>` | Checkbox with label |
+| URadio | `<URadio>` | Radio button |
+
+## Top UX Patterns
+
+### 1. Button Variants and States
+```vue
+<!-- Primary action -->
+<UButton color="primary" variant="solid" size="md" @click="save">
+  Save changes
+</UButton>
+
+<!-- With icon and loading state -->
+<UButton
+  color="primary"
+  variant="solid"
+  icon="i-heroicons-check"
+  :loading="saving"
+  :disabled="saving"
+  @click="save"
+>
+  Save changes
+</UButton>
+
+<!-- Destructive action -->
+<UButton color="red" variant="soft" icon="i-heroicons-trash" @click="remove">
+  Delete
+</UButton>
+
+<!-- Ghost / subtle -->
+<UButton color="gray" variant="ghost" icon="i-heroicons-x-mark" @click="cancel">
+  Cancel
+</UButton>
+```
+
+### 2. Form with Schema Validation
+```vue
+<script setup lang="ts">
+import { z } from 'zod';
+import type { FormSubmitEvent } from '#ui/types';
+
+const schema = z.object({
+  email: z.string().email('Invalid email'),
+  password: z.string().min(8, 'At least 8 characters'),
+});
+
+type Schema = z.output<typeof schema>;
+
+const state = reactive({ email: '', password: '' });
+
+async function onSubmit(event: FormSubmitEvent<Schema>) {
+  await login(event.data);
+}
+</script>
+
+<template>
+  <UForm :schema="schema" :state="state" @submit="onSubmit" class="space-y-4">
+    <UFormGroup label="Email" name="email" required>
+      <UInput v-model="state.email" type="email" placeholder="you@example.com" />
+    </UFormGroup>
+
+    <UFormGroup label="Password" name="password" required>
+      <UInput v-model="state.password" type="password" />
+    </UFormGroup>
+
+    <UButton type="submit" color="primary" block>Sign in</UButton>
+  </UForm>
+</template>
+```
+
+### 3. Toast Notifications
+```typescript
+const toast = useToast();
+
+// Success
+toast.add({
+  title: 'Saved!',
+  description: 'Your changes have been saved.',
+  icon: 'i-heroicons-check-circle',
+  color: 'green',
+});
+
+// Error
+toast.add({
+  title: 'Error',
+  description: 'Failed to save. Please try again.',
+  icon: 'i-heroicons-x-circle',
+  color: 'red',
+  timeout: 5000,
+});
+
+// Info with action
+toast.add({
+  title: 'New version available',
+  actions: [{ label: 'Refresh', click: () => window.location.reload() }],
+});
+```
+
+```vue
+<!-- Place once in app.vue -->
+<template>
+  <div>
+    <NuxtPage />
+    <UNotifications />
+  </div>
+</template>
+```
+
+### 4. Modal Dialog
+```vue
+<script setup lang="ts">
+const isOpen = ref(false);
+</script>
+
+<template>
+  <UButton @click="isOpen = true">Open dialog</UButton>
+
+  <UModal v-model="isOpen">
+    <UCard :ui="{ ring: '', divide: 'divide-y divide-gray-100 dark:divide-gray-800' }">
+      <template #header>
+        <div class="flex items-center justify-between">
+          <h3 class="text-base font-semibold">Edit item</h3>
+          <UButton color="gray" variant="ghost" icon="i-heroicons-x-mark" @click="isOpen = false" />
+        </div>
+      </template>
+
+      <p>Modal content goes here.</p>
+
+      <template #footer>
+        <div class="flex justify-end gap-3">
+          <UButton color="gray" variant="ghost" @click="isOpen = false">Cancel</UButton>
+          <UButton color="primary" @click="save">Save</UButton>
+        </div>
+      </template>
+    </UCard>
+  </UModal>
+</template>
+```
+
+### 5. Data Table with Columns
+```vue
+<script setup lang="ts">
+const columns = [
+  { key: 'name', label: 'Name', sortable: true },
+  { key: 'email', label: 'Email' },
+  { key: 'role', label: 'Role' },
+  { key: 'actions', label: '' },
+];
+
+const { data: users } = await useFetch('/api/users');
+</script>
+
+<template>
+  <UTable
+    :rows="users"
+    :columns="columns"
+    :loading="pending"
+    :empty-state="{ icon: 'i-heroicons-users', label: 'No users found.' }"
+  >
+    <template #actions-data="{ row }">
+      <UDropdown :items="[[{ label: 'Edit', click: () => edit(row) }, { label: 'Delete', click: () => remove(row) }]]">
+        <UButton icon="i-heroicons-ellipsis-horizontal" color="gray" variant="ghost" />
+      </UDropdown>
+    </template>
+  </UTable>
+</template>
+```
+
+### 6. Command Palette
+```vue
+<script setup lang="ts">
+const isOpen = ref(false);
+const { metaSymbol } = useShortcuts();
+
+defineShortcuts({
+  meta_k: { usingInput: false, handler: () => { isOpen.value = !isOpen.value; } },
+});
+
+const groups = [
+  {
+    key: 'pages',
+    label: 'Pages',
+    commands: [
+      { id: 'home', label: 'Home', icon: 'i-heroicons-home', to: '/' },
+      { id: 'dashboard', label: 'Dashboard', icon: 'i-heroicons-squares-2x2', to: '/dashboard' },
+    ],
+  },
+];
+</script>
+
+<template>
+  <UModal v-model="isOpen">
+    <UCommandPalette :groups="groups" @update:model-value="isOpen = false" />
+  </UModal>
+</template>
+```
+
+### 7. Slideover Side Panel
+```vue
+<template>
+  <USlideover v-model="isOpen" side="right">
+    <UCard class="h-full rounded-none">
+      <template #header>
+        <div class="flex items-center justify-between">
+          <h3>Filter options</h3>
+          <UButton icon="i-heroicons-x-mark" color="gray" variant="ghost" @click="isOpen = false" />
+        </div>
+      </template>
+      <FilterForm />
+    </UCard>
+  </USlideover>
+</template>
+```
+
+### 8. Dropdown Menu
+```vue
+<script setup lang="ts">
+const items = [
+  [
+    { label: 'Profile', icon: 'i-heroicons-user', to: '/profile' },
+    { label: 'Settings', icon: 'i-heroicons-cog-6-tooth', to: '/settings' },
+  ],
+  [
+    { label: 'Sign out', icon: 'i-heroicons-arrow-right-on-rectangle', click: signOut },
+  ],
+];
+</script>
+
+<template>
+  <UDropdown :items="items">
+    <UAvatar :src="user.avatar" :alt="user.name" />
+  </UDropdown>
+</template>
+```
+
+## Theming (app.config.ts)
+
+```typescript
+// app.config.ts
+export default defineAppConfig({
+  ui: {
+    primary: 'indigo',           // Primary color — any Tailwind color
+    gray: 'slate',               // Gray scale — slate, cool, zinc, neutral, stone
+
+    // Component-level defaults
+    button: {
+      default: {
+        size: 'md',
+        color: 'primary',
+        variant: 'solid',
+      },
+    },
+
+    input: {
+      default: {
+        size: 'md',
+      },
+    },
+
+    // Custom variant example
+    badge: {
+      variant: {
+        custom: 'bg-{color}-100 text-{color}-700 ring-1 ring-{color}-300',
+      },
+    },
+  },
+});
+```
+
+## Icons
+
+Nuxt UI uses Heroicons by default. Icons are accessed via CSS class names:
+
+```vue
+<!-- Outline (default) -->
+<UIcon name="i-heroicons-home" class="w-5 h-5" />
+
+<!-- Solid variant -->
+<UIcon name="i-heroicons-home-solid" />
+
+<!-- In components -->
+<UButton icon="i-heroicons-plus" />
+<UInput icon="i-heroicons-magnifying-glass" />
+```
+
+Install additional icon sets:
+```bash
+npm install @iconify-json/lucide      # Lucide icons — i-lucide-*
+npm install @iconify-json/ph          # Phosphor icons — i-ph-*
+npm install @iconify-json/tabler      # Tabler icons — i-tabler-*
+```
+
+## Best Practices by Category
+
+### Components
+- Always use `<UFormGroup>` around form inputs — it wires up the label/input association, hint text, and error display automatically
+- Use `<UModal>` and `<USlideover>` instead of building custom overlays — they handle focus trap, Escape key, scroll lock, and ARIA out of the box
+- Use the `color` prop with theme values (`primary`, `gray`, `red`, `green`) — never hardcode hex colors
+- Use `variant` prop to convey hierarchy: `solid` for primary, `soft` or `outline` for secondary, `ghost` for tertiary
+
+### Forms
+- `<UForm>` with `:schema` (Zod) handles validation automatically on submit and on change
+- `<UFormGroup name="fieldName">` matches the Zod schema key — errors display automatically
+- Use `:loading` on submit button — never disable the button without visual feedback
+
+### Notifications
+- `useToast()` is the only notification system — do not build a custom one
+- Place `<UNotifications />` once in `app.vue`
+- Use `color` prop to convey meaning: `green` for success, `red` for error, `yellow` for warning
+
+### Accessibility
+- All Nuxt UI components are built on Headless UI — ARIA roles, keyboard navigation, and focus management are handled automatically
+- Do not suppress the built-in focus ring — it is essential for keyboard users
+- Use `aria-label` on icon-only buttons: `<UButton icon="i-heroicons-x-mark" aria-label="Close" />`
+
+### State
+- `v-model` on `<UModal>` and `<USlideover>` for open/close state
+- `useToast()` composable — auto-imported, no import needed
+- `useShortcuts()` for keyboard shortcuts that interact with UI
+
+## Common Anti-Patterns
+
+1. Not using `<UFormGroup>` — input loses label association, hint text, and auto error display
+2. Building a custom modal — `<UModal>` and `<USlideover>` handle all accessibility automatically (focus trap, Escape key, scroll lock)
+3. Hardcoded colors in `class` or `style` — use `color` prop so theming works correctly
+4. Building a custom toast/notification system — `useToast()` + `<UNotifications />` is already provided
+5. Importing components manually — all Nuxt UI components are auto-imported
+6. Not passing `aria-label` on icon-only buttons — screen readers cannot identify the action
+7. Using `disabled` on form submit without `:loading` — users see no feedback that something is happening
+8. Nested `<UCard>` inside `<UModal>` without removing the ring — creates double border; use `:ui="{ ring: '' }"`
+
+## Performance Checklist
+
+- [ ] `<UTable>` with `:rows` for all data tables — has built-in empty state and loading state
+- [ ] `<UCommandPalette>` for app-wide search — built-in filtering and keyboard navigation
+- [ ] `<UModal>` content only renders when open — no hidden DOM overhead when closed
+- [ ] `<UNotifications />` placed once at app root — not duplicated per page
+- [ ] Icon sets installed only as needed — each `@iconify-json/*` adds to bundle
+- [ ] Theme configured in `app.config.ts` — avoids runtime style computation
+- [ ] `<UButton :loading="true">` used during async operations — prevents double-submit