Peppe Design System

Card-atalho com 2 a 4 ações rotuladas. Espelho de jornadas frequentes do WhatsApp no app.

Quando usar

Para agrupar ações rotineiras que o usuário executa com frequência — "Mandar boleto", "Adicionar compromisso", "Ver agenda", "Consultar viabilidade".
Como espelho no app das jornadas frequentes do WhatsApp — encurta o caminho que o usuário já percorre lá.
Em dashboards e telas de entrada onde o produto antecipa as próximas ações prováveis em vez de exigir navegação por menu.
Em onboarding, como cartão de orientação após o cadastro: "comece por aqui".

Quando não usar

Para uma ação isolada — usar Button direto. Card-atalho de 1 item é embalagem sem função.
Para listagem de comandos > 4 — considere menu dedicado ou listagem própria. Mais que 4 atalhos fragmenta atenção e o card vira muralha de ícones.
Para ações de alto risco (autorizar transferência, fechar conta, contestar débito) — essas pedem botão único em superfície dedicada com confirmação, não atalho rápido.
Como card-mãe do dashboard — o Quick Actions Card tem peso de card-filho. Não use peppe-card--mother.

Anatomia

Quatro slots, um obrigatório (items com pelo menos 2 entradas). Os slots kicker, title e footerAction são opcionais. Cada item da lista é um <button type="button"> focável — não div nem span — pra preservar a semântica de ação.

kicker (opcional) — caps xs sans tracking-loose, --color-ink-tertiary. Etiqueta de seção: "ATALHOS DO MÊS", "AÇÕES RÁPIDAS".
title (opcional) — sans md medium --color-ink-primary. Linha curta de contexto. Pode ser omitido em cards mais secos.
items (obrigatório, 2–4) — cada item carrega icon + label + targetAction. Renderizado como <button> focável. O targetAction é intenção de domínio (não href): string semântica resolvida pelo backend SDUI (ex.: "send_boleto", "add_commitment", "view_calendar"), separando o que o usuário quer fazer de como a ação é renderizada.
footerAction (opcional) — Button emphasis=tertiary. Convite pra contexto completo: "Ver agenda completa →".

Variantes

Três layouts conforme viewport e número de items. A escolha do modificador é decisão do consumidor — não há media query interna que troque o layout automaticamente.

Modificador	Layout	Uso
`--grid-2x2`	Grade 2 colunas × 2 linhas	Default para 4 items. Equilíbrio entre densidade e clareza.
`--grid-4x1`	4 items em linha	Cabeçalho de tela larga (desktop) ou faixa horizontal estreita.
`--grid-2x1`	2 items em linha	Quando a lista de atalhos do usuário tem 2 entradas relevantes.

ATALHOS DO MÊS

Maio

--grid-2x2 · 4 items · com kicker, title e footerAction

AÇÕES RÁPIDAS

--grid-2x1 · 2 items · sem title, sem footerAction

Variantes por canal. app: card visual com grid responsivo (default). voz: o assistente abre direto na lista ("Aqui os atalhos: mandar boleto, adicionar compromisso, ver agenda, consultar viabilidade. Qual?"). whatsapp / sms: lista numerada de quick replies — limite 4 — uma por linha ("1. Mandar boleto · 2. Adicionar compromisso · 3. Ver agenda · 4. Consultar viabilidade"). e-mail: lista HTML com cada item virando link no corpo do e-mail.

Estados

Três estados — default (Registro A profissional), loading (skeletons preservam dimensões dos slots), vazio (onboarding sem ação sugerida ainda — Registro B com pitada, conforme voice-and-tone.md §3.1 linha "Onboarding").

loading · skeletons preservam dimensões

Nenhuma ação sugerida ainda. Continua usando que o Peppe aprende.

vazio · onboarding sem histórico

Tokens

O Quick Actions Card herda de Card a superfície raised, sombra, border gradient e padding. O CSS próprio entrega apenas o layout interno dos slots e os papéis tipográficos do kicker/title/items/footer-action.

