O contrato entre gesto e resposta.
A aparência da ação nasce da sua responsabilidade. Nome, disponibilidade, foco e retorno formam um único contrato: o controle permite prever o efeito, operar por teclado e entender o resultado sem depender da cor.
Anatomia de uma ação com estado
O botão articula um plano tátil, um limite funcional, um sinal redundante e um verbo preciso. A legenda de retorno fica ao lado do contexto; ela não desaparece dentro de um ícone.
-
Plano tátil
O fundo opaco e o brilho interno separam o controle do suporte. A borda dupla é decorativa; o limite externo continua reconhecível sem textura.
-
Sinal redundante
O pequeno quadrado acompanha o nome da ação. Não pode ser a única indicação de pronto, erro ou processamento.
-
Verbo e objeto
“Revisar aplicação” comunica o próximo efeito. Manter o nome durante o processamento para preservar a relação entre intenção e retorno.
-
Atalho documentado
O kbd apresenta a combinação, aria-keyshortcuts a documenta e data-xq-shortcut a registra no XequeCore. O módulo ignora campos em edição, composição de texto e controles desabilitados; o atalho não substitui Tab e Enter.
-
Foco de dois anéis
O intervalo interno conserva separação do botão; o anel externo permanece visível sobre a superfície. Não recortar o foco com overflow ou chanfro.
-
Retorno contextual
A mensagem descreve o estado e sua recuperação. Validação local não equivale a envio; não anunciar cadastro ou contato concluído.
Contratos de tokens CSS
Valor ou alias no tema claro, propriedade consumidora e limite de uso. Cores são apresentadas em RGB equivalente; a fonte continua no CSS de tokens. O inspetor mostra a resolução no tema escolhido.
| Token / expressão | Aplicação CSS | Regra |
|---|---|---|
--xq-controle-lg
56px
|
.xq-btn
min-block-size
|
56 px na ação principal. Não comprimir o alvo para acomodar texto; permitir quebra ou empilhar ações. |
--xq-raio-controle
3px
|
.xq-btn
border-radius
|
3 px no controle. A assinatura usa precisão de borda; não substituir por uma cápsula arbitrária. |
--xq-realce
rgb(36 71 53)
|
.xq-btn
background, border-color
|
Cor semântica da ação principal em cada tema; aplicar junto de --xq-sobre-realce. |
--xq-sobre-realce
rgb(247 248 242)
|
.xq-btn
color
|
Texto e ícones do plano de ação. Não herdar a tinta do corpo sobre o fundo de realce. |
--xq-surface-inset
inset 0px 1px 0px 0px var(--xq-surface-specular), inset 0px -1px 0px 0px var(--xq-surface-shade)
|
.xq-btn
box-shadow
|
Iluminação interna compartilhada. Foco visível acrescenta seus anéis sem apagar este material. |
--xq-ritmo-3
12px
|
.xq-btn
gap
|
12 px entre sinal, texto, ícone e atalho; o texto pode ocupar o espaço flexível. |
--xq-font
'Schibsted Grotesk', Arial, sans-serif
|
.xq-btn
font-family
|
Schibsted Grotesk para o comando legível. Reservar mono para atalho, índice e dado técnico. |
--xq-mono
'Xeque Mono', monospace
|
.xq-btn-atalho
font-family
|
Xeque Mono no atalho. A largura estável distingue a medição da linguagem da ação. |
--xq-focus-width
2px
|
.xq-btn:focus-visible
outline-width
|
Espessura de 2 px. O foco precisa permanecer completo no teclado e nos seis temas. |
--xq-focus-outer
var(--xq-anel)
|
.xq-btn:focus-visible
outline-color
|
Anel semântico externo. Não substitui o espaço do anel interno. |
--xq-focus-gap
2px
|
.xq-btn:focus-visible
outline-offset, box-shadow
|
Intervalo de 2 px mais suporte interno. Nunca neutralizar com outline: none. |
--xq-motion-press
100ms
|
.xq-btn
transition-duration
|
100 ms na resposta de transform. A preferência por movimento reduzido neutraliza o deslocamento. |
Uso correto × uso incorreto
Compare a mesma intenção em duas composições. Os exemplos são amostras de leitura; os controles operáveis ficam no playground.
Amostra visual do comando. Retorno: aplicação pronta para revisão local.
- Um comando dominante com verbo e objeto; contexto informa o alcance local.
- Sinal e texto trabalham juntos, com separação técnica entre mensagem e atalho.
- A anatomia documenta o foco; a amostra visual usa span para não fingir operação.
Faça acontecer!
ContinuarEnviarComeçarPronto!
- Três comandos disputam a mesma prioridade, sem esclarecer o efeito de cada um.
- “Pronto!” omite o que foi concluído e se houve envio.
- Formato de cápsula e selo promocional não descrevem responsabilidade ou estado.
Bancada de resposta da ação
Troque o estado da validação e examine como o retorno mantém verbo, contexto e número de protocolo. “Executar teste local” simula a resposta local; “Repetir” reinicia a transição sem duplicar efeitos.
Aplicação em revisão.
Pronto para conferir os campos da demonstração.
Este laboratório altera apenas o estado de apresentação. A validação operável permanece nos exemplos anteriores.
Pronto. Altere um controle para inspecionar o contrato.
Ensaio local e determinístico. A ação percorre carregamento → sucesso; movimento reduzido entrega o estado final imediatamente. Repetir preserva os controles.
Inspecionar tokens resolvidos
--xq-controle-lg- 56px
--xq-raio-controle- 3px
--xq-realce- rgb(36 71 53)
--xq-sobre-realce- rgb(247 248 242)
--xq-surface-inset- inset 0px 1px 0px 0px var(--xq-surface-specular), inset 0px -1px 0px 0px var(--xq-surface-shade)
--xq-ritmo-3- 12px
--xq-font- 'Schibsted Grotesk', Arial, sans-serif
--xq-mono- 'Xeque Mono', monospace
--xq-focus-width- 2px
--xq-focus-outer- var(--xq-anel)
--xq-focus-gap- 2px
--xq-motion-press- 100ms
Aplicar o contrato
Separar envio de validação
A função de validação confirma requisitos dos campos. O texto de sucesso deve declarar esse resultado específico; só uma confirmação real do destino permite anunciar envio.
<button class="xq-btn" type="submit">Validar aplicação</button>
<p class="xq-form-status" role="status">Campos conferidos localmente.</p>Explicar uma ação indisponível
disabled remove o acionamento nativo. A justificativa continua junto ao controle e se conecta por aria-describedby; não depender de tooltip inacessível.
<button class="xq-btn" type="button" disabled
aria-describedby="acao-motivo">Indisponível</button>
<p id="acao-motivo">Este exemplo não possui permissão de envio.</p>Documentar e registrar o mesmo atalho
aria-keyshortcuts informa a combinação à tecnologia assistiva; não executa o comando. Com XequeCore carregado, data-xq-shortcut encaminha Alt+R ao mesmo clique nativo. O exemplo reutiliza o toast local existente e não envia dados.
<button class="xq-btn" type="button"
aria-keyshortcuts="Alt+R" data-xq-shortcut="Alt+R"
data-xq-toast-trigger="Exemplo pronto para revisão. Nenhum dado foi enviado.">
<span class="xq-btn-texto">Revisar exemplo</span>
<kbd class="xq-btn-atalho" aria-hidden="true">Alt R</kbd>
</button>Critérios de aceite
- Percorrer as ações por Tab e conferir o anel completo, sem recorte.
- Acionar menu, abas, combobox e diálogos com as teclas descritas nos exemplos.
- Confirmar que disabled, readonly e aria-busy mantêm significados distintos.
- Forçar erro e corrigi-lo: a mensagem precisa apontar campo e recuperação.
- Testar Alt+R fora e dentro de um campo: só o comando visível e habilitado recebe o atalho fora da edição.