aiox-core 5.0.1 → 5.0.3

package/pro/squads/design/checklists/atomic-refactor-checklist.md

@@ -0,0 +1,299 @@
+# Atomic Design Refactoring Checklist
+
+> Use este checklist para cada componente refatorado.
+> Referência: `app/components/ops/users/` (OpsUsersTemplate)
+>
+> **v2.0 - Jan/2026:** Adicionados gates anti-over-engineering.
+
+---
+
+## ⛔ GATE 0: Devo Atomizar? (ANTES DE TUDO)
+
+```bash
+wc -l {arquivo}
+grep -c "useState" {arquivo}
+```
+
+| Linhas | useState | Decisão |
+|--------|----------|---------|
+| >800 | qualquer | **SIM** |
+| 500-800 | >7 | **SIM** |
+| 500-800 | ≤7 | **TALVEZ** - só se hooks reusáveis |
+| <500 | qualquer | **NÃO** - organizar inline |
+
+- [ ] Componente passa no GATE 0? Se **NÃO** → pare aqui, apenas organize inline
+
+---
+
+## Pre-Flight (Antes de Começar)
+
+### Análise do Componente
+- [ ] Ler arquivo COMPLETO (não só o início)
+- [ ] Contar linhas totais: `wc -l {arquivo}`
+- [ ] Listar todos `useState` (quantos? _____)
+- [ ] Listar todas funções `render{X}()` (quantas? _____)
+- [ ] Identificar padrões JSX repetidos (2+ vezes)
+- [ ] Mapear dependências externas (hooks, utils, types)
+
+### Verificar Shared Components
+- [ ] Checar `app/components/shared/hooks/` - hook já existe?
+- [ ] Checar `app/components/shared/molecules/` - molecule já existe?
+- [ ] Checar `app/components/ui/` - componente UI existe?
+- [ ] Se precisar de novo shared → adicionar em `docs/refactoring/SHARED_REQUESTS.md`
+
+### Confirmar Domínio
+- [ ] Identificar domínio correto: `{domain}/{feature}/`
+- [ ] Verificar que não existe pasta com mesmo nome
+- [ ] Confirmar que não vai tocar arquivos de OUTRO domínio
+
+---
+
+## Estrutura (Criar Pastas/Arquivos)
+
+### Criar Estrutura Base
+```
+app/components/{domain}/{feature}/
+├── types.ts
+├── index.ts
+├── {Feature}Template.tsx
+├── hooks/
+│   └── index.ts
+├── molecules/
+│   └── index.ts
+└── organisms/
+    └── index.ts
+```
+
+- [ ] Criar pasta `{domain}/{feature}/`
+- [ ] Criar `types.ts` com interfaces
+- [ ] Criar `index.ts` (barrel export)
+- [ ] Criar pasta `hooks/` + `index.ts`
+- [ ] Criar pasta `molecules/` + `index.ts` (se necessário)
+- [ ] Criar pasta `organisms/` + `index.ts`
+
+---
+
+## Extração (Decompor o Componente)
+
+### 1. Types (types.ts) - CRÍTICO ⚠️
+- [ ] Mover/criar todas interfaces de Props
+- [ ] Mover/criar tipos de dados (enums, unions)
+- [ ] Mover/criar configurações (COLORS, ICONS, etc.)
+- [ ] Exportar tudo com `export`
+- [ ] **VALIDAÇÃO OBRIGATÓRIA:** Após criar `data/*.ts`, verificar que TODOS os types importados existem em `types.ts`
+  ```bash
+  # Listar types importados em data/
+  grep -h "from '../types'" {pasta}/data/*.ts | grep -oE "{ [^}]+ }"
+  # Verificar se existem em types.ts
+  grep "export interface\|export type" {pasta}/types.ts
+  ```
+  **Se algum type estiver faltando → ADICIONAR antes de continuar**
+
+### 2. Hooks (hooks/) - ⚠️ GATE 1 POR HOOK
+
+**Para CADA hook que você vai criar, responda:**
+```
+Esse hook será usado em OUTRO componente?
+[ ] SIM - onde: ____________
+[ ] NÃO → NÃO crie, mantenha useState inline
+```
+
+- [ ] **GATE 1 passou para todos os hooks?**
+- [ ] Agrupar `useState` relacionados em hooks customizados
+- [ ] Naming: `use{Feature}{Concern}.ts`
+  - Dados: `use{Feature}Data.ts`
+  - Filtros: `use{Feature}Filters.ts`
+  - Dialogs: `use{Dialog}Dialog.ts`
+- [ ] Cada hook retorna objeto com estado + setters
+- [ ] Exportar no `hooks/index.ts`
+
+### 3. Molecules (molecules/) - Se Necessário
+- [ ] Extrair padrões JSX repetidos 2+ vezes
+- [ ] Componentes pequenos, stateless
+- [ ] Props bem definidas em types.ts
+- [ ] Exportar no `molecules/index.ts`
+
+### 4. Organisms (organisms/)
+- [ ] Cada `render{X}()` vira `{X}View.tsx` ou `{X}Section.tsx`
+- [ ] Recebe props, não usa hooks diretamente (exceto UI state)
+- [ ] Naming consistente: `{Feature}Header.tsx`, `{Feature}ListView.tsx`
+- [ ] Exportar no `organisms/index.ts`
+
+### 5. Template Orchestrator
+- [ ] Importar todos hooks
+- [ ] Importar todos organisms
+- [ ] Apenas composição (sem lógica de negócio)
+- [ ] Layout e ordem dos organisms
+- [ ] Passar props para cada organism
+
+---
+
+## Validação (Pós-Extração)
+
+### TypeScript
+- [ ] `npx tsc --noEmit` - 0 erros
+- [ ] Sem `any` types (exceto quando inevitável)
+- [ ] Props tipadas corretamente
+
+### Contagem de Linhas
+- [ ] Template orchestrator: **≤100 linhas** (sem estado, só composição)
+- [ ] Cada hook: ≤150 linhas
+- [ ] Cada molecule: ≤100 linhas
+- [ ] Cada organism: ≤200 linhas (exceções documentadas)
+- [ ] types.ts: sem limite (configs podem ser grandes)
+
+### Imports - CRÍTICO ⚠️
+
+**REGRA: SEMPRE usar aliases `@/`, NUNCA paths relativos para UI**
+
+```typescript
+// ✅ CORRETO
+import { Icon } from '@/components/ui/icon';
+import { Button } from '@/components/ui/button';
+import { Card } from '@/components/ui/card';
+
+// ❌ ERRADO - NÃO usar
+import { Icon } from '../../../ui/icon';
+import { Button } from '../../shared/ui/button';
+```
+
+- [ ] **Validação obrigatória antes de concluir:**
+  ```bash
+  grep -rn "from '\.\./\.\./\.\." {pasta-criada}/
+  ```
+  Se retornar resultados → **CORRIGIR antes de reportar conclusão**
+
+- [ ] Todos imports de `@/components/ui/*` usam alias
+- [ ] Sem imports circulares
+- [ ] Barrel exports funcionando (`import { X } from './hooks'`)
+- [ ] Paths relativos OK apenas para arquivos do mesmo módulo
+
+### Funcionalidade
+- [ ] Testar no browser - renderiza igual ao original?
+- [ ] Testar interações - botões, forms, dialogs funcionam?
+- [ ] Testar edge cases - loading, empty, error states
+
+### Consistência com Padrão
+- [ ] Comparar estrutura com `ops/users/`
+- [ ] Naming conventions seguidas
+- [ ] Barrel exports no mesmo padrão
+
+---
+
+## Finalização
+
+### Documentação
+- [ ] Atualizar `docs/refactoring/COMPONENT_REFACTORING_ROADMAP.md`
+  - [ ] Marcar status como ✅ Done
+  - [ ] Adicionar linha count (antes → depois)
+  - [ ] Adicionar estrutura de arquivos criados
+- [ ] Se criou shared component → documentar uso
+
+### Git
+- [ ] `git add` apenas arquivos do domínio refatorado
+- [ ] Commit message: `refactor({domain}): decompose {Component} ({antes}→{depois} lines)`
+- [ ] Não commitar arquivos de outros domínios
+
+### Cleanup
+- [ ] Deletar arquivo original (se moveu para nova pasta)
+- [ ] Atualizar imports em arquivos que usavam o componente
+- [ ] Verificar que nenhum import quebrou
+
+### AppRoutes.tsx - CRÍTICO ⚠️
+
+**Se o componente mudou de path (ex: `templates/X.tsx` → `x-feature/X.tsx`):**
+
+- [ ] **OBRIGATÓRIO:** Atualizar import em `app/components/AppRoutes.tsx`
+  ```bash
+  # Verificar se AppRoutes importa o componente antigo
+  grep "{ComponentName}" app/components/AppRoutes.tsx
+  ```
+- [ ] Corrigir o path do import lazy:
+  ```typescript
+  // ANTES (path antigo)
+  const MyTemplate = React.lazy(() => import('./domain/templates/MyTemplate'));
+
+  // DEPOIS (novo path)
+  const MyTemplate = React.lazy(() => import('./domain/my-feature/MyTemplate'));
+  ```
+- [ ] **Validar:** `npm run typecheck` não deve ter erro `Cannot find module`
+
+---
+
+## ⛔ GATE 2: Validação Final (OBRIGATÓRIO)
+
+```bash
+# Contar linhas TOTAIS da pasta criada
+find {pasta-criada} -name "*.ts" -o -name "*.tsx" | xargs wc -l | tail -1
+```
+
+| Métrica | Limite | Se Falhar |
+|---------|--------|-----------|
+| Linhas totais | ≤ original | Simplificar ou reverter |
+| Arquivos criados | ≤7 | Consolidar |
+| Hooks sem uso externo | 0 | Mover inline |
+
+- [ ] **GATE 2 passou?** Se não → simplificar antes de commitar
+
+---
+
+## Métricas de Sucesso
+
+| Métrica | Critério | Check |
+|---------|----------|-------|
+| **GATE 2: Linhas totais** | **≤ original** | [ ] |
+| **GATE 2: Arquivos** | **≤7** | [ ] |
+| **GATE 2: Hooks órfãos** | **0** | [ ] |
+| Redução de linhas no template | ≥70% | [ ] |
+| Template orchestrator | **≤100 linhas** | [ ] |
+| Maior organism | ≤200 linhas | [ ] |
+| TypeScript errors | 0 | [ ] |
+| Import validation | 0 `../../../` | [ ] |
+| Types consistency | Todos types em data/ existem em types.ts | [ ] |
+| AppRoutes.tsx | Import atualizado (se mudou path) | [ ] |
+| Funcionalidade | 100% igual | [ ] |
+
+---
+
+## Quick Reference
+
+### Naming Conventions
+
+```
+Hooks:      use{Feature}{Concern}.ts     → useCoursesData.ts
+Molecules:  {Pattern}.tsx                 → StatCard.tsx
+Organisms:  {Feature}{Type}.tsx           → CoursesListView.tsx
+Template:   {Feature}Template.tsx         → CoursesTemplate.tsx
+Types:      types.ts                      → types.ts
+Index:      index.ts                      → index.ts
+```
+
+### Extração de useState
+
+```typescript
+// ANTES (no template)
+const [search, setSearch] = useState('');
+const [filters, setFilters] = useState({});
+
+// DEPOIS (em hooks/useFilters.ts)
+export function useFilters() {
+  const [search, setSearch] = useState('');
+  const [filters, setFilters] = useState({});
+  return { search, setSearch, filters, setFilters };
+}
+```
+
+### Extração de render{X}
+
+```typescript
+// ANTES (no template)
+const renderHeader = () => <div>...</div>;
+
+// DEPOIS (em organisms/Header.tsx)
+export const Header: React.FC<HeaderProps> = (props) => <div>...</div>;
+```
+
+---
+
+*Checklist v1.2 - Adicionadas validações críticas: types consistency e AppRoutes.tsx*
+*Baseado em 18+ componentes refatorados com 91% de redução média*

