iron-edge 1.0.0

package/squads/squad-design/tasks/design-focus-management.md

@@ -0,0 +1,165 @@
+---
+task: design-focus-management
+responsavel: "@dx-accessibility-specialist"
+responsavel_type: Agent
+atomic_layer: Task
+elicit: false
+
+Entrada:
+  - campo: context
+    tipo: object
+    origem: "workflow ou manual"
+    obrigatorio: true
+
+Saida:
+  - campo: resultado
+    tipo: document
+    destino: "stakeholders"
+
+Checklist:
+  - "[ ] Validar inputs e pre-condicoes"
+  - "[ ] Executar steps conforme documentado"
+  - "[ ] Verificar criterios de qualidade"
+  - "[ ] Gerar output no formato especificado"
+---
+
+# Task: Design Focus Management
+
+## Metadata
+- **Squad:** squad-design
+- **Agent:** Beacon (dx-accessibility-specialist)
+- **Complexity:** Complex
+
+## Objetivo
+Projetar estrategia de focus management — definir como o foco se move, onde vai apos acoes, e como e visualizado em todo o produto.
+
+## Entrada
+- User flows
+- Component library
+- Interactive patterns
+- WCAG 2.2 focus requirements
+
+## Passos
+
+### 1. Focus Order Principles
+| Principio | Descricao |
+|-----------|-----------|
+| Source order | Tab order segue DOM order |
+| Logical flow | Sequencia faz sentido contextual |
+| No positive tabindex | Nunca usar tabindex > 0 |
+| Skip navigation | Skip links no topo |
+| Grouped controls | Radio/tabs use roving tabindex |
+
+### 2. Focus Movement Patterns
+| Cenario | Focus After Action |
+|---------|-------------------|
+| Modal opens | Primeiro focusable no modal |
+| Modal closes | Elemento que abriu o modal |
+| Dropdown opens | Primeiro item |
+| Dropdown closes (select) | Trigger element |
+| Dropdown closes (escape) | Trigger element |
+| Form error | Primeiro campo com erro |
+| Form success | Mensagem de sucesso ou redirect |
+| Toast appears | NAO move focus (aria-live) |
+| Tab switch | Conteudo do tab panel |
+| Accordion toggle | Mantém no trigger |
+| Delete item | Proximo item ou container vazio |
+| Page navigation | Main content (h1 ou main) |
+
+### 3. Focus Trapping
+Para modals, drawers e popovers:
+```typescript
+function useFocusTrap(containerRef: RefObject<HTMLElement>) {
+  useEffect(() => {
+    const container = containerRef.current;
+    if (!container) return;
+
+    const focusableElements = container.querySelectorAll(
+      'a[href], button, textarea, input, select, [tabindex]:not([tabindex="-1"])'
+    );
+    const firstEl = focusableElements[0] as HTMLElement;
+    const lastEl = focusableElements[focusableElements.length - 1] as HTMLElement;
+
+    function handleKeyDown(e: KeyboardEvent) {
+      if (e.key !== 'Tab') return;
+
+      if (e.shiftKey && document.activeElement === firstEl) {
+        e.preventDefault();
+        lastEl.focus();
+      } else if (!e.shiftKey && document.activeElement === lastEl) {
+        e.preventDefault();
+        firstEl.focus();
+      }
+    }
+
+    container.addEventListener('keydown', handleKeyDown);
+    firstEl?.focus();
+
+    return () => container.removeEventListener('keydown', handleKeyDown);
+  }, [containerRef]);
+}
+```
+
+### 4. Roving Tabindex
+Para grupos de controles (tabs, radio, toolbar):
+```typescript
+// Only one item in the group has tabindex="0"
+// Others have tabindex="-1"
+// Arrow keys move focus within group
+// Tab exits group
+
+function useRovingTabindex(items: HTMLElement[]) {
+  const [activeIndex, setActiveIndex] = useState(0);
+
+  function handleKeyDown(e: KeyboardEvent) {
+    if (e.key === 'ArrowRight' || e.key === 'ArrowDown') {
+      e.preventDefault();
+      const next = (activeIndex + 1) % items.length;
+      setActiveIndex(next);
+      items[next].focus();
+    }
+    // ... ArrowLeft/ArrowUp, Home, End
+  }
+}
+```
+
+### 5. Focus Indicator Design
+```css
+/* Focus indicator spec */
+:focus-visible {
+  outline: 2px solid var(--color-focus-ring);
+  outline-offset: 2px;
+  border-radius: var(--radius-sm);
+}
+
+/* Remove for mouse users */
+:focus:not(:focus-visible) {
+  outline: none;
+}
+```
+
+Requirements (WCAG 2.4.13):
+- Area >= 2px perimeter
+- Contrast >= 3:1 against adjacent
+- Not obscured by other content (2.4.11)
+
+### 6. Scroll and Focus
+- Focus DEVE ser visivel (scroll into view se necessario)
+- Sticky headers/footers NAO devem obscurecer focused element
+- `scrollIntoView({ block: 'nearest', behavior: 'smooth' })`
+
+## Saida
+- Focus management strategy document
+- Focus movement map per pattern
+- Focus trap implementation
+- Roving tabindex implementation
+- Focus indicator specification
+- Handoff para Scaffold (implementation)
+
+## Validacao
+- [ ] Focus order logico em todas as paginas
+- [ ] Focus trap em modais/overlays
+- [ ] Roving tabindex em tab groups
+- [ ] Focus indicator visivel (3:1 contrast)
+- [ ] Focus nao obscurecido por sticky elements
+- [ ] Focus retorna corretamente apos fechar overlays

