iron-edge 1.0.0

package/squads/squad-design/tasks/design-component-api-contracts.md

@@ -0,0 +1,167 @@
+---
+task: design-component-api-contracts
+responsavel: "@dx-design-system-architect"
+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 Component API Contracts
+
+## Metadata
+- **Squad:** squad-design
+- **Agent:** Stratum (dx-design-system-architect)
+- **Complexity:** Complex
+
+## Objetivo
+Projetar contratos de API de componentes — definir props, variants, slots, eventos e composicao de cada componente de forma que a interface publica seja estavel, previsivel e extensivel.
+
+## Entrada
+- Component inventory
+- Visual design specs (de Canvas)
+- Accessibility requirements (de Beacon)
+- Usage patterns observados
+
+## Passos
+
+### 1. Definir API Design Principles
+| Principio | Descricao |
+|-----------|-----------|
+| Minimal API surface | Menor numero de props necessarias |
+| Sensible defaults | Funciona sem props opcionais |
+| Composable | Compoe com outros componentes |
+| Accessible by default | A11y built-in, nao opt-in |
+| Type-safe | TypeScript strict |
+| Consistent | Padroes iguais entre componentes |
+
+### 2. Template de API Contract
+```typescript
+// Component API Contract
+interface ButtonProps {
+  // Required
+  children: React.ReactNode;
+
+  // Variants
+  variant?: 'primary' | 'secondary' | 'ghost' | 'danger';
+  size?: 'sm' | 'md' | 'lg';
+
+  // State
+  disabled?: boolean;
+  loading?: boolean;
+
+  // Behavior
+  onClick?: (event: React.MouseEvent) => void;
+  type?: 'button' | 'submit' | 'reset';
+
+  // Composition
+  leftIcon?: React.ReactNode;
+  rightIcon?: React.ReactNode;
+
+  // Polymorphism
+  as?: React.ElementType;
+
+  // A11y (built-in)
+  // - role="button" (default)
+  // - aria-disabled when disabled
+  // - aria-busy when loading
+
+  // Styling
+  className?: string;
+}
+```
+
+### 3. Padroes de API Cross-Component
+| Pattern | Componentes | Props |
+|---------|-----------|-------|
+| Variant + Size | Button, Input, Badge, Avatar | variant, size |
+| Controlled/Uncontrolled | Input, Select, Checkbox | value/defaultValue, onChange |
+| Compound Components | Tabs, Accordion, Menu | Parent + Child |
+| Render Props/Slots | Modal, Popover, Table | header, content, footer |
+| Polymorphic (as) | Button, Link, Card | as={Component} |
+
+### 4. Definir per Component
+Para cada componente core:
+
+```yaml
+component_api:
+  name: ""
+  element: ""  # Semantic HTML base
+  description: ""
+
+  props:
+    required: []
+    variants: []
+    state: []
+    behavior: []
+    composition: []
+    a11y_auto: []  # Handled internally
+
+  events:
+    - name: ""
+      payload: ""
+      when: ""
+
+  slots:
+    - name: ""
+      type: ""
+      description: ""
+
+  composition_rules:
+    allowed_children: []
+    forbidden_patterns: []
+
+  a11y_contract:
+    role: ""
+    aria_attributes: []
+    keyboard: {}
+    focus_management: ""
+```
+
+### 5. Versioning Strategy
+| Change Type | Version Impact | Example |
+|------------|---------------|---------|
+| New optional prop | Patch | Add `leftIcon` to Button |
+| New variant | Minor | Add `ghost` variant |
+| Rename prop | Major (breaking) | `color` → `variant` |
+| Remove prop | Major (breaking) | Remove `outline` |
+| Change default | Major (if behavior changes) | Change default size |
+
+### 6. Documentation Requirements
+Cada API contract deve incluir:
+- Props table com types e defaults
+- Usage examples (basic, with variants, composed)
+- Do/Don't examples
+- Accessibility notes
+- Migration guide (se breaking change)
+
+## Saida
+- API contracts per component (TypeScript interfaces)
+- Cross-component pattern documentation
+- Versioning policy
+- Documentation templates
+- Handoff para Scaffold (implementation)
+
+## Validacao
+- [ ] API minimal (sem props desnecessarias)
+- [ ] Defaults sensiveis (funciona sem config)
+- [ ] TypeScript strict compliant
+- [ ] A11y built-in (nao opt-in)
+- [ ] Consistent patterns cross-component
+- [ ] Versioning policy definida