package/pro/squads/design/checklists/component-adaptation-checklist.md

@@ -0,0 +1,81 @@
+# Component Adaptation Checklist
+
+> Checklist para validacao da adaptacao de componentes shadcn.
+> Usado nos QA gates das Phases 2 e 3 (`f2-qa-base-components`, `f3-qa-derived-components`).
+
+## Por Componente
+
+### Integridade Funcional
+
+- [x] Componente importa sem erros de TypeScript
+- [x] Componente renderiza sem runtime errors
+- [x] Todas as variantes renderizam
+- [x] Todas as props existentes funcionam
+
+### Props API
+
+- [x] Nenhuma prop removida
+- [x] Nenhuma prop obrigatoria adicionada
+- [x] Types/interfaces inalterados
+- [x] `className` prop faz merge corretamente
+- [x] `ref` forwarding funciona (se aplicavel)
+
+### Visual — Estados
+
+- [x] Default state corresponde ao design
+- [x] Hover state tem feedback visual
+- [x] Focus state tem ring visivel (focus-visible)
+- [x] Active/Pressed state tem feedback
+- [x] Disabled state visualmente distinto e nao interativo
+
+### Tokens
+
+- [x] Nenhuma cor hardcoded (hex/rgb nas classes)
+- [x] Usa tokens semanticos (`bg-primary`, `text-foreground`, etc.)
+- [x] Extensoes (warning, info, success) usam tokens do @theme inline
+- [x] Radius usa variavel `--radius` ou derivado
+
+### Acessibilidade
+
+- [x] ARIA attributes preservados
+- [x] `data-slot` attributes preservados
+- [x] Focus-visible ring presente (componentes interativos)
+- [x] Keyboard navigation funcional
+- [x] Contraste foreground/background >= 4.5:1
+
+### Dark Mode
+
+- [x] Componente adapta em `.dark` class
+- [x] Contraste mantido em dark
+- [x] Nenhum estado visual desaparece
+
+## Cross-Component (batch)
+
+### Consistencia
+
+- [x] Border-radius consistente entre componentes similares
+- [x] Transicoes (duracao, easing) consistentes
+- [x] Shadow scale consistente
+- [x] Focus ring style consistente
+- [x] Disabled pattern consistente
+- [x] Padding scale proporcional
+
+### Integracao
+
+- [x] `npm run dev` sem erros
+- [x] Sem warnings de Tailwind
+- [x] Sem warnings de React/Next.js
+
+## Notas
+
+- Componentes que NAO sao interativos (Separator, Skeleton, AspectRatio) podem pular checks de hover/focus/disabled
+- Componentes de layout (Form, ScrollArea) tem mudancas minimas — validar apenas tokens e dark mode
+
+---
+
+**Resultado: 15/15 componentes PASS | 4 issues corrigidos | 0 pendentes**
+**Build: PASS (TypeScript 0 errors, next build OK)**
+**Verdict: PASS**
+
+*Validado em: 2026-02-21*
+*Validado por: Foundations Pipeline — f2-qa-base-components*

