aiox-core 5.0.2 → 5.0.4

package/pro/squads/design/tasks/f1-map-tokens-to-shadcn.md

@@ -0,0 +1,145 @@
+# f1-map-tokens-to-shadcn
+
+> **Phase 1, Step 2** — Mapear tokens normalizados do Figma para CSS vars do shadcn em OKLch.
+
+## Metadata
+
+```yaml
+task:
+  id: f1-map-tokens-to-shadcn
+  phase: 1
+  step: 2
+  agent: ds-foundations-lead
+  depends_on: f1-ingest-figma-tokens
+  blocking: false
+  next: f1-apply-foundations
+```
+
+## Objetivo
+
+Transformar os tokens normalizados na Step 1 em mapeamento direto para as CSS variables que o shadcn/UI usa, convertendo todos os valores de cor para OKLch.
+
+## shadcn CSS Variables (Target)
+
+Todas estas variaveis DEVEM ter mapeamento:
+
+### Core (obrigatorio)
+
+| CSS Variable | Descricao | Padrao Light | Padrao Dark |
+|---|---|---|---|
+| `--background` | Fundo da pagina | oklch(1 0 0) | oklch(0.145 0 0) |
+| `--foreground` | Texto principal | oklch(0.145 0 0) | oklch(0.985 0 0) |
+| `--card` | Fundo de cards | oklch(1 0 0) | oklch(0.205 0 0) |
+| `--card-foreground` | Texto em cards | oklch(0.145 0 0) | oklch(0.985 0 0) |
+| `--popover` | Fundo de popovers | oklch(1 0 0) | oklch(0.205 0 0) |
+| `--popover-foreground` | Texto em popovers | oklch(0.145 0 0) | oklch(0.985 0 0) |
+| `--primary` | Cor primaria | oklch(0.205 0 0) | oklch(0.922 0 0) |
+| `--primary-foreground` | Texto sobre primaria | oklch(0.985 0 0) | oklch(0.205 0 0) |
+| `--secondary` | Cor secundaria | oklch(0.97 0 0) | oklch(0.269 0 0) |
+| `--secondary-foreground` | Texto sobre secundaria | oklch(0.205 0 0) | oklch(0.985 0 0) |
+| `--muted` | Fundo atenuado | oklch(0.97 0 0) | oklch(0.269 0 0) |
+| `--muted-foreground` | Texto atenuado | oklch(0.556 0 0) | oklch(0.708 0 0) |
+| `--accent` | Cor de destaque | oklch(0.97 0 0) | oklch(0.269 0 0) |
+| `--accent-foreground` | Texto sobre destaque | oklch(0.205 0 0) | oklch(0.985 0 0) |
+| `--destructive` | Cor de erro/perigo | oklch(0.577 0.245 27.325) | oklch(0.704 0.191 22.216) |
+| `--border` | Cor de bordas | oklch(0.922 0 0) | oklch(1 0 0 / 10%) |
+| `--input` | Borda de inputs | oklch(0.922 0 0) | oklch(1 0 0 / 15%) |
+| `--ring` | Focus ring | oklch(0.708 0 0) | oklch(0.556 0 0) |
+| `--radius` | Radius base | 0.625rem | (same) |
+
+### Chart (manter default se Figma nao fornecer)
+
+| CSS Variable | Descricao |
+|---|---|
+| `--chart-1` through `--chart-5` | Cores para graficos |
+
+### Sidebar (manter default se Figma nao fornecer)
+
+| CSS Variable | Descricao |
+|---|---|
+| `--sidebar` | Fundo do sidebar |
+| `--sidebar-foreground` | Texto do sidebar |
+| `--sidebar-primary` / `--sidebar-primary-foreground` | Itens ativos |
+| `--sidebar-accent` / `--sidebar-accent-foreground` | Hover/destaque |
+| `--sidebar-border` | Bordas do sidebar |
+| `--sidebar-ring` | Focus ring do sidebar |
+
+## Execution Steps
+
+### Step 1: Mapear Tokens Semanticos
+
+Para cada token Figma normalizado, encontrar a correspondencia shadcn:
+
+```
+Figma "brand/primary" → --primary
+Figma "brand/primary-text" → --primary-foreground
+Figma "surface/default" → --background
+Figma "text/primary" → --foreground
+Figma "surface/card" → --card
+Figma "feedback/error" → --destructive
+...
+```
+
+**Regra:** Se o Figma usar nomes diferentes, perguntar ao usuario para confirmar o mapeamento.
+
+### Step 2: Converter para OKLch
+
+Todos os valores de cor devem ser convertidos para formato OKLch:
+
+- `#3B82F6` → `oklch(0.623 0.214 259.815)`
+- `rgb(239, 68, 68)` → `oklch(0.577 0.245 27.325)`
+- `hsl(222, 47%, 31%)` → converter para oklch
+
+**Ferramenta:** Usar formula de conversao ou solicitar que o usuario use um conversor.
+
+### Step 3: Identificar Extensoes
+
+Tokens que o Figma tem mas o shadcn nao:
+
+| Token Figma | CSS Variable Proposta | Nota |
+|---|---|---|
+| `feedback/warning` | `--warning` / `--warning-foreground` | Extensao |
+| `feedback/info` | `--info` / `--info-foreground` | Extensao |
+| `feedback/success` | `--success` / `--success-foreground` | Extensao |
+
+Extensoes devem seguir o padrao shadcn: `--{role}` + `--{role}-foreground`.
+
+### Step 4: Gerar Tabela de Mapeamento
+
+Produzir tabela completa:
+
+| Figma Token | CSS Variable | Tailwind Utility | Light Value | Dark Value |
+|---|---|---|---|---|
+| brand/primary | --primary | bg-primary | oklch(...) | oklch(...) |
+| ... | ... | ... | ... | ... |
+
+### Step 5: Validar Completude
+
+- [ ] Todos os 18 core tokens mapeados
+- [ ] Todos os 5 chart tokens mapeados (ou defaults mantidos)
+- [ ] Todos os 8 sidebar tokens mapeados (ou defaults mantidos)
+- [ ] --radius mapeado
+- [ ] Extensoes documentadas
+- [ ] Dark mode mapeado para cada token
+
+## Output
+
+- `squads/design/data/token-mapping-reference.md` — Tabela completa de mapeamento
+- Dados de mapeamento para a proxima task (f1-apply-foundations)
+
+## Conversao OKLch Reference
+
+Para converter cores, usar a formula:
+
+1. Converter para sRGB linear
+2. Converter para CIEXYZ (D65)
+3. Converter para OKLab
+4. Converter para OKLch (polar form)
+
+Formato: `oklch(L C H)` onde L=[0,1], C=[0,0.4], H=[0,360]
+
+Para alfa: `oklch(L C H / alpha%)`
+
+## Related Checklists
+
+- `squads/design/checklists/token-mapping-checklist.md`

