``` ### 3. SEMPRE usar variáveis semânticas | Propósito | Variável CSS | Classe Tailwind | |-----------|-------------|-----------------| | Background principal | `var(--cloud)` | `bg-cloud` ou `bg-surface` | | Background elevado | `var(--arctic-mist)` | `bg-arctic-mist` ou `bg-surface-muted` | | Texto principal | `var(--graphite-depth)` | `text-graphite-depth` | | Texto secundário | `var(--soft-steel)` | `text-soft-steel` | | Bordas | `var(--soft-arctic)` | `border-soft-arctic` | | Accent/Links | `var(--teal-intense)` | `text-teal-intense` | | Brand | `var(--emerald-abyss)` | `bg-emerald-abyss` | ### 4. Dark mode é AUTOMÁTICO Quando você usa variáveis CSS, o dark mode funciona automaticamente: ```css /* As variáveis são redefinidas em html.dark-mode */ :root { --cloud: #F5F8FA; /* Light mode */ } html.dark-mode { --cloud: #0d1117; /* Dark mode */ } /* Seu código usa a variável - funciona em ambos os modos */ .meu-componente { background: var(--cloud); /* Automaticamente adapta! */ } ``` **NUNCA crie overrides manuais para dark mode** como: ```css /* ❌ PROIBIDO - Não faça isso! */ html.dark-mode .meu-componente { background: #161b22 !important; } ``` ### 5. Wrappers React em `ds-nextjs/` são cascas finas A regra "NUNCA criar CSS personalizado que o DS já cubra" vale também para componentes React no pacote `ds-nextjs/`. Wrappers React **apenas** compõem `className` sobre classes do DS — nunca definem estilos próprios. ```tsx // ❌ PROIBIDO export function Drop({ variant }) { return ...; } export function Drop({ variant }) { return ...; // classe inventada } // ✅ CORRETO export function Drop({ variant, shape = "pill", size = "sm" }) { const classes = ["drop", `drop-${variant}`, `drop-${shape}`, `drop-${size}`].join(" "); return ...; } ``` Se um componente precisa de estilo que o DS não cobre, **adicione no DS primeiro** (em `tokens/` ou `src/components/`) e só então crie o wrapper React. Nunca improvise CSS dentro do `ds-nextjs/`. --- ## Mapeamento de Cores ### Cores de Background | Uso | Variável | Light | Dark | |-----|----------|-------|------| | Página/Container | `--cloud` | #F5F8FA | #0d1117 | | Cards/Modais | `--arctic-mist` | #E9ECEF | #161b22 | | Áreas sutis | `--soft-arctic` | #E5E8EB | #21262d | ### Cores de Texto | Uso | Variável | Light | Dark | |-----|----------|-------|------| | Texto principal | `--graphite-depth` | #1F2937 | #f0f6fc | | Texto secundário | `--soft-steel` | #374151 | #b1bac4 | ### Cores de Accent | Uso | Variável | Light | Dark | |-----|----------|-------|------| | Links/CTAs | `--teal-intense` | #1a8b7d | #3dc9bd | | Hover | `--emerald-abyss` | #0B2D2A | #7ee2d0 | | Highlights | `--mint-signal` | #B7E4D5 | #1a3d3a | > **Nota**: `--teal-intense` foi ajustado de #2AA198 para #1a8b7d para melhorar contraste (WCAG AA 4.6:1) ### Cores de Status | Status | Variável | Uso | |--------|----------|-----| | Sucesso | `--success` | Confirmações, aprovações | | Aviso | `--warning` | Alertas, pendências | | Erro | `--error` | Erros, rejeições | | Info | `--info` | Informações neutras | --- ## Checklist Antes de Commitar Antes de qualquer commit que modifique arquivos `.css`, `.html`, `.tsx` ou `.ts`: - [ ] Nenhum `background: white` ou `background: #fff` - [ ] Nenhum `bg-white`, `bg-gray-*`, `text-gray-*`, `border-gray-*` - [ ] Todas as cores usam `var(--nome-variavel)` ou classes Tailwind do preset - [ ] Nenhum override `!important` para dark mode - [ ] Testado visualmente em light E dark mode - [ ] Wrappers React em `ds-nextjs/components/ds/` são cascas finas sobre classes do DS — não definem estilos próprios, `style={{}}`, nem cores inline - [ ] Se editou algo em `tokens/`, o `ds-nextjs` ainda compila (`cd ds-nextjs && npm run build`) - [ ] Se editou um preset Tailwind (`integrations/tailwind-preset/tailwind.config.js` **ou** `ds-nextjs/tailwind.config.ts`), atualizou o outro para manter paridade ### Validação Automática Execute antes de commitar: ```bash ./scripts/validate-colors.sh ``` O pre-commit hook também executa automaticamente e **bloqueia commits com violações**. --- ## Exemplos de Componentes Corretos ### Card ```html

Título

Descrição do card

``` ### Formulário ```html

Campo

``` ### Tabela ```html

Coluna
Valor

``` --- ## O Que Mudou (Dezembro 2024) ### Migração Realizada 1. **119 ocorrências** de `bg-white` → `bg-cloud` 2. **52 ocorrências** de `background: white` → `var(--cloud)` 3. **~80 ocorrências** de `text-gray-*` → `text-graphite/text-soft-steel` 4. **392 → 190 linhas** em `dark-mode-base.css` (removidos overrides) ### Novos Arquivos - `scripts/validate-colors.sh` - Validação automática - `showcase/shared/utilities.css` - Classes utilitárias `.ds-*` - `docs/ARCHITECTURE_ANALYSIS.md` - Documentação completa - `.git/hooks/pre-commit` - Enforcement automático ### Novas Classes Tailwind ```javascript // Semânticas (preferir estas) 'surface', 'surface-elevated', 'surface-muted' 'text-primary', 'text-secondary' 'border-default', 'border-subtle' 'accent', 'accent-hover' // Status com variantes light 'success-light', 'warning-light', 'error-light', 'info-light' ``` --- ## Resumo Executivo > **A regra de ouro**: Se você está escrevendo uma cor, ela DEVE ser uma variável CSS (`var(--nome)`) ou uma classe Tailwind que mapeia para uma variável (`bg-cloud`, não `bg-white`). Se seguir esta regra, o dark mode funcionará automaticamente e o sistema permanecerá consistente. --- ## Skeleton Loaders Para estados de carregamento, use os skeleton loaders em vez de spinners genéricos. Eles mostram a estrutura esperada do conteúdo. ### Classes Disponíveis | Classe | Uso | |--------|-----| | `.skeleton-line` | Linhas de texto | | `.skeleton-circle` | Avatares, ícones | | `.skeleton-badge` / `.skeleton-drop` | Tags, drops farmacêuticos | | `.skeleton-avatar` | Avatares de usuário | | `.skeleton-button` | Botões | | `.skeleton-input` | Campos de formulário | | `.skeleton-card` | Cards genéricos | ### Tamanhos ```html

``` ### Componentes PharmData ```html

``` ### Animações - **Shimmer** (padrão): Efeito de brilho que passa da esquerda para direita - **Pulse**: Opacidade que pulsa suavemente - use `.skeleton-pulse` - **Stagger**: Atraso sequencial em listas - use `.skeleton-stagger` no container ### Acessibilidade O skeleton respeita `prefers-reduced-motion` automaticamente, trocando shimmer por pulse suave. ### Showcase Veja exemplos interativos em: `showcase/components/skeleton-showcase.html` --- ## Drops com Ícones (Font Awesome) Os drops possuem ícones Font Awesome automáticos via `::before`. **NUNCA use emojis**. ### Dependência ```html ``` ### Ícones por Categoria | Categoria | Classe | Ícone FA | |-----------|--------|----------| | Denominações Comerciais | `.drop-dec` | fa-pills | | Substâncias Ativas | `.drop-sub` | fa-dna | | Laboratórios | `.drop-lab` | fa-industry | | Concentrações | `.drop-cnc` | fa-flask | | Gotas | `.drop-gts` | fa-droplet | | Formas Farmacêuticas | `.drop-fofa` | fa-syringe | | Formas de Apresentação | `.drop-fap` | fa-box-open | | Vias de Administração | `.drop-via` | fa-stethoscope | | Embalagens | `.drop-emb` | fa-boxes-stacked | ### Controle de Ícones ```html Substância Substância ``` --- ## Modo Compacto (Power Users) Para interfaces densas com muitos dados, use o modo compacto. ### Ativação ```html

``` ### Modos Disponíveis | Modo | Classe/Atributo | Escala | Uso | |------|-----------------|--------|-----| | Default | (nenhum) | 1.0 | Padrão, boa legibilidade | | Compact | `.density-compact` | 0.85 | Power users, muitos dados | | Comfortable | `.density-comfortable` | 1.15 | Touch, acessibilidade | ### Toggle de Densidade ```html

``` --- ## Atalhos de Teclado ### Estilos para Teclas ```html A para aprovar Ctrl + S para salvar ``` ### Indicador de Atalho em Botões ```html ``` ### Barra de Ações de Workflow ```html

3 de 25

``` ### Atalhos Padrão Sugeridos | Ação | Atalho | |------|--------| | Aprovar | `A` | | Rejeitar | `R` | | Próximo | `N` ou `→` | | Anterior | `P` ou `←` | | Editar | `E` | | Salvar | `Ctrl+S` | | Cancelar | `Esc` | --- ## Breadcrumb Farmacêutico Navegação hierárquica para a estrutura: **Composições → Formulações → Embalagens → Apresentações** ### Uso Básico ```html ``` ### Variantes | Classe | Descrição | |--------|-----------| | `.breadcrumb-pharma` | Horizontal com setas coloridas | | `.breadcrumb-pharma-compact` | Versão menor | | `.breadcrumb-pharma-vertical` | Layout vertical para sidebars | ### Níveis e Cores Cada nível usa cores do sistema de drops: - `composicoes` → azul (--drop-sub) - `formulacoes` → roxo (--drop-fofa) - `embalagens` → índigo (--drop-emb) - `apresentacoes` → rosa (--drop-dec) --- ## Arquivos de Token Adicionados | Arquivo | Descrição | |---------|-----------| | `tokens/skeleton.css` | Skeleton loaders para loading states | | `tokens/density.css` | Modos de densidade (compact/comfortable) | | `tokens/keyboard-shortcuts.css` | Estilos para atalhos e workflow | --- *Última atualização: 2026-04-12 — adição do pacote `ds-nextjs/` (wrappers React MVP), biblioteca de ícones de saúde, guia `docs/usando-next.js.md`.* *PharmData Design System v3.2.0*