forlogic-core — Design System v4

Biblioteca oficial de interface, layout e infraestrutura compartilhada dos produtos Qualiex.

Versão documentada: 4.0.2 Tema claro oficial: Deep Blue #0544AB Tema escuro oficial: Navy #021838

Este é o documento normativo único do Design System: instalação, regras transversais, racional de decisão, foundations, padrões de composição e governança. Props, exemplos executáveis e observações específicas de cada export vivem no JSDoc publicado nos arquivos .d.ts; o catálogo interativo em /ds demonstra cada família e variante.

1. Comece aqui

1.1 Instale

npm install forlogic-core

O pacote é público no npmjs e se chama forlogic-core, sem escopo. Os subpaths seguem o mesmo nome: forlogic-core/index.css, /vite, /eslint, /tailwind, /sign, /audit-trail, /action-plans, /leadership, /places, /edge, /storage, /validation.

1.2 Importe o CSS oficial

/* src/index.css */
@import 'forlogic-core/index.css';

O CSS já contém tipografia, estados, superfícies, utilidades normativas e os temas oficiais. Não copie variáveis para o projeto consumidor.

1.3 Use o preset Tailwind e a configuração Vite

// tailwind.config.ts
import { forlogicContentPaths, forlogicTailwindPreset } from 'forlogic-core/tailwind';

export default {
  presets: [forlogicTailwindPreset],
  content: [...forlogicContentPaths, './src/**/*.{ts,tsx}'],
};

// vite.config.ts
import { createForlogicViteConfig } from 'forlogic-core/vite';

export default createForlogicViteConfig({});

O preset é a fonte única do tema. Não redeclare theme.extend no projeto consumidor: qualquer cópia local diverge com o tempo e passa a exibir um DS que a biblioteca não entrega.

// eslint.config.js — estrutura de pastas do padrão de client (§1)
import { createClientStructureConfig } from 'forlogic-core/eslint';

export default tseslint.config(/* … config do app … */, ...createClientStructureConfig());

O preset de ESLint verifica as camadas de src/, a fronteira de cada feature e o ciclo entre features, como o §1 do padrão de client (docs/padroes/client.md) descreve.

1.4 Monte os providers e o app shell

import { BrowserRouter, Route, Routes } from 'react-router';
import { AppLayout, BodyContent, CoreProviders } from 'forlogic-core';
import ptBR from './locales/pt-BR.json';

export default function App() {
  return (
    <CoreProviders
      backend="supabase"
      moduleAlias="quality"
      appTranslations={{ 'pt-BR': ptBR }}
    >
      <BrowserRouter>
        <AppLayout sidebarConfig={sidebarConfig}>
          <BodyContent>
            <Routes>
              <Route path="/:alias/quality" element={<HomePage />} />
            </Routes>
          </BodyContent>
        </AppLayout>
      </BrowserRouter>
    </CoreProviders>
  );
}

CoreProviders entrega Query Client, i18n, autenticação, locale, módulo, controle de acesso, captura de erro e fontes. AppLayout entrega os contextos de navegação, metadados, abas e sidebar.

1.5 Configure o ambiente

Para backend="supabase":

VITE_APP_ENV="PROD"
SUPABASE_URL="..."
SUPABASE_PUBLISHABLE_KEY="..."
VITE_SUPABASE_PK_OVERRIDE="..."

VITE_APP_ENV aceita PROD ou DEV; ausente significa PROD. A publishable key pode estar no cliente, mas secrets e service_role nunca podem usar prefixo VITE_.

Para um produto que usa somente a API .NET:

<CoreProviders backend="dotnet" appTranslations={{ 'pt-BR': ptBR }}>
  <BrowserRouter>{/* aplicação */}</BrowserRouter>
</CoreProviders>

Use isSupabaseConfigured() antes de inicializar recursos condicionais. sign, audit-trail, action-plans, leadership e places continuam dependentes de Supabase.

Marca não precisa de configuração. Logo e favicon do Qualiex vêm embutidos no pacote como data URI: funcionam offline, no primeiro import, sem env var, sem loader de asset e sem liberar domínio na CSP. Projetos que servem a própria marca sobrescrevem com configureBrandAssets() e chamam applyFavicon() em seguida.

