aiox-core 5.0.2 → 5.0.3

package/pro/squads/design/tasks/f3-derive-components.md

@@ -0,0 +1,145 @@
+# f3-derive-components
+
+> **Phase 3, Step 8** — Derivar componentes restantes seguindo padroes estabelecidos nas Fases 1 e 2.
+
+## Metadata
+
+```yaml
+task:
+  id: f3-derive-components
+  phase: 3
+  step: 8
+  agent: ds-foundations-lead
+  depends_on: f2-qa-base-components (PASS)
+  blocking: false
+  next: f3-qa-derived-components
+```
+
+## Objetivo
+
+Atualizar os componentes shadcn restantes (alem dos base) aplicando os padroes visuais e tokens estabelecidos nas Fases 1 e 2. Esta fase e mais autonoma — o agente aplica os padroes sem precisar de input novo do Figma para cada componente.
+
+## Logica de Derivacao
+
+Os padroes extraidos dos componentes base servem como guia:
+
+| Padrao | Fonte | Aplicacao |
+|---|---|---|
+| Border radius | Button, Card | Todos os containers e inputs |
+| Transition | Button | Todos os interativos |
+| Shadow | Card | Containers elevados |
+| Focus ring | Input, Button | Todos os focusaveis |
+| Padding scale | Button, Card | Componentes de tamanho similar |
+| Typography | Badge, Alert | Componentes de texto |
+
+**Regra:** Se Button usa `rounded-lg`, Dialog tambem usa `rounded-lg`. Se Input usa `transition-all duration-200`, Select tambem usa.
+
+## Grupos de Componentes
+
+### Forms
+
+| Componente | Arquivo | Derivar de |
+|---|---|---|
+| Select | `components/ui/select.tsx` | Input (border, focus, padding) |
+| Checkbox | `components/ui/checkbox.tsx` | Input (focus ring), Button (radius) |
+| RadioGroup | `components/ui/radio-group.tsx` | Checkbox (pattern) |
+| Switch | `components/ui/switch.tsx` | Button (transition), Input (focus) |
+| Slider | `components/ui/slider.tsx` | Input (track), Button (thumb) |
+| Textarea | `components/ui/textarea.tsx` | Input (direct extension) |
+| Form | `components/ui/form.tsx` | Layout only (minimal changes) |
+| Label | `components/ui/label.tsx` | Typography tokens |
+
+### Overlays
+
+| Componente | Arquivo | Derivar de |
+|---|---|---|
+| Drawer | `components/ui/drawer.tsx` | Dialog (backdrop, container) |
+| Sheet | `components/ui/sheet.tsx` | Dialog (overlay pattern) |
+| Popover | `components/ui/popover.tsx` | Card (container), Dialog (overlay) |
+| Tooltip | `components/ui/tooltip.tsx` | Badge (compact), Popover (overlay) |
+| HoverCard | `components/ui/hover-card.tsx` | Card + Popover |
+| DropdownMenu | `components/ui/dropdown-menu.tsx` | Popover (container) |
+| ContextMenu | `components/ui/context-menu.tsx` | DropdownMenu (same pattern) |
+| Menubar | `components/ui/menubar.tsx` | DropdownMenu (same pattern) |
+| Command | `components/ui/command.tsx` | Dialog + Input |
+| AlertDialog | `components/ui/alert-dialog.tsx` | Dialog (direct extension) |
+
+### Navigation
+
+| Componente | Arquivo | Derivar de |
+|---|---|---|
+| Tabs | `components/ui/tabs.tsx` | Button (interactive), Badge (indicator) |
+| Breadcrumb | `components/ui/breadcrumb.tsx` | Typography, muted colors |
+| NavigationMenu | `components/ui/navigation-menu.tsx` | Button + Popover |
+| Pagination | `components/ui/pagination.tsx` | Button (page numbers) |
+| Sidebar | `components/ui/sidebar.tsx` | Sidebar tokens, Button |
+
+### Data Display
+
+| Componente | Arquivo | Derivar de |
+|---|---|---|
+| Table | `components/ui/table.tsx` | Card (container), border tokens |
+| Accordion | `components/ui/accordion.tsx` | Card (container), Button (trigger) |
+| Carousel | `components/ui/carousel.tsx` | Card + Button (controls) |
+| Progress | `components/ui/progress.tsx` | Primary token (fill) |
+| Calendar | `components/ui/calendar.tsx` | Button (days), Card (container) |
+| Avatar | `components/ui/avatar.tsx` | Badge (shape), primary tokens |
+| AspectRatio | `components/ui/aspect-ratio.tsx` | Container only (minimal) |
+| Collapsible | `components/ui/collapsible.tsx` | Accordion (same pattern) |
+| Resizable | `components/ui/resizable.tsx` | Border tokens |
+| ScrollArea | `components/ui/scroll-area.tsx` | Border/muted tokens |
+| Separator | `components/ui/separator.tsx` | Border token |
+| Skeleton | `components/ui/skeleton.tsx` | Muted token |
+
+### Feedback
+
+| Componente | Arquivo | Derivar de |
+|---|---|---|
+| Toast/Sonner | `components/ui/sonner.tsx` | Alert (feedback pattern) |
+| Toggle | `components/ui/toggle.tsx` | Button (interactive) |
+| ToggleGroup | `components/ui/toggle-group.tsx` | Toggle (group pattern) |
+
+## Execution Steps
+
+### Step 1: Extrair Padroes dos Componentes Base
+
+Ler os componentes base adaptados e extrair padroes:
+
+```yaml
+patterns:
+  radius: "rounded-lg"           # from Button, Card
+  transition: "transition-all duration-200"  # from Button
+  shadow: "shadow-sm"            # from Card
+  focus_ring: "focus-visible:ring-2 focus-visible:ring-ring"  # from Input
+  border: "border"               # from Card, Input
+  disabled: "disabled:opacity-50 disabled:pointer-events-none"  # from Button
+```
+
+### Step 2: Aplicar por Grupo
+
+Processar cada grupo na ordem: Forms → Overlays → Navigation → Data Display → Feedback.
+
+Para cada componente:
+1. Ler arquivo atual
+2. Identificar classes Tailwind que divergem dos padroes
+3. Substituir para manter consistencia
+4. Nao alterar estrutura/props/accessibility
+
+### Step 3: Documentar Mudancas
+
+Log de mudancas por componente (apenas componentes que foram alterados).
+
+## Validacao
+
+- [ ] Todos os componentes renderizam sem erros
+- [ ] Consistencia visual cross-component
+- [ ] Tokens semanticos usados em todos
+
+## Output
+
+- Componentes modificados em `components/ui/`
+- Log de mudancas consolidado
+
+## Related Checklists
+
+- `squads/design/checklists/component-adaptation-checklist.md`