package/pro/squads/design/tasks/f1-qa-foundations.md

@@ -0,0 +1,95 @@
+# f1-qa-foundations
+
+> **Phase 1, Step 4** — QA gate de foundations e tokens. BLOQUEANTE para Phase 2.
+
+## Metadata
+
+```yaml
+task:
+  id: f1-qa-foundations
+  phase: 1
+  step: 4
+  agent: ds-foundations-lead
+  depends_on: f1-apply-foundations
+  blocking: true
+  gate: true
+  next: f2-ingest-base-components (se PASS)
+```
+
+## Objetivo
+
+Validar que todos os tokens foram aplicados corretamente em `globals.css`, que nenhum componente shadcn ficou orfao, e que dark mode e acessibilidade de contraste estao ok.
+
+## QA Checklist
+
+### Token Completude
+
+- [ ] Todos os 18 core tokens shadcn presentes em `:root` (`--background`, `--foreground`, `--card`, `--card-foreground`, `--popover`, `--popover-foreground`, `--primary`, `--primary-foreground`, `--secondary`, `--secondary-foreground`, `--muted`, `--muted-foreground`, `--accent`, `--accent-foreground`, `--destructive`, `--border`, `--input`, `--ring`)
+- [ ] `--radius` presente em `:root`
+- [ ] 5 chart tokens presentes (`--chart-1` through `--chart-5`)
+- [ ] 8 sidebar tokens presentes
+- [ ] Nenhum token shadcn original removido sem substituto
+
+### Formato de Valores
+
+- [ ] Todos os valores de cor em formato OKLch valido
+- [ ] OKLch L entre 0 e 1
+- [ ] OKLch C >= 0 (tipicamente 0 a 0.4)
+- [ ] OKLch H entre 0 e 360 (quando C > 0)
+- [ ] Valores alpha em formato `/ percentage` quando usado
+
+### Dark Mode
+
+- [ ] Todos os tokens de `:root` tem correspondente em `.dark`
+- [ ] Valores dark sao visualmente distintos dos light
+- [ ] Inversao logica correta (background claro → escuro, foreground escuro → claro)
+
+### @theme inline Bridge
+
+- [ ] Todas as `--color-*` vars mapeiam para `var(--*)` correspondente
+- [ ] Extensoes (warning, info, success) tem bridge em `@theme inline`
+- [ ] Radius scale mantido (`--radius-sm` through `--radius-4xl`)
+- [ ] Font vars mantidas (`--font-sans`, `--font-mono`)
+
+### Acessibilidade — Contraste WCAG AA
+
+Verificar contraste minimo (4.5:1 para texto normal, 3:1 para texto grande):
+
+- [ ] `--foreground` sobre `--background` >= 4.5:1
+- [ ] `--primary-foreground` sobre `--primary` >= 4.5:1
+- [ ] `--secondary-foreground` sobre `--secondary` >= 4.5:1
+- [ ] `--muted-foreground` sobre `--muted` >= 3:1 (texto atenuado)
+- [ ] `--accent-foreground` sobre `--accent` >= 4.5:1
+- [ ] `--card-foreground` sobre `--card` >= 4.5:1
+- [ ] `--popover-foreground` sobre `--popover` >= 4.5:1
+- [ ] `--destructive` sobre `--background` >= 3:1 (feedback color)
+
+**Repetir checks acima para dark mode.**
+
+### Integridade Estrutural
+
+- [ ] Imports inalterados (`@import "tailwindcss"`, `@import "tw-animate-css"`, `@import "shadcn/tailwind.css"`)
+- [ ] `@custom-variant dark` inalterado
+- [ ] `@layer base` block inalterado
+- [ ] Arquivo CSS parseia sem erros de sintaxe
+
+### Componentes
+
+- [ ] Nenhum componente shadcn referencia variavel inexistente
+- [ ] `npm run dev` executa sem erros (se possivel verificar)
+
+## Verdicts
+
+| Verdict | Condicao | Acao |
+|---------|----------|------|
+| **PASS** | Todos os checks criticos ok | Prosseguir para Phase 2 |
+| **PASS com observacoes** | Checks criticos ok, warnings em contraste | Documentar e prosseguir |
+| **FAIL** | Qualquer token ausente, valor invalido, ou estrutura quebrada | Retornar para f1-apply-foundations |
+
+## Output
+
+Report de QA com resultado por check e verdict final.
+
+## Related Checklists
+
+- `squads/design/checklists/token-mapping-checklist.md`

