Movimento e acessibilidade

Orbz tem um perfil animado e uma apresentação estática de movimento reduzido para cada estado. A aplicação escolhe a política; Orbz renderiza.

Política de movimento reduzido

Use reduced-motion para escolher o comportamento:

O padrão é system.

<orb-z state="idle" reduced-motion="system"></orb-z>

Movimento reduzido não é um quadro genérico de inatividade. Cada estado tem uma composição estática distinta: listening, thinking, speaking e asleep continuam visualmente diferentes sem animação contínua.

Use never apenas quando houver uma razão clara para ignorar a preferência do sistema. Em configurações do usuário, salve a escolha e vincule-a diretamente:

import type { OrbzElement, OrbzReducedMotion } from "@neongate-ai/orbz";
 
function setMotionPreference(value: OrbzReducedMotion) {
  const orb = document.querySelector<OrbzElement>("orb-z");
  if (orb) orb.reducedMotion = value;
}

Velocidade

speed altera a duração da animação. Valores acima de 1 aceleram; entre 0 e 1, desaceleram. O valor deve ser positivo.

<orb-z speed="0.8"></orb-z>
<orb-z speed="1.25"></orb-z>

O padrão é 1. Zero, valores negativos, não numéricos ou não finitos são normalizados para o padrão.

A velocidade não tem efeito visível no modo reduzido, pois seus perfis são estáticos.

Pausar e retomar

O atributo booleano paused congela a animação atual. Não silencia áudio, interrompe gravação, cancela pedidos nem altera state.

<orb-z state="thinking" paused></orb-z>

import type { OrbzElement } from "@neongate-ai/orbz";
 
const orb = document.querySelector<OrbzElement>("orb-z");
 
orb?.pause();
orb?.play();
orb?.restart();

Como elevated, paused segue a semântica booleana HTML. paused="false" continua pausado. Remova o atributo ou defina a propriedade como false.

Comunique o significado fora da animação

A esfera interna é marcada como decorativa. Estados, erros, pedidos de permissão e ações precisam de HTML semântico na aplicação hospedeira.

<section aria-labelledby="assistant-heading">
  <h2 id="assistant-heading">Voice assistant</h2>
 
  <div role="status" aria-live="polite">
    <orb-z state="listening"></orb-z>
    <span>Assistant is listening</span>
  </div>
 
  <button type="button">Stop listening</button>
</section>

A interface ao redor deve:

• anunciar mudanças importantes com texto, não apenas cor ou movimento
• manter controles de microfone e parada acessíveis por teclado
• descrever erros e formas de recuperação explicitamente
• preservar status útil com movimento reduzido
• evitar anunciar cada quadro ou transição decorativa

Use role="status" e aria-live só para mensagens que realmente precisam ser anunciadas. Para atualizações sem importância ao leitor de tela, texto visível comum pode ser melhor.

Um padrão prático

Para a maioria dos produtos:

<orb-z
  state="idle"
  speed="1"
  reduced-motion="system"
></orb-z>

Mantenha um rótulo de texto próximo sincronizado com o mesmo estado. Isso respeita a preferência do sistema, preserva todos os estados e não atribui ao movimento a responsabilidade pelo significado.