BaseKpiCard

Número do painel: mostra o número que decide o que a pessoa faz a seguir, com rótulo, variação, contexto e alerta. Serve para o resumo no topo de uma lista ou de um painel gerencial.

Valor contratado

R$ 186,4 mi186,4 milhões de reais

+2,1%subiu 2,1%melhorou3 aditivos em outubro

Saldo de empenho

R$ 3,2 mi3,2 milhões de reais

em 12 contratos

Alerta: Medições atrasadas

5

há mais de 10 dias

Ver medições atrasadas

Aditivos perto do limite

2

acima de 80% do limite

Uso

• Use para números que levam a uma ação: atrasos, saldo, limite. No máximo 4 por faixa.
• Não use para enfeitar a página com números que ninguém usa, para valores de um registro só (use o BaseSummaryList) nem para séries no tempo (use um gráfico).
• O rótulo diz o que é o número em até 4 palavras: "Saldo de empenho".
• O valor chega formatado e curto, sem centavos: "R$ 3,2" com unit="mi", não "R$ 3.214.877,12". Uma casa decimal e a unidade (mil, mi, bi) para caber no olhar e no celular.
• Um valor vazio ou só com espaços, vindo dos dados, aparece como um traço e é lido como "Não informado".
• O helperText dá o contexto embaixo do número: "desde setembro", "em 12 contratos".

Variação

delta é a variação em porcentagem, com sinal: -18 quer dizer que caiu 18%. A seta e o número com sinal dizem para onde foi: "+2,1%", "−18%". O sinal fica no texto para a direção não depender só da fonte de ícones. A porcentagem segue a regra do painel: sem casa decimal, e com uma casa só abaixo de 10% ("2,1%", "18%"). Uma variação que arredonda para zero aparece como "0%", com um traço no lugar da seta.

Depois do número, uma palavra diz se a variação é boa ou ruim: "melhorou" ou "piorou". A cor reforça a palavra (verde ou vermelho) e segue o julgamento, não a direção. Por padrão, subir é bom. Para números que devem cair, como atrasos e custos, use :increase-is-good="false": aí cair aparece como "melhorou" em verde e subir como "piorou" em vermelho. Saldo de empenho caindo é "piorou". Sem variação, não há palavra.

Subiu, bom

R$ 186,4 mi

+2,1%subiu 2,1%melhorouno mês

Desceu, ruim

R$ 3,2 mi

−18%caiu 18%pioroudesde setembro

Atraso médio

12 dias

−25%caiu 25%melhorouno trimestre

Sem variação

42

0%sem variação, 0%contratos ativos

Alerta

Use tone="error" só quando a pessoa precisa agir hoje, e tone="warning" para acompanhar. O alerta ganha um traço à esquerda, um ícone no lugar do ícone do rótulo e um texto para leitor de tela antes do rótulo ("Alerta:" ou "Atenção:"). No error, o número também fica vermelho. Diga no helperText o motivo do alerta.

Alerta: Medições atrasadas

5

há mais de 10 dias

Atenção: Garantias a vencer

3

nos próximos 30 dias

Com link

href leva à lista por trás do número. Prefira um link-label que diga o destino. Sem ele, o link mostra "Ver detalhes" e o leitor de tela ouve o rótulo junto: "Ver detalhes: Saldo de empenho".

Alerta: Medições atrasadas

5

há mais de 10 dias

Ver medições atrasadas

Saldo de empenho

R$ 3,2 mi

em 12 contratos

Ver detalhes: Saldo de empenho

Carregando

Com loading, o valor e o contexto viram marcadores do tamanho do conteúdo real, para o cartão não pular quando os dados chegam. O rótulo e o link continuam visíveis.

Saldo de empenho

Carregando

Faixa de números

Sozinho, o cartão tem borda, raio e sombra. Dentro de um elemento com a classe tj-kpi-row, os cartões viram uma faixa só, com uma linha fina entre eles: uma linha com até 4 números na tela larga, duas colunas abaixo de 992 px.

Estilo