package/pro/squads/design/tasks/f2-adapt-shadcn-components.md

@@ -0,0 +1,155 @@
+# f2-adapt-shadcn-components
+
+> **Phase 2, Step 6** — Adaptar componentes shadcn para o visual do Figma.
+
+## Metadata
+
+```yaml
+task:
+  id: f2-adapt-shadcn-components
+  phase: 2
+  step: 6
+  agent: ds-foundations-lead
+  depends_on: f2-ingest-base-components
+  blocking: false
+  next: f2-qa-base-components
+```
+
+## Objetivo
+
+Modificar as classes Tailwind dos componentes shadcn/UI base para corresponder ao visual do Figma, preservando logica, props API e acessibilidade.
+
+## Regras de Adaptacao
+
+### PRESERVAR (nunca alterar)
+
+- Estrutura JSX e composicao de componentes
+- Todas as props existentes (type, variant, size, etc.)
+- Radix UI primitives e event handlers
+- `data-slot` attributes
+- ARIA attributes e roles
+- Keyboard navigation (onKeyDown handlers)
+- `focus-visible` styles (pode mudar cor, nao remover)
+- `disabled` behavior logic
+- Exports e imports
+
+### MODIFICAR (classes Tailwind apenas)
+
+- Cores: `bg-primary` → confirmar que token corresponde ao Figma
+- Border radius: `rounded-md` → `rounded-lg` (ou valor do Figma)
+- Padding/spacing: `px-4 py-2` → valores do Figma
+- Hover states: `hover:bg-primary/90` → transicao do Figma
+- Focus ring: `focus-visible:ring-2` → estilo do Figma
+- Transitions: `transition-colors` → `transition-all duration-200`
+- Shadows: adicionar se Figma especificar
+- Typography: `text-sm font-medium` → valores do Figma
+
+### NUNCA FAZER
+
+- Adicionar props novas obrigatorias
+- Remover props existentes
+- Mudar a estrutura de arquivos
+- Hardcodar valores de cor (hex, rgb direto)
+- Remover `focus-visible` styles
+- Alterar logica de variantes (cva/class-variance-authority patterns)
+
+## Ordem de Adaptacao
+
+Adaptar na seguinte ordem (simples → composto):
+
+1. **Button** (`components/ui/button.tsx`)
+   - Padrao visual mais critico
+   - Define patterns para todos os outros componentes
+
+2. **Input** (`components/ui/input.tsx`)
+   - Padrao de formularios
+   - Border, focus ring, placeholder styles
+
+3. **Badge** (`components/ui/badge.tsx`)
+   - Componente simples
+   - Valida que tokens semanticos funcionam
+
+4. **Card** (`components/ui/card.tsx`)
+   - Container pattern
+   - Background, border, shadow, padding
+
+5. **Alert** (`components/ui/alert.tsx`)
+   - Feedback pattern
+   - Usa destructive + possiveis extensoes (warning, info)
+
+6. **Dialog** (`components/ui/dialog.tsx`)
+   - Overlay pattern
+   - Backdrop, container, animation
+
+## Execution Steps (por componente)
+
+### Step 1: Ler Componente Atual
+
+```
+Read("components/ui/{component}.tsx")
+```
+
+Entender a estrutura atual: variantes, slots, classes Tailwind.
+
+### Step 2: Comparar com Spec do Figma
+
+Comparar classes Tailwind atuais com spec visual da Step 5.
+
+### Step 3: Gerar Diff de Classes
+
+Documentar mudancas planejadas:
+
+```
+Button variant="default":
+  ANTES: bg-primary text-primary-foreground shadow-xs hover:bg-primary/90
+  DEPOIS: bg-primary text-primary-foreground shadow-sm hover:bg-primary/90 transition-all duration-200
+
+Button variant="outline":
+  ANTES: border bg-background shadow-xs hover:bg-accent hover:text-accent-foreground
+  DEPOIS: border-2 bg-background shadow-none hover:bg-accent hover:text-accent-foreground
+```
+
+### Step 4: Aplicar Mudancas
+
+Editar arquivo com mudancas minimas — alterar apenas classes Tailwind.
+
+### Step 5: Documentar Changelog
+
+Para cada componente adaptado:
+
+```markdown
+## Button — Changelog
+
+### Visual Changes
+- Increased border-radius from rounded-md to rounded-lg
+- Added transition-all duration-200 for smoother hover
+- Changed shadow-xs to shadow-sm for more depth
+- outline variant: border → border-2
+
+### Preserved
+- All 6 variants (default, destructive, outline, secondary, ghost, link)
+- All 4 sizes (default, sm, lg, icon)
+- Radix Slot composition
+- data-slot="button"
+- Focus-visible ring
+- Disabled state behavior
+```
+
+## Validacao por Componente
+
+- [ ] Componente importa e renderiza sem erros
+- [ ] Props API inalterada (TypeScript nao reclama)
+- [ ] Hover state corresponde ao Figma
+- [ ] Focus state tem ring visivel
+- [ ] Disabled state funciona
+- [ ] Dark mode correto
+- [ ] Tokens semanticos usados (sem cores hardcoded)
+
+## Output
+
+- Componentes modificados em `components/ui/`
+- Changelog por componente em `squads/design/data/`
+
+## Related Checklists
+
+- `squads/design/checklists/component-adaptation-checklist.md`

