maestro-bundle 1.3.1 → 1.5.0

package/templates/bundle-frontend-spa/skills/component-design/SKILL.md

@@ -1,25 +1,70 @@
 ---
 name: component-design
-description: Criar componentes UI reutilizáveis com Tailwind + Shadcn/UI seguindo design system. Use quando for criar componentes de interface, botões, cards, modais, tabelas, ou elementos de UI.
+description: Create reusable UI components with Tailwind CSS and Shadcn/UI following design system principles. Use when you need to create buttons, cards, modals, tables, badges, or any UI element with consistent styling and accessibility.
+version: 1.0.0
+author: Maestro
 ---
 
 # Component Design
 
-## Princípios
+Build accessible, reusable UI components with Tailwind CSS, Shadcn/UI, and TypeScript.
 
-1. **Um componente = uma responsabilidade**
-2. **Props tipadas** com interface TypeScript
-3. **Composição** sobre configuração (slots > props booleanas)
-4. **Acessibilidade** built-in (aria-labels, keyboard nav)
+## When to Use
+- User needs to create a reusable UI component (button, card, modal, table)
+- User wants to implement a design system with consistent variants
+- User needs data tables with pagination and sorting
+- User wants loading skeletons, error states, or empty states
+- User needs accessible components with ARIA labels and keyboard navigation
 
-## Componente Base — Template
+## Available Operations
+1. Create variant-based components (Button, Badge, Input)
+2. Build compound components (Card with Header/Content/Footer)
+3. Implement data tables with TanStack Table
+4. Create async content wrappers (loading/error/empty states)
+5. Add Shadcn/UI components to the project
 
+## Multi-Step Workflow
+
+### Step 1: Set Up Shadcn/UI (If Not Already Installed)
+```bash
+npx shadcn@latest init
+npx shadcn@latest add button card table badge input dialog
+npm install @tanstack/react-table clsx tailwind-merge
+```
+
+Create a utility for merging Tailwind classes:
 ```tsx
+// src/lib/utils.ts
+import { clsx, type ClassValue } from 'clsx';
+import { twMerge } from 'tailwind-merge';
+
+export function cn(...inputs: ClassValue[]) {
+  return twMerge(clsx(inputs));
+}
+```
+
+### Step 2: Create a Variant-Based Button Component
+```tsx
+// src/components/ui/Button.tsx
+import { cn } from '@/lib/utils';
+
+const variants = {
+  primary: 'bg-blue-600 text-white hover:bg-blue-700',
+  secondary: 'bg-gray-100 text-gray-700 hover:bg-gray-200',
+  danger: 'bg-red-600 text-white hover:bg-red-700',
+  ghost: 'bg-transparent hover:bg-gray-100',
+} as const;
+
+const sizes = {
+  sm: 'px-3 py-1.5 text-sm',
+  md: 'px-4 py-2 text-base',
+  lg: 'px-6 py-3 text-lg',
+} as const;
+
 interface ButtonProps extends React.ButtonHTMLAttributes<HTMLButtonElement> {
-  variant?: 'primary' | 'secondary' | 'danger';
-  size?: 'sm' | 'md' | 'lg';
+  variant?: keyof typeof variants;
+  size?: keyof typeof sizes;
   loading?: boolean;
-  children: React.ReactNode;
 }
 
 export function Button({
@@ -28,36 +73,43 @@ export function Button({
   loading = false,
   children,
   disabled,
+  className,
   ...props
 }: ButtonProps) {
   return (
     <button
       className={cn(
-        'rounded font-medium transition-colors',
+        'rounded font-medium transition-colors focus:outline-none focus:ring-2 focus:ring-offset-2',
         variants[variant],
         sizes[size],
-        (disabled || loading) && 'opacity-50 cursor-not-allowed'
+        (disabled || loading) && 'opacity-50 cursor-not-allowed',
+        className
       )}
       disabled={disabled || loading}
+      aria-busy={loading}
       {...props}
     >
-      {loading ? <Spinner size={size} /> : children}
+      {loading ? <span className="animate-spin inline-block w-4 h-4 border-2 border-current border-t-transparent rounded-full" /> : children}
     </button>
   );
 }
 ```
 