package/squads/squad-design/tasks/design-component-visual-states.md

@@ -0,0 +1,132 @@
+---
+task: design-component-visual-states
+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 Component Visual States
+
+## Metadata
+- **Squad:** squad-design
+- **Agent:** Canvas (dx-ui-designer)
+- **Complexity:** Standard
+
+## Objetivo
+Projetar todos os estados visuais de cada componente — garantir que cada estado possivel e visualmente comunicado com clareza, consistencia e acessibilidade.
+
+## Entrada
+- Component inventory (de Stratum)
+- Brand tokens (cores, tipografia)
+- Accessibility requirements (WCAG 2.2)
+- Interaction patterns (de Kinetic)
+
+## Passos
+
+### 1. Definir Estado Matrix
+Para cada componente, mapear estados:
+
+| Estado | Descricao | Trigger |
+|--------|-----------|---------|
+| Default | Estado normal, nenhuma interacao | — |
+| Hover | Mouse sobre o elemento | mouseenter |
+| Focus | Navegacao por teclado | tab/focus |
+| Active/Pressed | Sendo clicado/tocado | mousedown/touchstart |
+| Selected | Item selecionado | click |
+| Disabled | Indisponivel | programmatic |
+| Loading | Aguardando resposta | async operation |
+| Error | Validacao falhou | validation |
+| Success | Acao completada | confirmation |
+| Empty | Sem conteudo | no data |
+| Skeleton | Carregando conteudo | initial load |
+| Read-only | Visivel mas nao editavel | permission |
+
+### 2. Definir Visual Language por Estado
+```yaml
+state_visual_system:
+  hover:
+    background: "lighten 5% or darken 5%"
+    cursor: "pointer"
+    transition: "150ms ease-out"
+
+  focus:
+    outline: "2px solid focus-ring-color"
+    outline_offset: "2px"
+    # WCAG 2.2: Focus indicator must have 3:1 contrast
+    # WCAG 2.4.13: Focus appearance area >= 2px perimeter
+
+  active:
+    transform: "scale(0.98)"
+    background: "darken 10%"
+    transition: "50ms ease-in"
+
+  disabled:
+    opacity: 0.5
+    cursor: "not-allowed"
+    # NAO usar apenas cor para indicar disabled
+
+  error:
+    border_color: "error-500"
+    icon: "error-icon"
+    message_color: "error-700"
+    # Usar icone + cor + texto (nao apenas cor)
+
+  loading:
+    animation: "pulse or spinner"
+    aria_busy: true
+    interaction: "blocked"
+```
+
+### 3. Componentes por Prioridade
+| Prioridade | Componentes |
+|-----------|------------|
+| P0 | Button, Input, Link, Checkbox, Radio |
+| P1 | Select, Textarea, Card, Modal, Toast |
+| P2 | Tabs, Accordion, Table, Pagination |
+| P3 | Tooltip, Popover, Breadcrumb, Badge |
+
+### 4. Documentar State Combinations
+Alguns estados se combinam:
+- Hover + Focus (mouse sobre elemento focado)
+- Disabled + Selected (item selecionado mas desabilitado)
+- Error + Focus (campo com erro recebendo foco)
+- Loading + Disabled (loading impede interacao)
+
+### 5. Criar State Sheet
+Para cada componente, produzir um "state sheet" visual:
+- Todos os estados lado a lado
+- Com annotations de tokens usados
+- Dark mode variants incluidos
+
+## Saida
+- State visual system documentation
+- State sheets por componente
+- Token mapping por estado
+- Dark mode state variants
+- Handoff para Scaffold (implementation) e Beacon (a11y review)
+
+## Validacao
+- [ ] Todos os estados mapeados por componente
+- [ ] Focus visible com contraste >= 3:1 (WCAG 2.4.13)
+- [ ] Disabled nao depende apenas de cor
+- [ ] Error usa icone + cor + texto
+- [ ] State combinations documentadas
+- [ ] Dark mode variants incluidos

