aiox-core 5.0.2 → 5.0.4

package/pro/squads/design/checklists/reading-accessibility-checklist.md

@@ -0,0 +1,275 @@
+# Reading Accessibility Checklist
+
+> Use este checklist para validar experiências de leitura digital.
+> Referência: `squads/super-agentes/data/high-retention-reading-guide.md`
+
+---
+
+## 1. Tipografia — CRÍTICO
+
+### Tamanho de Fonte
+- [ ] Body text ≥ 16px (WCAG mínimo)
+- [ ] Ideal para leitura: 18-21px
+- [ ] Captions/footnotes ≥ 11px
+- [ ] Labels/metadata ≥ 13px
+
+### Altura de Linha
+- [ ] Body text: line-height ≥ 1.5
+- [ ] Ideal para leitura: 1.6
+- [ ] Headings: 1.25-1.375
+- [ ] Código: 1.5-1.625
+
+### Comprimento de Linha
+- [ ] Máximo WCAG: 80ch
+- [ ] Ideal: 65ch
+- [ ] Mobile: 35-50ch
+- [ ] Desktop: 60-75ch
+
+### Peso de Fonte
+- [ ] Body text: ≥ 400 (Regular)
+- [ ] Nunca usar light (300) para body
+- [ ] Headings: 600-700
+
+### Espaçamento de Letras
+- [ ] Letter-spacing: ~0.012em (0.12x)
+- [ ] Mobile: considerar 0.016em
+- [ ] Ajustável pelo usuário
+
+### Alinhamento
+- [ ] Texto alinhado à esquerda (NUNCA justificado)
+- [ ] Headings podem ser centralizados
+- [ ] Sem ALL CAPS em blocos de texto
+- [ ] Sem itálico em blocos longos
+
+### Escalabilidade
+- [ ] Texto pode ser ampliado até 200% sem perda
+- [ ] Zoom funciona sem quebrar layout
+- [ ] Sem texto em imagens (exceto logos)
+
+---
+
+## 2. Cor e Contraste — WCAG
+
+### Contraste de Texto
+- [ ] Texto normal: ≥ 4.5:1 (AA)
+- [ ] Texto grande (≥18px bold ou ≥24px): ≥ 3:1
+- [ ] Ideal para leitura prolongada: 7:1 (AAA)
+- [ ] Links vs texto ao redor: ≥ 3:1
+
+### Modo Claro
+- [ ] Fundo: off-white (#FAFAFA a #F5F5F5)
+- [ ] NÃO usar branco puro (#FFFFFF) para body
+- [ ] Texto: #212121 a #424242
+
+### Modo Escuro
+- [ ] Fundo: #121212 a #1E1E1E
+- [ ] NUNCA usar preto puro (#000000)
+- [ ] Texto: #E0E0E0 a #EDEDED
+- [ ] NUNCA usar branco puro (#FFFFFF)
+- [ ] Evitar contraste 21:1 (causa halation)
+
+### Opções de Tema
+- [ ] Tema claro disponível
+- [ ] Tema escuro disponível
+- [ ] Tema sépia/creme disponível (ideal para 2+ horas)
+- [ ] Opção "seguir sistema" (prefers-color-scheme)
+
+### Links
+- [ ] Distinguíveis além da cor (sublinhado, peso, ícone)
+- [ ] Contraste ≥ 3:1 com texto ao redor
+- [ ] Estado visitado diferenciado
+- [ ] Estado hover visível
+
+### Highlights
+- [ ] Opacidade 40% para manter legibilidade
+- [ ] Múltiplas cores disponíveis
+- [ ] Contraste mantido sobre highlight
+
+---
+
+## 3. Acessibilidade Cognitiva
+
+### Parágrafos
+- [ ] 3-4 sentenças por parágrafo (máx 5)
+- [ ] Uma ideia principal por parágrafo
+- [ ] Evitar blocos de texto >5 linhas
+
+### Headings
+- [ ] A cada 3-5 parágrafos
+- [ ] Hierarquia lógica (H1 → H2 → H3)
+- [ ] Descritivos do conteúdo
+- [ ] Facilitam escaneamento
+
+### Estrutura
+- [ ] TL;DR/resumo no início (long-form)
+- [ ] Table of Contents (>5 seções)
+- [ ] Seções expansíveis/colapsáveis
+- [ ] Pirâmide invertida (conclusão primeiro)
+
+### Navegação
+- [ ] Skip links disponíveis
+- [ ] Landmarks ARIA (main, nav, article)
+- [ ] Navegação por teclado funcional
+- [ ] Ordem de tab lógica
+
+---
+
+## 4. Elementos de UI para Leitura
+
+### Indicador de Progresso
+- [ ] Barra de progresso visível (topo ou lateral)
+- [ ] Ou: porcentagem numérica
+- [ ] Ou: "X min restantes"
+- [ ] Scroll depth rastreado
+
+### Tempo de Leitura
+- [ ] Exibido para artigos >500 palavras
+- [ ] Formato: "X min de leitura"
+- [ ] Cálculo: palavras ÷ 200
+
+### Salvar Posição
+- [ ] Posição de leitura salva automaticamente
+- [ ] "Continue de onde parou" funcional
+- [ ] Histórico de leituras disponível
+
+### Anotações
+- [ ] Highlight em múltiplas cores
+- [ ] Notas marginais ou inline
+- [ ] Exportar anotações
+
+---
+
+## 5. Responsividade
+
+### Mobile (< 640px)
+- [ ] Font size: 16px
+- [ ] Line length: 35-50ch
+- [ ] Padding lateral: ≥ 16px
+- [ ] Line height: 1.6-1.7
+- [ ] Touch targets: ≥ 44x44px
+
+### Tablet (640-1023px)
+- [ ] Font size: 17px
+- [ ] Line length: 55-70ch
+- [ ] Padding: 24px
+
+### Desktop (≥ 1024px)
+- [ ] Font size: 18px
+- [ ] Line length: 60-75ch
+- [ ] Padding: 32px
+
+### Large (≥ 1280px)
+- [ ] Font size: 18-21px
+- [ ] Line length: 65-80ch
+- [ ] Padding: 40px
+
+---
+
+## 6. Preferências do Sistema
+
+### Motion
+- [ ] Respeita prefers-reduced-motion
+- [ ] Animações podem ser desabilitadas
+- [ ] Sem auto-scroll obrigatório
+- [ ] Sem parallax distratora
+
+### Contraste
+- [ ] Respeita prefers-contrast
+- [ ] Opção de alto contraste disponível
+
+### Tema
+- [ ] Respeita prefers-color-scheme
+- [ ] Override manual disponível
+
+### Mídia
+- [ ] Sem auto-play obrigatório
+- [ ] Controles de mídia acessíveis
+
+---
+
+## 7. Suporte a Dislexia
+
+- [ ] Opção de fonte sans-serif
+- [ ] Opção OpenDyslexic ou similar
+- [ ] Texto NUNCA justificado
+- [ ] Line height aumentável (até 1.8)
+- [ ] Letter spacing aumentável
+- [ ] Word spacing aumentável
+- [ ] Fundos sem padrões/texturas
+- [ ] Tema sépia disponível
+
+---
+
+## 8. Suporte a Baixa Visão
+
+- [ ] Zoom 200% funcional
+- [ ] Alto contraste disponível
+- [ ] Font size customizável
+- [ ] Alt text em todas imagens
+- [ ] Sem texto em imagens
+- [ ] Focus visível (outline/ring)
+
+---
+
+## 9. Validação de Contraste
+
+### Ferramentas
+- WebAIM Contrast Checker: https://webaim.org/resources/contrastchecker/
+- Coolors Contrast Checker: https://coolors.co/contrast-checker
+
+### Comandos de Validação
+```bash
+# Verificar cores hardcoded que podem ter baixo contraste
+grep -rn "#[0-9A-Fa-f]\{6\}" {path}/ --include="*.tsx" --include="*.css"
+
+# Verificar uso de branco/preto puros (evitar em dark mode)
+grep -rn "#FFFFFF\|#000000" {path}/ --include="*.tsx" --include="*.css"
+```
+
+---
+
+## 10. Métricas de Sucesso
+
+| Métrica | Critério | Check |
+|---------|----------|-------|
+| Font size body | ≥16px | [ ] |
+| Line height | ≥1.5 | [ ] |
+| Line length | ≤80ch | [ ] |
+| Contraste AA | ≥4.5:1 | [ ] |
+| Contraste AAA | ≥7:1 | [ ] |
+| Temas disponíveis | ≥2 | [ ] |
+| Zoom 200% | Funcional | [ ] |
+| Progress indicator | Visível | [ ] |
+| Skip links | Disponível | [ ] |
+| Keyboard nav | Funcional | [ ] |
+
+---
+
+## 11. Comandos de Validação Rápida
+
+```bash
+# 1. Verificar font sizes hardcoded
+grep -rn "font-size:" {path}/ | grep -E "1[0-5]px|[0-9]px"
+
+# 2. Verificar line-heights baixos
+grep -rn "line-height:" {path}/ | grep -E "1\.[0-4]|1$"
+
+# 3. Verificar text-align: justify
+grep -rn "text-align:\s*justify" {path}/
+
+# 4. Verificar ALL CAPS
+grep -rn "text-transform:\s*uppercase" {path}/
+
+# 5. Verificar branco/preto puros
+grep -rn "#FFFFFF\|#000000\|rgb(255,\s*255,\s*255)\|rgb(0,\s*0,\s*0)" {path}/
+
+# 6. Verificar prefers-reduced-motion
+grep -rn "prefers-reduced-motion" {path}/
+
+# 7. Verificar prefers-color-scheme
+grep -rn "prefers-color-scheme" {path}/
+```
+
+---
+
+*Checklist v1.0.0 — Baseado em WCAG 2.1/2.2, Apple HIG, Material Design 3, e práticas de publishers.*

package/pro/squads/design/checklists/token-mapping-checklist.md

@@ -0,0 +1,107 @@
+# Token Mapping Checklist
+
+> Checklist para validacao do mapeamento de tokens Figma → shadcn CSS vars.
+> Usado no QA gate da Phase 1 (`f1-qa-foundations`).
+
+## Token Completude
+
+- [x] `--background` definido em `:root` e `.dark`
+- [x] `--foreground` definido em `:root` e `.dark`
+- [x] `--card` definido em `:root` e `.dark`
+- [x] `--card-foreground` definido em `:root` e `.dark`
+- [x] `--popover` definido em `:root` e `.dark`
+- [x] `--popover-foreground` definido em `:root` e `.dark`
+- [x] `--primary` definido em `:root` e `.dark`
+- [x] `--primary-foreground` definido em `:root` e `.dark`
+- [x] `--secondary` definido em `:root` e `.dark`
+- [x] `--secondary-foreground` definido em `:root` e `.dark`
+- [x] `--muted` definido em `:root` e `.dark`
+- [x] `--muted-foreground` definido em `:root` e `.dark`
+- [x] `--accent` definido em `:root` e `.dark`
+- [x] `--accent-foreground` definido em `:root` e `.dark`
+- [x] `--destructive` definido em `:root` e `.dark`
+- [x] `--border` definido em `:root` e `.dark`
+- [x] `--input` definido em `:root` e `.dark`
+- [x] `--ring` definido em `:root` e `.dark`
+- [x] `--radius` definido em `:root`
+
+## Chart Tokens
+
+- [x] `--chart-1` through `--chart-5` definidos em `:root` e `.dark`
+
+## Sidebar Tokens
+
+- [x] `--sidebar` definido em `:root` e `.dark`
+- [x] `--sidebar-foreground` definido em `:root` e `.dark`
+- [x] `--sidebar-primary` definido em `:root` e `.dark`
+- [x] `--sidebar-primary-foreground` definido em `:root` e `.dark`
+- [x] `--sidebar-accent` definido em `:root` e `.dark`
+- [x] `--sidebar-accent-foreground` definido em `:root` e `.dark`
+- [x] `--sidebar-border` definido em `:root` e `.dark`
+- [x] `--sidebar-ring` definido em `:root` e `.dark`
+
+## @theme inline Bridge
+
+- [x] `--color-background: var(--background)` presente
+- [x] `--color-foreground: var(--foreground)` presente
+- [x] Todos os core tokens tem bridge `--color-{name}: var(--{name})`
+- [x] Sidebar tokens tem bridge
+- [x] Chart tokens tem bridge
+- [x] Extensoes (warning, info, success) tem bridge
+- [x] Radius scale mantido (`--radius-sm` through `--radius-4xl`)
+- [x] Font vars mantidas (`--font-sans`, `--font-mono`, `--font-heading`, `--font-body`)
+
+## Formato de Valores
+
+- [x] Todos os valores de cor em OKLch
+- [x] Formato correto: `oklch(L C H)` ou `oklch(L C H / alpha)`
+- [x] L entre 0 e 1
+- [x] C >= 0
+- [x] H entre 0 e 360 (se C > 0)
+- [x] Nenhum valor em hex, rgb, ou hsl
+
+## Contraste WCAG AA
+
+### Light Mode
+
+- [x] foreground/background: 19.03:1 >= 4.5:1
+- [x] primary-foreground/primary: 19.03:1 >= 4.5:1
+- [x] secondary-foreground/secondary: 17.00:1 >= 4.5:1
+- [x] muted-foreground/muted: 5.79:1 >= 3:1
+- [x] accent-foreground/accent: 17.00:1 >= 4.5:1
+- [x] card-foreground/card: 19.03:1 >= 4.5:1
+- [x] popover-foreground/popover: 19.03:1 >= 4.5:1
+- [x] destructive/background: 3.53:1 >= 3:1
+
+### Dark Mode
+
+- [x] foreground/background: 17.00:1 >= 4.5:1
+- [x] primary-foreground/primary: 19.03:1 >= 4.5:1
+- [x] secondary-foreground/secondary: 11.79:1 >= 4.5:1
+- [x] muted-foreground/muted: 5.29:1 >= 3:1
+- [x] accent-foreground/accent: 11.79:1 >= 4.5:1
+- [x] card-foreground/card: 14.55:1 >= 4.5:1
+- [x] popover-foreground/popover: 14.55:1 >= 4.5:1
+- [x] destructive/background: 5.39:1 >= 3:1
+
+## Estrutura do Arquivo
+
+- [x] Imports inalterados (`@import "tailwindcss"`, `@import "tw-animate-css"`, `@import "shadcn/tailwind.css"`)
+- [x] `@custom-variant dark` inalterado
+- [x] `@layer base` inalterado
+- [x] CSS valido (sem erros de sintaxe)
+- [x] `next build` compila sem erros
+
+## Componentes
+
+- [x] Build passa — nenhum componente referencia variavel inexistente
+- [x] Nenhum token shadcn original removido sem substituto
+
+---
+
+**Resultado: 138 PASS | 0 FAIL | 0 WARN**
+**Contraste: 16/16 PASS (WCAG AA)**
+**Verdict: PASS**
+
+*Validado em: 2026-02-21*
+*Validado por: Foundations Pipeline — f1-qa-foundations*

package/pro/squads/design/config/coding-standards.md

@@ -0,0 +1,286 @@
+# Design Squad - Coding Standards
+
+## Design Token Naming
+
+### Token Hierarchy
+```
+{category}.{property}.{variant}.{state}
+```
+
+### Examples
+```css
+/* Colors */
+--color-primary-500
+--color-neutral-100
+--color-semantic-error
+
+/* Typography */
+--font-family-sans
+--font-size-lg
+--font-weight-bold
+--line-height-tight
+
+/* Spacing */
+--spacing-4
+--spacing-8
+--spacing-16
+
+/* Borders */
+--border-radius-sm
+--border-width-default
+
+/* Shadows */
+--shadow-sm
+--shadow-lg
+```
+
+### Naming Rules
+1. **Use kebab-case** for all token names
+2. **Prefix with category** (color, font, spacing, etc.)
+3. **Use semantic names** when possible (primary, error, success)
+4. **Use numeric scales** for gradients (100-900 for colors, 1-12 for spacing)
+5. **Avoid magic numbers** - always reference tokens
+
+## Component Naming
+
+### File Structure
+```
+ComponentName/
+├── ComponentName.tsx      # Main component
+├── ComponentName.test.tsx # Tests
+├── ComponentName.stories.tsx # Storybook
+├── index.ts              # Public exports
+└── styles.css            # Scoped styles (if needed)
+```
+
+### Naming Convention
+```typescript
+// PascalCase for components
+export function Button() {}
+export function CardHeader() {}
+
+// camelCase for hooks
+export function useTheme() {}
+export function useDesignTokens() {}
+
+// camelCase for utilities
+export function formatColor() {}
+export function calculateContrast() {}
+```
+
+## CSS Standards
+
+### Tailwind Classes Order
+```html
+<!-- Order: Layout → Sizing → Spacing → Typography → Visual → Interactive -->
+<div class="
+  flex flex-col           /* Layout */
+  w-full h-auto           /* Sizing */
+  p-4 mt-2                /* Spacing */
+  text-sm font-medium     /* Typography */
+  bg-white border rounded /* Visual */
+  hover:bg-gray-50        /* Interactive */
+">
+```
+
+### Custom CSS Rules
+```css
+/* Use CSS custom properties for tokens */
+.component {
+  color: var(--color-text-primary);
+  padding: var(--spacing-4);
+  border-radius: var(--border-radius-md);
+}
+
+/* Avoid magic numbers */
+/* ❌ Bad */
+.component { padding: 16px; }
+
+/* ✅ Good */
+.component { padding: var(--spacing-4); }
+```
+
+## Accessibility Standards
+
+### WCAG 2.1 AA Compliance
+```yaml
+required:
+  - Color contrast ratio: 4.5:1 (normal text), 3:1 (large text)
+  - Focus indicators: visible on all interactive elements
+  - Alt text: all images must have descriptive alt
+  - Keyboard navigation: all functionality accessible via keyboard
+  - ARIA labels: interactive elements without visible text
+```
+
+### Code Requirements
+```tsx
+// ✅ Good - accessible button
+<button
+  aria-label="Close dialog"
+  onClick={onClose}
+  className="focus:ring-2 focus:ring-primary-500"
+>
+  <CloseIcon aria-hidden="true" />
+</button>
+
+// ❌ Bad - inaccessible
+<div onClick={onClose}>
+  <CloseIcon />
+</div>
+```
+
+## Component API Standards
+
+### Props Interface
+```typescript
+interface ButtonProps {
+  /** Button visual variant */
+  variant?: 'primary' | 'secondary' | 'ghost';
+  /** Button size */
+  size?: 'sm' | 'md' | 'lg';
+  /** Disabled state */
+  disabled?: boolean;
+  /** Loading state */
+  loading?: boolean;
+  /** Click handler */
+  onClick?: () => void;
+  /** Button content */
+  children: React.ReactNode;
+}
+```
+
+### Default Props
+```typescript
+const defaultProps: Partial<ButtonProps> = {
+  variant: 'primary',
+  size: 'md',
+  disabled: false,
+  loading: false,
+};
+```
+
+## Documentation Standards
+
+### Component Documentation
+```tsx
+/**
+ * Button component for user interactions.
+ *
+ * @example
+ * ```tsx
+ * <Button variant="primary" onClick={handleClick}>
+ *   Click me
+ * </Button>
+ * ```
+ *
+ * @see {@link https://design.example.com/components/button}
+ */
+export function Button(props: ButtonProps) {}
+```
+
+### Storybook Stories
+```tsx
+export default {
+  title: 'Components/Button',
+  component: Button,
+  tags: ['autodocs'],
+} satisfies Meta<typeof Button>;
+
+export const Primary: Story = {
+  args: {
+    variant: 'primary',
+    children: 'Primary Button',
+  },
+};
+```
+
+## Icon Standards
+
+### Icon Naming
+```
+{category}-{name}[-{variant}]
+```
+
+### Examples
+```
+icon-arrow-right
+icon-arrow-left
+icon-check
+icon-check-circle
+icon-user
+icon-user-plus
+```
+
+### Icon Component API
+```typescript
+interface IconProps {
+  name: IconName;
+  size?: 'sm' | 'md' | 'lg' | number;
+  color?: string;
+  className?: string;
+  'aria-label'?: string;
+  'aria-hidden'?: boolean;
+}
+```
+
+## Image Standards
+
+### Thumbnail Specifications
+| Platform | Size | Aspect Ratio |
+|----------|------|--------------|
+| YouTube | 1280x720 | 16:9 |
+| Instagram Feed | 1080x1080 | 1:1 |
+| Instagram Story | 1080x1920 | 9:16 |
+| Twitter | 1200x675 | 16:9 |
+
+### Export Settings
+```yaml
+web:
+  format: webp (with jpg fallback)
+  quality: 80-90%
+  max_width: 2400px
+
+thumbnails:
+  format: jpg
+  quality: 90%
+  exact_size: true
+
+icons:
+  format: svg
+  optimized: true (SVGO)
+```
+
+## Git Commit Standards
+
+### Commit Message Format
+```
+type(scope): description
+
+[optional body]
+
+[optional footer]
+```
+
+### Types
+```
+feat:     New feature
+fix:      Bug fix
+docs:     Documentation
+style:    Formatting, styling
+refactor: Code refactoring
+test:     Tests
+chore:    Maintenance
+```
+
+### Examples
+```
+feat(tokens): add semantic color tokens
+fix(button): correct focus ring color
+docs(readme): update component API
+style(card): adjust padding for mobile
+```
+
+---
+
+*Design Squad Coding Standards v1.0*
+*Last Updated: 2026-02-13*

package/pro/squads/design/config/source-tree.md

@@ -0,0 +1,59 @@
+# Design System Squad - Source Tree
+
+## Squad Structure
+
+```text
+squads/design/
+├── config.yaml
+├── squad.yaml
+├── README.md
+├── agents/
+│   ├── design-chief.md
+│   ├── brad-frost.md
+│   ├── dan-mall.md
+│   ├── dave-malouf.md
+│   └── nano-banana-generator.md
+├── tasks/
+│   ├── ds-*.md
+│   ├── a11y-audit.md
+│   ├── aria-audit.md
+│   ├── contrast-matrix.md
+│   ├── focus-order-audit.md
+│   ├── atomic-refactor-plan.md
+│   ├── atomic-refactor-execute.md
+│   ├── design-triage.md
+│   └── design-review-orchestration.md
+├── checklists/
+├── templates/
+├── data/
+├── workflows/
+├── protocols/
+└── scripts/
+```
+
+## Responsibilities
+
+| Agent | File | Responsibility |
+|---|---|---|
+| Design Chief | `agents/design-chief.md` | triage, routing, orchestration |
+| Brad Frost | `agents/brad-frost.md` | DS architecture, components, tokens |
+| Dan Mall | `agents/dan-mall.md` | DS buy-in, adoption messaging |
+| Dave Malouf | `agents/dave-malouf.md` | design ops, process, governance |
+| Nano Banana | `agents/nano-banana-generator.md` | visual utility support |
+
+## Task Domains
+
+| Domain | Prefix/Files | Owner |
+|---|---|---|
+| Design System Core | `ds-*` | Brad Frost |
+| Accessibility | `a11y-audit`, `aria-audit`, `contrast-matrix`, `focus-order-audit` | Brad Frost |
+| Atomic Refactor | `atomic-refactor-*` | Brad Frost |
+| DesignOps | `designops-*`, `design-process-optimization`, `design-team-scaling`, `design-tooling-audit` | Dave Malouf |
+| Orchestration | `design-triage`, `design-review-orchestration` | Design Chief |
+| Utilities | remaining utility tasks | Mixed |
+
+## Cross-Squad Policy
+
+- Brand/logo/pricing requests -> `squads/brand`
+- Thumbnail/photo/video requests -> `squads/content-visual`
+- `squads/design` does not execute those domains anymore.