Tipografia

text() desenha um pedaço de texto num dos tamanhos da biblioteca. A variante escolhe um elemento sensato — variant: 'h2' desenha um <h2> a sério — por isso os cabeçalhos entram no esquema do documento sem ninguém ter de pensar nisso.

Variantes

Cabeçalho 1

Cabeçalho 2

Cabeçalho 3

Cabeçalho 4

Cabeçalho 5

Cabeçalho 6

Lead — um degrau acima do corpo de texto, para a frase sob um título.

Body — a predefinição.

Small — legendas que ainda são frases.

Caption — as letras miudinhas.Overline

stack({ gap: 'sm' },
  text({ variant: 'h1' }, 'Cabeçalho 1'),
  text({ variant: 'h2' }, 'Cabeçalho 2'),
  text({ variant: 'h3' }, 'Cabeçalho 3'),
  text({ variant: 'h4' }, 'Cabeçalho 4'),
  text({ variant: 'h5' }, 'Cabeçalho 5'),
  text({ variant: 'h6' }, 'Cabeçalho 6'),
  text({ variant: 'lead' }, 'Lead — um degrau acima do corpo de texto, para a frase sob um título.'),
  text({ variant: 'body' }, 'Body — a predefinição.'),
  text({ variant: 'small' }, 'Small — legendas que ainda são frases.'),
  text({ variant: 'caption' }, 'Caption — as letras miudinhas.'),
  text({ variant: 'overline' }, 'Overline'),
)

Cabeçalhos

heading() recebe um level de esquema e dimensiona-se em conformidade. O size separa os dois: um <h1> com ar de h3 continua a ser um h1 para um leitor de ecrã.

Um cabeçalho de nível 2, dimensionado a condizer

Um cabeçalho de nível 2, dimensionado como um h5

stack({ gap: 'sm' },
  heading({ level: 2 }, 'Um cabeçalho de nível 2, dimensionado a condizer'),
  heading({ level: 2, size: 'h5' }, 'Um cabeçalho de nível 2, dimensionado como um h5'),
)

Tom

Três graus de ênfase, do contraste cheio ao cinzento legível mais discreto.

Predefinição — a cor em que o corpo de texto é composto.

Esbatido — texto secundário, ainda confortável de ler.

Discreto — etiquetas e metadados.

stack({ gap: 'xs' },
  text('Predefinição — a cor em que o corpo de texto é composto.'),
  text({ tone: 'muted' }, 'Esbatido — texto secundário, ainda confortável de ler.'),
  text({ tone: 'subtle' }, 'Discreto — etiquetas e metadados.'),
)

Alinhamento

Início

Centro

Fim

stack({ gap: 'xs' },
  text({ align: 'start' }, 'Início'),
  text({ align: 'center' }, 'Centro'),
  text({ align: 'end' }, 'Fim'),
)

Truncar e limitar linhas

truncate corta uma única linha com reticências. O lines limita antes a um número de linhas, que é o que o resumo de um cartão costuma querer.

Uma única linha que continua muito para lá da largura do seu contentor e acaba cortada com reticências em vez de mudar de linha.

Limitado a duas linhas. Este parágrafo estende-se por um bocado para que o limite tenha mesmo algo que cortar, e depois continua mais um pouco, para lá do ponto onde a terceira linha teria começado.

stack({ gap: 'md' },
  card({ variant: 'flat' }, cardBody(
    text({ truncate: true }, 'Uma única linha que continua muito para lá da largura do seu contentor e acaba cortada com reticências em vez de mudar de linha.'),
  )),
  card({ variant: 'flat' }, cardBody(
    text({ lines: 2, tone: 'muted' }, 'Limitado a duas linhas. Este parágrafo estende-se por um bocado para que o limite tenha mesmo algo que cortar, e depois continua mais um pouco, para lá do ponto onde a terceira linha teria começado.'),
  )),
)

Código inline e teclas

Corre sitelo build ou carrega em ⌘ K para pesquisar.

text(
  'Corre ', code('sitelo build'), ' ou carrega em ', kbd('⌘'), ' ', kbd('K'), ' para pesquisar.',
)

Os filhos são renderizados como HTML — é isso que faz o aninhamento funcionar em toda a biblioteca, e o code() não é exceção. Por isso um exemplo com etiquetas precisa da prop text, que as escapa:

<em>Olá</em> — text: mostrado tal como escrito

Olá — filhos: interpretados como marcação

stack({ gap: 'sm' },
  text(code({ text: '<em>Olá</em>' }), ' — text: mostrado tal como escrito'),
  text(code('<em>Olá</em>'), ' — filhos: interpretados como marcação'),
)

Ambos servem. O text é para um exemplo de código, onde uma etiqueta deve ser lida e não construída. Os filhos são para saída já com realce de sintaxe, onde a marcação é o objetivo — um resultado do Prism ou do Shiki entra diretamente.

sitelo build --root docs

sitelo build

stack({ gap: 'sm' },
  text(code({ text: 'sitelo build --root docs' })),
  text(code('<span style="color: var(--su-primary-soft-fg)">sitelo</span> build')),
)

Compor

O text aceita filhos, e não apenas uma cadeia — por isso ligações, código e ênfase aninham-se lá dentro tal como fariam em HTML.

As páginas são funções que devolvem HTML. Vê o guia de escrever páginas.

text({ variant: 'lead' },
  'As páginas são funções que devolvem ',
  code('HTML'),
  '. Vê o guia de ',
  link({ href: '/pt/docs/pages' }, 'escrever páginas'),
  '.',
)

Mudar o elemento

O as substitui o elemento sem mudar o aspeto — para um cabeçalho visual que não deve aparecer no esquema, ou um <span> no meio de uma linha de texto.

Parece um cabeçalho, é um div

Estilo de caption num parágrafo

stack({ gap: 'xs' },
  text({ variant: 'h4', as: 'div' }, 'Parece um cabeçalho, é um div'),
  text({ variant: 'caption', as: 'p' }, 'Estilo de caption num parágrafo'),
)

Escondido visualmente

visuallyHidden() mantém o conteúdo na árvore de acessibilidade mas fora do ecrã — a etiqueta de que um leitor de ecrã precisa, ali onde os leitores que veem a tiram do contexto.

Estado da construção: a passar — a última construção teve sucesso há 4 minutos

text(
  'Estado da construção: ',
  chip({ color: 'success', dot: true }, 'a passar'),
  visuallyHidden(' — a última construção teve sucesso há 4 minutos'),
)

Props

Prop	Tipo	Predefinição	Descrição
`variant`	`'h1'…'h6' \| 'lead' \| 'body' \| 'small' \| 'caption' \| 'overline'`	`'body'`	Tamanho, peso e elemento predefinido.
`tone`	`'default' \| 'muted' \| 'subtle'`	`'default'`	Quanto contraste o texto carrega.
`align`	`'start' \| 'center' \| 'end'`	`'start'`	Alinhamento do texto.
`truncate`	`boolean`	`false`	Uma linha, cortada com reticências.
`lines`	`number`	—	Limitar a este número de linhas.
`as`	`string`	—	Substitui o elemento que a variante escolheria.

O heading() recebe level (1–6) e um size opcional; tudo o resto é igual.