package/squads/squad-design/tasks/design-form-patterns.md

@@ -0,0 +1,138 @@
+---
+task: design-form-patterns
+responsavel: "@dx-ui-designer"
+responsavel_type: Agent
+atomic_layer: Task
+elicit: false
+
+Entrada:
+  - campo: context
+    tipo: object
+    origem: "workflow ou manual"
+    obrigatorio: true
+
+Saida:
+  - campo: resultado
+    tipo: document
+    destino: "stakeholders"
+
+Checklist:
+  - "[ ] Validar inputs e pre-condicoes"
+  - "[ ] Executar steps conforme documentado"
+  - "[ ] Verificar criterios de qualidade"
+  - "[ ] Gerar output no formato especificado"
+---
+
+# Task: Design Form Patterns
+
+## Metadata
+- **Squad:** squad-design
+- **Agent:** Canvas (dx-ui-designer)
+- **Complexity:** Standard
+
+## Objetivo
+Projetar padroes de formulario consistentes e acessiveis — definir layouts, validacao visual, error states e patterns de input que otimizam completion rate.
+
+## Entrada
+- Component visual states (de design-component-visual-states)
+- Accessibility requirements (WCAG 2.2)
+- User flows que envolvem formularios
+- Content requirements (labels, help text)
+
+## Passos
+
+### 1. Definir Form Layout Patterns
+| Pattern | Quando usar | Vantagem |
+|---------|------------|----------|
+| Single column | Default, mobile | Facil de scanear |
+| Two column | Campos relacionados (name + surname) | Compacto |
+| Stepped/Wizard | Formularios longos (>7 campos) | Reduz overwhelm |
+| Inline | Edicao rapida em contexto | Nao interrompe fluxo |
+| Floating labels | Espaco limitado | Compacto mas acessivel |
+
+### 2. Definir Input States
+```yaml
+input_states:
+  default:
+    border: "neutral-300"
+    background: "white"
+    label: "neutral-700"
+
+  focus:
+    border: "brand-500"
+    outline: "2px solid brand-200"
+    label: "brand-600"
+
+  filled:
+    border: "neutral-400"
+    background: "white"
+    label: "neutral-600"
+
+  error:
+    border: "error-500"
+    background: "error-50"
+    label: "error-700"
+    icon: "alert-circle"
+    message: "error-600"
+
+  success:
+    border: "success-500"
+    icon: "check-circle"
+
+  disabled:
+    border: "neutral-200"
+    background: "neutral-50"
+    text: "neutral-400"
+    cursor: "not-allowed"
+```
+
+### 3. Padronizar Validacao Visual
+| Tipo | Quando mostrar | Visual |
+|------|---------------|--------|
+| Real-time | Ao sair do campo (blur) | Inline message |
+| On submit | Ao enviar formulario | Summary + inline |
+| Character count | Campos com limite | Counter badge |
+| Strength | Senhas | Progress bar |
+| Format hint | Campos com formato especifico | Placeholder ou help text |
+
+### 4. Definir Help Text System
+| Tipo | Posicao | Quando usar |
+|------|---------|------------|
+| Label | Acima do campo | Sempre (obrigatorio) |
+| Help text | Abaixo do campo | Quando precisa explicacao |
+| Placeholder | Dentro do campo | Exemplo de formato (nunca como label) |
+| Tooltip | Ao lado do label | Informacao adicional on-demand |
+| Error message | Abaixo do campo (substitui help) | Apos validacao falhar |
+
+### 5. Accessibility Requirements (WCAG 2.2)
+- Labels sempre associados (`for`/`id`)
+- Error messages referenciadas com `aria-describedby`
+- Required fields com `aria-required="true"` + visual indicator
+- Error summary com links para campos (WCAG 3.3.1)
+- Autocomplete attributes (WCAG 1.3.5)
+- No CAPTCHA sem alternativa acessivel (WCAG 3.3.8)
+- Nao pedir info ja fornecida (WCAG 3.3.7)
+
+### 6. Submit Button Patterns
+| Estado | Visual | Comportamento |
+|--------|--------|--------------|
+| Default | Primary button | Clickable |
+| Submitting | Loading spinner + text | Disabled |
+| Success | Success icon + message | Redirect ou reset |
+| Error | Error message | Re-enable form |
+
+## Saida
+- Form pattern library
+- Input state specifications
+- Validation visual patterns
+- Help text guidelines
+- Submit flow specifications
+- Handoff para Scaffold (implementation) e Beacon (a11y review)
+
+## Validacao
+- [ ] Labels nunca substituidos por placeholders
+- [ ] Error messages claras e acionaveis
+- [ ] Focus management em forms multi-step
+- [ ] Autocomplete attributes definidos
+- [ ] Touch targets >= 44x44px
+- [ ] Keyboard navigation funcional