2. Regras invioláveis

1. Lib-first: procure em forlogic-core antes de criar uma peça visual.
2. Imports visuais: use exports de forlogic-core; não importe primitivas internas diretamente.
3. Tokens semânticos: não use cores literais, text-white, bg-black ou paletas como blue-500 em componentes.
4. Erro: use a variante semântica danger, nunca destructive na API pública.
5. Ícones: use @phosphor-icons/react; Material Symbols é exceção exclusiva do IconPicker.
6. i18n: importe useTranslation de forlogic-core, não de react-i18next.
7. Supabase: use getSupabaseClient() e .schema('<schema-do-projeto>') em toda query.
8. Exclusão: use soft delete com deleted_at; não faça DELETE físico como fluxo de produto.
9. Acesso: policies são TO authenticated; anon exige funcionalidade pública e justificativa documentada.
10. Roles: nunca determine permissão por localStorage/sessionStorage ou por campo de profile.
11. Scroll: root h-screen overflow-hidden; uma única área flex-1 min-h-0 overflow-y-auto.
12. Layout: gutter horizontal canônico de 24px; não recentralize a página com max-w-* ou mx-auto.
13. Tenant: /:alias/... é a fonte de verdade da navegação multi-tenant.

3. Imports publicados

import {
  AppLayout,
  BodyContent,
  Button,
  CoreProviders,
  PageHeader,
  createCrudPage,
} from 'forlogic-core';

import 'forlogic-core/index.css';
import { forlogicTailwindPreset } from 'forlogic-core/tailwind';
import { createForlogicViteConfig } from 'forlogic-core/vite';
import { createClientStructureConfig } from 'forlogic-core/eslint';
import { emailSchema } from 'forlogic-core/validation';

Subpaths opt-in:

import { DocumentSigner } from 'forlogic-core/sign';
import { AuditTrailPage } from 'forlogic-core/audit-trail';
import { /* ... */ } from 'forlogic-core/action-plans';
import { /* ... */ } from 'forlogic-core/leadership';
import { /* ... */ } from 'forlogic-core/places';
import { /* helpers Deno */ } from 'forlogic-core/edge';
import { /* helpers de storage */ } from 'forlogic-core/storage';

Não existem subpaths públicos forlogic-core/ui, forlogic-core/crud ou forlogic-core/modular.

4. Visão e critério de oficialidade

O forlogic-core reduz decisões repetidas e torna os produtos Qualiex reconhecíveis, previsíveis e acessíveis. Um padrão só é oficial quando possui:

1. propósito de produto claro;
2. comportamento consistente em todos os estados;
3. tokens semânticos para claro e escuro;
4. suporte a teclado e tecnologia assistiva;
5. API pública documentada em JSDoc;
6. demonstração no catálogo;
7. validação compatível com o risco da mudança.

O sistema prioriza densidade operacional, leitura rápida, segurança contra erro e continuidade entre módulos. Consistência não significa rigidez: a composição pode variar quando a tarefa exige, mas foundations e contratos de interação não são recriados localmente.

4.1 Como decidir

Antes de escolher um componente, responda:

1. Qual tarefa a pessoa tenta concluir? Comece pelo resultado, não pela aparência.
2. O padrão já existe? Consulte o catálogo e o JSDoc antes de criar algo.
3. Qual é a frequência e o risco? Ação frequente deve ser direta; ação irreversível exige confirmação proporcional.
4. Qual é a quantidade e estrutura dos dados? Isso distingue tabela, lista, cards, accordion, kanban e gráfico.
5. A ação muda de contexto? Navegação muda endereço; botão executa comando.
6. O estado é compreensível sem cor? Texto, ícone e posição devem sustentar o significado.
7. Funciona em teclado, zoom, modo escuro e movimento reduzido? Se não, a solução não está pronta.

4.2 Heurísticas de Nielsen aplicadas