Token	Valor	Papel
`--color-surface-raised-top` / `-bottom`	—	Fundo gradiente do card (herdado de Card)
`--shadow-raised`	—	Sombra direcional do card (herdado de Card)
`--radius-md` / `--radius-lg`	16px / 24px	Raio do card (herdado) / raio do item (botão)
`--space-24`	24px	Gap entre items no grid
`--space-16`	16px	Gap interno do item entre icon e label · gap mobile
`--space-32`	32px	Padding interno do card (herdado)
`--icon-size-md`	24px	Tamanho do ícone do item
`--icon-stroke`	1.5px	Espessura do stroke do ícone
`--color-ink-secondary`	#6B6B6B	Ícone e label do item em rest
`--color-ink-primary`	#171717	Ícone e label do item em hover/focus
`--color-ink-tertiary`	#A1A1A1	Kicker e empty-text
`--type-family-sans`	Instrument Sans	Toda a tipografia do componente
`--type-size-xs`	12px	Kicker (caps tracking-loose)
`--type-size-sm`	14px	Label do item · empty-text · footerAction
`--type-size-lg`	20px	Title do card (sans medium — abaixo do limiar de 32px do serif)

Conteúdo

Labels em verbo direto, 1–3 palavras. "Mandar boleto", "Ver agenda", "Adicionar compromisso", "Consultar viabilidade". Não "Cliques aqui pra mandar um boleto" nem "Boletos".
Máximo 4 items. 5+ fragmenta atenção. Se a lista cresce, repensa: virou menu, não mais atalho.
FooterAction como convite contextual. "Ver agenda completa →", "Todas as ações →". Sempre com seta — sinaliza saída pra contexto maior.
Kicker em caps curtas. "ATALHOS DO MÊS", "AÇÕES RÁPIDAS". Não usar como rótulo decorativo.
Voz e tom: Registro A no padrão (dashboard); Registro B com pitada em onboarding. Ver voice-and-tone.md §3.1.

Acessibilidade