-## Status Badge — Para tasks e demandas
-
+### Step 3: Create a Status Badge
 ```tsx
+// src/components/ui/StatusBadge.tsx
 const statusConfig = {
-  pending: { label: 'Pendente', className: 'bg-gray-100 text-gray-700' },
-  in_progress: { label: 'Em andamento', className: 'bg-blue-100 text-blue-700' },
-  completed: { label: 'Concluído', className: 'bg-green-100 text-green-700' },
-  failed: { label: 'Falhou', className: 'bg-red-100 text-red-700' },
+  pending: { label: 'Pending', className: 'bg-gray-100 text-gray-700' },
+  in_progress: { label: 'In Progress', className: 'bg-blue-100 text-blue-700' },
+  completed: { label: 'Completed', className: 'bg-green-100 text-green-700' },
+  failed: { label: 'Failed', className: 'bg-red-100 text-red-700' },
 } as const;
 
-export function StatusBadge({ status }: { status: keyof typeof statusConfig }) {
+interface StatusBadgeProps {
+  status: keyof typeof statusConfig;
+}
+
+export function StatusBadge({ status }: StatusBadgeProps) {
   const config = statusConfig[status];
   return (
     <span className={cn('px-2 py-1 rounded-full text-xs font-medium', config.className)}>
@@ -67,14 +119,16 @@ export function StatusBadge({ status }: { status: keyof typeof statusConfig }) {
 }
 ```
 
-## Data Table — Com paginação
-
+### Step 4: Build a Data Table with Pagination
 ```tsx
+// src/components/ui/DataTable.tsx
+import { useReactTable, getCoreRowModel, flexRender, type ColumnDef } from '@tanstack/react-table';
+
 interface DataTableProps<T> {
   data: T[];
-  columns: ColumnDef<T>[];
-  pagination: { page: number; size: number; total: number };
-  onPageChange: (page: number) => void;
+  columns: ColumnDef<T, unknown>[];
+  pagination?: { page: number; size: number; total: number };
+  onPageChange?: (page: number) => void;
 }
 
 export function DataTable<T>({ data, columns, pagination, onPageChange }: DataTableProps<T>) {
@@ -86,30 +140,126 @@ export function DataTable<T>({ data, columns, pagination, onPageChange }: DataTa
 
   return (
     <div>
-      <Table>
-        <TableHeader>{/* ... */}</TableHeader>
-        <TableBody>{/* ... */}</TableBody>
-      </Table>
-      <Pagination
-        page={pagination.page}
-        total={pagination.total}
-        size={pagination.size}
-        onChange={onPageChange}
-      />
+      <table className="w-full border-collapse">
+        <thead>
+          {table.getHeaderGroups().map((headerGroup) => (
+            <tr key={headerGroup.id} className="border-b bg-gray-50">
+              {headerGroup.headers.map((header) => (
+                <th key={header.id} className="px-4 py-3 text-left text-sm font-medium text-gray-600">
+                  {flexRender(header.column.columnDef.header, header.getContext())}
+                </th>
+              ))}
+            </tr>
+          ))}
+        </thead>
+        <tbody>
+          {table.getRowModel().rows.map((row) => (
+            <tr key={row.id} className="border-b hover:bg-gray-50">
+              {row.getVisibleCells().map((cell) => (
+                <td key={cell.id} className="px-4 py-3 text-sm">
+                  {flexRender(cell.column.columnDef.cell, cell.getContext())}
+                </td>
+              ))}
+            </tr>
+          ))}
+        </tbody>
+      </table>
+
+      {pagination && onPageChange && (
+        <div className="flex items-center justify-between p-4">
+          <span className="text-sm text-gray-600">
+            Page {pagination.page} of {Math.ceil(pagination.total / pagination.size)}
+          </span>
+          <div className="flex gap-2">
+            <Button size="sm" variant="secondary" onClick={() => onPageChange(pagination.page - 1)} disabled={pagination.page <= 1}>
+              Previous
+            </Button>
+            <Button size="sm" variant="secondary" onClick={() => onPageChange(pagination.page + 1)} disabled={pagination.page >= Math.ceil(pagination.total / pagination.size)}>
+              Next
+            </Button>
+          </div>
+        </div>
+      )}
     </div>
   );
 }
 ```
 