package/squads/squad-design/tasks/design-dashboard-layouts.md

@@ -0,0 +1,134 @@
+---
+task: design-dashboard-layouts
+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 Dashboard Layouts
+
+## Metadata
+- **Squad:** squad-design
+- **Agent:** Canvas (dx-ui-designer)
+- **Complexity:** Complex
+
+## Objetivo
+Projetar layouts de dashboard que comunicam informacao densa de forma clara — organizar widgets, KPIs, graficos e acoes em composicoes escaneabeis e acionaveis.
+
+## Entrada
+- User personas (quem usa dashboards)
+- KPIs e metricas relevantes
+- Data types e volumes
+- User tasks no dashboard
+- Device priorities
+
+## Passos
+
+### 1. Classificar Tipo de Dashboard
+| Tipo | Proposito | Densidade | Interatividade |
+|------|----------|-----------|---------------|
+| Strategic | Visao executiva | Baixa | Drill-down |
+| Analytical | Explorar dados | Alta | Filtros, slicing |
+| Operational | Monitorar em tempo real | Media | Alertas, acoes |
+| Informational | Reportar status | Media-baixa | Minimal |
+
+### 2. Definir Layout Structure
+```yaml
+dashboard_layout:
+  type: ""
+  grid: "12-column"
+
+  regions:
+    - name: "header"
+      span: "1-12"
+      content: ["title", "date_range", "filters", "actions"]
+
+    - name: "kpi_bar"
+      span: "1-12"
+      content: ["kpi_card x 4-6"]
+      height: "auto"
+
+    - name: "primary_chart"
+      span: "1-8"
+      content: ["main visualization"]
+      height: "400px"
+
+    - name: "secondary_panel"
+      span: "9-12"
+      content: ["supporting data", "recent activity"]
+      height: "400px"
+
+    - name: "detail_grid"
+      span: "1-12"
+      content: ["table or card grid"]
+      height: "auto"
+```
+
+### 3. Projetar Widget System
+| Widget | Uso | Tamanho Grid |
+|--------|-----|-------------|
+| KPI Card | Single metric + trend | 2-3 cols |
+| Line Chart | Trends over time | 4-8 cols |
+| Bar Chart | Comparacoes | 4-8 cols |
+| Donut/Pie | Distribuicao | 3-4 cols |
+| Table | Data detalhada | 6-12 cols |
+| Activity Feed | Eventos recentes | 3-4 cols |
+| Map | Dados geograficos | 6-8 cols |
+| Sparkline | Inline trends | 2-3 cols |
+
+### 4. Information Hierarchy
+| Nivel | Conteudo | Visual Treatment |
+|-------|----------|-----------------|
+| L1 | KPIs principais (3-5) | Grande, topo, bold |
+| L2 | Trends e charts | Meio, graficos |
+| L3 | Detalhes e tabelas | Abaixo, menor |
+| L4 | Filtros e acoes | Header ou sidebar |
+
+### 5. Responsive Adaptation
+| Viewport | KPIs | Charts | Tables |
+|----------|------|--------|--------|
+| Desktop | 4-6 em linha | Full-size | Full columns |
+| Tablet | 3 em linha | Reduced | Key columns |
+| Mobile | 2 em linha, stacked | Simplified | Card view |
+
+### 6. Data Visualization Principles
+- **Escolher chart type pelo tipo de dado** (nao por estetica)
+- **Manter ratio informacao/tinta alto** (Tufte)
+- **Evitar 3D, shadows em charts**
+- **Labels diretos** (nao legendas separadas quando possivel)
+- **Cores acessiveis** para daltonismo (nao apenas cor)
+- **Loading states** para dados asincrono (skeleton)
+
+## Saida
+- Dashboard layout templates
+- Widget design specifications
+- Data visualization guidelines
+- Responsive adaptation rules
+- Loading/empty state specs
+- Handoff para Scaffold (implementation)
+
+## Validacao
+- [ ] Hierarquia de informacao clara
+- [ ] KPIs visiveis acima do fold
+- [ ] Charts adequados ao tipo de dado
+- [ ] Responsive em todos os breakpoints
+- [ ] Loading states para dados async
+- [ ] Color-blind safe palette