| Heurística | Aplicação no DS | |---|---| | Visibilidade do estado | loading, sucesso, erro, seleção e progresso aparecem próximos à ação que os causou | | Correspondência com o mundo real | rótulos usam o vocabulário do produto; ícones apoiam, não substituem termos ambíguos | | Controle e liberdade | fechar, cancelar, desfazer ou voltar preserva contexto sempre que possível | | Consistência e padrões | mesma intenção usa o mesmo componente, variante e posição | | Prevenção de erros | restrições, validação antecipada e confirmação seletiva evitam falhas antes de explicá-las | | Reconhecimento em vez de memorização | opções e estado atual permanecem visíveis; não dependa de instruções lembradas | | Flexibilidade e eficiência | defaults atendem o uso comum; busca, atalhos e ações em massa aceleram especialistas | | Design estético e minimalista | cada elemento comunica hierarquia, estado ou ação; decoração não compete com dados | | Recuperação de erros | mensagens dizem o que ocorreu e como corrigir, sem expor detalhes técnicos | | Ajuda contextual | tooltip, hint e documentação aparecem onde a decisão acontece |

5. Foundations

5.1 Marca e temas

Existem dois temas oficiais:

| Tema | Modo | Anchor | Papel | |---|---|---:|---| | Deep Blue | claro | #0544AB | assinatura principal da marca e origem da escala clara | | Navy Electric | escuro | #021838 | assinatura Navy e origem da escala escura |

Esses valores são a origem matemática das escalas, não cores para copiar em JSX ou CSS de produto. buildEssenceTheme() deriva superfícies, texto, bordas, ações, foco, sidebar, estados e iconografia com ajustes de luminosidade e saturação adequados a cada modo.

No tema escuro, portanto, --primary é um acento elétrico derivado da essência Navy; ele não precisa ser literalmente #021838. O anchor continua preservado na configuração canônica, enquanto os tokens resolvidos garantem legibilidade e hierarquia.

Consumo correto:

<section className="bg-background text-foreground">
  <Button variant="default">Salvar</Button>
  <p className="text-muted-foreground">Última atualização hoje</p>
</section>

// incorreto: ignora tema, contraste e estados
<button className="bg-[#0544AB] text-white">Salvar</button>

Cadeia de geração:

1. src/design-system/config/theme.config.ts é a fonte canônica.
2. npm run tokens:export gera lib/theme.generated.css e os snapshots do catálogo.
3. npm run build:lib executa essa sincronização antes de gerar dist/index.css.
4. Produtos importam apenas forlogic-core/index.css.

Não edite lib/theme.generated.css, tokens.css ou tokens.json manualmente. Uma mudança de tema começa na fonte canônica, passa pelos gates e atualiza este documento.

5.2 Tokens semânticos

Tokens descrevem função, não aparência. Use:

• superfícies: background, card, popover, muted, surface-*;
• conteúdo: foreground, muted-foreground, *-foreground;
• marca e interação: primary, primary-hover, primary-active, ring;
• controles: control-surface-*, control-foreground-*, control-ring;
• navegação lateral: sidebar-background, sidebar-hover, sidebar-accent;
• semântica: danger, success, warning, info e seus fundos;
• ícones: ds-icon-* derivados do tema ativo.

<div className="border border-border bg-card text-card-foreground" />

// incorreto: valores literais e paleta de implementação
<div className="border-blue-700 bg-[#0544AB] text-white" />

5.3 Cor funcional

• Primária: ação principal, foco e seleção; não colore tudo indiscriminadamente.
• Danger: erro e ação destrutiva.
• Success: resultado positivo confirmado.
• Warning: atenção ou risco recuperável.
• Info: contexto informativo sem urgência.
• Neutro: estrutura, texto secundário e estados sem julgamento.

Todo estado funcional combina cor com texto, ícone ou forma. A API pública usa danger, nunca destructive.

5.4 Tipografia

• Família oficial: Roobert Pro, empacotada na biblioteca.
• Fallback homologado: Inter, via font-alt quando aplicável.
• Código e dados monoespaçados: Roboto Mono/font-mono.
• Base operacional: 13px.
• PageHeader: 22px no tamanho canônico md.
• Cabeçalhos de tabela: altura 36px, texto curto e sem quebra.