-## Loading States
+### Step 5: Create Async Content Wrapper
+```tsx
+// src/components/ui/AsyncContent.tsx
+import type { UseQueryResult } from '@tanstack/react-query';
 
-Sempre mostrar skeleton enquanto carrega, error state quando falha:
+interface AsyncContentProps<T> {
+  query: UseQueryResult<T>;
+  children: (data: T) => React.ReactNode;
+}
 
-```tsx
-function AsyncContent<T>({ query, children }: { query: UseQueryResult<T>, children: (data: T) => ReactNode }) {
+export function AsyncContent<T>({ query, children }: AsyncContentProps<T>) {
   if (query.isLoading) return <Skeleton />;
-  if (query.error) return <ErrorState message={query.error.message} />;
-  if (!query.data) return <EmptyState />;
+  if (query.error) return <ErrorState message={query.error.message} onRetry={query.refetch} />;
+  if (!query.data) return <EmptyState message="No data found" />;
   return <>{children(query.data)}</>;
 }
+
+function Skeleton() {
+  return (
+    <div className="animate-pulse space-y-4">
+      <div className="h-4 bg-gray-200 rounded w-3/4" />
+      <div className="h-4 bg-gray-200 rounded w-1/2" />
+      <div className="h-4 bg-gray-200 rounded w-5/6" />
+    </div>
+  );
+}
+
+function ErrorState({ message, onRetry }: { message: string; onRetry?: () => void }) {
+  return (
+    <div className="text-center p-8">
+      <p className="text-red-600">{message}</p>
+      {onRetry && <Button variant="secondary" onClick={onRetry} className="mt-4">Retry</Button>}
+    </div>
+  );
+}
+
+function EmptyState({ message }: { message: string }) {
+  return <div className="text-center p-8 text-gray-500">{message}</div>;
+}
+```
+
+### Step 6: Verify Components
+```bash
+npm run dev
+# Open http://localhost:5173 and visually verify components
+
+npx tsc --noEmit
+# Check for TypeScript errors
 ```
+
+## Resources
+- `references/tailwind-patterns.md` - Common Tailwind utility patterns
+- `references/accessibility-checklist.md` - ARIA and keyboard nav requirements
+
+## Examples
+### Example 1: Create a Card Component
+User asks: "Create a reusable card component with header, body, and footer slots"
+Response approach:
+1. Create a Card compound component with Card.Header, Card.Content, Card.Footer
+2. Use Tailwind for styling with cn() for class merging
+3. Add className prop pass-through for customization
+4. Show usage example
+
+### Example 2: Build a Status Dashboard Widget
+User asks: "Create a metric card that shows a number with label and icon"
+Response approach:
+1. Create MetricCard with props: title, value, icon, trend
+2. Style with Tailwind using responsive sizing
+3. Add trend indicator (up/down arrow with color)
+4. Show usage in a dashboard grid
+
+## Notes
+- Always extend native HTML attributes (React.ButtonHTMLAttributes, etc.)
+- Use the cn() utility to merge Tailwind classes safely
+- Every interactive element must be keyboard accessible
+- Add aria-label to icon-only buttons
+- Use `as const` for config objects to get literal type inference
+- Test components in isolation before integrating into pages

package/templates/bundle-frontend-spa/skills/component-design/references/accessibility-checklist.md

@@ -0,0 +1,41 @@
+# Accessibility Checklist
+
+## Interactive Elements
+- [ ] All buttons have visible text or `aria-label`
+- [ ] Icon-only buttons have `aria-label` describing the action
+- [ ] Links have descriptive text (not "click here")
+- [ ] Focus states are visible (outline or ring)
+- [ ] Tab order follows visual layout
+
+## Forms
+- [ ] Every input has a `<label>` with matching `htmlFor`/`id`
+- [ ] Required fields are marked with `aria-required="true"`
+- [ ] Error messages are linked with `aria-describedby`
+- [ ] Form validation errors are announced to screen readers
+
+## Modals/Dialogs
+- [ ] Uses `role="dialog"` and `aria-modal="true"`
+- [ ] Focus is trapped inside the dialog
+- [ ] Escape key closes the dialog
+- [ ] Focus returns to trigger element on close
+
+## Loading States
+- [ ] Loading spinners have `aria-busy="true"` on container
+- [ ] Loading announcements use `aria-live="polite"`
+
+## Images
+- [ ] Decorative images have `alt=""`
+- [ ] Informative images have descriptive `alt` text
+
+## Color
+- [ ] Text contrast ratio is at least 4.5:1 (normal text)
+- [ ] Information is not conveyed by color alone
+- [ ] Focus indicators have 3:1 contrast ratio
+
+## Testing
+```bash
+# Run axe accessibility audit
+npx @axe-core/cli http://localhost:5173
+
+# Or in browser: install axe DevTools extension
+```

package/templates/bundle-frontend-spa/skills/component-design/references/tailwind-patterns.md

@@ -0,0 +1,65 @@
+# Tailwind CSS Common Patterns
+
+## Flexbox Layouts
+```html
+<!-- Center content -->
+<div class="flex items-center justify-center">
+
+<!-- Space between items -->
+<div class="flex items-center justify-between">
+
+<!-- Stack vertically with gap -->
+<div class="flex flex-col gap-4">
+
+<!-- Inline items with wrap -->
+<div class="flex flex-wrap gap-2">
+```
+
+## Grid Layouts
+```html
+<!-- Responsive grid -->
+<div class="grid grid-cols-1 sm:grid-cols-2 lg:grid-cols-4 gap-4">
+
+<!-- Sidebar + main -->
+<div class="grid grid-cols-[250px_1fr]">
+
+<!-- Auto-fill responsive -->
+<div class="grid grid-cols-[repeat(auto-fill,minmax(300px,1fr))] gap-4">
+```
+
+## Common Component Patterns
+```html
+<!-- Card -->
+<div class="rounded-lg border bg-white shadow-sm p-4">
+
+<!-- Badge -->
+<span class="px-2 py-1 rounded-full text-xs font-medium bg-blue-100 text-blue-700">
+
+<!-- Input -->
+<input class="w-full rounded border border-gray-300 px-3 py-2 focus:outline-none focus:ring-2 focus:ring-blue-500" />
+
+<!-- Overlay/Modal backdrop -->
+<div class="fixed inset-0 bg-black/50 flex items-center justify-center">
+```
+
+## Animations
+```html
+<!-- Pulse (loading skeleton) -->
+<div class="animate-pulse bg-gray-200 rounded h-4 w-3/4">
+
+<!-- Spin (loading spinner) -->
+<div class="animate-spin h-5 w-5 border-2 border-current border-t-transparent rounded-full">
+
+<!-- Fade in -->
+<div class="animate-in fade-in duration-200">
+```
+
+## Responsive Breakpoints
+| Prefix | Min-width | Target |
+|---|---|---|
+| (none) | 0px | Mobile (default) |
+| `sm:` | 640px | Landscape mobile |
+| `md:` | 768px | Tablet |
+| `lg:` | 1024px | Desktop |
+| `xl:` | 1280px | Wide desktop |
+| `2xl:` | 1536px | Ultra-wide |