npm - ui-ux-consultant-cli - Versions diffs - 1.0.0 - Mend

ui-ux-consultant-cli 1.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (30) hide show

package/assets/ui-ux-consultant/SKILL.md +844 -0
package/assets/ui-ux-consultant/references/accessibility.md +175 -0
package/assets/ui-ux-consultant/references/alt-libraries.md +90 -0
package/assets/ui-ux-consultant/references/animations.md +448 -0
package/assets/ui-ux-consultant/references/catalog/colors.md +91 -0
package/assets/ui-ux-consultant/references/catalog/fonts.md +363 -0
package/assets/ui-ux-consultant/references/catalog/products.md +340 -0
package/assets/ui-ux-consultant/references/catalog/styles.md +165 -0
package/assets/ui-ux-consultant/references/components.md +1116 -0
package/assets/ui-ux-consultant/references/patterns.md +600 -0
package/assets/ui-ux-consultant/references/performance.md +198 -0
package/assets/ui-ux-consultant/references/stacks/astro.md +382 -0
package/assets/ui-ux-consultant/references/stacks/flutter.md +308 -0
package/assets/ui-ux-consultant/references/stacks/html-tailwind.md +415 -0
package/assets/ui-ux-consultant/references/stacks/jetpack-compose.md +333 -0
package/assets/ui-ux-consultant/references/stacks/laravel.md +521 -0
package/assets/ui-ux-consultant/references/stacks/nextjs.md +275 -0
package/assets/ui-ux-consultant/references/stacks/nuxt-ui.md +384 -0
package/assets/ui-ux-consultant/references/stacks/nuxtjs.md +264 -0
package/assets/ui-ux-consultant/references/stacks/react-native.md +346 -0
package/assets/ui-ux-consultant/references/stacks/react.md +268 -0
package/assets/ui-ux-consultant/references/stacks/shadcn.md +485 -0
package/assets/ui-ux-consultant/references/stacks/svelte.md +429 -0
package/assets/ui-ux-consultant/references/stacks/swiftui.md +336 -0
package/assets/ui-ux-consultant/references/stacks/threejs.md +366 -0
package/assets/ui-ux-consultant/references/stacks/vue.md +272 -0
package/assets/ui-ux-consultant/references/theming.md +701 -0
package/dist/index.d.ts +2 -0
package/dist/index.js +130 -0
package/package.json +51 -0

package/assets/ui-ux-consultant/references/stacks/shadcn.md ADDED Viewed

