pswex-design-system 7.0.0

package/skill/references/componentes.md

@@ -0,0 +1,628 @@
+# Componentes
+
+36 no total, todos em `window.PSWEX`.
+O tipo completo de cada um está em `componentes/tipos/<Nome>.d.ts`.
+
+### Fundamentos
+
+#### EscalaTipografica
+
+Gilroy em cinco pesos, escala em clamp, sem breakpoint.
+
+| Prop | Tipo | Obrigatória | O que faz |
+|---|---|---|---|
+| `className` | `string` | não |  |
+
+```jsx
+<EscalaTipografica />
+```
+
+#### Icone
+
+Catálogo de 72 ícones de traço: um para cada um dos 14 serviços, um para cada uma das 12 campanhas, e 20 de interface. Os que terminam em `-compact` são a versão simplificada, para 20px ou menos.
+
+| Prop | Tipo | Obrigatória | O que faz |
+|---|---|---|---|
+| `nome` | um dos 72 nomes do catálogo, lista na seção Ícones | sim | Nome do ícone no catálogo. O sufixo `-compact` é a versão simplificada, para 20px ou menos. |
+| `tamanho` | `number` | não | Lado do quadrado, em px. O traço não engrossa junto, por isso 24 é o tamanho de desenho. |
+| `titulo` | `string` | não | Rótulo para leitor de tela. Sem ele o ícone é tratado como decoração. |
+| `className` | `string` | não |  |
+| `id` | `string` | não |  |
+| `style` | `React.CSSProperties` | não |  |
+
+```jsx
+<Icone nome="agentes-ia" tamanho={26} />
+<Icone nome="whatsapp-chat" tamanho={18} titulo="Falar no WhatsApp" />
+```
+
+#### PaletaMarca
+
+As dez cores da identidade, iguais nos dois temas.
+
+| Prop | Tipo | Obrigatória | O que faz |
+|---|---|---|---|
+| `className` | `string` | não |  |
+
+```jsx
+<PaletaMarca />
+```
+
+#### PaletaSemantica
+
+Os tokens de papel na tela, que invertem no tema escuro.
+
+| Prop | Tipo | Obrigatória | O que faz |
+|---|---|---|---|
+| `className` | `string` | não |  |
+
+```jsx
+<PaletaSemantica />
+```
+
+### Componentes
+
+#### Btn
+
+Botão pílula em três variantes.
+
+| Prop | Tipo | Obrigatória | O que faz |
+|---|---|---|---|
+| `variante` | `"cta" \| "red" \| "ghost"` | não | `cta` é o lime, usado para conversão e só uma vez por tela. `red` é o vermelho da marca. `ghost` é contorno, para ação secundária. |
+| `href` | `string` | não | Destino do link. O componente renderiza um `<a>`, então href é o que torna o botão clicável. |
+| `target` | `string` | não |  |
+| `rel` | `string` | não |  |
+| `children` | `React.ReactNode` | não |  |
+| `className` | `string` | não |  |
+| `id` | `string` | não |  |
+| `style` | `React.CSSProperties` | não |  |
+
+```jsx
+<Btn variante="cta" href="#contato">Falar no WhatsApp</Btn>
+<Btn variante="ghost" href="/projetos">Ver projetos</Btn>
+```
+
+#### Card
+
+Card de conteúdo com eyebrow, título, apoio e link.
+
+| Prop | Tipo | Obrigatória | O que faz |
+|---|---|---|---|
+| `icone` | um dos 72 nomes do catálogo, lista na seção Ícones | não | Ícone do catálogo, acima do eyebrow. É o que tira o card de ser só texto. Ver Icone para a lista. |
+| `eyebrow` | `React.ReactNode` | não |  |
+| `titulo` | `React.ReactNode` | sim |  |
+| `texto` | `React.ReactNode` | não | Texto de apoio do card. |
+| `href` | `string` | não | Quando existe, o card inteiro vira link e ganha o hover de elevação. |
+| `linkTexto` | `React.ReactNode` | não | Rótulo do link de texto no pé do card. |
+| `className` | `string` | não |  |
+
+```jsx
+<Card
+  eyebrow="Serviço"
+  titulo="Agentes de IA"
+  texto="Atendimento que responde na hora e não deixa lead esfriar."
+  href="/agentes-de-ia"
+  linkTexto="Ver como funciona"
+/>
+```
+
+#### Cards
+
+Grade fluida de cards, 2, 3 ou 4 colunas.
+
+| Prop | Tipo | Obrigatória | O que faz |
+|---|---|---|---|
+| `colunas` | `2 \| 3 \| 4` | não | Número de colunas alvo. A grade é fluida e quebra sozinha no mobile. |
+| `children` | `React.ReactNode` | não |  |
+| `className` | `string` | não |  |
+| `id` | `string` | não |  |
+| `style` | `React.CSSProperties` | não |  |
+
+```jsx
+<Cards colunas={3}>
+  <Card titulo="Sites" texto="Página que carrega rápido e converte." />
+</Cards>
+```
+
+#### Caso
+
+Card de caso com tag de categoria.
+
+| Prop | Tipo | Obrigatória | O que faz |
+|---|---|---|---|
+| `icone` | um dos 72 nomes do catálogo, lista na seção Ícones | não | Ícone do catálogo, acima da tag. Ver Icone para a lista. |
+| `tag` | `React.ReactNode` | não | Rótulo do setor ou do tipo de trabalho. |
+| `titulo` | `React.ReactNode` | sim |  |
+| `texto` | `React.ReactNode` | não |  |
+| `className` | `string` | não |  |
+
+```jsx
+<Caso tag="Autoescola" titulo="Clube Líder" texto="O que era feito à mão virou fila automática." />
+```
+
+#### Eyebrow
+
+Rótulo curto em caixa alta acima do título.
+
+| Prop | Tipo | Obrigatória | O que faz |
+|---|---|---|---|
+| `children` | `React.ReactNode` | não |  |
+| `className` | `string` | não |  |
+| `id` | `string` | não |  |
+| `style` | `React.CSSProperties` | não |  |
+
+```jsx
+<Eyebrow>Belo Horizonte</Eyebrow>
+```
+
+#### Faq
+
+Item de FAQ em details.
+
+| Prop | Tipo | Obrigatória | O que faz |
+|---|---|---|---|
+| `pergunta` | `React.ReactNode` | sim |  |
+| `children` | `React.ReactNode` | não |  |
+| `aberto` | `boolean` | não | Deixa o item aberto no primeiro render. |
+| `className` | `string` | não |  |
+
+```jsx
+<Faq pergunta="Em quanto tempo fica pronto?">Depende do escopo. A proposta traz o prazo fechado.</Faq>
+```
+
+#### Field
+
+Campo de formulário com label, controle e linha de erro.
+
+| Prop | Tipo | Obrigatória | O que faz |
+|---|---|---|---|
+| `label` | `React.ReactNode` | sim | Texto da label. |
+| `nota` | `React.ReactNode` | não | Complemento da label, em peso leve. Serve para "opcional". |
+| `nome` | `string` | sim | `id` e `name` do controle. |
+| `tipo` | `unknown` | não |  |
+| `placeholder` | `string` | não |  |
+| `erro` | `React.ReactNode` | não | Mensagem de erro abaixo do campo. |
+| `className` | `string` | não |  |
+
+```jsx
+<Field nome="whatsapp" label="WhatsApp" tipo="tel" placeholder="(31) 99999-9999" />
+```
+
+#### Lead
+
+Parágrafo de abertura, maior que o corpo.
+
+| Prop | Tipo | Obrigatória | O que faz |
+|---|---|---|---|
+| `children` | `React.ReactNode` | não |  |
+| `className` | `string` | não |  |
+| `id` | `string` | não |  |
+| `style` | `React.CSSProperties` | não |  |
+
+```jsx
+<Lead>Seu time faz o trabalho. O processo faz o trabalho voltar.</Lead>
+```
+
+#### PillList
+
+Pílulas de navegação secundária.
+
+| Prop | Tipo | Obrigatória | O que faz |
+|---|---|---|---|
+| `itens` | `{ rotulo: React.ReactNode; href: string; }[]` | sim | Cada item vira uma pílula clicável. |
+| `className` | `string` | não |  |
+
+```jsx
+<PillList itens={[{rotulo:'Sites', href:'/sites'}, {rotulo:'Lojas virtuais', href:'/lojas'}]} />
+```
+
+#### Quote
+
+Depoimento com régua vermelha e atribuição.
+
+| Prop | Tipo | Obrigatória | O que faz |
+|---|---|---|---|
+| `children` | `React.ReactNode` | não | A citação. |
+| `autor` | `React.ReactNode` | não | Quem falou, e de onde. |
+| `className` | `string` | não |  |
+
+```jsx
+<Quote autor="Michele, clínica">
+  Resolveu a agenda que vivia dando choque de horário.
+</Quote>
+```
+
+#### Quotes
+
+Grade fluida de depoimentos.
+
+| Prop | Tipo | Obrigatória | O que faz |
+|---|---|---|---|
+| `children` | `React.ReactNode` | não |  |
+| `className` | `string` | não |  |
+| `id` | `string` | não |  |
+| `style` | `React.CSSProperties` | não |  |
+
+```jsx
+<Quotes><Quote autor="Bruno, climatização">Chegou lead no mesmo dia.</Quote></Quotes>
+```
+
+#### Ratingbar
+
+Faixa fina logo abaixo do hero, no navy mais escuro, com frases curtas de contexto.
+
+| Prop | Tipo | Obrigatória | O que faz |
+|---|---|---|---|
+| `estrelas` | `React.ReactNode` | não | Estrelas em texto. Vazio por padrão: nota de avaliação só entra com fonte conferida. |
+| `destaque` | `React.ReactNode` | não | Trecho em negrito logo depois das estrelas. |
+| `itens` | `React.ReactNode[]` | não | Frases curtas ao lado, separadas pelo próprio flex. |
+| `className` | `string` | não |  |
+
+```jsx
+<Ratingbar itens={["Mais de 10 anos fazendo tecnologia que vende", "Belo Horizonte, atendendo o Brasil inteiro"]} />
+```
+
+#### Reveal
+
+Envelope de entrada: o conteúdo sobe 14px e aparece quando ganha a classe `in`.
+
+| Prop | Tipo | Obrigatória | O que faz |
+|---|---|---|---|
+| `visivel` | `boolean` | não | `true` já entra visível, que é o que o script do site faz ao cruzar a viewport. |
+| `children` | `React.ReactNode` | não |  |
+| `className` | `string` | não |  |
+| `id` | `string` | não |  |
+| `style` | `React.CSSProperties` | não |  |
+
+```jsx
+<Reveal visivel>
+  <SecHead titulo="Onde a gente já entregou" />
+</Reveal>
+```
+
+#### Row2
+
+Duas colunas dentro do formulário.
+
+| Prop | Tipo | Obrigatória | O que faz |
+|---|---|---|---|
+| `children` | `React.ReactNode` | não |  |
+| `className` | `string` | não |  |
+| `id` | `string` | não |  |
+| `style` | `React.CSSProperties` | não |  |
+
+```jsx
+<Row2><Field nome="nome" label="Nome" /><Field nome="email" label="E-mail" tipo="email" /></Row2>
+```
+
+#### SecHead
+
+Eyebrow, h2 e apoio, o cabeçalho de toda seção.
+
+| Prop | Tipo | Obrigatória | O que faz |
+|---|---|---|---|
+| `eyebrow` | `React.ReactNode` | não | Rótulo em caixa alta acima do título. |
+| `titulo` | `React.ReactNode` | sim | Título da seção, sai como h2. |
+| `apoio` | `React.ReactNode` | não | Linha de apoio abaixo do título. |
+| `className` | `string` | não |  |
+
+```jsx
+<SecHead
+  eyebrow="Projetos"
+  titulo="Onde a gente já entregou"
+  apoio="Cliente com nome, setor e o que foi feito."
+/>
+```
+
+#### Selos
+
+Pílulas de contorno para credencial e localização.
+
+| Prop | Tipo | Obrigatória | O que faz |
+|---|---|---|---|
+| `itens` | `React.ReactNode[]` | sim | Credencial, localização, CNPJ, o que for verificável. |
+| `className` | `string` | não |  |
+
+```jsx
+<Selos itens={['Belo Horizonte', 'CNPJ 28.477.119/0001-79', 'Google Ads AI']} />
+```
+
+#### SkipLink
+
+Atalho de teclado para pular a navegação e cair no conteúdo.
+
+| Prop | Tipo | Obrigatória | O que faz |
+|---|---|---|---|
+| `children` | `React.ReactNode` | não |  |
+| `className` | `string` | não |  |
+| `id` | `string` | não |  |
+| `style` | `React.CSSProperties` | não |  |
+
+```jsx
+<SkipLink href="#conteudo">Ir para o conteúdo</SkipLink>
+```
+
+#### StepsList
+
+Método numerado, com a numeração vinda do CSS.
+
+| Prop | Tipo | Obrigatória | O que faz |
+|---|---|---|---|
+| `passos` | `PassoProps[]` | sim |  |
+| `className` | `string` | não |  |
+
+```jsx
+<StepsList passos={[
+  {titulo:'Elimina', texto:'O que não precisa existir sai.'},
+  {titulo:'Simplifica', texto:'O que sobra fica com menos passo.'},
+]} />
+```
+
+#### Ticks
+
+Lista de checagem com marcador redondo.
+
+| Prop | Tipo | Obrigatória | O que faz |
+|---|---|---|---|
+| `itens` | `React.ReactNode[]` | sim | Itens da lista. |
+| `positivo` | `boolean` | não | `false` troca o marcador para o X em fundo rosa claro. |
+| `className` | `string` | não |  |
+
+```jsx
+<Ticks itens={['Hospedagem inclusa', 'Open Graph em todas as páginas']} />
+```
+
+#### TxtLink
+
+Link de texto com sublinhado no hover.
+
+| Prop | Tipo | Obrigatória | O que faz |
+|---|---|---|---|
+| `href` | `string` | não | Destino do link. O componente renderiza um `<a>`. |
+| `target` | `string` | não |  |
+| `rel` | `string` | não |  |
+| `children` | `React.ReactNode` | não |  |
+| `className` | `string` | não |  |
+| `id` | `string` | não |  |
+| `style` | `React.CSSProperties` | não |  |
+
+```jsx
+<TxtLink href="/servicos">Ver todos os serviços</TxtLink>
+```
+
+#### Vid
+
+Depoimento em vídeo em proporção 16 por 10, com o nome de quem fala sobreposto embaixo.
+
+| Prop | Tipo | Obrigatória | O que faz |
+|---|---|---|---|
+| `src` | `string` | não |  |
+| `placeholder` | `React.ReactNode` | não | Texto mostrado no lugar do player enquanto não existe arquivo de vídeo. |
+| `poster` | `string` | não | Imagem que aparece antes do play. |
+| `legenda` | `React.ReactNode` | não | Nome e contexto de quem fala, sobre um véu escuro no rodapé. |
+| `className` | `string` | não |  |
+
+```jsx
+<Vid src="/depoimentos/bruno.mp4" poster="/depoimentos/bruno.jpg" legenda="Bruno, Climatização" />
+```
+
+### Blocos
+
+#### Footer
+
+Rodapé no navy mais escuro. Coluna da marca com descrição e selos, mais até três colunas de navegação, e a linha legal no pé.
+
+| Prop | Tipo | Obrigatória | O que faz |
+|---|---|---|---|
+| `logo` | `React.ReactNode` | não |  |
+| `descricao` | `React.ReactNode` | não | Parágrafo de posicionamento embaixo do logo. |
+| `selos` | `React.ReactNode` | não | Selos da primeira coluna. Um `Selos` cabe aqui. |
+| `colunas` | `FooterColuna[]` | não |  |
+| `legal` | `React.ReactNode[]` | não | Linha final: razão social, CNPJ, endereço, telefone. |
+| `className` | `string` | não |  |
+
+```jsx
+<Footer
+  logo={<img src="/logo-branco.png" alt="PSWEX" height={28} />}
+  descricao="Nós fazemos seu negócio dar certo."
+  selos={<Selos itens={["Meta Tech Provider", "Google Ads AI"]} />}
+  colunas={[{ titulo: "Serviços", links: [{ href: "/sites", label: "Criação de sites" }] }]}
+  legal={["PSWEX Tecnologia", "CNPJ 28.477.119/0001-79", "(31) 99922-9792"]}
+/>
+```
+
+#### Hero
+
+Dobra de abertura em navy com foto de fundo.
+
+| Prop | Tipo | Obrigatória | O que faz |
+|---|---|---|---|
+| `eyebrow` | `React.ReactNode` | não |  |
+| `titulo` | `React.ReactNode` | sim |  |
+| `apoio` | `React.ReactNode` | não |  |
+| `acoes` | `React.ReactNode` | não | Botões da dobra. Um cta e um ghost é o padrão da casa. |
+| `nota` | `React.ReactNode` | não | Linha pequena abaixo dos botões. |
+| `lado` | `React.ReactNode` | não | Coluna da direita: imagem, vídeo, o que a página pedir. |
+| `fundo` | `"foto" \| "grad" \| "grad-azul" \| "grad-vermelho"` | não | `foto` é o webp de fundo. `grad` é a arte vetorial, que troca sozinha de arquivo em 1400px e em 980px. `grad-azul` e `gr |
+| `className` | `string` | não |  |
+
+```jsx
+<Hero
+  eyebrow="Belo Horizonte, 10 anos"
+  titulo="Nós fazemos seu negócio dar certo"
+  apoio="Seu time faz o trabalho. O processo faz o trabalho voltar. E você paga pelas duas vezes."
+  acoes={<><Btn variante="cta" href="#contato">Falar no WhatsApp</Btn><Btn variante="ghost" href="/projetos">Ver projetos</Btn></>}
+  nota="Resposta no mesmo dia útil."
+/>
+```
+
+#### LeadForm
+
+Formulário de captura em card branco.
+
+| Prop | Tipo | Obrigatória | O que faz |
+|---|---|---|---|
+| `children` | `React.ReactNode` | não |  |
+| `botao` | `React.ReactNode` | não | Texto do botão de envio. |
+| `nota` | `React.ReactNode` | não | Linha de privacidade abaixo do botão. |
+| `className` | `string` | não |  |
+
+```jsx
+<LeadForm botao="Quero falar com a PSWEX" nota="Seus dados ficam com a PSWEX.">
+  <Row2><Field nome="nome" label="Nome" /><Field nome="tel" label="WhatsApp" tipo="tel" /></Row2>
+  <Field nome="empresa" label="Empresa" nota="opcional" />
+</LeadForm>
+```
+
+#### PhoneMock
+
+Aparelho desenhado em CSS com uma conversa dentro. É a coluna direita do hero da home.
+
+| Prop | Tipo | Obrigatória | O que faz |
+|---|---|---|---|
+| `mensagens` | `PhoneMensagem[]` | sim |  |
+| `passos` | `React.ReactNode[]` | não | Pílulas que entram animadas ao lado do aparelho. Abaixo de 1100px empilham. |
+| `className` | `string` | não |  |
+
+```jsx
+<PhoneMock
+  mensagens={[
+    { texto: "Vocês fazem orçamento de quanto?" },
+    { texto: "Depende do que você precisa.", de: "voce" },
+  ]}
+  passos={["Entender o que trava", "Escolher por onde começar"]}
+/>
+```
+
+#### Secao
+
+Seção com padding vertical da escala e Shell embutido.
+
+| Prop | Tipo | Obrigatória | O que faz |
+|---|---|---|---|
+| `fundo` | um dos 10 nomes do catálogo, lista na seção Ícones | não | Fundo da seção. `dark` é o navy da marca. `grad` é a arte vetorial da casa, azul de um lado e vermelho do outro, com a p |
+| `children` | `React.ReactNode` | não |  |
+| `className` | `string` | não |  |
+| `id` | `string` | não |  |
+| `style` | `React.CSSProperties` | não |  |
+
+```jsx
+<Secao fundo="dark">
+  <SecHead eyebrow="Método" titulo="Elimina, simplifica, automatiza" />
+  <StepsList passos={[{titulo:'Elimina', texto:'O que não precisa existir sai.'}]} />
+</Secao>
+```
+
+#### Servicos
+
+Grade de serviço com ícone. É o atalho para não montar `Cards` cheio de `Card` na mão em toda página.
+
+| Prop | Tipo | Obrigatória | O que faz |
+|---|---|---|---|
+| `itens` | um dos 72 nomes do catálogo, lista na seção Ícones | sim | Um item por card. O ícone é obrigatório, que é o ponto do bloco. |
+| `titulo` | `React.ReactNode` | sim |  |
+| `texto` | `React.ReactNode` | não |  |
+| `href` | `string` | não | Quando existe, o card vira link e ganha o rótulo "Ver" no pé. |
+| `colunas` | `2 \| 3 \| 4` | não |  |
+| `className` | `string` | não |  |
+
+```jsx
+<Servicos
+  colunas={3}
+  itens={[
+    { icone: 'criacao-de-sites', titulo: 'Sites', texto: 'Carrega rápido e tem para onde ir.', href: '/sites' },
+    { icone: 'agentes-ia', titulo: 'Agentes de IA', texto: 'Responde na hora e qualifica.', href: '/ia' },
+  ]}
+/>
+```
+
+#### Shell
+
+Container de 1200px com respiro lateral.
+
+| Prop | Tipo | Obrigatória | O que faz |
+|---|---|---|---|
+| `children` | `React.ReactNode` | não |  |
+| `className` | `string` | não |  |
+| `id` | `string` | não |  |
+| `style` | `React.CSSProperties` | não |  |
+
+```jsx
+<Shell>
+  <SecHead titulo="Serviços" />
+</Shell>
+```
+
+#### Split
+
+Duas colunas dentro de uma `section`, que viram uma só abaixo de 900px.
+
+| Prop | Tipo | Obrigatória | O que faz |
+|---|---|---|---|
+| `proporcao` | `"a" \| "b" \| "c"` | não | `a` dá mais espaço à esquerda, `b` divide igual, `c` divide igual e centraliza na vertical. |
+| `children` | `React.ReactNode` | não |  |
+| `className` | `string` | não |  |
+| `id` | `string` | não |  |
+| `style` | `React.CSSProperties` | não |  |
+
+```jsx
+<section>
+  <Split proporcao="a">
+    <div><SecHead titulo="O que você recebe." /></div>
+    <div><StepsList passos={[{ titulo: "Entender" }]} /></div>
+  </Split>
+</section>
+```
+
+#### Topbar
+
+Cabeçalho fixo em navy translúcido. Logo à esquerda, navegação no meio, botão de conversão à direita.
+
+| Prop | Tipo | Obrigatória | O que faz |
+|---|---|---|---|
+| `logo` | `React.ReactNode` | não | Logo da marca. Imagem de 30px de altura sobre o navy. |
+| `href` | `string` | não |  |
+| `links` | `TopbarLink[]` | não |  |
+| `acao` | `React.ReactNode` | não | Botão da direita. Um `Btn` com variante `cta` é o padrão. |
+| `className` | `string` | não |  |
+
+```jsx
+<Topbar
+  logo={<img src="/logo-branco.png" alt="PSWEX" height={30} />}
+  href="/"
+  links={[{ href: "/servicos", label: "Serviços" }, { href: "/cases", label: "Projetos", atual: true }]}
+  acao={<Btn variante="cta" href="/avaliacao">Falar com a gente</Btn>}
+/>
+```
+
+#### Wall
+
+Parede de logos de cliente em grade automática.
+
+| Prop | Tipo | Obrigatória | O que faz |
+|---|---|---|---|
+| `titulo` | `React.ReactNode` | não | Rótulo centralizado acima da grade. |
+| `logos` | `WallLogo[]` | sim |  |
+| `className` | `string` | não |  |
+
+```jsx
+<Wall titulo="Quem já confiou" logos={[{ src: "/logos/unimed.png", alt: "Unimed, cliente PSWEX" }]} />
+```
+
+#### WhatsAppModal
+
+Pede nome e número antes de abrir a conversa no WhatsApp. É o que separa um clique anônimo de um lead com nome.
+
+| Prop | Tipo | Obrigatória | O que faz |
+|---|---|---|---|
+| `aberto` | `boolean` | não | `false` mantém o `hidden`, que é como o modal nasce antes do clique. |
+| `eyebrow` | `React.ReactNode` | não |  |
+| `titulo` | `React.ReactNode` | não |  |
+| `apoio` | `React.ReactNode` | não |  |
+| `botao` | `React.ReactNode` | não |  |
+| `nota` | `React.ReactNode` | não | Linha de privacidade centralizada abaixo do botão. |
+| `className` | `string` | não |  |
+| `style` | `React.CSSProperties` | não | Escape para ancorar o modal dentro de um container, em vez de cobrir a tela. |
+
+```jsx
+<WhatsAppModal aberto />
+```