package/squads/squad-design/tasks/design-icon-system.md

@@ -0,0 +1,136 @@
+---
+task: design-icon-system
+responsavel: "@dx-ui-designer"
+responsavel_type: Agent
+atomic_layer: Task
+elicit: false
+
+Entrada:
+  - campo: context
+    tipo: object
+    origem: "workflow ou manual"
+    obrigatorio: true
+
+Saida:
+  - campo: resultado
+    tipo: document
+    destino: "stakeholders"
+
+Checklist:
+  - "[ ] Validar inputs e pre-condicoes"
+  - "[ ] Executar steps conforme documentado"
+  - "[ ] Verificar criterios de qualidade"
+  - "[ ] Gerar output no formato especificado"
+---
+
+# Task: Design Icon System
+
+## Metadata
+- **Squad:** squad-design
+- **Agent:** Canvas (dx-ui-designer)
+- **Complexity:** Standard
+
+## Objetivo
+Projetar o sistema de icones do produto — definir estilo, tamanhos, grid, e guidelines de uso que garantem consistencia visual e acessibilidade.
+
+## Entrada
+- Brand guidelines (estilo visual)
+- UI component inventory
+- Navigation patterns
+- Accessibility requirements
+
+## Passos
+
+### 1. Definir Estilo
+| Aspecto | Opcoes | Decisao |
+|---------|--------|---------|
+| Tipo | Outline / Filled / Duo-tone | |
+| Peso do traço | 1px / 1.5px / 2px | |
+| Cantos | Sharp / Rounded (2px) / Round | |
+| Grid base | 16px / 20px / 24px | |
+| Padding | 1px / 2px | |
+
+### 2. Configurar Icon Grid
+```yaml
+icon_system:
+  grid: 24px  # Base grid
+  stroke_width: 1.5px
+  corner_radius: 2px
+  padding: 2px  # Safe area
+  optical_adjustment: true
+
+  sizes:
+    - name: "xs"
+      size: "16px"
+      usage: "Inline text, badges"
+      min_touch: false
+
+    - name: "sm"
+      size: "20px"
+      usage: "Buttons, inputs"
+      min_touch: false
+
+    - name: "md"
+      size: "24px"
+      usage: "Default, navigation"
+      min_touch: true  # 24x24 min target
+
+    - name: "lg"
+      size: "32px"
+      usage: "Feature highlights"
+      min_touch: true
+
+    - name: "xl"
+      size: "48px"
+      usage: "Empty states, illustrations"
+      min_touch: true
+```
+
+### 3. Categorizar Icones
+| Categoria | Exemplos | Quantidade |
+|-----------|---------|-----------|
+| Navigation | Home, menu, back, search, close | ~10 |
+| Action | Add, edit, delete, share, download | ~15 |
+| Status | Success, error, warning, info, loading | ~8 |
+| Content | File, image, video, link, text | ~10 |
+| Communication | Email, chat, notification, phone | ~8 |
+| User | Profile, settings, logout, group | ~6 |
+| Commerce | Cart, payment, invoice, shipping | ~8 |
+| Social | Like, comment, share, bookmark | ~6 |
+
+### 4. Definir Guidelines de Uso
+- **Sempre com label** para acoes primarias (a11y)
+- **aria-hidden="true"** quando decorativo
+- **aria-label** quando standalone sem texto
+- **currentColor** para herdar cor do parent
+- **Nao usar icones como unico indicador** (a11y)
+
+### 5. Documentar Naming Convention
+```
+[category]-[name]-[variant]
+```
+Exemplos: `nav-home`, `action-edit`, `status-success-filled`
+
+### 6. Export Pipeline
+| Formato | Uso | Otimizacao |
+|---------|-----|-----------|
+| SVG | Web, inline | SVGO optimized |
+| React Component | Next.js/React | Tree-shakeable |
+| SVG Sprite | Multi-icon pages | Single request |
+| Icon Font | Legacy support | Fallback |
+
+## Saida
+- Icon style guide
+- Icon grid specification
+- Icon inventory com categorias
+- Usage guidelines (a11y-compliant)
+- Export pipeline configuration
+- Handoff para Scaffold (implementation)
+
+## Validacao
+- [ ] Grid base e estilo definidos
+- [ ] Todas as categorias cobertas
+- [ ] Guidelines de a11y documentados
+- [ ] Naming convention consistente
+- [ ] Sizes com touch targets adequados (WCAG 2.5.8)
+- [ ] Export pipeline configurado