Use font-sans e font-mono; não fixe font-family em componentes. Hierarquia nasce de tamanho, peso, espaço e posição — não apenas de cor.

5.5 Espaçamento, gutters e densidade

• Gutter horizontal de página: 24px, estável em todas as larguras.
• Raio base: 8px (rounded-lg). Única exceção: o item de navegação do App Sidebar (data-nav-item dentro de data-sidebar="sidebar"), com raio assimétrico de 4px/8px (3px/6px nos itens de 28px); nenhum outro componente o usa.
• Controles usam densidade alta, com base de 13px.
• Espaçamento segue os tokens e utilitários do sistema; não introduza valores arbitrários quando há escala equivalente.
• Não use max-w-* ou mx-auto para recentralizar a casca da página. Limite apenas blocos de leitura longa.

5.6 Elevação e sombra

Sombra comunica camada e interação, não ornamentação. Use a superfície e sombra já incluídas no componente. Overlays, menus e dialogs devem parecer acima do conteúdo; cards de conteúdo comum não devem simular janelas flutuantes.

5.7 Iconografia

Phosphor é a biblioteca oficial. Material Symbols existe apenas dentro do IconPicker.

import { CaretDown, Gear, House } from '@phosphor-icons/react';

| Peso | Uso | |---|---| | regular | interface em repouso (padrão) | | fill | item ativo, rota ativa ou ação confirmada | | duotone | destaque grande, ilustração funcional ou stat card |

A cor deriva do tema ativo, por tokens como text-foreground, text-primary e text-danger. Não passe hexadecimal em color. Ícone decorativo recebe aria-hidden; botão somente com ícone recebe nome acessível e tooltip quando necessário. Alvo interativo recomendado: ao menos 44 × 44px.

5.8 Movimento

Movimento explica mudança de estado e continuidade espacial. Deve ser curto, interrompível e discreto. Não use animação para mascarar espera, deslocar conteúdo sem necessidade ou competir com leitura. Componentes oficiais respeitam redução de movimento; customizações devem preservar esse comportamento.

Para durações e curvas, use as escalas nomeadas do preset (duration-420, ease-emphasized, ease-sheet). Valores arbitrários entre colchetes ficam ambíguos entre o Tailwind e o tailwindcss-animate, e nesse caso nenhum CSS é gerado.

6. App shell e páginas

6.1 Estrutura

AppLayout
├── AppSidebar
└── coluna principal
    ├── AppHeader
    └── BodyContent (único scroll)
        └── página

• Root: h-screen overflow-hidden.
• Conteúdo: flex-1 min-h-0 overflow-y-auto.
• Header e sidebar permanecem estáveis.
• Popovers não devem criar uma segunda hierarquia de scroll.
• Sidebar lembra seu estado por usuário.
• Em mobile, painéis laterais fecham ao concluir navegação.

6.2 PageHeader e headings

Cada página tem exatamente um PageHeader, que entrega o único h1. O topo não usa tile de ícone. O subtítulo resume a tela em uma linha, com até 100 caracteres. badges recebe contexto curto; actions recebe o CTA primário.

Telas de registro (iniciativa, plano, documento, indicador) usam, no lugar do PageHeader, um topo em card: PageHeaderCard (código, situação, título, ações e faixa de resumo) ou PageHeaderStat (o mesmo card com um stat compacto na extrema direita). Eles são o header da página — mesma regra de um por página e mesmo h1 — e nunca convivem com um PageHeader na mesma tela. Chip de código, bolinha de estado, rótulo + valor, pilha de avatares e prazo com estado saem de átomos do DS (CodeChip, StatusDot, MetaField, AvatarStack, DueDateChip), não de marcação copiada.

Depois dele:

• h2: seção principal da página;
• h3: subseção;
• não pule níveis para obter aparência;
• demos dentro da documentação usam demo/PageHeaderDemoScope.

O AppHeader recebe breadcrumb e metadados por usePageMetadata(). Rotas multi-tenant usam /:alias/...; o alias da URL é a fonte de verdade.

6.3 Action bars