package/pro/squads/design/checklists/design-fidelity-checklist.md

@@ -0,0 +1,283 @@
+# Design Fidelity Checklist
+
+> Use este checklist para validar que componentes seguem o design spec.
+> Referencia: `squads/super-agentes/data/design-tokens-spec.yaml`
+
+---
+
+## Pre-Validacao
+
+### Carregar Spec
+- [ ] Ler `design-tokens-spec.yaml` completo
+- [ ] Identificar tokens relevantes para o componente
+- [ ] Anotar valores esperados
+
+### Identificar Componente
+- [ ] Tipo de componente: _____________ (button, input, card, modal, etc.)
+- [ ] Variantes: _____________ (primary, secondary, outline, etc.)
+- [ ] Estados: _____________ (default, hover, focus, disabled, etc.)
+
+---
+
+## Validacao de Cores
+
+### Cores Primarias
+- [ ] Cor primaria usa `studio-primary` ou `var(--primary-color)`
+- [ ] Hover usa `studio-primary-dark` ou `var(--primary-dark)`
+- [ ] NUNCA hardcoded `#D4AF37` ou `#B8962E`
+
+### Cores de Background
+- [ ] Background principal usa `studio-bg` ou `bg-background`
+- [ ] Cards usam `studio-card-bg` ou `bg-card`
+- [ ] Surfaces usam `bg-surface` ou `bg-[#1a1a1f]` com comentario
+- [ ] NUNCA hardcoded `#0A0A0F` ou `#111116` sem justificativa
+
+### Cores de Texto
+- [ ] Texto primario usa `text-foreground` ou `text-white`
+- [ ] Texto secundario usa `text-muted-foreground` ou `text-studio-text-secondary`
+- [ ] Texto muted usa `text-muted` ou `text-studio-text-muted`
+
+### Cores Semanticas
+- [ ] Success usa `text-green-500` ou `status-success`
+- [ ] Warning usa `text-yellow-500` ou `status-warning`
+- [ ] Error usa `text-red-500` ou `status-error`
+- [ ] Info usa `text-blue-500` ou `status-info`
+
+### Validacao Automatica
+```bash
+# Executar e verificar 0 resultados
+grep -rn "#D4AF37\|#B8962E\|#0A0A0F\|#111116" {componente}/
+```
+- [ ] Comando executado, 0 resultados
+
+---
+
+## Validacao de Tipografia
+
+### Font Family
+- [ ] UI text usa `font-sans` (Inter)
+- [ ] Headings usam `font-display` (Rajdhani) se aplicavel
+- [ ] Code usa `font-mono` (JetBrains Mono)
+
+### Font Size
+| Uso | Token | Tailwind | Check |
+|-----|-------|----------|-------|
+| Caption | xs | text-xs | [ ] |
+| Button/Secondary | sm | text-sm | [ ] |
+| Body | base | text-base | [ ] |
+| Lead | lg | text-lg | [ ] |
+| Heading | xl-5xl | text-xl a text-5xl | [ ] |
+
+### Font Weight
+- [ ] Body text: `font-normal` (400)
+- [ ] Buttons: `font-medium` (500)
+- [ ] Headings: `font-semibold` (600)
+- [ ] Emphasis: `font-bold` (700)
+
+### Line Height
+- [ ] Texto curto: `leading-tight` ou `leading-5`
+- [ ] Body text: `leading-normal` ou `leading-6`
+- [ ] Headings grandes: `leading-none` ou `leading-tight`
+
+---
+
+## Validacao de Espacamento
+
+### Padding
+| Contexto | Token | Tailwind | Check |
+|----------|-------|----------|-------|
+| Tight | 1-2 | p-1, p-2 | [ ] |
+| Small | 3 | p-3 | [ ] |
+| Standard | 4 | p-4 | [ ] |
+| Medium | 5-6 | p-5, p-6 | [ ] |
+| Large | 8+ | p-8+ | [ ] |
+
+### Gap/Spacing
+- [ ] Itens em lista: `gap-2` ou `gap-3`
+- [ ] Secoes: `gap-4` ou `gap-6`
+- [ ] Grupos: `gap-6` ou `gap-8`
+- [ ] Secoes maiores: `gap-8` ou `gap-12`
+
+### Validacao Automatica
+```bash
+# Verificar hardcoded pixel values
+grep -rn "p-\[.*px\]\|m-\[.*px\]\|gap-\[.*px\]" {componente}/
+```
+- [ ] Comando executado, 0 resultados (ou justificados)
+
+---
+
+## Validacao de Bordas e Radius
+
+### Border Width
+- [ ] Default: `border` (1px)
+- [ ] Emphasis: `border-2` (2px)
+- [ ] NUNCA `border-[3px]` ou valores arbitrarios
+
+### Border Radius
+| Componente | Token | Tailwind | Check |
+|------------|-------|----------|-------|
+| Badge | sm | rounded-sm | [ ] |
+| Button | md | rounded-md | [ ] |
+| Input | md | rounded-md | [ ] |
+| Card | lg-xl | rounded-lg ou rounded-xl | [ ] |
+| Modal | 2xl | rounded-2xl | [ ] |
+| Avatar/Pill | full | rounded-full | [ ] |
+
+### Border Color
+- [ ] Default: `border-border` ou `border-white/10`
+- [ ] Primary: `border-studio-primary/50` ou `border-[var(--primary-color)]/50`
+- [ ] Subtle: `border-white/5`
+
+---
+
+## Validacao de Sombras
+
+- [ ] Sem sombra: `shadow-none`
+- [ ] Sutil: `shadow-sm`
+- [ ] Card/Dropdown: `shadow-md`
+- [ ] Modal: `shadow-lg` ou `shadow-xl`
+- [ ] Glow primario: custom com `rgba(212, 175, 55, 0.3)`
+
+---
+
+## Validacao de Motion
+
+### Duracao
+- [ ] Micro-interactions: `duration-100` (fast)
+- [ ] Standard: `duration-200` (normal)
+- [ ] Page transitions: `duration-300` (slow)
+
+### Easing
+- [ ] Enter: `ease-out`
+- [ ] Exit: `ease-in`
+- [ ] Standard: `ease-in-out`
+
+### Transicoes
+- [ ] Hover states: `transition-colors duration-200`
+- [ ] Transform: `transition-transform duration-200`
+- [ ] All: `transition-all duration-200`
+
+---
+
+## Validacao de Contraste (WCAG AA)
+
+### Texto Normal (< 18px)
+Minimo: **4.5:1**
+
+| Combinacao | Ratio | Status |
+|------------|-------|--------|
+| text-white on bg-base | ~15:1 | [ ] OK |
+| text-secondary on bg-base | ~7:1 | [ ] OK |
+| text-muted on bg-base | ~4.5:1 | [ ] Check |
+| text-muted on bg-elevated | ~3.8:1 | [ ] WARN |
+
+### Texto Grande (>= 18px ou 14px bold)
+Minimo: **3.0:1**
+
+### UI Components
+Minimo: **3.0:1**
+
+### Ferramenta de Verificacao
+```bash
+# Usar WebAIM Contrast Checker ou similar
+# https://webaim.org/resources/contrastchecker/
+```
+
+---
+
+## Validacao de Componentes Especificos
+
+### Button
+- [ ] Padding: `py-2 px-4` (sm), `py-2.5 px-5` (md), `py-3 px-6` (lg)
+- [ ] Border radius: `rounded-md`
+- [ ] Font: `text-sm font-medium`
+- [ ] Min height: 32px (sm), 40px (md), 48px (lg)
+- [ ] Primary: `bg-studio-primary text-studio-bg hover:bg-studio-primary-dark`
+- [ ] Focus ring: `focus:ring-2 focus:ring-studio-primary/50`
+
+### Input
+- [ ] Height: 32px (sm), 40px (md), 48px (lg)
+- [ ] Padding: `py-2 px-3`
+- [ ] Border: `border border-white/10`
+- [ ] Background: `bg-surface` ou `bg-[#1a1a1f]`
+- [ ] Focus: `focus:ring-2 focus:ring-studio-primary/50`
+
+### Card
+- [ ] Padding: `p-4` (sm), `p-6` (md), `p-8` (lg)
+- [ ] Border radius: `rounded-xl`
+- [ ] Background: `bg-card` ou `bg-studio-card-bg`
+- [ ] Border: `border border-white/10`
+
+### Modal
+- [ ] Max width: 384px (sm), 448px (md), 512px (lg)
+- [ ] Padding: `p-6`
+- [ ] Border radius: `rounded-2xl`
+- [ ] Background: `bg-card`
+- [ ] Overlay: `bg-black/80`
+
+---
+
+## Metricas de Sucesso
+
+| Metrica | Criterio | Check |
+|---------|----------|-------|
+| Hardcoded colors | 0 | [ ] |
+| Hardcoded spacing | 0 (ou justificado) | [ ] |
+| Contrast violations | 0 | [ ] |
+| Wrong token usage | 0 | [ ] |
+| Visual match to spec | 100% | [ ] |
+
+---
+
+## Comandos de Validacao Rapida
+
+```bash
+# 1. Cores hardcoded
+grep -rn "#[0-9A-Fa-f]\{6\}" {componente}/ | grep -v "node_modules\|\.yaml\|\.json"
+
+# 2. Spacing hardcoded
+grep -rn "\[.*px\]" {componente}/ | grep -E "p-|m-|gap-|w-|h-"
+
+# 3. Font sizes hardcoded
+grep -rn "text-\[" {componente}/
+
+# 4. Imports corretos
+grep -rn "from '@/components/ui" {componente}/
+```
+
+---
+
+*Checklist v1.0 - Baseado em design-tokens-spec.yaml v1.0.0*
+
+---
+
+## Scoring
+
+### Point System
+Each checkbox item = 1 point.
+
+| Category | Items | Weight |
+|----------|-------|--------|
+| Pre-Validacao | 6 | 6pts |
+| Validacao de Cores | 15 | 15pts |
+| Validacao de Tipografia | 15 | 15pts |
+| Validacao de Espacamento | 10 | 10pts |
+| Validacao de Bordas e Radius | 12 | 12pts |
+| Validacao de Sombras | 5 | 5pts |
+| Validacao de Motion | 9 | 9pts |
+| Validacao de Contraste | 4 | 4pts |
+| Validacao de Componentes Especificos | 20 | 20pts |
+| Metricas de Sucesso | 5 | 5pts |
+| **Total** | **101** | **101pts** |
+
+### Pass/Fail Thresholds
+| Grade | Score | Action |
+|-------|-------|--------|
+| PASS | >= 80% (81+) | Proceed to next phase |
+| CONDITIONAL | 60-79% (61-80) | Fix critical items, re-check |
+| FAIL | < 60% (60-) | Major rework required |
+
+### Auto-Correction
+If items fail:
+- Run `*ds-extract-tokens` to identify hardcoded values. Use `*contrast-matrix` for color issues.