package/pro/squads/design/tasks/f2-ingest-base-components.md

@@ -0,0 +1,148 @@
+# f2-ingest-base-components
+
+> **Phase 2, Step 5** — Receber especificacoes visuais de componentes base do Figma.
+
+## Metadata
+
+```yaml
+task:
+  id: f2-ingest-base-components
+  phase: 2
+  step: 5
+  agent: ds-foundations-lead
+  depends_on: f1-qa-foundations (PASS)
+  blocking: false
+  next: f2-adapt-shadcn-components
+```
+
+## Objetivo
+
+Receber do usuario as especificacoes visuais dos componentes base do Figma (via Dev Mode CSS, screenshots, ou ambos) e extrair propriedades visuais por componente.
+
+## Componentes Base (ordem de prioridade)
+
+1. **Button** — Componente mais usado, define padrao visual
+2. **Input** — Define padrao de formularios
+3. **Badge** — Componente simples, valida tokens
+4. **Card** — Container fundamental
+5. **Alert** — Feedback component
+6. **Dialog** — Overlay fundamental
+
+## Formatos de Input
+
+### CSS do Dev Mode (recomendado)
+
+```css
+/* Button — Default variant */
+background: #3B82F6;
+color: #FFFFFF;
+border-radius: 8px;
+padding: 8px 16px;
+font-size: 14px;
+font-weight: 500;
+
+/* Button — Hover */
+background: #2563EB;
+
+/* Button — Disabled */
+opacity: 0.5;
+```
+
+### Screenshots/Prints
+
+- Imagem do componente em cada estado (default, hover, focus, active, disabled)
+- **REQUER validacao humana** dos valores extraidos
+
+### Ambos (recomendado)
+
+CSS do Dev Mode + screenshot para validacao visual cruzada.
+
+## Execution Steps
+
+### Step 1: Solicitar Input por Componente
+
+Para cada componente base, perguntar:
+
+```
+Componente: Button
+
+Cole o CSS do Dev Mode do Figma para cada variante/estado:
+- Default
+- Hover
+- Focus
+- Active
+- Disabled
+
+(Opcional: cole tambem screenshot para validacao cruzada)
+```
+
+### Step 2: Extrair Propriedades
+
+Para cada componente, extrair:
+
+| Propriedade | Valores por Estado |
+|---|---|
+| `background` | default, hover, focus, active, disabled |
+| `color` (text) | default, hover, focus, active, disabled |
+| `border` | color, width, style |
+| `border-radius` | valor |
+| `padding` | top, right, bottom, left |
+| `font-size` | valor |
+| `font-weight` | valor |
+| `line-height` | valor |
+| `box-shadow` | default, focus |
+| `opacity` | disabled |
+| `transition` | propriedade, duracao, easing |
+
+### Step 3: Mapear para Tokens Semanticos
+
+Relacionar valores visuais com tokens da Phase 1:
+
+```
+Button background → --primary (ja mapeado)
+Button text color → --primary-foreground (ja mapeado)
+Button radius → --radius (ou valor especifico)
+Button hover → variacao de --primary
+```
+
+### Step 4: Documentar Spec
+
+Para cada componente, gerar spec:
+
+```yaml
+component: Button
+variants:
+  default:
+    background: "var(--primary)"
+    color: "var(--primary-foreground)"
+    border-radius: "var(--radius)"
+    padding: "8px 16px"
+  hover:
+    background: "oklch(0.55 0.214 259.815)"  # slightly darker primary
+  focus:
+    ring: "var(--ring)"
+    ring-offset: "2px"
+  disabled:
+    opacity: "0.5"
+    pointer-events: "none"
+sizes:
+  sm: { padding: "4px 12px", font-size: "12px" }
+  md: { padding: "8px 16px", font-size: "14px" }
+  lg: { padding: "12px 24px", font-size: "16px" }
+```
+
+## Validacao
+
+- [ ] Pelo menos Button e Input especificados
+- [ ] Todos os estados basicos cobertos (default, hover, disabled)
+- [ ] Valores podem ser mapeados para tokens existentes
+- [ ] Screenshots confirmam CSS do Dev Mode (se ambos fornecidos)
+
+## Output
+
+- Spec visual por componente (em memoria ou JSON)
+- Lista de componentes prontos para adaptacao
+
+## Related Checklists
+
+- `squads/design/checklists/component-adaptation-checklist.md`