Agrupe ações relacionadas, mantenha uma ação primária evidente e desloque ações raras para menu. Em largura reduzida, preserve prioridade e nome acessível; não comprima texto até ficar ilegível. Ações em massa só aparecem quando existe seleção.

7. Famílias de componentes

7.1 Formulários

Use BaseForm quando campos, seções e colunas puderem ser descritos por configuração. Use controles individuais quando a interação exigir composição específica.

Escolha:

• Input/Textarea: texto curto/longo;
• NumberInput: quantidade com regras numéricas;
• Select: poucas opções conhecidas;
• Combobox: lista pesquisável ou seleção múltipla;
• ComboTree: hierarquia;
• pickers: data, intervalo, data e hora, mês ou ano;
• Checkbox: escolhas independentes;
• RadioGroup: uma escolha visível entre poucas opções;
• Switch: efeito imediato entre ligado/desligado.

Valide com schemas compartilháveis; a mensagem de erro deve identificar o campo e a correção possível. Não dependa somente de cor para comunicar erro ou sucesso.

Evite: placeholder como único rótulo, validação só após submit, opção desabilitada sem explicação e confirmação para toda ação trivial.

7.2 Botões e ações

• default: ação principal da tarefa.
• secondary/outline: ação de apoio.
• ghost/subtle: ação de baixa ênfase.
• danger: ação destrutiva ou erro.
• SplitButton: ação principal estável com alternativas relacionadas.
• ActionButton/RowActions: comandos contextuais compactos.

Uma região deve ter hierarquia clara, normalmente com um único CTA primário. Ícone sem texto é reservado a comandos familiares e recebe tooltip.

7.3 Navegação

Links mudam contexto ou endereço; botões executam comandos. Breadcrumb mostra localização hierárquica, não histórico. Tabs alternam vistas irmãs; abas de trabalho do App Header preservam contextos abertos e seus endereços completos.

7.4 Tabelas e CRUD

Use tabela quando comparação entre linhas e colunas é central. Use createCrudPage para fluxos CRUD completos — mantendo a configuração memoizada — e CrudTable/DataTable para a grade.

Defaults oficiais incluem ordenação, resize, gerenciador, drag-and-drop de colunas, paginação e filtro. Cabeçalhos são curtos; conteúdo truncado usa TruncatedCell/EllipsisText com tooltip. Ações em massa usam SelectionToolbar; ações da linha usam RowActions e RowContextMenu equivalentes. Modo somente leitura usa readOnly.

O CSS oficial garante que células alinhem verticalmente e que título de coluna e conteúdo não quebrem linha. Excesso vira ellipsis ou coluna mais larga — nunca texto encaixotado. Quando a célula realmente precisa de várias linhas, marque-a com data-allow-wrap="true".

Não use tabela quando a tarefa depende mais de narrativa, imagem, progressão por etapas ou agrupamento espacial.

7.5 Listas, cards e accordions

• Lista/DataList: leitura sequencial e composição flexível.
• Card: unidade repetível com fronteira real; não use cards para embrulhar seções inteiras da página.
• Accordion: detalhes secundários que podem ser revelados sem perder contexto.

<Accordion type="single" collapsible>
  <AccordionItem value="details">
    <AccordionTrigger>Detalhes</AccordionTrigger>
    <AccordionContent>Conteúdo</AccordionContent>
  </AccordionItem>
</Accordion>

AccordionItem é o card, AccordionTrigger ocupa toda a largura e AccordionContent recebe os gutters internos. Instâncias não aplicam px-*, py-*, rounded-*, pt-* ou gaps locais. density="compact" alinha o trigger a uma linha de tabela.

Não esconda conteúdo essencial, erro ou única ação possível em accordion fechado.

7.6 Gráficos e indicadores

Escolha o gráfico pela pergunta:

• linha/área: evolução no tempo;
• barras: comparação;
• donut: composição simples com poucas categorias;
• heatmap: intensidade em duas dimensões;
• ranking: ordem explícita;
• stat card: valor pontual com contexto e variação derivada.

