sinapse-ai 9.2.0 → 9.4.0

package/squads/squad-design/knowledge-base/brazilian-design-context.md

@@ -0,0 +1,223 @@
+# Knowledge Base: Brazilian Design Context
+
+## Escopo
+Mercado de design no Brasil — design systems nacionais, regulatorio (LBI, e-MAG), comunidade, salarios, desafios especificos e contexto de acessibilidade legal. Fonte: MS-002 Design System Research (2026-04-07).
+
+---
+
+## 1. Mercado de Design Digital no Brasil (2025)
+
+### Tamanho e Crescimento
+- **200.000+** profissionais de UX/UI design (ABEDESIGN + LinkedIn Economic Graph, 2025)
+- **15-20% a.a.** de crescimento do mercado
+- Aceleracao pos-pandemia: digital-first em fintechs, e-commerce, saude digital
+
+### Centros de Design
+| Cidade | Destaque |
+|--------|----------|
+| **Sao Paulo** | Hub principal, maioria das agencias e tech companies |
+| **Florianopolis** | Polo tecnologico forte (Resultados Digitais, Ahgora, TOTVS) |
+| **Belo Horizonte** | Ecossistema crescente (Hotmart, Rock Content) |
+| **Recife** | Porto Digital como polo de inovacao |
+| **Porto Alegre, Curitiba, Brasilia** | Comunidades ativas e crescentes |
+
+### Salarios UX/UI Design (2025, CLT, Sao Paulo)
+| Nivel | Faixa |
+|-------|-------|
+| Junior | R$ 3.000 - R$ 5.500 |
+| Pleno | R$ 6.000 - R$ 12.000 |
+| Senior | R$ 12.000 - R$ 22.000 |
+| Lead / Manager | R$ 18.000 - R$ 35.000 |
+| Head of Design | R$ 25.000 - R$ 50.000+ |
+
+Salarios PJ geralmente 30-50% acima do CLT para o mesmo nivel.
+
+---
+
+## 2. Design Systems Brasileiros
+
+### Nubank — NuDS (Nubank Design System)
+O Nubank e referencia global em fintech design. O NuDS evoluiu de uma biblioteca minimalista para um framework multi-mercado com:
+- **100+ componentes** reutilizaveis e templates de tela
+- Suporte a multiplos mercados (Brasil, Mexico, Colombia, Argentina)
+
+**Nu Sans (2025):** A Nubank lancou tipografia propria desenvolvida pela **Blackletra Type Foundry**:
+- 2 tamanhos oticos (texto e display)
+- 3 larguras
+- 4 pesos com italicos
+- **32 fontes no total**
+
+**Impacto de tokens na pratica:** A atualizacao recente de brand colors para contas empresariais (Nubank Empresas) foi implementada em **um unico sprint** gracas a arquitetura de tokens do NuDS. Sem tokens, isso levaria semanas de refactor.
+
+**Referencia:** building.nubank.com/design, figma.com/customers/nubank-design-system-accessible-experiences-with-figma
+
+### Itau Unibanco — Design System
+O maior banco privado da America Latina com design system robusto para seus canais digitais:
+- App, internet banking, ATMs, totem, correspondente bancario
+- Foco: consistencia cross-channel, acessibilidade regulatoria financeira, escala (dezenas de milhoes de usuarios diarios)
+
+**Reformulacao digital 2025:** O Itau anunciou meta de atender **75% dos clientes de varejo exclusivamente por canais digitais** nos proximos 3 anos (vs 15% atual em 2025). Isso implica investimento significativo na evolucao do design system e na experiencia digital.
+
+### Natura Design System (Natura &Co)
+Um dos casos mais avancados de design system multi-brand no Brasil. Grupo possui:
+- Natura, Avon, The Body Shop, Aesop
+
+**Desafio tecnico:** Um sistema que suporta multiplas marcas visuais sobre mesma arquitetura. Solucao: core system de tokens e componentes "neutros" tematizados via L1 tokens de marca. O mesmo `<Button>` renderiza verde para Natura, rosa para Avon.
+
+### VTEX Design System (Styleguide)
+Plataforma de e-commerce brasileira com design system open-source. Um dos poucos DS brasileiros genuinamente open-source, usado por times de desenvolvimento de lojistas VTEX.
+
+### RD Station (Resultados Digitais)
+Lider em marketing digital no Brasil. DS interno para produtos do ecossistema (Marketing, CRM, Conversas). React-based, foco em consistencia entre produtos.
+
+### Magazine Luiza (Magalu)
+DS para unificar experiencia entre app, site e marketplace. Destaque para inclusao da "Lu" (avatar digital) como elemento do sistema de brand — integracao de IP/mascote em design system.
+
+---
+
+## 3. Regulatorio Brasileiro de Acessibilidade
+
+### Lei Brasileira de Inclusao (LBI — Lei 13.146/2015)
+
+Artigo 63:
+> "E obrigatoria a acessibilidade nos sitios da internet mantidos por empresas com sede ou representacao comercial no Pais ou por orgaos de governo."
+
+**Implicacoes para design systems:**
+- Componentes DEVEM atender **WCAG AA** como minimo
+- Acessibilidade digital e **obrigacao legal**, nao diferencial competitivo
+- Multas podem ser aplicadas pelo Ministerio Publico
+- Empresas com representacao no Brasil estao sujeitas (inclui empresas estrangeiras)
+
+### e-MAG (Modelo de Acessibilidade em Governo Eletronico)
+Versao brasileira do WCAG, publicada pelo governo federal. Atualmente baseado no **WCAG 2.0**, com recomendacoes adicionais para o contexto brasileiro.
+
+**Todo site governamental deve seguir e-MAG.** Sites privados seguem LBI (que referencia WCAG).
+
+Diferenca WCAG vs e-MAG:
+| Aspecto | WCAG (internacional) | e-MAG (brasileiro) |
+|---------|---------------------|-------------------|
+| Base | W3C | Governo Federal do Brasil |
+| Versao atual | 2.2 (2023) | Baseado em WCAG 2.0 |
+| Obrigatoriedade | Por lei em varios paises | Governo federal (obligatorio) |
+| Privados | Por LBI | Por LBI (referencia WCAG) |
+
+### Decreto 10.645/2021
+Regulamenta avaliacao de acessibilidade de sites governamentais:
+- Exige **selo de acessibilidade**
+- Auditorias periodicas obrigatorias
+- Ranking de acessibilidade de sites governamentais
+
+### Checklist Legal para DS Brasileiro
+```
+- [ ] Componentes atendem WCAG 2.2 AA (minimo legal LBI)
+- [ ] Contraste de texto minimo 4.5:1 (normal) e 3:1 (grande)
+- [ ] Contraste de componentes UI minimo 3:1 (1.4.11)
+- [ ] Navegacao por teclado completa
+- [ ] Sites governamentais: seguir e-MAG
+- [ ] Documentar conformidade WCAG (VPAT/declaracao de acessibilidade)
+```
+
+---
+
+## 4. Desafios Especificos do Brasil
+
+### 1. Diversidade de Dispositivos Android
+O Brasil tem enorme variedade de dispositivos Android de baixo custo (R$ 400-800). Implicacoes:
+- Telas menores (5"-5.5" comuns vs 6"+ nos EUA)
+- Menor RAM (2-4GB)
+- Processadores mais lentos
+- **Design systems precisam priorizar performance em low-end**
+
+### 2. Conectividade Variavel
+Muitos usuarios acessam via conexoes lentas (3G ainda significativo) ou instáveis (Wi-Fi compartilhado). Implicacoes:
+- Progressive loading e skeleton screens
+- Graceful degradation (app funciona com conteudo parcial)
+- Service workers para caching agressivo
+- **Imagens otimizadas para conexoes lentas (AVIF/WebP, lazy loading)**
+
+### 3. PIX como Padrao de Pagamento
+Desde 2020, PIX transformou checkout digital no Brasil. **120M+ usuarios** (maior adocao global proporcional). Design systems de e-commerce e fintech devem incluir patterns especificos:
+- QR Code display (tamanho, contraste, loading state)
+- Copia-e-cola (action + feedback de copia)
+- Timer de expiracao (countdown com accessible announcement)
+- Confirmacao de pagamento (success state com animacao)
+
+### 4. WhatsApp-First Journey
+Brasil e o segundo maior mercado do WhatsApp (120M+ usuarios, 2025). Muitas jornadas de usuario comecam ou terminam no WhatsApp:
+- Click-to-chat buttons (pattern padrao em landing pages)
+- WhatsApp share (compartilhar produto/servico via WhatsApp)
+- Notificacoes via WhatsApp Business
+- **Design systems devem incluir patterns de integracao com WhatsApp**
+
+### 5. Multilingue de Facto
+Embora portugues seja dominante, operacoes internacionais precisam de i18n:
+- Natura, Nubank: espanhol (LATAM), ingles
+- Desafio: datas (dd/mm/yyyy vs mm/dd/yyyy), moedas (R$ vs $, $ vs €)
+- **Internacionalizacao como parte das foundations, nao addon tardio**
+
+---
+
+## 5. Comunidade Brasileira de Design
+
+### Eventos
+- **Interaction Latin America (IxDA):** Principal evento de interaction design na America Latina
+- **Design Sprint Brasil:** Comunidade focada em metodologias de design
+- **UX Conf BR:** Conferencia de UX brasileira
+- **Figma Community Brasil:** Meetups e eventos de usuarios Figma
+
+### Publicacoes e Comunidades
+- **UX Collective Brasil** (brasil.uxdesign.cc): Blog coletivo com milhares de artigos em portugues
+- **Design Team Brasil:** Comunidade no Slack
+- **Ladies that UX:** Capitulos em SP, RJ, BH, POA, Floripa
+- **Design no Brasil** (designe.com.br): Recursos, salarios, comunidade
+
+### Formacao
+| Escola | Formato | Foco |
+|--------|---------|------|
+| Mergo (Pedro Aquino) | Online | UX Research e Design |
+| Tera | Bootcamp | Product Design, UX |
+| Digital House | Presencial/Online | UX/UI |
+| Domestika | Online | Cursos avulsos |
+| Alura | Online | Design Digital, Figma |
+
+---
+
+## 6. Brasilian DS Checklist (Requisitos Especificos)
+
+```
+Legal:
+- [ ] WCAG 2.2 AA compliance (LBI obrigatorio)
+- [ ] e-MAG compliance (sites governamentais)
+- [ ] LGPD compliance em formularios (consentimento claro)
+- [ ] Declaracao de acessibilidade publicada
+
+UX Patterns Brasileiros:
+- [ ] PIX payment pattern (QR code, copia-e-cola, timer, success)
+- [ ] WhatsApp integration pattern (click-to-chat, share)
+- [ ] Boleto bancario pattern (se aplicavel)
+- [ ] CPF/CNPJ input masks
+
+Performance (low-end devices):
+- [ ] Testado em Android mid-range (Moto G ou similar)
+- [ ] Funciona em 3G (simular com DevTools throttling)
+- [ ] JS bundle < 300KB initial
+- [ ] Imagens lazy-loaded com skeleton placeholder
+
+Internacionalizacao (se multi-mercado):
+- [ ] date-fns com locale pt-BR
+- [ ] Intl.NumberFormat para moedas (R$, MXN, COP)
+- [ ] RTL support (para expansao futura)
+- [ ] Strings externalizadas (nao hardcoded em portugues)
+```
+
+---
+
+## Referencias
+- ABEDESIGN — abedesign.org.br
+- Lei Brasileira de Inclusao (Lei 13.146/2015) — planalto.gov.br
+- e-MAG — emag.governoeletronico.gov.br
+- Decreto 10.645/2021 — planalto.gov.br
+- Nubank Design — building.nubank.com/design
+- Figma Customers: Nubank — figma.com/customers/nubank
+- UX Collective Brasil — brasil.uxdesign.cc
+- MS-002 Design System Research — SINAPSE (2026-04-07)

package/squads/squad-design/knowledge-base/component-api-patterns.md

@@ -348,8 +348,212 @@ const Button = ({ color, variant, ...props }: ButtonProps) => {
 
 ---
 
+---
+
+## 9. Headless Components — Padroes Avancados
+
+### Por que Headless?
+Separa **logica/comportamento** da **apresentacao visual**. Maxima flexibilidade de estilo sem reimplementar acessibilidade.
+
+### Radix UI — asChild Pattern
+```typescript
+// asChild delega renderizacao para o filho, mesclando props
+import * as Dialog from '@radix-ui/react-dialog';
+
+<Dialog.Root>
+  <Dialog.Trigger asChild>
+    {/* Button customizado — mas com toda a logica do trigger */}
+    <Button variant="primary">Open Dialog</Button>
+  </Dialog.Trigger>
+  <Dialog.Portal>
+    <Dialog.Overlay className="fixed inset-0 bg-black/50" />
+    <Dialog.Content className="fixed top-1/2 left-1/2 -translate-x-1/2 -translate-y-1/2 w-96 bg-white rounded-lg p-6 shadow-xl">
+      <Dialog.Title className="text-lg font-semibold">Title</Dialog.Title>
+      <Dialog.Description className="text-sm text-gray-600 mt-2">Description</Dialog.Description>
+      <Dialog.Close asChild>
+        <button className="absolute top-4 right-4">×</button>
+      </Dialog.Close>
+    </Dialog.Content>
+  </Dialog.Portal>
+</Dialog.Root>
+```
+
+**Acessibilidade out-of-the-box:**
+- Focus trap automatico
+- Esc fecha o dialog
+- Focus retorna ao trigger ao fechar
+- `aria-modal`, `aria-labelledby` configurados
+
+### React Aria (Adobe) — Hooks Approach
+```typescript
+// useButton — logica de button com ARIA
+import { useButton } from '@react-aria/button';
+import { useRef } from 'react';
+
+function Button(props) {
+  const ref = useRef(null);
+  const { buttonProps } = useButton(props, ref);
+
+  return (
+    <button
+      {...buttonProps}
+      ref={ref}
+      className="btn"
+    >
+      {props.children}
+    </button>
+  );
+}
+```
+
+React Aria resolve problemas que outros ignoram: date pickers acessiveis em multiplos idiomas, color pickers com suporte a screen reader, comboboxes com filtro acessivel.
+
+### Controlled vs Uncontrolled — useControllableState
+```typescript
+// Hook que unifica ambos os modos
+function useControllableState<T>({
+  value,
+  defaultValue,
+  onChange,
+}: {
+  value?: T;
+  defaultValue?: T;
+  onChange?: (value: T) => void;
+}) {
+  const [internalValue, setInternalValue] = useState(defaultValue);
+  const isControlled = value !== undefined;
+  const currentValue = isControlled ? value : internalValue;
+
+  const setValue = useCallback((next: T) => {
+    if (!isControlled) setInternalValue(next);
+    onChange?.(next);
+  }, [isControlled, onChange]);
+
+  return [currentValue, setValue] as const;
+}
+
+// Uso em componente
+function Select({ value, defaultValue, onChange, ...props }) {
+  const [selectedValue, setSelectedValue] = useControllableState({
+    value, defaultValue, onChange,
+  });
+  // ...
+}
+```
+
+---
+
+## 10. Polymorphic Components
+
+Componentes que renderizam como elementos HTML diferentes:
+
+```typescript
+// Pattern asChild (Radix — mais type-safe)
+<Button asChild>
+  <a href="/page">Navigate as link</a>
+</Button>
+
+// Pattern as prop (classico)
+<Text as="h1" size="4xl">Heading</Text>
+<Text as="p" size="base">Paragraph</Text>
+<Text as="span" size="sm">Inline</Text>
+```
+
+**Implementacao type-safe com as prop:**
+```typescript
+type TextElement = 'h1' | 'h2' | 'h3' | 'h4' | 'p' | 'span' | 'div';
+
+interface TextProps<T extends TextElement = 'p'> {
+  as?: T;
+  size?: 'sm' | 'base' | 'lg' | '2xl' | '4xl';
+  children: React.ReactNode;
+}
+
+function Text<T extends TextElement = 'p'>({
+  as,
+  size = 'base',
+  children,
+  ...props
+}: TextProps<T> & React.ComponentPropsWithoutRef<T>) {
+  const Tag = (as ?? 'p') as React.ElementType;
+  return <Tag className={cn(textVariants({ size }))} {...props}>{children}</Tag>;
+}
+```
+
+---
+
+## 11. RTL (Right-to-Left) Support
+
+Para linguas arabes, hebraicas, persas. CSS Logical Properties sao a abordagem moderna:
+
+```css
+/* Physical (RTL-unsafe) → Logical (RTL-safe) */
+margin-left: 16px;        → margin-inline-start: 16px;
+margin-right: 8px;        → margin-inline-end: 8px;
+padding-left: 16px;       → padding-inline-start: 16px;
+padding-right: 8px;       → padding-inline-end: 8px;
+text-align: left;         → text-align: start;
+border-left: 2px solid;   → border-inline-start: 2px solid;
+```
+
+**HTML dir attribute:**
+```html
+<!-- Nivel de pagina -->
+<html lang="ar" dir="rtl">
+
+<!-- Nivel de componente (se diferente da pagina) -->
+<blockquote dir="ltr" lang="en">English quote</blockquote>
+```
+
+Suporte nativo em CSS moderno (todos os browsers modernos). Design systems como Material, Fluent e Spectrum suportam RTL nativamente.
+
+---
+
+## 12. Component Quality Gates
+
+### Antes de Adicionar ao Design System
+```
+TypeScript:
+- [ ] Props com tipos completos (nenhum `any`)
+- [ ] Discriminated unions para props mutuamente exclusivas
+- [ ] forwardRef implementado (para ref passthrough)
+- [ ] displayName definido (DevTools)
+
+API Design:
+- [ ] Minimal surface area (expor apenas o necessario)
+- [ ] Sensible defaults (funciona sem props)
+- [ ] Composicao sobre configuracao
+- [ ] Naming consistente com outros componentes do sistema
+
+Acessibilidade:
+- [ ] Elementos HTML semanticos usados quando possivel
+- [ ] ARIA attributes corretos (role, aria-label, aria-*)
+- [ ] Keyboard navigation funcionando
+- [ ] Focus indicator visivel (WCAG 2.4.7)
+- [ ] axe-core: zero violations
+
+Performance:
+- [ ] Bundle size < 5KB gzipped (atoms), < 20KB (organisms)
+- [ ] Re-renders otimizados (useCallback/useMemo quando necessario)
+- [ ] Tree-shakeable (ESM export)
+
+Tokens:
+- [ ] Nenhum valor visual hardcoded
+- [ ] Component tokens (L3) definidos
+- [ ] Dark mode funcionando via tokens
+
+Documentacao:
+- [ ] Story para cada variante e estado
+- [ ] MDX com when/not-to-use
+- [ ] Migration guide se substitui componente anterior
+```
+
+---
+
 ## Referencias
-- shadcn/ui — Component patterns reference
-- Radix UI — Primitive component APIs
-- React Aria (Adobe) — Accessible component hooks
-- CVA documentation — Variant management
+- shadcn/ui — ui.shadcn.com
+- Radix UI — radix-ui.com
+- React Aria (Adobe) — react-spectrum.adobe.com/react-aria
+- CVA documentation — cva.style
+- Heydon Pickering — inclusive-components.design
+- Nathan Curtis — Component API Design articles (EightShapes)