Movimento e elevação nos Web Components
Este guia aplica as diretrizes de movimento do GovBR-DS e elevação ao pacote Web Components. Movimento é usado somente quando explica uma mudança de estado, hierarquia ou progresso; ele não é adicionado como decoração a componentes estáticos.
Política de movimento
O pacote usa os tokens de duração e easing disponíveis no @govbr-ds/core compatível com a
versão publicada. Não existe uma prop global de animação.
| Situação | Duração de referência | Propriedades permitidas |
|---|---|---|
| Feedback e indicador | 100 ms | cor, opacidade, sombra |
| Entrada de disclosure ou superfície | 300 ms | opacidade e ícones internos |
| Navegação, painel e progresso | 500 ms | opacidade, indicador e progresso contido |
| Carregamento contínuo | velocidade configurada | traço/rotação do indicador |
Entradas usam ease-out; saídas usam ease-in somente quando o elemento continua renderizado;
estados reversíveis usam ease-in-out. Fechamento, foco, Escape, eventos e remoção da top layer
continuam imediatos.
Famílias cobertas
- Superfícies e disclosures: Breadcrumb, Collapse, CookieBar, DateTimePicker, Dropdown, Footer Category, Header List/Search, List, Menu, Modal, Notification, Scrim, Select e Tooltip.
- Navegação e progresso: Carousel, Loading, Tab e Wizard.
- Microinterações existentes: Header sticky, Slider, Switch, Tag e Skip Link.
- Sem novo movimento: componentes de conteúdo, formulário, tabela, ações e indicadores que não precisam de transição para comunicar estado.
Subcomponentes e aliases herdam a política da família. Uma mudança de opacidade não substitui
aria-expanded, aria-selected, aria-busy, foco visível ou qualquer outro estado semântico.
Redução de movimento
As regras ficam estáticas por padrão e são habilitadas somente em
@media (prefers-reduced-motion: no-preference). Com reduce:
- superfícies abrem sem transição e não deslocam conteúdo;
- Loading permanece visível, porém estático; no modo progressivo, a interpolação do percentual é cancelada;
- Carousel não inicia autoplay, pausa se a preferência mudar durante a reprodução e não reinicia sozinho quando a preferência voltar ao normal;
- controles Play/Pause, teclado, foco e eventos continuam disponíveis.
Essa política atende à preferência do usuário documentada pela MDN e aos critérios WCAG de animação decorrente de interação e pausar, parar ou ocultar movimento.
Elevação e composição
Sombra e empilhamento são responsabilidades diferentes:
| Camada | Uso |
|---|---|
| 0 | fluxo normal e conteúdo |
| 1 | Dropdown, Select, Notification e fallback de Tooltip |
| 2 | navegação persistente e Header |
| 3 | Menu temporário |
| 4 | bloqueadores e fallbacks |
| top layer | Modal, Scrim fullscreen, CookieBar bloqueante, Menu sobreposto e Popover nativo |
Máscara e painel usam subcamadas locais. Hosts, âncoras e alvos posicionados pelo Floating UI
não recebem transform, z-index animado ou will-change permanente. Card e Magic Button
mantêm sua sombra visual sem criar uma camada global.
Checklist do consumidor
- Teste
no-preferenceereduceem teclado e leitor de tela. - Confirme que o foco não fica oculto por uma superfície elevada.
- Não use tooltip ou movimento como única comunicação de erro, instrução ou estado.
- Ao combinar superfícies, mantenha Modal/Scrim/CookieBar bloqueantes acima de menus e tooltips.
- Para Carousel com autoplay, mantenha um controle Play/Pause visível e acionável.