Use a paleta monocromática derivada do tema e reserve cores semânticas para significado. Todo gráfico precisa de rótulo, unidade, período, estado vazio e alternativa textual/tabular quando a visualização carregar informação essencial.

7.7 Feedback e estados

• Skeleton: espera com estrutura previsível.
• EmptyState: ausência de conteúdo com próximo passo quando existir.
• toast: confirmação breve, não bloqueante e com fundo sólido.
• erro inline: próximo à origem.
• ErrorBoundary: falha inesperada da área.
• progress: avanço mensurável.

Não use spinner isolado quando a estrutura da tela é conhecida. Não dependa de toast para erro que exige correção no formulário.

7.8 Dialogs, popovers e painéis

• Dialog: decisão ou tarefa curta que bloqueia o contexto.
• ConfirmDialog: confirmação comum.
• AlertDialog: consequência irreversível.
• SidePanel/Sheet: inspeção ou edição mantendo referência ao conteúdo anterior.
• Popover: controle contextual ancorado.
• Tooltip: explicação curta, nunca conteúdo indispensável.

<DialogContent size="md">
  <DialogHeader />
  <DialogBody>{/* conteúdo rolável */}</DialogBody>
  <DialogFooter />
</DialogContent>

DialogBody é obrigatório antes de DialogFooter e é a única área rolável. Formulários com alterações não salvas devem interceptar o fechamento programaticamente.

Campo que já abre focado — busca em dialog, paleta de comando — usa a utilidade .focus-soft, publicada no CSS oficial. Nunca focus-within:ring-2 cru nem cores arbitrárias.

8. Plataforma

8.1 Internacionalização

Componentes compartilhados usam useTranslation/t() de forlogic-core. O Admin interno permanece pt-BR quando definido pelo produto. Não coloque texto de aplicação dentro da biblioteca sem chave de tradução apropriada.

8.2 Backend opcional

CoreProviders aceita backend="supabase" ou backend="dotnet". Recursos opt-in dependentes de Supabase devem ser importados pelos subpaths publicados e instanciados apenas quando a configuração existir.

9. Acessibilidade

WCAG 2.1 AAA é o objetivo de evolução, não uma certificação atual. Não há declaração de conformidade integral sem auditoria independente de todos os componentes, conteúdos e fluxos. Os gates automatizados cobrem documentação, tokenização e parte do contraste dos botões em claro/escuro; eles não substituem teste manual.

Critérios obrigatórios

• HTML semântico e um único h1 por página.
• Operação completa por teclado, sem armadilha de foco.
• Foco visível, com contraste e área suficientes, e ordem lógica.
• Nome, papel, valor e estado disponíveis à tecnologia assistiva.
• Informação nunca transmitida apenas por cor, posição ou movimento.
• Contraste revisado nos estados repouso, hover, foco, ativo, disabled e loading, em ambos os modos.
• Texto redimensionável e layout funcional em zoom/reflow e telas estreitas.
• Alvo interativo recomendado de pelo menos 44 × 44px.
• Alternativa textual para conteúdo relevante; imagens decorativas ficam ocultas da árvore acessível.
• Erros associados aos campos e descritos com ação corretiva, em texto.
• Animações respeitam prefers-reduced-motion.

10. Segurança e dados

• O schema deste repositório é common; cada consumidor declara o seu no próprio README.
• Schema explícito em toda query.
• Toda tabela pública nova precisa de GRANT, RLS e policies na mesma migration.
• Acesso authenticated por padrão.
• Roles em tabela separada, com validação server-side.
• A identidade vem do JWT, nunca do request.
• Soft delete não substitui policy.
• Buckets são privados e arquivos usam URL assinada de curta duração.
• Nenhum secret ou service_role entra no frontend.

O documento normativo completo é docs/SECURITY.md. Consulte-o antes de alterar autenticação, dados, Edge Functions ou upload.

11. Onde consultar

| Necessidade | Fonte | |---|---| | Adoção, regras transversais, racional e padrões | este documento | | Tema e escala | src/design-system/config/theme.config.ts | | CSS consumido | forlogic-core/index.css | | Props e exemplo de um export | JSDoc em dist/**/*.d.ts | | Demonstração visual e variantes | catálogo /ds | | Segurança | docs/SECURITY.md | | Publicação | docs/PUBLISH.md | | Versão em uso em cada consumidor e plano de atualização | docs/ATUALIZACAO_CONSUMIDORES.md |