package/pro/squads/design/tasks/f2-qa-base-components.md

@@ -0,0 +1,98 @@
+# f2-qa-base-components
+
+> **Phase 2, Step 7** — QA gate de componentes base. BLOQUEANTE para Phase 3.
+
+## Metadata
+
+```yaml
+task:
+  id: f2-qa-base-components
+  phase: 2
+  step: 7
+  agent: ds-foundations-lead
+  depends_on: f2-adapt-shadcn-components
+  blocking: true
+  gate: true
+  next: f3-derive-components (se PASS)
+```
+
+## Objetivo
+
+Validar que todos os componentes base adaptados estao corretos: renderizam sem erros, mantiveram API, correspondem visualmente ao Figma, e preservaram acessibilidade.
+
+## QA Checklist (por componente)
+
+### Renderizacao
+
+- [ ] Componente importa sem erros de TypeScript
+- [ ] Componente renderiza sem runtime errors
+- [ ] Todas as variantes renderizam corretamente
+
+### Props API
+
+- [ ] Nenhuma prop removida
+- [ ] Nenhuma prop obrigatoria adicionada
+- [ ] Tipos TypeScript inalterados
+- [ ] `className` prop funciona (merge com classes internas)
+
+### Visual — Estados
+
+- [ ] **Default** — Corresponde ao Figma
+- [ ] **Hover** — Transicao visual conforme Figma
+- [ ] **Focus** — Ring visivel, cor correta
+- [ ] **Active/Pressed** — Feedback visual presente
+- [ ] **Disabled** — Visualmente distinto, nao interativo
+
+### Tokens Semanticos
+
+- [ ] Nenhuma cor hardcoded (hex/rgb direto nas classes)
+- [ ] Usa `bg-primary`, `text-foreground`, etc. (semantic tokens)
+- [ ] Tokens customizados via `@theme inline` (se extensoes)
+
+### Acessibilidade
+
+- [ ] ARIA attributes preservados
+- [ ] `data-slot` attributes preservados
+- [ ] Focus ring visivel via teclado (`focus-visible`)
+- [ ] Contraste texto/fundo >= 4.5:1 (WCAG AA)
+- [ ] Keyboard navigation funcional
+
+### Dark Mode
+
+- [ ] Componente adapta corretamente em `.dark`
+- [ ] Contraste mantido em dark mode
+- [ ] Nenhum estado visual "desaparece" em dark mode
+
+### Consistencia Cross-Component
+
+- [ ] Mesmo border-radius entre componentes relacionados
+- [ ] Mesma escala de padding
+- [ ] Mesmas transicoes (duracao, easing)
+- [ ] Mesmos shadow patterns
+
+## Componentes a Validar
+
+| Componente | Arquivo | Status |
+|---|---|---|
+| Button | `components/ui/button.tsx` | [ ] |
+| Input | `components/ui/input.tsx` | [ ] |
+| Badge | `components/ui/badge.tsx` | [ ] |
+| Card | `components/ui/card.tsx` | [ ] |
+| Alert | `components/ui/alert.tsx` | [ ] |
+| Dialog | `components/ui/dialog.tsx` | [ ] |
+
+## Verdicts
+
+| Verdict | Condicao | Acao |
+|---------|----------|------|
+| **PASS** | Todos os checks ok para todos os componentes | Prosseguir para Phase 3 |
+| **PASS com observacoes** | Checks criticos ok, minor visual diffs | Documentar e prosseguir |
+| **FAIL** | API quebrada, acessibilidade comprometida, render error | Retornar para f2-adapt-shadcn-components |
+
+## Output
+
+Report de QA com resultado por componente e verdict final.
+
+## Related Checklists
+
+- `squads/design/checklists/component-adaptation-checklist.md`