package/squads/squad-design/tasks/design-duration-scale.md

@@ -0,0 +1,128 @@
+---
+task: design-duration-scale
+responsavel: "@dx-interaction-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 Duration Scale
+
+## Metadata
+- **Squad:** squad-design
+- **Agent:** Kinetic (dx-interaction-designer)
+- **Complexity:** Standard
+
+## Objetivo
+Projetar escala de duracao de animacoes — definir tempos padronizados que criam ritmo consistente e respeitam o Doherty Threshold (< 400ms).
+
+## Entrada
+- Motion principles
+- Interaction types
+- Performance requirements
+- Accessibility (max duration)
+
+## Passos
+
+### 1. Duration Scale
+```json
+{
+  "motion": {
+    "duration": {
+      "instant": { "$value": "50ms", "$type": "duration", "$description": "Hover states, opacity changes" },
+      "fast": { "$value": "100ms", "$type": "duration", "$description": "Button states, small reveals" },
+      "normal": { "$value": "200ms", "$type": "duration", "$description": "Default UI transitions" },
+      "slow": { "$value": "300ms", "$type": "duration", "$description": "Complex transitions, panels" },
+      "slower": { "$value": "500ms", "$type": "duration", "$description": "Page transitions, large reveals" },
+      "deliberate": { "$value": "700ms", "$type": "duration", "$description": "Attention-grabbing, onboarding" }
+    }
+  }
+}
+```
+
+### 2. Duration by Context
+| Contexto | Duration | Rationale |
+|----------|----------|-----------|
+| Hover feedback | 50-100ms | Immediate response |
+| Focus ring | 0ms (instant) | Never delay focus |
+| Button state change | 100ms | Quick feedback |
+| Tooltip appear | 100ms delay + 100ms fade | Brief wait |
+| Dropdown open | 200ms | Smooth reveal |
+| Modal enter | 200-300ms | Comfortable appearance |
+| Modal exit | 150-200ms | Faster exit than enter |
+| Tab content switch | 150-200ms | Quick swap |
+| Page transition | 300-500ms | Noticeable but not slow |
+| Loading skeleton | continuous | Until content loads |
+| Notification auto-dismiss | 5000ms | Time to read |
+
+### 3. Rules
+| Regra | Descricao |
+|-------|-----------|
+| **Doherty Threshold** | Resposta total < 400ms para sentir "instantaneo" |
+| **Exit < Enter** | Animacao de saida 20-30% mais rapida que entrada |
+| **Larger = Slower** | Elementos maiores precisam de mais tempo |
+| **Closer = Faster** | Movimentos curtos sao mais rapidos |
+| **Max decorative** | 800ms maximo para animacoes decorativas |
+| **No infinite** | Exceto loading spinners, nada infinito |
+
+### 4. Size-Duration Relationship
+| Tamanho do movimento | Duration |
+|---------------------|----------|
+| Micro (< 100px) | 100-200ms |
+| Small (100-300px) | 200-300ms |
+| Medium (300-600px) | 300-500ms |
+| Large (> 600px) | 500-700ms |
+
+### 5. Staggering (Sequencing)
+Para listas animadas:
+```yaml
+stagger:
+  delay_between_items: "50ms"
+  max_total_duration: "500ms"  # Cap total stagger
+  max_items: 10  # Stop staggering after 10
+  direction: "[top-down/left-right/center-out]"
+```
+
+### 6. CSS Custom Properties
+```css
+:root {
+  --duration-instant: 50ms;
+  --duration-fast: 100ms;
+  --duration-normal: 200ms;
+  --duration-slow: 300ms;
+  --duration-slower: 500ms;
+  --duration-deliberate: 700ms;
+}
+```
+
+## Saida
+- Duration scale (W3C DTCG tokens)
+- Duration by context guide
+- Size-duration relationship
+- Staggering rules
+- CSS custom properties
+
+## Validacao
+- [ ] Scale progressiva e consistente
+- [ ] Doherty Threshold respeitado (< 400ms para feedback)
+- [ ] Exit < Enter rule documentada
+- [ ] Max duration 800ms para decorativas
+- [ ] Stagger capped em 500ms total
+- [ ] Tokens em formato W3C DTCG