package/pro/squads/design/tasks/f3-qa-derived-components.md

@@ -0,0 +1,101 @@
+# f3-qa-derived-components
+
+> **Phase 3, Step 9** — QA gate final de todos os componentes. Gate de conclusao do pipeline.
+
+## Metadata
+
+```yaml
+task:
+  id: f3-qa-derived-components
+  phase: 3
+  step: 9
+  agent: ds-foundations-lead
+  depends_on: f3-derive-components
+  blocking: true
+  gate: true
+  final: true
+```
+
+## Objetivo
+
+Validar TODOS os componentes shadcn (base + derivados) como um conjunto coeso, garantindo consistencia visual cross-component, acessibilidade, e dark mode.
+
+## QA Checklist — Batch Validation
+
+### Por Componente (todos)
+
+- [ ] Importa sem erros de TypeScript
+- [ ] Renderiza sem runtime errors
+- [ ] Props API inalterada
+- [ ] Tokens semanticos (sem hardcoded colors)
+- [ ] Dark mode funcional
+- [ ] Focus-visible presente (componentes interativos)
+
+### Consistencia Cross-Component
+
+- [ ] **Radius:** Mesmo border-radius para componentes de mesma categoria
+- [ ] **Transitions:** Mesma duracao e easing em todos os interativos
+- [ ] **Shadows:** Escala consistente (none → sm → md → lg)
+- [ ] **Focus ring:** Mesmo estilo em todos os focusaveis
+- [ ] **Disabled state:** Mesmo padrao visual em todos
+- [ ] **Padding scale:** Proporcional entre tamanhos (sm, md, lg)
+- [ ] **Typography:** Mesmos font-size/weight para elementos similares
+
+### Acessibilidade — Batch
+
+- [ ] Todos os pares foreground/background passam WCAG AA (4.5:1)
+- [ ] Todos os componentes interativos tem focus-visible
+- [ ] Nenhum ARIA attribute removido
+- [ ] Keyboard navigation funcional em Forms e Navigation components
+
+### Dark Mode — Batch
+
+- [ ] Todos os componentes adaptam em `.dark`
+- [ ] Contraste mantido em dark mode
+- [ ] Cores de feedback (destructive, warning, info, success) visiveis em ambos os modos
+
+### Integracao
+
+- [ ] `npm run dev` executa sem erros
+- [ ] Nenhum warning de Tailwind sobre classes desconhecidas
+- [ ] `@theme inline` bridge cobre todas as variaveis usadas
+
+## Grupos de Validacao
+
+| Grupo | Componentes | Status |
+|---|---|---|
+| Forms | Select, Checkbox, RadioGroup, Switch, Slider, Textarea, Form, Label | [ ] |
+| Overlays | Dialog, Drawer, Sheet, Popover, Tooltip, HoverCard, DropdownMenu, ContextMenu, Menubar, Command, AlertDialog | [ ] |
+| Navigation | Tabs, Breadcrumb, NavigationMenu, Pagination, Sidebar | [ ] |
+| Data Display | Table, Accordion, Carousel, Progress, Calendar, Avatar, Collapsible, Resizable, ScrollArea, Separator, Skeleton | [ ] |
+| Feedback | Alert, Toast/Sonner, Toggle, ToggleGroup | [ ] |
+| Base (re-check) | Button, Input, Badge, Card | [ ] |
+
+## Verdicts
+
+| Verdict | Condicao | Acao |
+|---------|----------|------|
+| **PASS** | Todos os checks ok | Pipeline completo |
+| **PASS com observacoes** | Checks criticos ok, minor visual diffs documentados | Pipeline completo com notas |
+| **FAIL** | API quebrada, acessibilidade comprometida, inconsistencia grave | Retornar para f3-derive-components |
+
+## Metricas de Conclusao
+
+Ao final, reportar:
+
+- Total de componentes adaptados: X / 56
+- Tokens customizados: X (core) + X (extensoes)
+- Checks de contraste WCAG: X passed / X total
+- Tempo total do pipeline: (registrar)
+
+## Output
+
+Report final de QA com:
+- Resultado por grupo
+- Metricas de conclusao
+- Lista de observacoes (se houver)
+- Verdict final
+
+## Related Checklists
+
+- `squads/design/checklists/component-adaptation-checklist.md`

