sinapse-ai 9.3.0 → 9.5.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)

package/squads/squad-design/knowledge-base/cross-surface-token-canon.md

@@ -0,0 +1,209 @@
+# Knowledge Base: Cross-Surface Token Canon
+
+> **Status:** Canon — canonical source of truth for how `squad-design` (Nexus) and `squad-artdir` (Atlas) share responsibility for tokens that cross surfaces.
+> **Version:** 1.0 (shipped with squad-design v2.0.0)
+> **Contracts with:** `squads/squad-artdir/agents/design-system-architect.md` (Atlas)
+> **Depends on:** `design-token-architecture.md` (this squad)
+
+## Why this doc exists
+
+Until squad-design v2.0.0, "design tokens" in SINAPSE lived in two places without a clear boundary:
+
+1. `squad-design/knowledge-base/design-token-architecture.md` — a generic three-tier taxonomy (primitive → semantic → component) useful for a single product surface.
+2. `squad-artdir` v2.0 introduced **Atlas** (`design-system-architect`), whose Pilar 9 is multi-surface design system architecture — brand, marketing, product, email, docs, PDF, mobile.
+
+Both were correct in isolation but the **boundary** between them was undefined. Product teams building a SaaS (marketing page + logged-in product + transactional email) did not know which squad to ask when a token decision spanned those surfaces, which led to ad-hoc token drift — the exact failure mode Atlas was created to prevent.
+
+This canon makes the boundary explicit and sets the handoff contract.
+
+---
+
+## 1. Token tiers (recap — single surface)
+
+The existing `design-token-architecture.md` three-tier model still holds for **a single surface**:
+
+| Tier | Name | Role | Example |
+|------|------|------|---------|
+| L1 | Primitive | Raw design value | `color.blue.500: #3B82F6` |
+| L2 | Semantic | Intent mapping | `color.action.primary: {color.blue.500}` |
+| L3 | Component | Component-specific | `button.primary.bg: {color.action.primary}` |
+
+Rules: L3 → L2 → L1. L3 → L1 is forbidden. L1 → L1 is forbidden. These rules are enforced by Nexus (squad-design) inside any single surface's design system.
+
+---
+
+## 2. The cross-surface problem (why L1-L2-L3 is insufficient alone)
+
+A modern product runs on **multiple surfaces**, and each surface has different rendering constraints:
+
+| Surface | Constraint | Example mismatch |
+|---------|-----------|------------------|
+| Brand identity | Canonical — no rendering | "#3B82F6 is our blue" |
+| Marketing site | Full CSS, modern browsers | `color-mix()`, `clamp()`, container queries |
+| Product UI | Full CSS but component contracts matter | `--button-primary-bg` token must exist |
+| Transactional email | Inline CSS, no `:root`, no custom props | `style="background:#3B82F6"` — no reference |
+| Documentation | Often a 3rd-party theme (Docusaurus, Mintlify) | Limited override surface |
+| Billing / invoice PDF | Print CSS or server-rendered PDF | No JS, muted color profile, CMYK concerns |
+| Mobile apps (iOS/Android) | Native token maps (XML, Swift) | No CSS variables at all |
+
+Primitive `color.blue.500: #3B82F6` is stable across all surfaces. Semantic `color.action.primary` is stable. But **component** `button.primary.bg` CAN NOT be the same token on email (no custom props) vs web product (full CSS) vs mobile (`UIColor`). Something has to translate. That translation layer is what Atlas calls a **surface dialect**.
+
+---
+
+## 3. Surface dialects (what Atlas owns)
+
+A **surface dialect** is a surface-specific translation of the canonical token tree into whatever that surface can actually consume.
+
+```
+Brand canon (Meridian)
+        │
+        ▼
+Token canon (Atlas) — versioned semver, single source of truth
+        │
+   ┌────┴────────┬──────────────┬──────────────┬──────────────┐
+   ▼             ▼              ▼              ▼              ▼
+Marketing    Product UI    Transactional    PDF          Mobile
+dialect      dialect       email dialect    dialect      dialects
+(Nexus       (Nexus        (Atlas —         (Atlas —     (Atlas —
+ owns)        owns)         specialized)     print)       native)
+```
+
+Atlas owns:
+- The canonical root (what the token values ARE)
+- The dialect definitions for surfaces that Nexus does not work on (email, PDF, mobile)
+- Semver versioning of the canonical token tree
+- Cross-surface drift audits
+- Breaking-change migration guides
+
+Nexus (squad-design) owns:
+- The component-level token usage on **web surfaces** (marketing + product UI)
+- The three-tier (L1/L2/L3) enforcement inside those surfaces
+- The component → token binding (which component reads which semantic token)
+- The design-to-code pipeline on the web surfaces
+
+## 4. Ownership diff matrix (authoritative)
+
+| Decision | Owner | Rationale |
+|----------|-------|-----------|
+| "What's our brand blue?" | Meridian (squad-brand) | Brand-level decision, upstream of both |
+| "What's the canonical hex for `color.action.primary`?" | Atlas | Canonical root — single source of truth |
+| "How is `color.action.primary` represented in a transactional email?" | Atlas | Email dialect — email cannot reference a CSS variable |
+| "How is `color.action.primary` represented in a PDF invoice?" | Atlas | PDF dialect — print-safe color profile |
+| "How is `color.action.primary` bound to `Button` component on the product UI?" | Nexus | Component binding inside web product surface |
+| "What is `spacing.md` on marketing site?" | Nexus | Marketing surface = web, Nexus domain |
+| "What is `spacing.md` on mobile (iOS/Android)?" | Atlas | Mobile is a surface Nexus does not work on |
+| "We need a `button.destructive` variant" | Nexus | Component-level addition inside web surface |
+| "We need to change `color.action.primary` from blue to teal" | Atlas | Canonical root change — requires semver major bump + migration guide |
+| "We found that marketing and product UI render `color.bg.subtle` slightly differently" | Atlas | Cross-surface drift audit, Atlas domain |
+| "Tailwind theme config for our marketing site" | Nexus | Web-surface token pipeline |
+| "Figma Variables that mirror the design tokens" | Nexus + Atlas (joint) | Figma lives on the boundary — nexus for day-to-day, Atlas for canonical publishes |
+
+**Rule of thumb:**
+- If the question is "single web surface, single component" → Nexus.
+- If the question is "canonical root, multi-surface, versioning, or non-web surface" → Atlas.
+
+## 5. Immutable vs surface-adapted tokens
+
+Not every token can or should be identical across all surfaces. The canon distinguishes three classes:
+
+| Class | Description | Example | Who decides |
+|-------|------------|---------|-------------|
+| **Immutable** | MUST be byte-identical across every surface | Brand primary color hex, logo colors, brand gradient stops | Meridian → Atlas |
+| **Semantically stable** | Meaning stays constant, rendering adapts per surface | `spacing.md` (web: 16px, mobile: 16pt, PDF: 12pt, email: 16px inline) | Atlas |
+| **Surface-local** | Only exists on one surface, no cross-surface meaning | `card.hover.shadow` (web only), `email.footer.divider.color` (email only) | Nexus (if web) / Atlas (if non-web) |
+
+**Immutable tokens are non-negotiable.** If a dialect cannot render the immutable token (e.g. email cannot render a 3-stop gradient), the dialect MUST document the fallback and the fallback is itself immutable. Surface owners cannot unilaterally pick their own fallback.
+
+**Semantically stable tokens** are where most of the day-to-day work happens. The meaning (`spacing.md = one comfortable unit`) is shared; the value differs per surface constraint.
+
+**Surface-local tokens** are small and should be kept small — aggressive growth of surface-local tokens is a smell that the semantic layer is too thin.
+
+## 6. Versioning contract
+
+Atlas owns semver on the canonical token tree.
+
+| Change type | Semver | Who approves | Example |
+|------------|--------|-------------|---------|
+| Add a new token (no break) | **MINOR** | Atlas alone | Add `color.action.tertiary` |
+| Change a value without changing the name | **MINOR** (if immutable class: **MAJOR**) | Atlas alone | Shift `color.border.subtle` one step lighter |
+| Rename a token | **MAJOR** | Atlas + Nexus + Meridian | Rename `color.action.primary` → `color.intent.primary` |
+| Remove a token | **MAJOR** | Atlas + Nexus + Meridian | Drop `color.action.tertiary` |
+| Change the canonical hex of an immutable | **MAJOR** | Atlas + Meridian | Brand rebrand |
+
+Every MAJOR bump MUST ship with:
+1. A migration guide (`CHANGELOG.md` entry with before/after per affected surface)
+2. Deprecation warnings on the old token for ≥1 minor cycle before the MAJOR cuts it
+3. A drift audit run after the MAJOR lands on all surfaces
+
+Nexus MUST consume canonical token tree by exact version, never "latest". `squad-design` tokens in a given project pin to a specific Atlas token tree version.
+
+## 7. Handoff protocol — Nexus ↔ Atlas
+
+### 7.1 When Nexus needs to request a token change
+
+1. Nexus opens a request describing: the component use case, the surface(s) affected, why existing tokens are insufficient.
+2. Atlas assesses: does this need a new semantic token, or does an existing semantic cover it?
+3. If NEW: Atlas creates the canonical token (L2 semantic), publishes a MINOR bump, and defines the dialect for each surface.
+4. Nexus binds the new semantic into the component library.
+
+### 7.2 When Atlas needs Nexus to adapt to a canonical change
+
+1. Atlas announces the upcoming canonical change with a proposed semver bump.
+2. Nexus reviews impact on web surface components.
+3. If MAJOR: migration guide is co-authored before the bump lands.
+4. Nexus migrates component bindings on the release boundary.
+
+### 7.3 When Meridian (brand) changes the brand canon
+
+1. Meridian publishes the brand change (brand guidelines update).
+2. Atlas absorbs the change, decides which tokens become immutable vs re-derived, publishes a MAJOR bump.
+3. Nexus cascades into web surface components.
+4. All three sign off on the migration guide before ship.
+
+---
+
+## 8. What goes in Nexus KBs vs Atlas KBs
+
+To avoid duplication going forward:
+
+**Nexus (squad-design) KBs cover:**
+- Single-surface token architecture (L1/L2/L3 — `design-token-architecture.md`)
+- Component → token bindings
+- Web-surface token export pipelines (CSS variables, Tailwind, Figma Variables sync)
+- Design-to-code pipeline on web
+- Component library patterns
+
+**Atlas (squad-artdir) KBs cover:**
+- Multi-surface canon
+- Surface dialects (email, PDF, mobile)
+- Semver and versioning strategy
+- Drift audits
+- Migration guides
+- Cross-surface enforcement automation
+
+**This KB (cross-surface-token-canon.md)** is the only doc that sits on the boundary and is co-authored / co-owned. If its content changes, both Nexus and Atlas orchestrators must agree.
+
+---
+
+## 9. Anti-patterns (forbidden)
+
+- **Nexus unilaterally defining an "email variant"** of a component → email is Atlas territory, request a dialect.
+- **Atlas designing component APIs** → component APIs are Nexus territory on web surfaces.
+- **Any agent hard-coding a hex value inside a component file** → always bind through the token tree.
+- **Skipping semver because "it's just a small value tweak"** → immutable-class values need MAJOR, always.
+- **Creating a new surface-local token when a semantic already covers the intent** → surface-local should be rare and justified.
+- **Copy-pasting tokens across surfaces instead of going through the dialect** → defeats the single source of truth.
+
+---
+
+## 10. Reference index
+
+- `design-token-architecture.md` — L1/L2/L3 taxonomy (this squad)
+- `design-to-code-pipeline.md` — how Nexus exports tokens to web (this squad)
+- `squads/squad-artdir/agents/design-system-architect.md` — Atlas persona
+- `squads/squad-artdir/knowledge-base/` — Atlas's full KB set (multi-surface, dialects, drift audits)
+- `squads/squad-brand/knowledge-base/` — Meridian's upstream brand canon
+
+## Change log
+
+- **2026-04-12 (v1.0)** — Created as part of squad-design v2.0.0 / fw-v2.2. Establishes the Nexus ↔ Atlas boundary, the ownership diff matrix, the immutable-vs-adapted token classes, and the semver handoff contract.