sinapse-ai 1.0.0

package/squad-design/knowledge-base/information-architecture.md

@@ -0,0 +1,240 @@
+# Knowledge Base: Information Architecture
+
+## Escopo
+Referencia abrangente de Information Architecture (IA) — taxonomia, navegacao, organizacao de conteudo e padroes de busca para experiencias digitais.
+
+---
+
+## 1. Fundamentos de IA
+
+### Definicao
+Information Architecture e a arte e ciencia de organizar e rotular conteudo em websites, apps e sistemas para suportar usabilidade e findability.
+
+### Pilares (Rosenfeld & Morville)
+| Pilar | Descricao | Artefato Principal |
+|-------|----------|-------------------|
+| Organization | Como conteudo e agrupado | Taxonomy, categorization |
+| Labeling | Como conteudo e nomeado | Labels, nomenclature |
+| Navigation | Como usuario se move | Menus, breadcrumbs, links |
+| Search | Como usuario busca | Search UI, filters, facets |
+
+---
+
+## 2. Sistemas de Organizacao
+
+### Schemas Exatos
+| Schema | Exemplo | Quando Usar |
+|--------|---------|------------|
+| Alphabetical | A-Z listing | Directories, glossarios |
+| Chronological | Timeline, blog posts | News, historicos |
+| Geographic | Map-based | Locations, regional content |
+
+### Schemas Ambiguos
+| Schema | Exemplo | Quando Usar |
+|--------|---------|------------|
+| Topic | Categorias tematicas | Maioria dos sites |
+| Task | Ações do usuario | Apps orientados a tarefas |
+| Audience | Por tipo de usuario | Sites com publicos distintos |
+| Metaphor | Analogia visual | Quando metafora e clara |
+| Hybrid | Combinação | Maioria dos casos reais |
+
+### Estruturas
+| Estrutura | Descricao | Exemplo |
+|-----------|----------|---------|
+| Hierarchy (tree) | Top-down, broad → narrow | Site navigation |
+| Database (flat) | Metadata-driven | Product catalog |
+| Hypertext (web) | Link-based connections | Wiki, knowledge base |
+| Linear (sequence) | Step-by-step | Onboarding, checkout |
+| Faceted | Multi-dimensional | E-commerce filters |
+
+---
+
+## 3. Padroes de Navegacao
+
+### Navegacao Global
+| Padrao | Descricao | Max Items |
+|--------|----------|-----------|
+| Horizontal nav bar | Menu principal no topo | 7 (Miller's Law) |
+| Mega menu | Menu expandido com categorias | 3-4 colunas |
+| Sidebar nav | Navegacao lateral persistente | 15-20 items |
+| Tab bar (mobile) | 3-5 icones na base | 5 max |
+
+### Navegacao Local
+| Padrao | Uso |
+|--------|-----|
+| Breadcrumbs | Hierarquia de localizacao |
+| Sidebar sub-nav | Paginas dentro de secao |
+| In-page anchors | Navegacao dentro de pagina longa |
+| Tabs | Conteudo alternativo na mesma pagina |
+| Pagination | Conteudo em multiplas paginas |
+
+### Navegacao Contextual
+| Padrao | Uso |
+|--------|-----|
+| Related content | Links para conteudo similar |
+| Cross-links | Conexoes entre secoes |
+| Inline links | Links no corpo do texto |
+| Card navigation | Grid de opcoes visuais |
+| Wizard/stepper | Progresso em processo linear |
+
+---
+
+## 4. Sitemap Patterns
+
+### Sitemap Flat
+```
+Home
+├── About
+├── Services
+├── Products
+├── Blog
+└── Contact
+```
+**Quando:** Sites simples, < 20 paginas.
+
+### Sitemap Deep
+```
+Home
+├── Products
+│   ├── Category A
+│   │   ├── Product 1
+│   │   └── Product 2
+│   └── Category B
+│       ├── Product 3
+│       └── Product 4
+├── Support
+│   ├── FAQ
+│   ├── Documentation
+│   │   ├── Getting Started
+│   │   └── API Reference
+│   └── Contact
+└── Account
+    ├── Profile
+    ├── Orders
+    └── Settings
+```
+**Quando:** Sites complexos, e-commerce, SaaS.
+
+### Regras de Profundidade
+| Profundidade | Recomendacao |
+|-------------|-------------|
+| 1 nivel | Ideal para findability |
+| 2 niveis | Aceitavel para maioria |
+| 3 niveis | Maximo recomendado |
+| 4+ niveis | Evitar — indica IA complexa demais |
+
+---
+
+## 5. Labeling System
+
+### Principios
+| Principio | Descricao |
+|-----------|----------|
+| Clarity | Labels devem ser auto-explicativas |
+| Consistency | Mesmo padrao em todo o site |
+| User language | Vocabulario do usuario, nao da empresa |
+| Specificity | Especifico o suficiente para diferenciar |
+| Brevity | Curto, max 2-3 palavras para nav items |
+
+### Patterns
+| Tipo | Exemplo Bom | Exemplo Ruim |
+|------|------------|-------------|
+| Nav label | "Pricing" | "Our Pricing Plans and Options" |
+| Page title | "Account Settings" | "Settings" (ambiguo) |
+| CTA | "Start Free Trial" | "Submit" |
+| Category | "Running Shoes" | "Shoes Type A" |
+| Breadcrumb | "Home > Products > Shoes" | "Main > Cat > Subcat" |
+
+---
+
+## 6. Search Patterns
+
+### Anatomia de Busca
+| Componente | Descricao |
+|-----------|----------|
+| Search box | Input com placeholder descritivo |
+| Autocomplete | Sugestoes em tempo real |
+| Filters/facets | Refinamento por atributos |
+| Results page | Lista com snippets relevantes |
+| No results | Mensagem util com alternativas |
+| Sort options | Relevance, date, price, etc. |
+
+### Search UX Best Practices
+| Pratica | Implementacao |
+|---------|-------------|
+| Prominent placement | Visivel no header, icone de busca |
+| Placeholder text | "Search products, articles..." |
+| Recent searches | Mostrar ultimas buscas do usuario |
+| Popular searches | Trending queries |
+| Fuzzy matching | Tolerar typos |
+| Scoped search | Buscar dentro de secao |
+
+---
+
+## 7. Card Sorting e Tree Testing
+
+### Card Sorting
+| Tipo | Descricao | Quando |
+|------|----------|--------|
+| Open | Usuarios criam categorias | Descoberta inicial |
+| Closed | Usuarios organizam em categorias dadas | Validacao |
+| Hybrid | Mix dos dois | Refinamento |
+
+**Tamanho:** 30-60 cards, 15-30 participantes, analise por similarity matrix.
+
+### Tree Testing
+| Aspecto | Detalhes |
+|---------|---------|
+| O que testa | Findability sem UI visual |
+| Tamanho | 8-12 tasks, 50+ participantes |
+| Metricas | Success rate, directness, time |
+| Target | >= 80% success rate |
+| Ferramenta | Optimal Workshop, UserZoom |
+
+---
+
+## 8. IA para Diferentes Contextos
+
+### E-commerce
+- Faceted navigation (filters)
+- Breadcrumbs com categorias
+- Product taxonomy hierarquica
+- Search com autocomplete e filtros
+
+### SaaS Dashboard
+- Sidebar navigation persistente
+- Top-level: features, not departments
+- Settings agrupados por dominio
+- Contextual help/docs links
+
+### Content Site (Blog/News)
+- Category + tag taxonomy
+- Chronological + topic organization
+- Related content links
+- Archive navigation
+
+### Mobile App
+- Tab bar (3-5 items primarios)
+- Hamburger para secundarios
+- Gestos para navegacao contextual
+- Deep linking para conteudo especifico
+
+---
+
+## 9. Metricas de Qualidade de IA
+
+| Metrica | Target | Como Medir |
+|---------|--------|-----------|
+| Findability | >= 80% success rate | Tree testing |
+| Time to find | < 30s for primary tasks | Usability test |
+| Navigation depth | <= 3 clicks to any page | Sitemap analysis |
+| Search success rate | >= 70% | Analytics |
+| Bounce rate from nav | < 20% | Analytics |
+| Breadcrumb usage | Tracked | Analytics |
+
+---
+
+## Referencias
+- Rosenfeld, L., Morville, P., Arango, J. (2015). Information Architecture for the World Wide Web
+- Spencer, D. (2010). A Practical Guide to Information Architecture
+- Nielsen Norman Group — IA research articles

package/squad-design/knowledge-base/motion-interaction-playbook.md

@@ -0,0 +1,400 @@
+# Knowledge Base: Motion & Interaction Playbook
+
+## Escopo
+Referencia completa de motion design para interfaces — principios, easing, duracao, micro-interacoes, transicoes e performance.
+
+---
+
+## 1. Motion Principles
+
+### 5 Principios Fundamentais
+| Principio | Descricao | Exemplo |
+|-----------|----------|---------|
+| Purposeful | Toda animacao tem razao de existir | Loading indicator = feedback |
+| Responsive | Feedback imediato a acao do usuario | Button press = instant response |
+| Natural | Movimento imita fisica do mundo real | Spring easing, gravity |
+| Accessible | Respeita prefers-reduced-motion | Desabilitar decorativas |
+| Performant | 60fps, GPU-accelerated | transform + opacity only |
+
+### Disney's 12 Principles (Adapted for UI)
+| Principio | Aplicacao UI |
+|-----------|-------------|
+| Squash & Stretch | Button press effect |
+| Anticipation | Micro-pull before action |
+| Staging | Direct attention with motion |
+| Follow Through | Overshoot on stop |
+| Slow In/Slow Out | Ease-in-out for natural feel |
+| Arcs | Curved motion paths |
+| Secondary Action | Icon spin while loading |
+| Timing | Duration matches importance |
+| Exaggeration | Emphasis on key moments |
+| Appeal | Personality through motion |
+
+---
+
+## 2. Easing Curves
+
+### Standard Curves
+| Nome | CSS | Bezier | Uso |
+|------|-----|--------|-----|
+| Standard | ease | (0.4, 0, 0.2, 1) | Movimento geral |
+| Decelerate | ease-out | (0, 0, 0.2, 1) | Elementos entrando |
+| Accelerate | ease-in | (0.4, 0, 1, 1) | Elementos saindo |
+| Sharp | ease-in-out | (0.4, 0, 0.6, 1) | Transicoes rapidas |
+| Linear | linear | (0, 0, 1, 1) | Progress bars, loops |
+
+### Spring Configs (Framer Motion)
+```typescript
+const springs = {
+  gentle: { type: 'spring', stiffness: 120, damping: 14 },
+  bouncy: { type: 'spring', stiffness: 300, damping: 10 },
+  stiff: { type: 'spring', stiffness: 400, damping: 30 },
+  slow: { type: 'spring', stiffness: 100, damping: 20 },
+};
+```
+
+### Regra de Escolha
+| Situacao | Easing |
+|----------|--------|
+| Elemento aparece | Decelerate (ease-out) |
+| Elemento desaparece | Accelerate (ease-in) |
+| Elemento se move | Standard (ease) |
+| Feedback tactil | Spring (bouncy) |
+| Loading/progress | Linear |
+| Emphasis | Spring (gentle) |
+
+---
+
+## 3. Duration Scale
+
+### Escala Padrao
+| Token | Valor | Uso |
+|-------|-------|-----|
+| instant | 0ms | State changes (color, opacity) |
+| fast | 100ms | Micro-feedback (hover, press) |
+| normal | 200ms | Standard transitions |
+| moderate | 300ms | Component animations |
+| slow | 400ms | Page transitions |
+| slower | 500ms | Complex choreography |
+| slowest | 700ms | Dramatic emphasis |
+
+### Duration Rules
+| Regra | Descricao |
+|-------|----------|
+| Doherty Threshold | Feedback em < 400ms para manter flow |
+| Smaller = Faster | Elementos menores = duracao menor |
+| Distance = Duration | Mais distancia = mais duracao |
+| Exit < Enter | Saida mais rapida que entrada |
+| Max 700ms | Nenhuma animacao > 700ms |
+| Mobile shorter | Mobile duracoes 20-30% menores |
+
+### Staggering
+| Padrao | Valor | Cap |
+|--------|-------|-----|
+| Stagger delay | 50ms por item | 500ms total |
+| List items | 30-50ms stagger | Max 10 items |
+| Grid items | 50ms stagger | Max 12 items |
+| Cascade | 75ms stagger | Max 6 items |
+
+---
+
+## 4. Micro-Interactions
+
+### Button
+```typescript
+const buttonMotion = {
+  rest: { scale: 1 },
+  hover: { scale: 1.02, transition: { duration: 0.2 } },
+  tap: { scale: 0.98, transition: { duration: 0.1 } },
+};
+
+// CSS alternative
+.button {
+  transition: transform 150ms ease, box-shadow 150ms ease;
+}
+.button:hover { transform: scale(1.02); }
+.button:active { transform: scale(0.98); }
+```
+
+### Switch/Toggle
+```typescript
+const switchMotion = {
+  layout: true,
+  transition: {
+    type: 'spring',
+    stiffness: 500,
+    damping: 30,
+  },
+};
+```
+
+### Input Focus
+```css
+.input {
+  transition: border-color 150ms ease, box-shadow 150ms ease;
+  border: 1px solid var(--border-default);
+}
+.input:focus {
+  border-color: var(--color-action-primary);
+  box-shadow: 0 0 0 3px var(--color-action-primary / 0.15);
+}
+```
+
+### Checkbox
+```css
+.checkbox-indicator {
+  transition: transform 200ms ease, opacity 200ms ease;
+  transform-origin: center;
+}
+.checkbox[data-state="checked"] .checkbox-indicator {
+  transform: scale(1);
+  opacity: 1;
+}
+.checkbox[data-state="unchecked"] .checkbox-indicator {
+  transform: scale(0.5);
+  opacity: 0;
+}
+```
+
+---
+
+## 5. Page Transitions
+
+### View Transitions API
+```css
+/* CSS-based page transitions */
+@view-transition {
+  navigation: auto;
+}
+
+::view-transition-old(root) {
+  animation: fade-out 200ms ease-in;
+}
+
+::view-transition-new(root) {
+  animation: fade-in 300ms ease-out;
+}
+
+@keyframes fade-out {
+  from { opacity: 1; }
+  to { opacity: 0; }
+}
+
+@keyframes fade-in {
+  from { opacity: 0; }
+  to { opacity: 1; }
+}
+```
+
+### Transition Types
+| Tipo | Quando | Duracao |
+|------|--------|---------|
+| Fade | Default page change | 200-300ms |
+| Slide | Navegacao lateral/hierarquica | 250-350ms |
+| Shared element | Elemento compartilhado entre views | 300-400ms |
+| Morph | Transformacao de layout | 300-500ms |
+| Scale | Modal/dialog open | 200-300ms |
+
+### Loading During Transition
+| Pattern | Uso |
+|---------|-----|
+| Skeleton screens | Content loading |
+| Progress bar (top) | Page navigation |
+| Spinner (inline) | Button actions |
+| Content shimmer | List/card loading |
+| Placeholder → Content | Gradual reveal |
+
+---
+
+## 6. Scroll Animations
+
+### Intersection Observer Pattern
+```typescript
+const useScrollReveal = (options?: IntersectionObserverInit) => {
+  const ref = useRef<HTMLElement>(null);
+  const [isVisible, setIsVisible] = useState(false);
+
+  useEffect(() => {
+    const observer = new IntersectionObserver(
+      ([entry]) => {
+        if (entry.isIntersecting) {
+          setIsVisible(true);
+          observer.disconnect(); // Animate once
+        }
+      },
+      { threshold: 0.1, ...options }
+    );
+
+    if (ref.current) observer.observe(ref.current);
+    return () => observer.disconnect();
+  }, []);
+
+  return { ref, isVisible };
+};
+```
+
+### CSS Scroll-Driven Animations
+```css
+@keyframes fade-in-up {
+  from {
+    opacity: 0;
+    transform: translateY(30px);
+  }
+  to {
+    opacity: 1;
+    transform: translateY(0);
+  }
+}
+
+.scroll-reveal {
+  animation: fade-in-up linear both;
+  animation-timeline: view();
+  animation-range: entry 0% entry 100%;
+}
+```
+
+### Scroll Animation Rules
+| Regra | Descricao |
+|-------|----------|
+| Subtle movement | Max 30px translation |
+| Fade in preferred | Opacity 0 → 1 |
+| No parallax on mobile | Performance concern |
+| Animate once | Nao re-animar ao scrollar pra cima |
+| Respect reduced motion | Sem scroll animations |
+| Content first | Conteudo visivel mesmo sem JS |
+
+---
+
+## 7. Feedback Animations
+
+### Success
+```typescript
+const checkmarkDraw = {
+  hidden: { pathLength: 0, opacity: 0 },
+  visible: {
+    pathLength: 1,
+    opacity: 1,
+    transition: {
+      pathLength: { type: 'spring', duration: 0.5, bounce: 0 },
+      opacity: { duration: 0.1 },
+    },
+  },
+};
+```
+
+### Error Shake
+```css
+@keyframes shake {
+  0%, 100% { transform: translateX(0); }
+  20% { transform: translateX(-6px); }
+  40% { transform: translateX(6px); }
+  60% { transform: translateX(-4px); }
+  80% { transform: translateX(4px); }
+}
+
+.error-shake {
+  animation: shake 400ms ease-in-out;
+}
+```
+
+### Toast Notification
+```typescript
+const toastMotion = {
+  initial: { opacity: 0, y: 50, scale: 0.95 },
+  animate: { opacity: 1, y: 0, scale: 1 },
+  exit: { opacity: 0, y: 20, scale: 0.95 },
+  transition: {
+    enter: { type: 'spring', stiffness: 300, damping: 24 },
+    exit: { duration: 0.2, ease: 'easeIn' },
+  },
+};
+```
+
+---
+
+## 8. Reduced Motion
+
+### CSS Implementation
+```css
+@media (prefers-reduced-motion: reduce) {
+  *,
+  *::before,
+  *::after {
+    animation-duration: 0.01ms !important;
+    animation-iteration-count: 1 !important;
+    transition-duration: 0.01ms !important;
+    scroll-behavior: auto !important;
+  }
+}
+```
+
+### React Hook
+```typescript
+function usePrefersReducedMotion() {
+  const [prefersReduced, setPrefersReduced] = useState(false);
+
+  useEffect(() => {
+    const mql = window.matchMedia('(prefers-reduced-motion: reduce)');
+    setPrefersReduced(mql.matches);
+
+    const handler = (e: MediaQueryListEvent) => setPrefersReduced(e.matches);
+    mql.addEventListener('change', handler);
+    return () => mql.removeEventListener('change', handler);
+  }, []);
+
+  return prefersReduced;
+}
+```
+
+### Animation Categories
+| Categoria | Reduced Motion | Exemplo |
+|-----------|---------------|---------|
+| Essential | KEEP (simplify) | Loading spinners, progress |
+| Informative | SIMPLIFY | State changes, transitions |
+| Decorative | REMOVE | Parallax, hover effects |
+| Interactive | SIMPLIFY | Button press, toggle |
+
+---
+
+## 9. Performance Guidelines
+
+### GPU-Only Properties
+| Property | GPU? | Uso |
+|----------|------|-----|
+| transform | YES | Mover, escalar, rotacionar |
+| opacity | YES | Fade in/out |
+| filter | YES | Blur, brightness |
+| clip-path | Partial | Reveal animations |
+| background-color | NO | Avoid animating |
+| width/height | NO | Use transform: scale |
+| top/left | NO | Use transform: translate |
+| box-shadow | NO | Use pseudo-element trick |
+
+### Performance Targets
+| Metrica | Target |
+|---------|--------|
+| Frame rate | 60fps (16.67ms/frame) |
+| Jank frames | < 1% of total frames |
+| Layout thrashing | 0 forced reflows |
+| Paint area | Minimize repaint regions |
+| Composite layers | < 30 promoted layers |
+
+### will-change Usage
+```css
+/* Apply BEFORE animation starts, remove after */
+.about-to-animate {
+  will-change: transform, opacity;
+}
+
+/* NEVER apply to many elements at once */
+/* NEVER use will-change: all */
+```
+
+---
+
+## Referencias
+- Material Design Motion Guidelines (Google)
+- Human Interface Guidelines — Motion (Apple)
+- Framer Motion Documentation
+- View Transitions API (MDN)
+- WCAG 2.3.1, 2.3.3 — Motion and Animation