# SectionTitle

> Componentes / Conteúdo · Estado: **Em andamento** — Implementado e utilizável, mas ainda sem a validação completa de acessibilidade.

Título de seção com chapéu opcional (em vermelho, caixa alta), o título (`h2` por padrão, `tituloComo` escolhe) e uma descrição, alinhados à esquerda, ao centro ou à direita — com versão para fundo escuro.

- Função: Conteúdo
- Também chamado de: título de seção, cabeçalho de seção, chapéu
- Mora em: `app/components/molecules/SectionTitle.tsx`
- Página: [https://phorte-design-system.vercel.app/styleguide/peca/SectionTitle](https://phorte-design-system.vercel.app/styleguide/peca/SectionTitle)
- Ficha no Storybook: [components-complex-sectiontitle](https://main--69b4847d498a9bd8659db9ba.chromatic.com/?path=/docs/components-complex-sectiontitle--docs)
- Prévia ao vivo, sozinha: [https://phorte-design-system.vercel.app/previa/SectionTitle/0](https://phorte-design-system.vercel.app/previa/SectionTitle/0)
- Todas as peças: [https://phorte-design-system.vercel.app/llms.txt](https://phorte-design-system.vercel.app/llms.txt)

## Como usar no código

```tsx
import { SectionTitle } from '@/app/components/molecules/SectionTitle';

<SectionTitle title={…}>…</SectionTitle>
```

O `…` marca as props obrigatórias — ver *Propriedades*.

## Uso

### Variantes na ficha

1. [Padrão](https://phorte-design-system.vercel.app/previa/SectionTitle/0)
2. [Centralizado](https://phorte-design-system.vercel.app/previa/SectionTitle/1)
3. [Só título](https://phorte-design-system.vercel.app/previa/SectionTitle/2)
4. [Texto Longo](https://phorte-design-system.vercel.app/previa/SectionTitle/3)
5. [Sobre Fundo Escuro](https://phorte-design-system.vercel.app/previa/SectionTitle/4)

No começo de cada seção de uma página — "Os Cursos", "Depoimentos", "Dúvidas Frequentes".

### Quando não usar

Para um título solto sem chapéu nem descrição, a Typography basta. Para o título da página (`h1`), a Typography com `variant="h1"`.

### Faça

- Use o chapéu para a categoria ("Pós-Graduação") e o título para a promessa.
- Use `superficie="escura"` sobre fundo escuro (E72; o antigo `titleColor="white"` é apelido por um ciclo): chapéu, título e descrição nos tokens inversos.
- Acerte o nível com `tituloComo`: `h1` quando é o título da página, `h3` numa subseção (E72).
- Nomeie a seção pelo título: `idDoTitulo={id}` aqui e `aria-labelledby={id}` na `<section>` em volta, com o `id` do `useId()` (E76). Só o título — chapéu e descrição ficam de fora do nome.
- Centralize só em seção centrada — texto longo centrado cansa.

### Evite

- Chapéu vermelho sobre fundo escuro: media 3,46:1 — por isso, com `superficie="escura"`, ele muda sozinho.
- Deixar o `h2` padrão numa subseção de outra seção `h2`: acerte o `tituloComo`.

### Anatomia

1. **Chapéu** — `subtitle`: `tiny` (12px, caixa alta), vermelho; branco sobre escuro.
2. **Chapéu e título** — Num `<hgroup>` (E72): o chapéu é um `<p>` e o título, o `tituloComo` (padrão `h2`), até `max-w-3xl`.
3. **Descrição** — `description`: parágrafo cinza (`--ink-inverse-muted` sobre escuro, E72 — era branco a 80% de opacidade), até `max-w-2xl`.

### Estados

| Estado | O que muda |
| --- | --- |
| Sobre claro | Chapéu `--primary`, título `--ink`, descrição `--muted-foreground`. |
| Sobre escuro | `superficie="escura"`: chapéu e título `--ink-inverse`, descrição `--ink-inverse-muted`. |
| Alinhamento | `left` (padrão), `center` ou `right`. |

### Comportamento

| Situação | O que acontece |
| --- | --- |
| Sem `subtitle` ou `description` | A parte simplesmente não aparece. |

### Relacionados

- [Typography](https://phorte-design-system.vercel.app/styleguide/md/Typography.md) — O texto que ele monta.
- [FAQ](https://phorte-design-system.vercel.app/styleguide/md/FAQ.md) — Uma seção que abre com ele.

## Especificação

### Propriedades

| Prop | Tipo | Padrão | Obrigatória | Descrição |
| --- | --- | --- | --- | --- |
| `subtitle` | `string` | — | não |  |
| `title` | `string` | — | sim |  |
| `description` | `string` | — | não |  |
| `align` | `'left' \| 'center' \| 'right'` | `'left'` | não |  |
| `superficie` | `'clara' \| 'escura'` | — | não | Sobre que superfície o título está (E72): `escura` usa os tokens inversos. Nomeado pela superfície, e não pela cor, para o tema escuro da Fase 2 não pedir outra troca de API. |
| `titleColor` | `'default' \| 'white'` | — | não | @deprecated Use `superficie` (E72). `'white'` = `superficie="escura"`; fica por um ciclo. |
| `tituloComo` | `ElementType` | `'h2'` | não | O elemento do título (E72). Padrão `h2`. Use `h1` quando o SectionTitle é o título da página, e `h3` numa subseção — a lista de títulos do leitor de tela depende disso. |
| `idDoTitulo` | `string` | — | não | `id` do título (E76), para a seção em volta se nomear por ele: `<section aria-labelledby={id}>`. Só o título — com chapéu e descrição, o nome da região ficaria uma frase. |

Aceita também: `React.HTMLAttributes<HTMLElement>`.

### Tokens de cor

| Token | Valor | Usado como |
| --- | --- | --- |
| `--ink-inverse-muted` | #C7C7C7 | `text-ink-inverse-muted` |

## Acessibilidade

### Leitor de tela

- O título é o `tituloComo` (padrão `<h2>`); chapéu e título ficam num `<hgroup>`, com o chapéu em `<p>` — quem pula de título em título encontra o grupo junto (E72, conferido no teste da ficha).

### O que sustenta o estado

Usa os padrões: estatico. Falta ouvir com leitor de tela: estatico.

## Status e recursos

| Tipo | Recurso | Status |
| --- | --- | --- |
| Código | `app/components/molecules/SectionTitle.tsx` | Disponível |
| Ficha | https://main--69b4847d498a9bd8659db9ba.chromatic.com/?path=/docs/components-complex-sectiontitle--docs | Disponível |
| Teste de acessibilidade | axe em `npm run test` | No gate de todo commit |
| Leitor de tela | Passada da E33 | Falta ouvir |
| Design | Figma | Desativado até a Fase 2 |

### Histórico

- `fdd10ff` 2026-09-29 — ESTADO: E109 concluida, roteiro final fechado; proximo o merge na main
- Histórico completo no GitHub: https://github.com/srbunnie/Pos-Phorte-Design-System/commits/main/app/components/molecules/SectionTitle.tsx