@@ -0,0 +1,485 @@
+# shadcn/ui — UI/UX Reference
+## When to Read
+Use this file when building with shadcn/ui — the copy-paste component system built on Radix UI primitives + Tailwind CSS. Works with React, Next.js, Astro, Remix, and any Tailwind-compatible React project.
+---
+## What shadcn/ui Is (and Isn't)
+**NOT a component library you install as a package.** You copy component source directly into your project (`components/ui/`). Each component is yours to read, modify, and own. The `npx shadcn` CLI adds components as files — you have full control.
+**Built on:**
+- **Radix UI** — headless, accessible primitives (dialogs, dropdowns, tooltips, etc.)
+- **Tailwind CSS** — utility classes for all styling
+- **class-variance-authority (cva)** — variant-based component styling
+- **clsx + tailwind-merge** — safe class name merging via `cn()`
+---
+## Recommended Additions
+| Package | Purpose | Install |
+|---|---|---|
+| `react-hook-form` | Form state management | `npm install react-hook-form` |
+| `zod` | Schema validation | `npm install zod` |
+| `@hookform/resolvers` | Connect zod to react-hook-form | `npm install @hookform/resolvers` |
+| `@tanstack/react-table` | Headless data tables | `npm install @tanstack/react-table` |
+| `cmdk` | Command palette | bundled with shadcn Command |
+| `sonner` | Toast notifications | `npx shadcn@latest add sonner` |
+| `vaul` | Drawer / bottom sheet | `npx shadcn@latest add drawer` |
+| `recharts` | Charts | `npx shadcn@latest add chart` |
+| `date-fns` | Date utilities | `npm install date-fns` |
+---
+## Style Recommendations
+- **Default shadcn style:** Clean, professional, neutral — safe for B2B SaaS
+- **New York style:** Sharper borders, tighter spacing — modern editorial feel
+- **Brand customization:** Edit `--primary` CSS variable; all components update
+- **Dark mode:** Built-in via `.dark` class on `<html>`; works out of the box
+- **Recommended pairings:** Inter or Geist font, 4px border radius for friendly, 0px for stark
+---
+## Setup
+```bash
+# Initialize shadcn in a Vite/Next.js/Astro project
+npx shadcn@latest init
+# Prompts: style (Default / New York), base color, CSS variables (yes)
+# Add individual components
+npx shadcn@latest add button
+npx shadcn@latest add card dialog form table badge avatar
+# Add multiple at once
+npx shadcn@latest add button card dialog form input label select textarea
+```
+---
+## Core Architecture Patterns
+### The `cn()` Helper
+```typescript
+// lib/utils.ts (auto-generated by init)
+import { clsx, type ClassValue } from 'clsx';
+import { twMerge } from 'tailwind-merge';
+export function cn(...inputs: ClassValue[]) {
+  return twMerge(clsx(inputs));
+}
+// Usage — merges classes safely, resolves Tailwind conflicts
+<Button className={cn('w-full', isLoading && 'opacity-50', className)} />
+```
+### Variant-Based Styling with `cva`
+```typescript
+// components/ui/button.tsx
+import { cva, type VariantProps } from 'class-variance-authority';
+const buttonVariants = cva(
+  // Base classes (always applied)
+  'inline-flex items-center justify-center gap-2 whitespace-nowrap rounded-md text-sm font-medium transition-colors focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring disabled:pointer-events-none disabled:opacity-50',
+  {
+    variants: {
+      variant: {
+        default:     'bg-primary text-primary-foreground hover:bg-primary/90',
+        outline:     'border border-input bg-background hover:bg-accent hover:text-accent-foreground',
+        ghost:       'hover:bg-accent hover:text-accent-foreground',
+        destructive: 'bg-destructive text-destructive-foreground hover:bg-destructive/90',
+        secondary:   'bg-secondary text-secondary-foreground hover:bg-secondary/80',
+        link:        'text-primary underline-offset-4 hover:underline',
+      },
+      size: {
+        default: 'h-10 px-4 py-2',
+        sm:      'h-9 rounded-md px-3',
+        lg:      'h-11 rounded-md px-8',
+        icon:    'h-10 w-10',
+      },
+    },
+    defaultVariants: { variant: 'default', size: 'default' },
+  }
+);
+interface ButtonProps
+  extends React.ButtonHTMLAttributes<HTMLButtonElement>,
+    VariantProps<typeof buttonVariants> {
+  asChild?: boolean;
+}
+export function Button({ className, variant, size, asChild = false, ...props }: ButtonProps) {
+  const Comp = asChild ? Slot : 'button';
+  return <Comp className={cn(buttonVariants({ variant, size, className }))} {...props} />;
+}
+```
+### `asChild` Pattern
+```tsx
+// asChild renders the child element instead of the default element
+// Use for link buttons, custom triggers, etc.
+<Button asChild>
+  <Link href="/dashboard">Go to Dashboard</Link>
+</Button>
+<DialogTrigger asChild>
+  <Button variant="outline">Open Dialog</Button>
+</DialogTrigger>
+```
+---
+## Top UX Patterns with Code
+### 1. Form with Validation (react-hook-form + zod)
+```tsx
+import { useForm } from 'react-hook-form';
+import { zodResolver } from '@hookform/resolvers/zod';
+import { z } from 'zod';
+import { Form, FormControl, FormDescription, FormField, FormItem, FormLabel, FormMessage } from '@/components/ui/form';
+import { Input } from '@/components/ui/input';
+import { Button } from '@/components/ui/button';
+const formSchema = z.object({
+  email: z.string().email('Invalid email address'),
+  name: z.string().min(2, 'Name must be at least 2 characters'),
+  role: z.enum(['admin', 'user', 'viewer']),
+});
+type FormValues = z.infer<typeof formSchema>;
+export function UserForm({ onSubmit }: { onSubmit: (data: FormValues) => Promise<void> }) {
+  const form = useForm<FormValues>({
+    resolver: zodResolver(formSchema),
+    defaultValues: { email: '', name: '', role: 'user' },
+  });
+  return (
+    <Form {...form}>
+      <form onSubmit={form.handleSubmit(onSubmit)} className="space-y-6">
+        <FormField
+          control={form.control}
+          name="email"
+          render={({ field }) => (
+            <FormItem>
+              <FormLabel>Email</FormLabel>
+              <FormControl>
+                <Input type="email" placeholder="you@example.com" {...field} />
+              </FormControl>
+              <FormDescription>We'll never share your email.</FormDescription>
+              <FormMessage />  {/* Auto-shows zod error messages */}
+            </FormItem>
+          )}
+        />
+        <Button type="submit" disabled={form.formState.isSubmitting}>
+          {form.formState.isSubmitting ? 'Saving...' : 'Save'}
+        </Button>
+      </form>
+    </Form>
+  );
+}
+```
+### 2. Dialog / Modal
+```tsx
+import {
+  Dialog, DialogContent, DialogDescription,
+  DialogFooter, DialogHeader, DialogTitle, DialogTrigger,
+} from '@/components/ui/dialog';
+export function DeleteConfirmDialog({ onConfirm }: { onConfirm: () => void }) {
+  const [open, setOpen] = React.useState(false);
+  return (
+    <Dialog open={open} onOpenChange={setOpen}>
+      <DialogTrigger asChild>
+        <Button variant="destructive">Delete</Button>
+      </DialogTrigger>
+      <DialogContent className="sm:max-w-md">
+        <DialogHeader>
+          <DialogTitle>Are you absolutely sure?</DialogTitle>
+          <DialogDescription>
+            This action cannot be undone. This will permanently delete your data.
+          </DialogDescription>
+        </DialogHeader>
+        <DialogFooter>
+          <Button variant="outline" onClick={() => setOpen(false)}>Cancel</Button>
+          <Button variant="destructive" onClick={() => { onConfirm(); setOpen(false); }}>
+            Delete
+          </Button>
+        </DialogFooter>
+      </DialogContent>
+    </Dialog>
+  );
+}
+```
+### 3. Data Table (TanStack Table)
+```tsx
+import {
+  useReactTable, getCoreRowModel, getSortedRowModel,
+  getPaginationRowModel, getFilteredRowModel,
+  type ColumnDef, type SortingState,
+} from '@tanstack/react-table';
+import { Table, TableBody, TableCell, TableHead, TableHeader, TableRow } from '@/components/ui/table';
+interface User { id: string; name: string; email: string; role: string; }
+const columns: ColumnDef<User>[] = [
+  { accessorKey: 'name', header: 'Name' },
+  { accessorKey: 'email', header: 'Email' },
+  {
+    accessorKey: 'role',
+    header: 'Role',
+    cell: ({ row }) => <Badge variant="outline">{row.getValue('role')}</Badge>,
+  },
+  {
+    id: 'actions',
+    cell: ({ row }) => <UserActions user={row.original} />,
+  },
+];
+export function UsersTable({ data }: { data: User[] }) {
+  const [sorting, setSorting] = React.useState<SortingState>([]);
+  const [globalFilter, setGlobalFilter] = React.useState('');
+  const table = useReactTable({
+    data,
+    columns,
+    state: { sorting, globalFilter },
+    onSortingChange: setSorting,
+    onGlobalFilterChange: setGlobalFilter,
+    getCoreRowModel: getCoreRowModel(),
+    getSortedRowModel: getSortedRowModel(),
+    getPaginationRowModel: getPaginationRowModel(),
+    getFilteredRowModel: getFilteredRowModel(),
+  });
+  return (
+    <div className="space-y-4">
+      <Input placeholder="Search..." value={globalFilter} onChange={e => setGlobalFilter(e.target.value)} />
+      <Table>
+        <TableHeader>
+          {table.getHeaderGroups().map(group => (
+            <TableRow key={group.id}>
+              {group.headers.map(header => (
+                <TableHead key={header.id}
+                  onClick={header.column.getToggleSortingHandler()}
+                  className="cursor-pointer">
+                  {flexRender(header.column.columnDef.header, header.getContext())}
+                </TableHead>
+              ))}
+            </TableRow>
+          ))}
+        </TableHeader>
+        <TableBody>
+          {table.getRowModel().rows.map(row => (
+            <TableRow key={row.id}>
+              {row.getVisibleCells().map(cell => (
+                <TableCell key={cell.id}>
+                  {flexRender(cell.column.columnDef.cell, cell.getContext())}
+                </TableCell>
+              ))}
+            </TableRow>
+          ))}
+        </TableBody>
+      </Table>
+    </div>
+  );
+}
+```
+### 4. Command Palette
+```tsx
+import {
+  CommandDialog, CommandEmpty, CommandGroup,
+  CommandInput, CommandItem, CommandList,
+} from '@/components/ui/command';
+export function CommandPalette() {
+  const [open, setOpen] = React.useState(false);
+  React.useEffect(() => {
+    const down = (e: KeyboardEvent) => {
+      if (e.key === 'k' && (e.metaKey || e.ctrlKey)) {
+        e.preventDefault();
+        setOpen(prev => !prev);
+      }
+    };
+    document.addEventListener('keydown', down);
+    return () => document.removeEventListener('keydown', down);
+  }, []);
+  return (
+    <CommandDialog open={open} onOpenChange={setOpen}>
+      <CommandInput placeholder="Type a command or search..." />
+      <CommandList>
+        <CommandEmpty>No results found.</CommandEmpty>
+        <CommandGroup heading="Navigation">
+          <CommandItem onSelect={() => { router.push('/dashboard'); setOpen(false); }}>
+            Dashboard
+          </CommandItem>
+          <CommandItem onSelect={() => { router.push('/settings'); setOpen(false); }}>
+            Settings
+          </CommandItem>
+        </CommandGroup>
+      </CommandList>
+    </CommandDialog>
+  );
+}
+```
+### 5. Toast Notifications with Sonner
+```tsx
+// In layout — add once
+import { Toaster } from '@/components/ui/sonner';
+<Toaster position="bottom-right" richColors />
+// In any component
+import { toast } from 'sonner';
+// Usage
+toast.success('Saved successfully');
+toast.error('Something went wrong');
+toast.promise(saveUser(data), {
+  loading: 'Saving...',
+  success: 'User saved!',
+  error: 'Failed to save',
+});
+```
+### 6. Dropdown Menu
+```tsx
+import {
+  DropdownMenu, DropdownMenuContent, DropdownMenuItem,
+  DropdownMenuLabel, DropdownMenuSeparator, DropdownMenuTrigger,
+} from '@/components/ui/dropdown-menu';
+<DropdownMenu>
+  <DropdownMenuTrigger asChild>
+    <Button variant="ghost" size="icon"><MoreHorizontal /></Button>
+  </DropdownMenuTrigger>
+  <DropdownMenuContent align="end">
+    <DropdownMenuLabel>Actions</DropdownMenuLabel>
+    <DropdownMenuSeparator />
+    <DropdownMenuItem onClick={() => navigator.clipboard.writeText(id)}>
+      Copy ID
+    </DropdownMenuItem>
+    <DropdownMenuItem onClick={() => onEdit(item)}>Edit</DropdownMenuItem>
+    <DropdownMenuSeparator />
+    <DropdownMenuItem className="text-destructive" onClick={() => onDelete(item)}>
+      Delete
+    </DropdownMenuItem>
+  </DropdownMenuContent>
+</DropdownMenu>
+```
+---
+## CSS Variables Theming
+```css
+/* globals.css — generated by shadcn init */
+@layer base {
+  :root {
+    --background: 0 0% 100%;
+    --foreground: 222.2 84% 4.9%;
+    --card: 0 0% 100%;
+    --card-foreground: 222.2 84% 4.9%;
+    --primary: 222.2 47.4% 11.2%;         /* Change this for brand color */
+    --primary-foreground: 210 40% 98%;
+    --secondary: 210 40% 96.1%;
+    --muted: 210 40% 96.1%;
+    --muted-foreground: 215.4 16.3% 46.9%;
+    --border: 214.3 31.8% 91.4%;
+    --ring: 222.2 84% 4.9%;
+    --radius: 0.5rem;                      /* Change for border-radius style */
+  }
+  .dark {
+    --background: 222.2 84% 4.9%;
+    --foreground: 210 40% 98%;
+    --primary: 210 40% 98%;
+    /* ... all tokens redefined for dark */
+  }
+}
+```
+**Brand customization:** change `--primary` HSL values. All buttons, links, focus rings update automatically. No component edits needed.
+---
+## Best Practices by Category
+### Component Modification
+- Edit component files directly — they live in `components/ui/`, not in `node_modules`
+- Use `cn()` for all conditional class merging to avoid Tailwind conflicts
+- Extend with `cva` variants rather than adding one-off className strings
+- Keep customizations in the component file, not via external CSS overrides
+### Form Patterns
+- Always pair shadcn Form with react-hook-form + zod for type-safe validation
+- Use `FormMessage` — it auto-displays the zod error for the field
+- Use `FormDescription` for helper text below inputs
+- `defaultValues` in `useForm` prevents uncontrolled→controlled warnings
+### Accessibility
+- Radix UI primitives handle focus trapping, keyboard navigation, ARIA automatically
+- Never remove `role` or `aria-*` attributes from generated components
+- Custom triggers should use `asChild` to preserve semantics
+- Test with keyboard only — tab, enter, escape, arrow keys must work
+### Dark Mode
+- shadcn ships with dark mode via `.dark` class on `<html>`
+- Next.js: use `next-themes` (`npm install next-themes`) for system preference and toggle
+- All CSS variables have dark counterparts — no component changes needed
+---
+## Common Anti-Patterns
+1. **Installing shadcn as an npm package** — there is no `npm install shadcn`. It's copy-paste by design. Components live in your codebase, not node_modules.
+2. **Not using `cn()` for conditional classes** — `className={`base ${condition ? 'a' : 'b'}`}` causes Tailwind conflicts. Always use `cn()` for merging.
+3. **Styling Radix components with external CSS** — use Tailwind classes directly in the component file. External CSS specificity battles are painful.
+4. **Adding components manually without `npx shadcn add`** — the CLI wires up imports, dependencies, and ensures correct file paths. Manual copying often misses peer deps.
+5. **Using `!important` to override** — edit the component file instead. You own it.
+6. **Wrapping every primitive in a div** — Radix's `asChild` prop renders the child element directly. Use it instead of wrapper divs.
+7. **Passing className without `cn()`** — `<Button className="w-full">` works, but `<Button className={cn('w-full', variant === 'danger' && 'bg-red-500')}>` is safer.
+8. **Not upgrading component files after `npx shadcn@latest add`** — running add again on an existing component regenerates it. Back up local modifications first.
+9. **Using `<select>` instead of shadcn Select** — native select is unstyled and inaccessible on some platforms. Use the Radix-backed Select component.
+10. **Skipping `<DialogDescription>`** — Radix Dialog warns (and NVDA/JAWS users miss context) without it. Always include for screen reader support.
+---
+## Performance Checklist
+- [ ] Tree-shaking: only imported components are bundled (no barrel `index.ts` needed)
+- [ ] `asChild` to avoid unnecessary DOM wrappers
+- [ ] Lazy-load Dialog, Sheet, Drawer content: `React.lazy(() => import('./HeavyDialog'))`
+- [ ] TanStack Table pagination — render only visible rows, not all data
+- [ ] `sonner` toasts are lazy-rendered, not always in DOM
+- [ ] Radix portals render outside the DOM tree — no overflow:hidden issues
+- [ ] `cmdk` Command palette uses virtual scrolling for large lists
+- [ ] Avoid re-creating `columns` array on every render — define outside component or `useMemo`
+- [ ] Dark mode via CSS variables — zero JavaScript color computation at runtime
+- [ ] `cn()` uses `twMerge` which is ~2KB — import only where needed