# Texto com gradiente em CSS, bem feito

[Canonical HTML page](https://gradiently.design/pt-pt/guide/css-gradient-text)

Três linhas de CSS põem um gradiente dentro das tuas letras. Torná-lo legível, robusto e de bom gosto exige mais algumas, e saber quando deixar o texto liso.

## The short version

- O texto com gradiente em CSS funciona pintando um gradiente como fundo do elemento, recortando-o à forma das letras com background-clip: text e tornando a cor do texto transparente.
- Define sempre primeiro uma cor de texto lisa e aplica a cor transparente só dentro de uma verificação @supports, para que as palavras nunca desapareçam.
- Cada parte do gradiente precisa de contraste suficiente com o fundo, por isso verifica as paragens mais clara e mais escura e não só uma.
- O texto com gradiente serve linhas curtas de destaque em tamanhos grandes e funciona mal em texto corrente, ligações e etiquetas pequenas.
- Acrescentar box-decoration-break: clone dá a cada linha de um elemento em linha que quebra o seu próprio gradiente completo.

O **texto com gradiente** em CSS faz-se pintando um gradiente como fundo do elemento de texto, recortando esse fundo às formas das letras com `background-clip: text` e tornando o próprio texto transparente para que o gradiente apareça. Bastam três declarações, funciona em todos os navegadores atuais e continua a ser texto real, selecionável e pesquisável, e não uma imagem.

```css
.gradient-text {
  background-image: linear-gradient(90deg, #6d28d9, #be185d);
  -webkit-background-clip: text;
  background-clip: text;
  color: transparent;
}
```

A técnica base. A linha com prefixo mantém contentes as versões mais antigas do Safari e do Chromium.

Violeta a rosa, para páginas claras: `linear-gradient(90deg, #6d28d9, #be185d)`

O gradiente dentro dessas letras. As duas pontas são escuras o suficiente para se lerem sobre branco.

O resto deste guia trata do que a versão de três linhas faz mal: falta de alternativas, contraste, texto em várias linhas, descendentes cortados e a questão de design de quando o texto com gradiente ajuda sequer. Para o aspeto das letras com gradiente em redes sociais e trabalho de marca, e não na web, vê os [efeitos de texto](https://gradiently.design/pt-pt/guide/text-effects).

## Uma receita robusta de texto com gradiente com alternativas

Se um navegador aplicar o `color: transparent` mas não o recorte, o texto desaparece. Protege-te: dá ao elemento uma cor lisa tirada do gradiente e passa depois à versão transparente só quando o navegador confirmar o suporte. Acrescenta uma reposição para o modo de cores forçadas, em que o sistema substitui as tuas cores e o texto tem de continuar visível.

```css
.gradient-text {
  color: #6d28d9; /* solid fallback from the gradient */
}

@supports (background-clip: text) or (-webkit-background-clip: text) {
  .gradient-text {
    background-image: linear-gradient(90deg, #6d28d9, #be185d);
    -webkit-background-clip: text;
    background-clip: text;
    color: transparent;
  }
}

@media (forced-colors: active) {
  .gradient-text {
    background: none;
    color: CanvasText;
  }
}
```

Primeiro a cor lisa, o gradiente só onde há suporte e uma cor do sistema quando o utilizador força as suas.

A [página da MDN sobre background-clip](https://developer.mozilla.org/en-US/docs/Web/CSS/background-clip) documenta o valor `text` e o seu suporte atual.

## Contraste: verifica as duas pontas do gradiente

Um verificador de contraste recebe uma só cor de texto, mas o texto com gradiente tem muitas. As palavras só são tão legíveis como a sua parte mais fraca, por isso verifica a paragem mais clara e a mais escura contra o fundo, e olha também para o meio, porque uma mistura sRGB pode ficar mais clara ou mais baça do que qualquer das pontas. Para texto de destaque grande, as WCAG pedem pelo menos 3:1; para texto normal, 4,5:1. O guia sobre [contraste de cor](https://gradiently.design/pt-pt/guide/color-contrast-accessibility) explica os rácios.

- Sobre branco: violeta a rosa: `linear-gradient(90deg, #6d28d9, #be185d)`
- Sobre branco: oceano a verde-azulado: `linear-gradient(90deg, #0369a1, #0f766e)`
- Sobre branco: brasa a rosa: `linear-gradient(90deg, #c2410c, #be185d)`
- Sobre quase preto: lilás a rosa: `linear-gradient(90deg, #a78bfa, #f472b6)`
- Sobre quase preto: ciano a limão: `linear-gradient(90deg, #67e8f9, #fde047)`

Gradientes de texto cujas paragens passam todas 5:1 no fundo indicado. Sobre branco, cada paragem mede mais de 5:1; sobre #0b0b12, mais de 7:1.

> **A falha comum** Um gradiente que esbate para uma cor pálida, como violeta a rosa-claro sobre branco, deixa o fim de cada palavra quase invisível. Mantém as duas pontas com uma luminosidade parecida e segura e deixa o matiz fazer a mudança.

## Corrigir texto com gradiente em várias linhas e letras cortadas

Num elemento em linha que quebra, o navegador estende um só fundo por todas as linhas como se fossem uma única tira, por isso a primeira linha fica com o início do gradiente e a última com o fim. Normalmente queres que cada linha leve o gradiente completo. O `box-decoration-break: clone` faz isso. Nos elementos de bloco, como um título, o gradiente já se estende por toda a caixa, por isso um gradiente longo num título largo pode mostrar só o meio nas linhas curtas.

```css
.gradient-text {
  -webkit-box-decoration-break: clone;
  box-decoration-break: clone;
  /* stop descenders being cut off */
  line-height: 1.15;
  padding-block-end: 0.08em;
}
```

Cada linha recebe o seu próprio gradiente completo, e as caudas do g, j, p e y ficam dentro da área pintada.

Os descendentes cortados são a outra surpresa. O fundo só pinta a caixa do elemento, por isso com um `line-height` muito justo, as partes das letras que pendem por baixo ficam transparentes e desaparecem. Uma altura de linha de cerca de 1,1 ou um pouco de preenchimento em baixo resolve. Os tipos de letra de destaque em itálico podem perder a ponta da última letra à direita pela mesma razão; um toque de preenchimento em linha ajuda.

## Quando o texto com gradiente funciona e quando não

### Evita

- Texto corrente, em que a mudança de cor atrasa a leitura
- Ligações e botões, em que a cor sinaliza o estado
- Etiquetas pequenas abaixo de cerca de 24px, em que o gradiente é invisível de qualquer forma
- Gradientes arco-íris com cinco ou mais matizes
- Texto com gradiente sobre um fundo com gradiente

### Usa-o para

- Uma palavra ou frase curta num título grande
- O nome de um produto ou marca num herói
- Números grandes num bloco de estatísticas
- Dois ou três matizes relacionados com luminosidade parecida
- Fundos simples e calmos que deixam as letras liderar

Uma boa regra: o texto com gradiente é um destaque, como o itálico. Uma palavra realçada num título chama o olhar; um parágrafo inteiro cansa-o. Os pesos fortes ajudam, porque os traços finos não mostram cor suficiente para se lerem como um gradiente. Se o resto da página já usa fundos em gradiente, a tipografia lisa costuma ser a escolha mais forte; o guia sobre [texto sobre fundos em gradiente](https://gradiently.design/pt-pt/guide/text-on-gradient) trata desse caso.

## Animar texto com gradiente

Para fazer a cor fluir pelas letras, faz o fundo maior do que o texto e move-o. Dá-lhe 200% de largura e anima o `background-position` para trás e para a frente com `alternate`, para nunca haver um salto quando o ciclo recomeça. Respeita as definições de [movimento reduzido](https://gradiently.design/pt-pt/guide/reduced-motion) e mantém-no lento: um brilho a cada poucos segundos lê-se como acabamento, um ciclo rápido lê-se como um aviso.

```css
.gradient-text--flow {
  background-image: linear-gradient(90deg, #6d28d9, #be185d, #c2410c);
  background-size: 200% 100%;
  animation: flow 6s ease-in-out infinite alternate;
}

@keyframes flow {
  from { background-position: 0% 50%; }
  to   { background-position: 100% 50%; }
}

@media (prefers-reduced-motion: reduce) {
  .gradient-text--flow { animation: none; }
}
```

A cor a derivar para trás e para a frente pelas palavras. Combina-a com o recorte e a alternativa da receita acima.

Os mesmos truques de fundo alimentam os [gradientes animados em CSS](https://gradiently.design/pt-pt/guide/css-animated-gradient) de forma mais geral, e os contornos com gradiente em vez de preenchimentos são tratados nas [bordas com gradiente em CSS](https://gradiently.design/pt-pt/guide/css-gradient-border).

## FAQ

### Como faço texto com gradiente em CSS?

Define um gradiente como `background-image`, acrescenta `-webkit-background-clip: text` e `background-clip: text` e define `color: transparent`. Põe uma cor lisa fora de uma verificação `@supports` como alternativa.

### Porque é que o meu texto com gradiente está invisível?

O texto é transparente mas o fundo não está a ser recortado, normalmente porque a declaração de recorte falta, está mal escrita ou não é suportada. Aplica o `color: transparent` só dentro de `@supports (background-clip: text)`.

### O texto com gradiente é acessível?

Pode ser, se cada parte do gradiente tiver contraste suficiente com o fundo e o texto continuar a ser texto real. Verifica as paragens mais clara e mais escura e repõe as cores no modo de cores forçadas.

### Porque é que as partes de baixo das minhas letras estão cortadas?

O fundo recortado só cobre a caixa do elemento, por isso uma altura de linha justa deixa os descendentes fora dela. Aumenta a altura de linha para cerca de 1,1 ou acrescenta um pouco de preenchimento em baixo.

### Posso usar texto com gradiente em emails?

O suporte para `background-clip: text` é irregular nos clientes de email, por isso usa aí uma cor lisa ou uma imagem com texto alternativo. Vê os [gradientes em email](https://gradiently.design/pt-pt/guide/gradients-in-email).