package/squads/squad-design/tasks/design-information-architecture.md

@@ -0,0 +1,123 @@
+---
+task: design-information-architecture
+responsavel: "@dx-ux-strategist"
+responsavel_type: Agent
+atomic_layer: Task
+elicit: false
+
+Entrada:
+  - campo: context
+    tipo: object
+    origem: "workflow ou manual"
+    obrigatorio: true
+
+Saida:
+  - campo: resultado
+    tipo: document
+    destino: "stakeholders"
+
+Checklist:
+  - "[ ] Validar inputs e pre-condicoes"
+  - "[ ] Executar steps conforme documentado"
+  - "[ ] Verificar criterios de qualidade"
+  - "[ ] Gerar output no formato especificado"
+---
+
+# Task: Design Information Architecture
+
+## Metadata
+- **Squad:** squad-design
+- **Agent:** Compass (dx-ux-strategist)
+- **Complexity:** Complex
+
+## Objetivo
+Projetar a arquitetura de informacao — organizar, estruturar e rotular conteudo de forma que usuarios encontrem o que precisam intuitivamente.
+
+## Entrada
+- User research synthesis
+- Personas e journey maps
+- Content inventory (se existente)
+- Business requirements
+- Card sorting results (se disponivel)
+
+## Passos
+
+### 1. Auditar Conteudo Existente
+| Tipo | Quantidade | Status | Notas |
+|------|-----------|--------|-------|
+| Paginas | | | |
+| Features | | | |
+| Content types | | | |
+| Media assets | | | |
+
+### 2. Definir Taxonomia
+Organizar conteudo em categorias logicas:
+- **Top-down:** Baseado em business goals e modelo mental dos stakeholders
+- **Bottom-up:** Baseado em card sorting e modelos mentais dos usuarios
+- **Resultado:** Hibrido validado
+
+### 3. Criar Sitemap
+```yaml
+sitemap:
+  - page: "Home"
+    path: "/"
+    priority: "primary"
+    children:
+      - page: ""
+        path: ""
+        children: []
+```
+
+Niveis de navegacao:
+- **Primario:** Ate 7 items (+/- 2, Miller's Law)
+- **Secundario:** Ate 7 items por categoria
+- **Terciario:** Contextual, progressive disclosure
+
+### 4. Definir Navigation Patterns
+| Pattern | Quando usar | Exemplo |
+|---------|------------|---------|
+| Global nav | Sempre visivel | Header menu |
+| Local nav | Dentro de secao | Sidebar |
+| Contextual nav | Relacionado ao conteudo | Related items |
+| Breadcrumbs | Hierarquia profunda | Category > Sub > Page |
+| Search | Conteudo vasto | Search bar |
+| Faceted nav | Filtering complexo | Product catalog |
+
+### 5. Criar Labeling System
+Principios de rotulacao:
+- Familiar ao usuario (nao jargao interno)
+- Consistente em todo o produto
+- Conciso mas descritivo
+- Validado via tree testing
+
+### 6. Validar com Tree Testing
+Preparar cenarios de teste:
+```yaml
+tree_test:
+  task: ""
+  expected_path: []
+  success_criteria: "Findability >= 80%"
+```
+
+### 7. Documentar IA
+- Sitemap completo
+- Navigation model
+- Content model (types, relationships)
+- Search strategy
+- URL structure
+
+## Saida
+- Sitemap hierarquico
+- Navigation model documentado
+- Content model
+- Labeling system
+- Tree test results (se executado)
+- Handoff para Canvas (layouts) e Scaffold (routing)
+
+## Validacao
+- [ ] Sitemap cobre todas as paginas/features
+- [ ] Navegacao primaria <= 7 items
+- [ ] Labels validados com usuarios
+- [ ] URL structure semantica e consistente
+- [ ] Modelo de conteudo definido
+- [ ] Accessibility da navegacao considerada

package/squads/squad-design/tasks/design-landing-page-ui.md

@@ -0,0 +1,112 @@
+---
+task: design-landing-page-ui
+responsavel: "@dx-ui-designer"
+responsavel_type: Agent
+atomic_layer: Task
+elicit: false
+
+Entrada:
+  - campo: context
+    tipo: object
+    origem: "workflow ou manual"
+    obrigatorio: true
+
+Saida:
+  - campo: resultado
+    tipo: document
+    destino: "stakeholders"
+
+Checklist:
+  - "[ ] Validar inputs e pre-condicoes"
+  - "[ ] Executar steps conforme documentado"
+  - "[ ] Verificar criterios de qualidade"
+  - "[ ] Gerar output no formato especificado"
+---
+
+# Task: Design Landing Page UI
+
+## Metadata
+- **Squad:** squad-design
+- **Agent:** Canvas (dx-ui-designer)
+- **Complexity:** Standard
+
+## Objetivo
+Projetar a UI visual de landing pages de alta conversao — aplicar principios de visual hierarchy, scanning patterns e brand para criar paginas que guiam o usuario ate a acao desejada.
+
+## Entrada
+- Wireframe brief (de Compass)
+- Copy estruturada (de squad-copy)
+- Brand tokens e visual guidelines
+- Conversion goals
+- Target audience
+
+## Passos
+
+### 1. Definir Secoes da LP
+| Secao | Proposito | Visual Priority |
+|-------|----------|----------------|
+| Hero | Capturar atencao, comunicar value prop | Maxima |
+| Social proof | Construir credibilidade | Alta |
+| Benefits | Mostrar valor | Alta |
+| How it works | Reduzir incerteza | Media |
+| Features | Detalhar funcionalidades | Media |
+| Testimonials | Validacao social | Media |
+| Pricing | Decisao | Alta |
+| FAQ | Resolver objecoes | Baixa |
+| Final CTA | Converter | Alta |
+
+### 2. Hero Section Design
+| Elemento | Specification |
+|----------|--------------|
+| Headline | Display size, max 60 chars, above fold |
+| Subheadline | Body-lg, max 120 chars |
+| CTA Primary | Large button, contrasting color |
+| CTA Secondary | Text link or ghost button |
+| Visual | Hero image/illustration/video, full-width or split |
+| Social proof | Logos, numbers, or mini-testimonial |
+
+### 3. Visual Rhythm
+- Alternar secoes claras e escuras para criar ritmo
+- Usar whitespace generoso entre secoes (64-120px)
+- Manter CTA visivel a cada 2-3 scroll depths
+- Gradual disclosure de complexidade
+
+### 4. CTA Design System
+| CTA Tipo | Visual | Posicao |
+|----------|--------|---------|
+| Primary | Filled, brand color, large | Hero, pricing, final |
+| Secondary | Outline or ghost | Alongside primary |
+| Sticky | Compact, fixed bottom (mobile) | Always visible |
+| Inline | Text link with arrow | Within content |
+
+### 5. Trust Signals
+| Tipo | Posicao | Formato |
+|------|---------|---------|
+| Client logos | Below hero | Logo strip, 4-6 logos |
+| Numbers | After hero or benefits | Big numbers + label |
+| Testimonials | Mid-page | Card with photo, name, role |
+| Badges | Near CTA | Security, guarantee icons |
+| Case studies | After features | Mini cards with results |
+
+### 6. Performance
+- Hero image: WebP, preloaded, < 100KB
+- Below-fold images: Lazy loaded
+- Video: Poster frame + lazy load
+- Fonts: 2 weights max, preloaded
+- LCP target: < 2.5s
+
+## Saida
+- Landing page visual design (high-fidelity)
+- Section-by-section specifications
+- CTA design system
+- Trust signal placement
+- Responsive adaptations
+- Handoff para Scaffold (build) e Apex (performance)
+
+## Validacao
+- [ ] Hero comunica value prop em 5 segundos
+- [ ] CTA visivel acima do fold
+- [ ] Visual rhythm consistente
+- [ ] Trust signals posicionados estrategicamente
+- [ ] Responsive em todos os breakpoints
+- [ ] Performance otimizada (hero < 100KB)