Propriedade	Token
Fundo	--tj-layer-01
Borda e raio	--tj-border-subtle-02, --tj-radius-lg, sombra --tj-shadow-1
Recuo	--tj-space-5 em cima e embaixo, --tj-space-6 dos lados; --tj-space-4 no celular
Espaço entre linhas	--tj-space-2
Rótulo e contexto	--tj-text-sm, --tj-text-helper; ícone --tj-icon-sm em --tj-icon-secondary
Valor	28/34 px, --tj-weight-bold, algarismos tabulares, --tj-text-primary; --tj-text-2xl no celular
Unidade	--tj-text-lg, --tj-weight-semibold, --tj-text-helper
Variação boa / ruim	--tj-support-success-text / --tj-support-error-text; sem variação, --tj-text-secondary
Palavra do julgamento	--tj-weight-regular, --tj-space-1 antes, na cor da variação
Traço de alerta	3 px, --tj-support-error (error) ou --tj-support-warning (warning)
Ícone e valor em alerta	--tj-support-error-text; ícone do warning em --tj-support-warning-text
Link	BaseLink size="sm": --tj-link-primary, --tj-link-primary-hover no mouse
Divisória da faixa	1 px, --tj-border-subtle-01
Foco do link	o do BaseLink: contorno --tj-border-interactive com --tj-ring (Highlight em alto contraste)

Código

<div class="tj-kpi-row">
  <BaseKpiCard
    label="Saldo de empenho"
    icon="cash-stack"
    value="R$ 3,2"
    unit="mi"
    value-label="3,2 milhões de reais"
    :delta="-18"
    helper-text="desde setembro"
    href="/empenhos"
    link-label="Ver empenhos"
  />
  <BaseKpiCard label="Medições atrasadas" tone="error" value="5" helper-text="há mais de 10 dias" />
</div>

Propriedade	Tipo	Padrão	Descrição
label	string	—	Rótulo do número (obrigatório)
value	string	—	Valor já formatado e curto (obrigatório); vazio vira traço
unit	string	—	Unidade menor depois do valor: "mi", "mil", "dias"
valueLabel	string	—	O que o leitor de tela ouve no lugar do valor e da unidade: "3,2 milhões de reais"; vazio ou só espaços é ignorado
delta	number | null	—	Variação em porcentagem, com sinal; null, NaN ou infinito escondem a variação
increaseIsGood	boolean	true	Se subir é bom; false para atrasos e custos
helperText	string	—	Contexto embaixo do número
tone	'neutral' | 'warning' | 'error'	'neutral'	Alerta; valor desconhecido vira 'neutral'
icon	string	—	Ícone do Bootstrap Icons para o rótulo, sem "bi-"; o alerta troca pelo dele
href	string	—	Endereço do link para a lista por trás do número
linkLabel	string	'Ver detalhes'	Texto do link
loading	boolean	false	Mostra marcadores no lugar do valor e do contexto

Eventos: nenhum. O tipo KpiTone é exportado junto com o componente.

Acessibilidade

• O cartão é texto comum, sem papel de região: uma faixa de quatro números não enche a lista de regiões do leitor de tela. O leitor lê na ordem da tela: rótulo, valor, variação e contexto.
• Valor e unidade são lidos juntos. Com valueLabel, o leitor de tela ouve "3,2 milhões de reais" em vez de "R$ 3,2 mi", que ele leria mal.
• A seta da variação é decorativa. O leitor de tela ouve "caiu 18% piorou desde setembro": a direção, o número e o julgamento estão no texto.
• Quem enxerga lê a direção pela seta e pelo sinal do número, e o julgamento pela palavra "melhorou" ou "piorou"; a cor só reforça a palavra. A cor nunca é o único sinal (WCAG 1.4.1), inclusive no modo de alto contraste, que apaga a cor. Quando a variação pede ação, use também o tone, que traz ícone e texto.
• O alerta tem três sinais além da cor: o traço, o ícone e o texto "Alerta:" ou "Atenção:" lido antes do rótulo.
• O link é um BaseLink. O texto padrão dele é completado pelo rótulo só para leitor de tela, para que vários "Ver detalhes" na mesma faixa tenham destinos distintos (WCAG 2.4.4). O link entra na ordem do Tab, abre com Enter e mostra o foco do BaseLink, que continua visível no alto contraste.
• Com loading, o cartão fica com aria-busy="true" e o leitor de tela ouve "Carregando" no lugar do valor. Os marcadores são decorativos e param de brilhar com prefers-reduced-motion, assim como a seta do link deixa de se mover no mouse.
• Se o número mudar enquanto a pessoa está na tela, avise com uma região aria-live na tela, não no cartão.
• No modo de alto contraste do Windows, o traço de alerta e as divisórias da faixa continuam visíveis.
• Os tokens trocam sozinhos no tema escuro ([data-theme="dark"]).
• Um valueLabel vazio ou só com espaços é ignorado: o leitor de tela lê o valor que está na tela.
• Testado com axe no padrão, com unidade e valueLabel, com valueLabel em branco, com valor vazio, com variação boa, ruim e zero, nos dois alertas, no warning com ícone de rótulo, com tom desconhecido, com link padrão e próprio, carregando e numa faixa de cartões.