Container com role="group" e aria-label descritivo derivado do title — quando o title está omitido, derivado do kicker. Ex.: aria-label="Atalhos do mês".
Cada item é <button type="button">. Foco navegável por teclado, ativação por Enter/Space, aria-label próprio se o label visível for ambíguo (ex.: ícone só, sem texto visível).
Focus ring herdado. Cada item recebe o focus ring padrão (--focus-ring-width + --focus-ring-offset) sobre o raio próprio do item.
Estado loading: container com aria-busy="true" e aria-label="Carregando atalhos"; cada skeleton filho recebe aria-hidden="true" — o anúncio do container basta.
Estado vazio: role="status" no card, aria-label="Nenhuma ação sugerida ainda".
Fallback de canal — voz: assistente lê a lista e pergunta "qual delas?". WhatsApp / SMS: vira lista numerada de quick replies, limite 4. E-mail: lista HTML com cada item como link.
Contraste. Label do item em --color-ink-secondary (#6B6B6B) sobre --color-surface-raised-top (#F7F7F7) passa WCAG AA em --type-size-sm (14px regular). No estado hover/focus, label sobe pra --color-ink-primary (#171717), folga de contraste maior ainda.

Do / Don't

Do

2 a 4 ações por card. Cabe na cognição do usuário, mantém a tela respirável e cada item ganha peso visual suficiente.

Don't

5 ou mais ações no mesmo card. Vira muralha de ícones — o ponto era atalho rápido, não menu. Se a lista cresce, troque por menu dedicado.

Do

Ícone como marcador semântico da ação. "Ver agenda" → glifo calendar. "Consultar viabilidade" → glifo de busca/lupa. O ícone reforça a leitura, não compete com ela.

Don't

Ícone sem relação semântica com o label — estrelinha decorativa, foguete, raio. Vira ornamento visual, confunde a leitura e dilui a função do glifo.

Do

FooterAction como link ghost / Button tertiary. "Ver agenda completa →" — convite discreto pra contexto maior, sem brigar com os items.

Don't

FooterAction em emphasis primary (Tecla V-B). Compete com os items do card por atenção e quebra a hierarquia: o footer vira o foco, não o convite.

Componentes relacionados

Card — primitivo base. O Quick Actions Card usa composição peppe-card peppe-quick-actions-card e herda surface, sombra e padding.
Button — o footerAction é uma instância de Button emphasis=tertiary. Cada item da lista também é um <button> (com estilo próprio), preservando semântica.
Icon — cada item carrega um glifo do catálogo. Todos em stroke 1.5px via currentColor.

Markup de referência

HTML namespaced copiável. kicker, title e footerAction são opcionais — apenas o slot items com pelo menos 2 entradas é obrigatório.

Decisão de arquitetura: o Quick Actions Card usa composição de classes — peppe-card peppe-quick-actions-card. A classe peppe-card entrega a superfície raised; a classe peppe-quick-actions-card entrega o layout do grid e os estilos próprios dos items.

<!-- Quick Actions Card — variante 2x2 com kicker, title e footerAction --> <article className="peppe-card peppe-quick-actions-card peppe-quick-actions-card--grid-2x2" aria-label="Atalhos do mês"> <!-- kicker: opcional --> <span className="peppe-quick-actions-card__kicker">ATALHOS DO MÊS</span> <!-- title: opcional --> <p className="peppe-quick-actions-card__title">Maio</p> <!-- items: obrigatório, 2-4 entradas --> <div className="peppe-quick-actions-card__items" role="group"> <button type="button" className="peppe-quick-actions-card__item" aria-label="Mandar boleto"> <span className="peppe-quick-actions-card__item-icon"> <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="1.5" strokeLinecap="round" strokeLinejoin="round" aria-hidden="true"> <line x1="22" y1="2" x2="11" y2="13"/> <polygon points="22 2 15 22 11 13 2 9 22 2"/> </svg> </span> <span className="peppe-quick-actions-card__item-label">Mandar boleto</span> </button> <!-- ... outros 1-3 items com a mesma estrutura ... --> </div> <!-- footerAction: opcional --> <a href="#" className="peppe-quick-actions-card__footer-action">Ver agenda completa →</a> </article> <!-- Quick Actions Card — variante 2x1 sem title, sem footerAction --> <article className="peppe-card peppe-quick-actions-card peppe-quick-actions-card--grid-2x1" aria-label="Ações rápidas"> <span className="peppe-quick-actions-card__kicker">AÇÕES RÁPIDAS</span> <div className="peppe-quick-actions-card__items" role="group"> <!-- 2 items --> </div> </article> <!-- Quick Actions Card — loading (skeletons preservam dimensões) --> <article className="peppe-card peppe-quick-actions-card peppe-quick-actions-card--grid-2x2 peppe-quick-actions-card--loading" aria-busy="true" aria-label="Carregando atalhos"> <div className="peppe-quick-actions-card__skeleton-kicker"></div> <div className="peppe-quick-actions-card__skeleton-title"></div> <div className="peppe-quick-actions-card__skeleton-items"> <div className="peppe-quick-actions-card__skeleton-item" aria-hidden="true"> <div className="peppe-quick-actions-card__skeleton-item-icon"></div> <div className="peppe-quick-actions-card__skeleton-item-label"></div> </div> <!-- ... mais 3 skeleton-item ... --> </div> </article> <!-- Quick Actions Card — vazio (onboarding) --> <article className="peppe-card peppe-quick-actions-card peppe-quick-actions-card--empty" role="status" aria-label="Nenhuma ação sugerida ainda"> <div className="peppe-quick-actions-card__empty"> <span className="peppe-quick-actions-card__empty-icon" aria-hidden="true"> <!-- glifo decorativo --> </span> <p className="peppe-quick-actions-card__empty-text">Nenhuma ação sugerida ainda. Continua usando que o Peppe aprende.</p> </div> </article>