package/squads/squad-design/tasks/design-feedback-animations.md

@@ -0,0 +1,147 @@
+---
+task: design-feedback-animations
+responsavel: "@dx-interaction-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 Feedback Animations
+
+## Metadata
+- **Squad:** squad-design
+- **Agent:** Kinetic (dx-interaction-designer)
+- **Complexity:** Standard
+
+## Objetivo
+Projetar animacoes de feedback — definir como o sistema comunica visualmente sucesso, erro, warning e progresso ao usuario.
+
+## Entrada
+- Feedback states (de Canvas)
+- Toast/notification patterns
+- Motion tokens
+- A11y requirements
+
+## Passos
+
+### 1. Feedback Animation Types
+| Tipo | Visual | Duracao | Easing |
+|------|--------|---------|--------|
+| Success | Checkmark draw + scale | 500ms | decelerate |
+| Error | Shake + error icon | 400ms | sharp |
+| Warning | Pulse attention | 300ms | standard |
+| Info | Fade-in | 200ms | decelerate |
+| Loading | Spinner/pulse | continuous | linear |
+| Progress | Fill bar | proportional | standard |
+
+### 2. Success Animation
+```yaml
+success:
+  checkmark:
+    animation: "stroke-dashoffset draw"
+    duration: "400ms"
+    delay: "100ms after container appears"
+    easing: "var(--ease-decelerate)"
+    color: "success-500"
+  container:
+    animation: "scale(0.8) → scale(1)"
+    duration: "300ms"
+    easing: "var(--ease-spring)"
+  reduced_motion: "Instant checkmark, no animation"
+```
+
+### 3. Error Animation
+```yaml
+error:
+  shake:
+    animation: "translateX [-4, 4, -4, 4, 0]px"
+    duration: "400ms"
+    easing: "var(--ease-sharp)"
+    apply_to: "form field or container"
+  icon:
+    animation: "scale(0) → scale(1)"
+    duration: "200ms"
+    easing: "var(--ease-spring)"
+  border:
+    animation: "color change to error"
+    duration: "var(--duration-fast)"
+  reduced_motion: "Instant color change, no shake"
+```
+
+### 4. Toast/Notification Animations
+```yaml
+toast:
+  enter:
+    from: "translateY(100%) opacity(0)"
+    to: "translateY(0) opacity(1)"
+    duration: "var(--duration-slow)"
+    easing: "var(--ease-decelerate)"
+  exit:
+    from: "translateY(0) opacity(1)"
+    to: "translateY(-20px) opacity(0)"
+    duration: "var(--duration-normal)"
+    easing: "var(--ease-accelerate)"
+  auto_dismiss:
+    delay: "5000ms"
+    countdown: "progress bar width 100% → 0%"
+  stacking: "newer pushes older up by toast height + 8px gap"
+  reduced_motion: "instant appear/disappear"
+```
+
+### 5. Progress Animations
+```yaml
+progress:
+  determinate:
+    animation: "width 0% → target%"
+    easing: "var(--ease-standard)"
+    transition: "width var(--duration-normal)"
+  indeterminate:
+    animation: "translateX(-100%) → translateX(100%)"
+    duration: "1.5s"
+    iteration: "infinite"
+    easing: "var(--ease-standard)"
+  reduced_motion:
+    determinate: "instant width change"
+    indeterminate: "pulse opacity"
+```
+
+### 6. Haptic Patterns (Mobile)
+| Feedback | Haptic | Quando |
+|----------|--------|--------|
+| Success | Light impact | Action completed |
+| Error | Notification | Validation failed |
+| Warning | Warning | Destructive action |
+| Toggle | Selection | Switch/checkbox |
+
+## Saida
+- Feedback animation specifications
+- Success/error/warning animation specs
+- Toast animation specs
+- Progress animation specs
+- Haptic feedback guide
+- Reduced motion alternatives
+
+## Validacao
+- [ ] Cada tipo de feedback tem animacao definida
+- [ ] Duracoes usando motion tokens
+- [ ] Reduced motion alternatives
+- [ ] Toast auto-dismiss timing
+- [ ] No flashing > 3/second
+- [ ] Screen readers anunciam feedback (aria-live)