package/pro/squads/design/checklists/design-handoff-checklist.md

@@ -0,0 +1,55 @@
+# Design System Handoff Checklist
+
+**Purpose:** Validate clean handoffs for DS execution and cross-squad routing.
+
+## 1. Context Integrity
+
+- [ ] Original request captured
+- [ ] Objective and success criteria explicit
+- [ ] Constraints documented (timeline/stack/governance)
+- [ ] Current phase/state identified
+
+## 2. Artifact Integrity
+
+- [ ] Changed files listed with paths
+- [ ] Deliverable status marked (`COMPLETE|IN_PROGRESS|BLOCKED`)
+- [ ] Pending issues listed
+- [ ] Required references attached (registry, token schema, reports)
+
+## 3. Technical Integrity
+
+- [ ] No broken paths in handoff payload
+- [ ] No placeholder-only sections
+- [ ] Acceptance criteria for next owner defined
+- [ ] Risks and assumptions declared
+
+## 4. Scope Integrity
+
+- [ ] Request classified as `in_scope` or `out_of_scope`
+- [ ] If out-of-scope, routed to correct squad:
+  - [ ] `/Brand` for brand/logo/pricing
+  - [ ] `/ContentVisual` for thumbnail/photo/video
+- [ ] DS squad did not execute out-of-scope work
+
+## 5. DS Flow Checks
+
+### 5.1 DesignOps -> Architecture (`@dave-malouf -> @brad-frost`)
+- [ ] Operating constraints are explicit
+- [ ] Team/process maturity status included
+- [ ] Tooling constraints included
+
+### 5.2 Architecture -> Orchestration (`@brad-frost -> @design-chief`)
+- [ ] Component/token decisions captured
+- [ ] Rollout/review requirement captured
+- [ ] Registry/metadata impact captured
+
+### 5.3 Adoption -> Execution (`@dan-mall -> @dave-malouf` or `@brad-frost`)
+- [ ] Stakeholder concerns documented
+- [ ] Adoption narrative and ROI points included
+- [ ] Execution ask is concrete and measurable
+
+## 6. Sign-off
+
+- [ ] Sender confirmed handoff completeness
+- [ ] Receiver confirmed handoff clarity
+- [ ] Next action owner and deadline assigned