package/pro/squads/design/tasks/focus-order-audit.md

@@ -0,0 +1,450 @@
+# Task: focus-order-audit
+
+> **Command:** `*focus-order {path}`
+> **Agent:** Brad Frost (Design System Architect)
+> **Purpose:** Validate keyboard navigation, tab order, and focus management
+> **Execution Type:** `Agent`
+> **Dependencies:** depends_on: `[]` · enables: `[]` · workflow: `accessibility`
+
+---
+
+## Overview
+
+Comprehensive keyboard accessibility audit covering:
+1. **Tab order validation** - logical focus sequence
+2. **Focus indicators** - visible, sufficient contrast
+3. **Keyboard traps** - elements that capture focus
+4. **Interactive elements** - all clickable = keyboard accessible
+5. **Focus management** - modals, dialogs, dynamic content
+
+---
+
+## Input
+
+| Parameter | Required | Description |
+|-----------|----------|-------------|
+| `path` | Yes | Directory to audit (e.g., `./app/components`) |
+| `--component` | No | Audit single component |
+| `--generate-map` | No | Generate visual focus order diagram |
+| `--fix` | No | Auto-fix simple issues |
+
+---
+
+## Execution Steps
+
+### Phase 1: Interactive Element Discovery
+
+Find all elements that should be keyboard accessible:
+
+```typescript
+interface InteractiveElement {
+  type: 'native' | 'custom';
+  element: string;            // button, a, div, span, etc.
+  file: string;
+  line: number;
+  hasTabIndex: boolean;
+  tabIndexValue: number | null;
+  hasClickHandler: boolean;
+  hasKeyHandler: boolean;
+  role: string | null;
+  issues: FocusIssue[];
+}
+
+// Elements to scan for
+const nativeInteractive = [
+  'button', 'a[href]', 'input', 'select', 'textarea',
+  '[contenteditable]', 'details', 'summary'
+];
+
+const customInteractive = [
+  // Elements with click handlers
+  'onClick=', '@click=', '(click)=',
+  // Elements with interactive roles
+  'role="button"', 'role="link"', 'role="tab"',
+  'role="menuitem"', 'role="option"', 'role="checkbox"',
+  'role="radio"', 'role="switch"', 'role="slider"'
+];
+```
+
+### Phase 2: Tab Order Analysis
+
+```typescript
+interface TabOrderResult {
+  element: string;
+  file: string;
+  line: number;
+  tabIndex: number;
+  order: number;         // Computed tab order position
+  issues: TabOrderIssue[];
+}
+
+type TabOrderIssue =
+  | 'positive-tabindex'     // tabIndex > 0 (anti-pattern)
+  | 'negative-tabindex'     // tabIndex < 0 on interactive
+  | 'out-of-order'          // Visual vs DOM order mismatch
+  | 'skip-heading'          // Skips heading levels
+  | 'focus-trap-detected';  // Can't tab out
+```
+
+**Tab Order Rules:**
+1. `tabIndex="0"` - Natural order (preferred)
+2. `tabIndex="-1"` - Programmatically focusable only
+3. `tabIndex="1+"` - ANTI-PATTERN (forces order, breaks predictability)
+
+### Phase 3: Focus Indicator Validation
+
+```typescript
+interface FocusIndicator {
+  element: string;
+  file: string;
+  line: number;
+  hasVisibleFocus: boolean;
+  focusStyle: {
+    outline: string | null;
+    boxShadow: string | null;
+    ring: string | null;      // Tailwind ring-*
+    custom: boolean;
+  };
+  contrastRatio: number;      // Focus vs background
+  issues: FocusIndicatorIssue[];
+}
+
+type FocusIndicatorIssue =
+  | 'outline-none-no-replacement'  // outline:none without alternative
+  | 'insufficient-contrast'        // Focus indicator < 3:1
+  | 'too-subtle'                   // Very thin/light focus
+  | 'focus-visible-missing';       // No :focus-visible support
+```
+
+**WCAG 2.2 Focus Requirements:**
+- **2.4.7 Focus Visible (AA):** Focus indicator must be visible
+- **2.4.11 Focus Not Obscured (AA):** Focus not fully hidden by other content
+- **2.4.12 Focus Not Obscured Enhanced (AAA):** Focus not partially hidden
+- **2.4.13 Focus Appearance (AAA):** Minimum 2px perimeter, 3:1 contrast
+
+### Phase 4: Keyboard Handler Validation
+
+```typescript
+interface KeyboardHandler {
+  element: string;
+  file: string;
+  line: number;
+  handlers: {
+    onClick: boolean;
+    onKeyDown: boolean;
+    onKeyUp: boolean;
+    onKeyPress: boolean;  // Deprecated
+  };
+  expectedKeys: string[];  // Enter, Space, Arrow*, Escape
+  issues: KeyboardIssue[];
+}
+
+type KeyboardIssue =
+  | 'click-only'              // onClick without keyboard handler
+  | 'missing-enter-space'     // Button without Enter/Space
+  | 'missing-escape'          // Modal/dialog without Escape
+  | 'missing-arrows'          // Menu/tabs without arrow keys
+  | 'using-deprecated';       // onKeyPress instead of onKeyDown
+```
+
+**Expected Keyboard Patterns:**
+
+| Element/Role | Required Keys |
+|--------------|---------------|
+| Button | Enter, Space |
+| Link | Enter |
+| Menu item | Enter, Arrow Up/Down |
+| Tab | Enter, Arrow Left/Right |
+| Modal/Dialog | Escape (close) |
+| Dropdown | Escape, Arrow Up/Down |
+| Slider | Arrow Left/Right |
+| Checkbox | Space |
+| Radio | Space, Arrow Up/Down |
+
+### Phase 5: Focus Trap Detection
+
+```typescript
+interface FocusTrap {
+  element: string;
+  file: string;
+  line: number;
+  trapType: 'intentional' | 'unintentional';
+  hasEscapeRoute: boolean;
+  issues: FocusTrapIssue[];
+}
+
+// Intentional traps (OK if implemented correctly)
+const intentionalTraps = [
+  'role="dialog"',
+  'role="alertdialog"',
+  'aria-modal="true"'
+];
+
+// Patterns that often cause unintentional traps
+const trapPatterns = [
+  'tabIndex="-1".*tabIndex="-1"',  // Sequential -1s
+  'onBlur.*focus',                  // Focus on blur
+  'useEffect.*focus'                // Auto-focus loops
+];
+```
+
+### Phase 6: Modal/Dialog Focus Management
+
+```typescript
+interface ModalFocusAudit {
+  component: string;
+  file: string;
+  checks: {
+    trapsFocus: boolean;           // Focus stays in modal
+    restoresFocus: boolean;        // Returns focus on close
+    firstFocusable: string | null; // First element focused
+    closesOnEscape: boolean;       // Escape key closes
+    hasAriaModal: boolean;         // aria-modal="true"
+  };
+  issues: ModalFocusIssue[];
+}
+```
+
+---
+
+## Output
+
+### 1. Focus Order Report
+
+```markdown
+# Focus Order Audit Report
+
+**Path:** ./app/components
+**Date:** 2026-01-05
+**Components Scanned:** 156
+
+## Summary
+
+| Category | Issues | Critical | Serious | Moderate |
+|----------|--------|----------|---------|----------|
+| Tab Order | 8 | 2 | 4 | 2 |
+| Focus Indicators | 12 | 5 | 4 | 3 |
+| Keyboard Handlers | 15 | 6 | 7 | 2 |
+| Focus Traps | 3 | 1 | 2 | 0 |
+| **Total** | **38** | **14** | **17** | **7** |
+
+## Critical Issues
+
+### 1. ❌ Click-only interactive element
+
+**File:** `app/components/ui/Card.tsx:45`
+**Element:** `<div onClick={handleClick}>`
+**Problem:** Has click handler but no keyboard support
+
+**Current:**
+```tsx
+<div onClick={handleClick} className="cursor-pointer">
+  Click me
+</div>
+```
+
+**Fix:**
+```tsx
+<button onClick={handleClick} className="cursor-pointer">
+  Click me
+</button>
+// OR if div is required:
+<div
+  role="button"
+  tabIndex={0}
+  onClick={handleClick}
+  onKeyDown={(e) => {
+    if (e.key === 'Enter' || e.key === ' ') {
+      e.preventDefault();
+      handleClick();
+    }
+  }}
+  className="cursor-pointer"
+>
+  Click me
+</div>
+```
+
+---
+
+### 2. ❌ Focus indicator removed without replacement
+
+**File:** `app/components/ui/Button.tsx:23`
+**Element:** `button`
+**Problem:** `outline: none` without visible focus alternative
+
+**Current:**
+```css
+button:focus {
+  outline: none;
+}
+```
+
+**Fix:**
+```css
+button:focus-visible {
+  outline: 2px solid var(--color-focus-ring);
+  outline-offset: 2px;
+}
+```
+
+---
+
+### 3. ❌ Positive tabIndex (anti-pattern)
+
+**File:** `app/components/forms/SearchInput.tsx:12`
+**Element:** `<input tabIndex={1}>`
+**Problem:** Positive tabIndex breaks natural tab order
+
+**Fix:** Remove tabIndex or use tabIndex={0}
+
+---
+
+### 4. ❌ Modal without focus trap
+
+**File:** `app/components/modals/ConfirmDialog.tsx:8`
+**Element:** `Dialog`
+**Problems:**
+- Focus can escape modal with Tab
+- No Escape key handler
+- Focus not restored on close
+
+**Required Implementation:**
+- Add focus trap (first/last element loop)
+- Add onKeyDown for Escape
+- Store activeElement before open, restore on close
+
+---
+
+## Tab Order Map
+
+```
+┌──────────────────────────────────────┐
+│ 1. [Skip to content]                 │
+│ 2. [Logo] → 3. [Nav: Home]           │
+│ 4. [Nav: Products] → 5. [Nav: About] │
+│ 6. [Search input]                    │
+│ 7. [Main content starts]             │
+│ ...                                  │
+│ ⚠️ 15. [Card div] - NOT FOCUSABLE   │
+│ 16. [Footer link 1]                  │
+└──────────────────────────────────────┘
+```
+
+## Focus Indicator Inventory
+
+| Component | Focus Style | Contrast | Status |
+|-----------|-------------|----------|--------|
+| Button | ring-2 ring-primary | 4.2:1 | ✅ Pass |
+| Input | ring-2 ring-blue-500 | 3.8:1 | ✅ Pass |
+| Link | underline + color | 3.1:1 | ✅ Pass |
+| Card | outline: none | N/A | ❌ Fail |
+| Tab | border-bottom | 2.1:1 | ⚠️ Low |
+
+## Recommendations
+
+1. **Replace all `<div onClick>` with `<button>`** - 6 occurrences
+2. **Add focus-visible styles** - 5 components missing
+3. **Remove positive tabIndex values** - 2 occurrences
+4. **Implement focus trap in modals** - 2 modals affected
+5. **Add Escape key handlers** - 3 dialogs missing
+```
+
+---
+
+## Auto-Fix (with --fix flag)
+
+```typescript
+// Auto-fixable patterns
+
+// 1. Add tabIndex to onClick divs
+- <div onClick={fn}>
++ <div onClick={fn} tabIndex={0} role="button" onKeyDown={handleKeyDown}>
+
+// 2. Add focus-visible where outline:none
+- button:focus { outline: none; }
++ button:focus-visible { outline: 2px solid var(--color-focus); outline-offset: 2px; }
+
+// 3. Convert positive tabIndex
+- <input tabIndex={1}>
++ <input tabIndex={0}>
+```
+
+---
+
+## Integration
+
+```bash
+# Full focus audit
+*focus-order ./app/components
+
+# Single component
+*focus-order ./app/components --component Modal
+
+# Generate visual map
+*focus-order ./app/components --generate-map
+
+# Auto-fix simple issues
+*focus-order ./app/components --fix
+
+# As part of full audit
+*a11y-audit ./app/components --scope keyboard
+```
+
+---
+
+## Failure Handling
+
+- **No interactive elements discovered:** Verify scan includes all file types (.tsx, .jsx, .vue, .html). If truly zero, report "No interactive elements found"
+- **Focus indicator detection misses Tailwind ring-* classes:** Expand scan patterns to include ring-*, outline-*, focus:*, focus-visible:* Tailwind utilities
+- **Tab order mapping fails for dynamic content:** Document dynamic sections as "tab order varies at runtime — requires manual testing" in report
+- **Auto-fix introduces breaking changes:** Generate fix suggestions as code comments instead of applying directly. Always preserve original code
+
+## State Update
+
+```yaml
+focus_order_audit:
+  last_run: "2026-01-05T14:30:00Z"
+  path: "./app/components"
+  results:
+    total_issues: 38
+    critical: 14
+    serious: 17
+    moderate: 7
+  categories:
+    tab_order: 8
+    focus_indicators: 12
+    keyboard_handlers: 15
+    focus_traps: 3
+  anti_patterns:
+    click_only_divs: 6
+    positive_tabindex: 2
+    outline_none: 5
+  auto_fixed: 0
+  next_action: "Fix 14 critical keyboard issues"
+```
+
+---
+
+## Success Criteria
+
+- [ ] All interactive elements discovered (native + custom with click/key handlers)
+- [ ] Tab order validated as logical and follows visual layout
+- [ ] Focus indicators verified visible with sufficient contrast (3:1 minimum)
+- [ ] Zero keyboard traps detected (or all documented with workarounds)
+- [ ] Custom interactive elements have keyboard equivalents for mouse events
+- [ ] Modal/dialog focus management validated (trap + restore)
+- [ ] Report generated with file:line references for every finding
+
+---
+
+**Brad says:** "If you can't Tab to it, keyboard users can't use it. Zero click-only elements."
+
+
+## Related Checklists
+
+- `squads/design/checklists/ds-accessibility-wcag-checklist.md`
+- `squads/design/checklists/ds-a11y-release-gate-checklist.md`
+
+## Process Guards
+- **On Fail:** Stop execution, capture evidence, and return remediation steps before proceeding.