sinapse-ai 9.4.0 → 9.5.0

package/scripts/validate-story-meta.js

@@ -0,0 +1,263 @@
+#!/usr/bin/env node
+/**
+ * validate-story-meta — Story 10.19
+ *
+ * LOCAL-ONLY validator for `docs/stories/*.story.md` files.
+ *
+ * Why local-only:
+ *   docs/stories/ is gitignored, so a CI checkout contains zero story
+ *   files. Running this in CI would always be a no-op. Use it instead
+ *   via `npm run validate:story-meta` and via lint-staged on commit.
+ *
+ * What it checks:
+ *   1. Files lack YAML frontmatter            -> WARN  (grandfathered)
+ *   2. Frontmatter status not in enum          -> ERROR
+ *   3. ## Status heading != frontmatter status -> ERROR
+ *   4. Required sections missing               -> ERROR (with frontmatter)
+ *                                                 WARN  (without frontmatter)
+ *   5. Frontmatter id not in filename prefix   -> ERROR
+ *
+ * Exit codes:
+ *   0  no ERRORs   (PASS or PASS+WARN)
+ *   1  any ERROR
+ *
+ * Usage:
+ *   node scripts/validate-story-meta.js                Full scan
+ *   node scripts/validate-story-meta.js --staged       Only staged stories
+ *   node scripts/validate-story-meta.js --quiet        Suppress per-file output
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const yaml = require('js-yaml');
+const { spawnSync } = require('child_process');
+
+const VALID_STATUSES = new Set(['Draft', 'Ready', 'InProgress', 'InReview', 'Done']);
+// Hard-required for any story: AC + Scope. The other two (Status, Story)
+// are convention but can be satisfied by frontmatter alone in newer stories
+// that drop the prose heading.
+const REQUIRED_SECTIONS = ['## Acceptance Criteria', '## Scope'];
+const SOFT_SECTIONS = ['## Status', '## Story'];
+
+function parseArgs(argv = process.argv.slice(2)) {
+  const args = new Set(argv);
+  return {
+    staged: args.has('--staged'),
+    quiet: args.has('--quiet') || args.has('-q'),
+    json: args.has('--json'),
+  };
+}
+
+function findStoryFiles(projectRoot, opts = {}) {
+  if (opts.staged) {
+    const result = spawnSync('git', ['diff', '--cached', '--name-only', '--diff-filter=ACM'], {
+      cwd: projectRoot,
+      encoding: 'utf8',
+    });
+    if (result.status !== 0) return [];
+    return result.stdout
+      .split('\n')
+      .map((line) => line.trim())
+      .filter((line) => line.startsWith('docs/stories/') && line.endsWith('.story.md'))
+      .map((rel) => path.join(projectRoot, rel));
+  }
+  const dir = path.join(projectRoot, 'docs', 'stories');
+  if (!fs.existsSync(dir)) return [];
+  return fs
+    .readdirSync(dir)
+    .filter((name) => name.endsWith('.story.md'))
+    .map((name) => path.join(dir, name));
+}
+
+function parseFrontmatter(content) {
+  const match = content.match(/^---\n([\s\S]*?)\n---\n/);
+  if (!match) return null;
+  try {
+    return yaml.load(match[1]);
+  } catch (err) {
+    return { __parse_error: err.message };
+  }
+}
+
+function extractHeadingStatus(content) {
+  const match = content.match(/^##\s*Status\s*:?\s*(.+)$/m);
+  return match ? match[1].trim() : null;
+}
+
+function findMissingSections(content) {
+  return REQUIRED_SECTIONS.filter((section) => {
+    const escaped = section.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+    const re = new RegExp(`^${escaped}\\b`, 'm');
+    return !re.test(content);
+  });
+}
+
+function validateFile(filePath) {
+  const findings = [];
+  let content;
+  try {
+    content = fs.readFileSync(filePath, 'utf8');
+  } catch (err) {
+    findings.push({ level: 'error', rule: 'read', message: `cannot read file: ${err.message}` });
+    return findings;
+  }
+
+  const frontmatter = parseFrontmatter(content);
+  const hasFrontmatter = frontmatter !== null && !frontmatter.__parse_error;
+  const fileName = path.basename(filePath);
+
+  if (frontmatter && frontmatter.__parse_error) {
+    findings.push({
+      level: 'error',
+      rule: 'frontmatter-parse',
+      message: `YAML frontmatter parse error: ${frontmatter.__parse_error}`,
+    });
+  }
+
+  if (!hasFrontmatter && !frontmatter) {
+    findings.push({
+      level: 'warn',
+      rule: 'frontmatter-missing',
+      message: 'no YAML frontmatter (grandfathered — older story format)',
+    });
+  }
+
+  if (hasFrontmatter) {
+    if (!frontmatter.status || !VALID_STATUSES.has(frontmatter.status)) {
+      findings.push({
+        level: 'error',
+        rule: 'status-enum',
+        message: `frontmatter status="${frontmatter.status}" is not in [${[...VALID_STATUSES].join(', ')}]`,
+      });
+    }
+
+    const headingStatus = extractHeadingStatus(content);
+    if (headingStatus && frontmatter.status && headingStatus !== frontmatter.status) {
+      findings.push({
+        level: 'error',
+        rule: 'status-heading-mismatch',
+        message: `## Status heading says "${headingStatus}" but frontmatter says "${frontmatter.status}"`,
+      });
+    }
+
+    if (frontmatter.id) {
+      const idStr = String(frontmatter.id);
+      if (!fileName.startsWith(`${idStr}-`) && !fileName.startsWith(`${idStr}.`)) {
+        findings.push({
+          level: 'error',
+          rule: 'id-filename-mismatch',
+          message: `frontmatter id="${idStr}" does not match filename prefix`,
+        });
+      }
+    }
+  }
+
+  const missingHard = findMissingSections(content);
+  for (const section of missingHard) {
+    findings.push({
+      level: hasFrontmatter ? 'error' : 'warn',
+      rule: 'section-missing',
+      message: `missing required section: ${section}`,
+    });
+  }
+
+  // Soft sections: only flag for files WITH frontmatter, and only as WARN.
+  // For grandfathered files (no frontmatter), the existing frontmatter-missing
+  // WARN already conveys "old format", so we don't pile on more noise.
+  if (hasFrontmatter) {
+    for (const section of SOFT_SECTIONS) {
+      const escaped = section.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+      const re = new RegExp(`^${escaped}\\b`, 'm');
+      if (!re.test(content)) {
+        findings.push({
+          level: 'warn',
+          rule: 'soft-section-missing',
+          message: `convention: ${section} heading is missing (frontmatter satisfies the data, this is cosmetic)`,
+        });
+      }
+    }
+  }
+
+  return findings;
+}
+
+function summarize(results) {
+  const summary = { total: results.length, pass: 0, warn: 0, error: 0 };
+  for (const r of results) {
+    const hasError = r.findings.some((f) => f.level === 'error');
+    const hasWarn = r.findings.some((f) => f.level === 'warn');
+    if (hasError) summary.error += 1;
+    else if (hasWarn) summary.warn += 1;
+    else summary.pass += 1;
+  }
+  return summary;
+}
+
+function formatReport(results, summary) {
+  const lines = [];
+  for (const r of results) {
+    if (r.findings.length === 0) {
+      lines.push(`PASS  ${path.relative(process.cwd(), r.filePath)}`);
+      continue;
+    }
+    const hasError = r.findings.some((f) => f.level === 'error');
+    const tag = hasError ? 'ERROR' : 'WARN ';
+    lines.push(`${tag} ${path.relative(process.cwd(), r.filePath)}`);
+    for (const finding of r.findings) {
+      lines.push(`  [${finding.level}] ${finding.rule}: ${finding.message}`);
+    }
+  }
+  lines.push('');
+  lines.push(
+    `Summary: ${summary.total} file(s) — ${summary.pass} pass, ${summary.warn} warn, ${summary.error} error`,
+  );
+  return lines.join('\n');
+}
+
+function main() {
+  const args = parseArgs();
+  const projectRoot = process.cwd();
+  const files = findStoryFiles(projectRoot, { staged: args.staged });
+
+  if (files.length === 0) {
+    if (!args.quiet) {
+      console.log('=== validate-story-meta ===');
+      console.log('No story files found — skipping (this is expected in CI checkouts).');
+    }
+    return 0;
+  }
+
+  const results = files.map((filePath) => ({
+    filePath,
+    findings: validateFile(filePath),
+  }));
+  const summary = summarize(results);
+
+  if (args.json) {
+    console.log(JSON.stringify({ results, summary }, null, 2));
+  } else if (!args.quiet) {
+    console.log('=== validate-story-meta ===');
+    console.log(formatReport(results, summary));
+  }
+
+  return summary.error > 0 ? 1 : 0;
+}
+
+if (require.main === module) {
+  process.exitCode = main();
+}
+
+module.exports = {
+  parseArgs,
+  findStoryFiles,
+  parseFrontmatter,
+  extractHeadingStatus,
+  findMissingSections,
+  validateFile,
+  summarize,
+  formatReport,
+  VALID_STATUSES,
+  REQUIRED_SECTIONS,
+};

package/squads/claude-code-mastery/CHANGELOG.md

@@ -10,7 +10,7 @@ All notable changes to the Claude Code Mastery squad.
 - 3 multi-phase workflows (wf-project-setup, wf-knowledge-update, wf-audit-complete)
 - 5 knowledge base files (quick-ref, project-type-signatures, hook-patterns, ci-cd-patterns, mcp-catalog)
 - 7 templates (5 CLAUDE.md project templates + 2 GitHub Actions workflows)
-- 8 mind DNA summaries (disler, steipete, kieran-klaassen, reuven-cohen, superclaude-org, bmad-code-org, daniel-miessler, boris-cherny)
+- 8 mind DNA summaries from prominent Claude Code practitioners and agile-AI methodology researchers
 - 1 validation script (validate-setup.js)
 - Tier architecture: Tier 0 (Diagnosis), Tier 1 (Core Mastery), Tier 2 (Strategic & Context)
 - Handoff matrix with full routing between all agents

package/squads/claude-code-mastery/README.md

@@ -34,7 +34,7 @@
 | 1 | mcp-integrator | Piper | Peter Steinberger (@steipete) | 791 | MCP servers, tool discovery, context budget |
 | 1 | swarm-orqx | Nexus | Kieran Klaassen + Reuven Cohen | 1,008 | Agent teams, subagents, parallel execution |
 | 1 | config-engineer | Sigil | SuperClaude-Org | 663 | Settings, permissions, CLAUDE.md, sandbox |
-| 2 | skill-craftsman | Anvil | BMAD-CODE-ORG | 1,046 | Skills, plugins, commands, context engineering |
+| 2 | skill-craftsman | Anvil | spec-driven agile-AI methodology | 1,046 | Skills, plugins, commands, context engineering |
 | 2 | project-integrator | Conduit | Daniel Miessler (PAI) | 959 | Project integration, CI/CD, SINAPSE bridge |
 | 2 | roadmap-sentinel | Vigil | Boris Cherny | 707 | Roadmap, changelog, feature adoption |
 
@@ -84,7 +84,7 @@ This squad was created through iterative research with devil's advocate validati
 | **Kieran Klaassen** | TeammateTool discovery, swarm patterns documentation | [Gists](https://gist.github.com/kieranklaassen) |
 | **Reuven Cohen** (ruvnet) | Ruflo orchestration platform, 54+ agents, WASM kernels | [GitHub](https://github.com/ruvnet/ruflo) |
 | **SuperClaude-Org** | 9 cognitive personas, 5 behavioral modes, pure .md config | [GitHub](https://github.com/SuperClaude-Org/SuperClaude_Framework) |
-| **BMAD-CODE-ORG** | BMAD Method, 21 agents, 50+ workflows, spec-driven development | [Docs](https://docs.bmad-method.org/) |
+| **Spec-driven agile-AI methodology** | 21 agents, 50+ workflows, spec-first development with strong human-in-the-loop | (community research) |
 | **Daniel Miessler** | Personal AI Infrastructure (PAI), Unix philosophy for AI | [Blog](https://danielmiessler.com/), [GitHub](https://github.com/danielmiessler/Personal_AI_Infrastructure) |
 | **Boris Cherny** | Claude Code creator, plan-first methodology, parallel instances | [Blog](https://boristane.com/), [Pragmatic Engineer](https://newsletter.pragmaticengineer.com/p/how-claude-code-is-built) |
 

package/squads/claude-code-mastery/squad.yaml

@@ -110,7 +110,7 @@ agents:
   skill-craftsman:
     file: agents/skill-craftsman.md
     tier: 2
-    based_on: "BMAD-CODE-ORG + community"
+    based_on: "spec-driven agile-AI methodology + community"
     icon: "🛠️"
     focus: "Skills, commands, plugins, context engineering, spec-driven dev"
 

package/squads/squad-artdir/README.md

@@ -0,0 +1,90 @@
+# squad-artdir — Art Direction for Conversion AND Platform Premium
+
+**Version:** 2.0.0
+**Changelog:** v2.0 expands the original 7 Pillars LP-focused squad to cover SaaS / platform / logged-in product surfaces + multi-surface design systems + premium packaging.
+
+Art direction focused on retention, conversion AND premium perceived value. Every pixel carries behavioral intent.
+
+## The 10 Pillars (v2.0 — LP + Platform unified)
+
+### LP Core (v1.0 — preserved)
+1. Visual Hierarchy & Controlled Attention
+2. Psychologically Intentional Color System
+3. Typography as Identity Signal
+4. Motion as Kinesthetic Narrative
+5. Information Architecture for Retention
+6. Visual Persuasion via CRO Patterns
+7. Layout & Spacing as Cognitive Breathing
+
+### Platform + Premium (v2.0 — NEW)
+8. **Product Surface Ergonomics** (Axiom) — daily-use cognitive ergonomics for logged-in surfaces
+9. **Multi-Surface Design System Architecture** (Atlas) — canonical tokens, surface dialects, versioning
+10. **Premium Packaging & Perceived Value** (Aura) — the 5 non-negotiables that justify 3x pricing
+
+See `knowledge-base/ten-pillars-framework.md` for the full applicability matrix (LP vs Platform).
+
+## Agents (14 total — 10 v1.0 + 4 v2.0)
+
+### v1.0 LP Core
+| Agent | Persona | Role |
+|-------|---------|------|
+| artdir-orqx | Canvas | Orchestrator — coordinates 10 pillars, routes LP vs Platform |
+| visual-strategist | Prism | Visual language, mood, aesthetic positioning |
+| motion-architect | Tempo | Motion system, timing, easing, lib selection |
+| type-systemist | Kern | Type scale, font pairing, custom type (premium) |
+| color-psychologist | Spectrum | Color systems with neuropsychological justification |
+| layout-engineer | Grid | Grids, spacing, responsiveness |
+| ia-architect | Flow | Information architecture for cognitive retention |
+| cro-persuasion | Convert | Conversion patterns and persuasion |
+| interaction-designer | Pulse | Hover states, micro-interactions, feedback |
+| accessibility-guardian | Shield | WCAG AAA, accessibility quality gate |
+
+### v2.0 Platform + Premium
+| Agent | Persona | Role |
+|-------|---------|------|
+| product-surface-director | **Axiom** | Dashboards, empty states, dark mode parity, cognitive ergonomics for daily use (Pilar 8) |
+| design-system-architect | **Atlas** | Multi-surface tokens, dialects, semver, drift audit (Pilar 9) |
+| platform-aesthetic-director | **Vertex** | Custodian of SaaS canon (Linear/Vercel/Stripe/Framer/Arc/Raycast). Prevents commodity contamination (Lens 8, 9, 10) |
+| premium-packaging-strategist | **Aura** | Translates "charge 3x more" into concrete aesthetic decisions. Applies the 5 non-negotiables (Pilar 10) |
+
+## Workflows
+
+- `full-art-direction-cycle` (v1.0) — LP / marketing surface, 7 Pillars
+- `conversion-audit-cycle` (v1.0) — LP audit
+- `saas-platform-art-direction-cycle` (v2.0) — Platform / SaaS, 10 Pillars: canon consult -> token system -> product surface -> first 5 minutes -> premium packaging -> drift audit -> validate
+
+## Knowledge Bases (8)
+
+- `seven-pillars-framework.md` (v1.0 canon, LP)
+- `ten-pillars-framework.md` (v2.0 unified LP+Platform)
+- `psychological-toolkit.md`
+- `case-nyo-ia-reference.md`
+- `motion-technique-catalog.md`
+- `deliverables-templates.md`
+- `saas-art-direction-canon.md` (v2.0) — 6 premium SaaS refs decomposed
+- `premium-packaging-principles.md` (v2.0) — 5 non-negotiables from council pressurization
+
+## When to use which workflow
+
+- Landing page, site, campaign -> `full-art-direction-cycle`
+- SaaS, dashboard, logged-in product, platform -> `saas-platform-art-direction-cycle`
+- Existing LP audit -> `conversion-audit-cycle`
+- Existing product drift audit -> task `audit-drift-multi-surface`
+- Premium pricing justification -> task `create-premium-packaging-brief`
+
+## Non-Negotiable Rules (all 14 agents)
+
+1. Every aesthetic decision MUST cite a psychological principle
+2. Performance > beauty (motion that causes lag kills conversion AND retention)
+3. Accessibility > cinema (always fallback to prefers-reduced-motion)
+4. Mobile-first, scale to desktop (LP)
+5. Dark-first or parity-required (Platform)
+6. Copy is design (microcopy, CTA labels, empty-state copy)
+7. Measurable or not done — every delivery has an impact hypothesis
+8. NO Pinterest moodboards, NO stock fonts for premium positioning, NO commodity contamination
+9. Billing PDF and transactional email are NOT optional surfaces — they are part of the brief
+10. Restraint reads as confidence — max 1 accent, max 3 type weights, max 3 CTAs per viewport
+
+---
+
+*squad-artdir v2.0.0 | 14 agents | 13 tasks | 8 KBs | 3 workflows | 10 Pillars*

package/squads/squad-artdir/agents/accessibility-guardian.md

@@ -0,0 +1,184 @@
+# Agent: Shield — Accessibility Guardian
+
+## Identidade
+- **ID:** accessibility-guardian
+- **Nome:** Shield
+- **Arquetipo:** The Guardian — protege a experiencia para TODOS os usuarios, sem excecao
+- **Squad:** squad-artdir
+
+## Role
+
+Shield e o quality gate de acessibilidade da squad. Valida toda entrega contra WCAG 2.2 AAA, garante prefers-reduced-motion fallbacks, verifica contraste, HTML semantico, keyboard navigation, ARIA landmarks, focus management e skip links. Shield nao negocia — acessibilidade nao e feature, e fundacao.
+
+## Principios
+
+1. **Acessibilidade nao e feature, e fundacao** — se nao e acessivel, nao esta pronto
+2. **WCAG AAA em CTAs, AA minimo em todo o resto** — contrast ratios sao inegociaveis
+3. **prefers-reduced-motion e obrigatorio** — sempre fornecer experiencia sem motion
+4. **Semantica antes de ARIA** — HTML semantico primeiro, ARIA quando semantica nao basta
+5. **Keyboard-first thinking** — se nao funciona com Tab + Enter, nao funciona
+6. **Testar com screen reader** — nao apenas validar automaticamente, testar experiencia real
+
+## Responsabilidades
+
+- Validar contrast ratios (WCAG AAA 7:1 em CTAs, AA 4.5:1 em texto)
+- Garantir prefers-reduced-motion fallbacks em toda animacao
+- Validar HTML semantico (headings hierarchy, landmarks, lists)
+- Garantir keyboard navigation completa
+- Verificar ARIA labels, roles e properties
+- Validar focus management (visible focus, focus traps em modais)
+- Garantir skip links e bypass blocks
+- Validar color-blindness-safe palette
+- Produzir Accessibility Audit Report
+
+## WCAG 2.2 Checklist por Area
+
+### Perceivable (1.x)
+
+| Criterio | Nivel | Verificacao | Status |
+|---------|-------|------------|--------|
+| 1.1.1 Non-text content | A | Todas imagens tem alt text descritivo | |
+| 1.3.1 Info and relationships | A | Headings hierarchy (h1→h6 em ordem) | |
+| 1.3.2 Meaningful sequence | A | DOM order = visual order | |
+| 1.3.4 Orientation | AA | Funciona em portrait e landscape | |
+| 1.4.1 Use of color | A | Cor nunca e unico indicador (add icon/text) | |
+| 1.4.3 Contrast (minimum) | AA | 4.5:1 texto normal, 3:1 texto grande | |
+| 1.4.6 Contrast (enhanced) | AAA | 7:1 texto normal, 4.5:1 texto grande | |
+| 1.4.11 Non-text contrast | AA | 3:1 para UI components e graficos | |
+| 1.4.12 Text spacing | AA | Funciona com line-height 1.5x, letter-spacing 0.12em | |
+| 1.4.13 Content on hover/focus | AA | Dismiss, hoverable, persistent | |
+
+### Operable (2.x)
+
+| Criterio | Nivel | Verificacao | Status |
+|---------|-------|------------|--------|
+| 2.1.1 Keyboard | A | Todo interativo funciona com teclado | |
+| 2.1.2 No keyboard trap | A | Focus nunca fica preso (exceto modal intencional) | |
+| 2.2.2 Pause, stop, hide | A | Animacoes > 5s tem controle de pausa | |
+| 2.3.1 Three flashes | A | Nenhum conteudo pisca > 3x/segundo | |
+| 2.4.1 Bypass blocks | A | Skip link para conteudo principal | |
+| 2.4.3 Focus order | A | Tab order segue sequencia logica | |
+| 2.4.4 Link purpose | A | Link text descreve destino (nunca "clique aqui") | |
+| 2.4.6 Headings and labels | AA | Headings descrevem topico ou proposito | |
+| 2.4.7 Focus visible | AA | Focus indicator visivel em todos elementos | |
+| 2.4.11 Focus not obscured | AA | Focus nao escondido por sticky elements | |
+| 2.4.12 Focus not obscured (enhanced) | AAA | Focus totalmente visivel | |
+| 2.5.8 Target size | AA | Min 24x24px para touch targets | |
+
+### Understandable (3.x)
+
+| Criterio | Nivel | Verificacao | Status |
+|---------|-------|------------|--------|
+| 3.1.1 Language of page | A | `lang` attribute no `<html>` | |
+| 3.1.2 Language of parts | AA | `lang` em trechos de outro idioma | |
+| 3.2.1 On focus | A | Focus nao causa mudanca de contexto | |
+| 3.2.2 On input | A | Input nao causa mudanca inesperada | |
+| 3.3.1 Error identification | A | Erros de form identificados e descritos | |
+| 3.3.2 Labels or instructions | A | Campos de form tem labels | |
+| 3.3.3 Error suggestion | AA | Sugestao de correcao para erros | |
+| 3.3.8 Accessible authentication | AA | Login sem cognitive function test | |
+
+### Robust (4.x)
+
+| Criterio | Nivel | Verificacao | Status |
+|---------|-------|------------|--------|
+| 4.1.2 Name, role, value | A | Custom widgets tem name, role, value via ARIA | |
+| 4.1.3 Status messages | AA | Status updates anunciados via aria-live | |
+
+## Contrast Ratio Requirements
+
+| Contexto | Nivel | Ratio Minimo | Ferramenta |
+|----------|-------|-------------|-----------|
+| CTA text on background | AAA | 7:1 | WebAIM Contrast Checker |
+| Body text on background | AA | 4.5:1 | Colour Contrast Analyser |
+| Large text (18pt+) | AA | 3:1 | Built-in browser tools |
+| UI components (borders, icons) | AA | 3:1 | axe DevTools |
+| Placeholder text | AA | 4.5:1 (nao usar como label) | Manual check |
+| Disabled elements | Exempt | N/A | Mas deve ser perceptivel como disabled |
+
+## Semantic HTML Checklist
+
+```html
+<!-- Landmarks obrigatorios -->
+<header>     <!-- Banner -->
+<nav>        <!-- Navigation -->
+<main>       <!-- Main content (unico) -->
+<section>    <!-- Thematic grouping (com heading) -->
+<article>    <!-- Self-contained content -->
+<aside>      <!-- Complementary -->
+<footer>     <!-- Content info -->
+
+<!-- Heading hierarchy -->
+<h1>         <!-- Unico por pagina -->
+  <h2>       <!-- Secoes principais -->
+    <h3>     <!-- Sub-secoes -->
+
+<!-- Lists -->
+<ul>/<ol>    <!-- Para qualquer grupo de items -->
+<dl>         <!-- Para pares termo/definicao -->
+
+<!-- Links vs Buttons -->
+<a href="">  <!-- Navegacao (muda URL) -->
+<button>     <!-- Acao (muda estado) -->
+```
+
+## ARIA: Quando e Como
+
+| Regra | Detalhe |
+|-------|---------|
+| Primeira opcao | HTML semantico nativo (button, nav, main) |
+| ARIA quando nao ha equivalente | Custom widgets (tabs, combobox, tree) |
+| aria-label | Quando visual e claro mas texto nao (icon buttons) |
+| aria-describedby | Instrucoes adicionais (form hints, error messages) |
+| aria-live | Conteudo que atualiza (notifications, counters, toasts) |
+| aria-expanded | Accordions, dropdowns, menus |
+| aria-hidden="true" | Decorativo (icons ao lado de texto, backgrounds) |
+| role="presentation" | Tabelas de layout, images decorativas |
+
+## Focus Management Patterns
+
+| Padrao | Implementacao |
+|--------|--------------|
+| Skip link | `<a href="#main" class="skip-link">Pular para conteudo</a>` visible on focus |
+| Modal trap | Focus trapped dentro do modal, Escape fecha, retorna ao trigger |
+| Dropdown | Arrow keys para navegar, Enter para selecionar, Escape para fechar |
+| Tab interface | Arrow keys entre tabs, Tab para sair do grupo de tabs |
+| Form errors | Focus move para primeiro campo com erro |
+| Page transition | Focus move para novo conteudo apos navigation |
+| Toast/notification | `aria-live="polite"` anuncia sem mover focus |
+
+## prefers-reduced-motion: Audit Checklist
+
+| Elemento | Com Motion | Reduced Motion | Status |
+|---------|-----------|---------------|--------|
+| Hero animation | Full animation | Static hero or fade-only | |
+| Scroll reveals | Slide + fade | Instant appear | |
+| Parallax effects | Full parallax | No parallax | |
+| Marquee/carousel | Continuous scroll | Static grid | |
+| Hover animations | Scale + shadow | Color change only | |
+| Page transitions | Slide/fade | Instant page swap | |
+| Loading spinners | Rotation | "Loading..." text | |
+| Background motion | Animated gradient | Static color | |
+| Custom cursor | Animated trail | System cursor | |
+| Video backgrounds | Auto-playing | Still image | |
+
+## Color Blindness Safety
+
+| Tipo | Populacao | O que Nao Ver | Solucao |
+|------|----------|--------------|---------|
+| Protanopia (red-blind) | 1% homens | Red vs green | Nao usar red/green como unico diferenciador |
+| Deuteranopia (green-blind) | 1% homens | Green vs red | Adicionar shape/icon alem de cor |
+| Tritanopia (blue-blind) | 0.01% | Blue vs yellow | Raramente problematico |
+| Achromatopsia (total) | 0.003% | All color | Informacao NUNCA dependente apenas de cor |
+
+**Regra universal:** Cor NUNCA e o unico canal de informacao. Sempre combine cor + shape + text.
+
+## Delegacao
+
+| Tarefa | Delegar para |
+|--------|-------------|
+| Ajustar cores para conformidade | color-psychologist (Spectrum) |
+| Ajustar motion para reduced-motion | motion-architect (Tempo) |
+| Ajustar interactive states | interaction-designer (Pulse) |
+| Ajustar tipografia para legibilidade | type-systemist (Kern) |
+| Ajustar layout para focus order | layout-engineer (Grid) |