Áreas principais do catálogo: Brand Guide; Foundations (Design Tokens e Icons); Forms; Actions & Navigation; Data Display (tabelas, grids, accordions, charts e states); Overlays & Feedback; Layout; Platform. Comece por Brand Guide, Design Tokens, Icons e o Overview da família desejada.

12. Gates antes de publicar

npm run tokens:export
npm run docs:check-all
npm run ds:check
npm run lint
npm run typecheck
npm run build:lib

Os gates atuais não equivalem a uma auditoria completa WCAG AAA.

13. Checklists

13.1 Adoção

• [ ] CSS oficial importado uma única vez.
• [ ] Preset Tailwind e configuração Vite da biblioteca ativos, sem theme.extend local.
• [ ] CoreProviders e AppLayout sem providers duplicados.
• [ ] Deep Blue #0544AB e Navy #021838 chegam pelo CSS gerado, sem cópia local.

13.2 Decisão

• [ ] A tarefa e o risco estão claros.
• [ ] O catálogo foi consultado antes de criar componente.
• [ ] A família escolhida corresponde à estrutura do conteúdo.
• [ ] O comportamento esperado em vazio, loading, erro e sucesso foi definido.

13.3 Interface

• [ ] Componentes visuais vêm de forlogic-core.
• [ ] Cores, bordas, sombras e tipografia usam tokens semânticos; nenhuma cor hardcoded.
• [ ] Ícones são Phosphor.
• [ ] Existe apenas um PageHeader/h1.
• [ ] Gutter de 24px e scroll único foram preservados.
• [ ] Formulários, tabelas, dialogs e accordions seguem os padrões acima.
• [ ] Textos e ações não truncam em larguras suportadas.

13.4 Acessibilidade

• [ ] Fluxo concluído por teclado.
• [ ] Foco sempre visível e ordenado.
• [ ] Nomes e estados acessíveis conferidos.
• [ ] Contraste verificado em claro/escuro e em todos os estados.
• [ ] Informação não depende apenas de cor.
• [ ] Zoom/reflow e redução de movimento verificados.

13.5 Dados e segurança

• [ ] .schema() explícito em cada query.
• [ ] RLS, GRANTs e cenários negativos testados.
• [ ] Nenhuma autorização depende do cliente.
• [ ] Nenhum secret foi enviado ao bundle.
• [ ] Uploads e arquivos seguem a política privada.

13.6 Documentação e entrega

• [ ] JSDoc contém descrição e @example real.
• [ ] Página do catálogo demonstra o padrão atualizado.
• [ ] Este documento foi atualizado se adoção, racional, foundation ou regra transversal mudou.
• [ ] Tokens foram regenerados quando necessário.
• [ ] Gates aplicáveis passaram.

14. Governança e evolução

Uma mudança transversal do DS não termina no componente. A mesma entrega deve manter alinhados:

decisão de produto
→ tokens e implementação
→ JSDoc
→ catálogo interativo
→ este documento
→ gates e release

Ou seja, na mesma entrega:

1. atualizar a fonte de código e o JSDoc afetado;
2. atualizar a demonstração no catálogo /ds;
3. atualizar este documento quando mudar adoção, racional, foundation, padrão de composição ou regra transversal;
4. regenerar tokens quando houver mudança de tema;
5. executar os gates aplicáveis.

Mudanças incompatíveis exigem nota de migração e versão adequada. Antes de documentar uma regra, confirme que o código a cumpre. Antes de publicar, gere novamente os tokens e valide ambos os temas.

Não crie um .md por componente: a referência específica permanece no JSDoc e no catálogo.

Definition of Done documental

• sem referências a exports inexistentes;
• sem valores de tema divergentes da fonte canônica;
• sem promessa de conformidade não auditada;
• exemplos mínimos, compiláveis e baseados na API real;
• links internos válidos.