Alert
Alerts exibem mensagens contextuais importantes para os usuários. A API cobre estilos de ênfase, ícones e buttons de fechar opcionais. Persistentes até serem dispensados.Alerts display important contextual messages to users. The API covers emphasis styles, optional icons, and optional close buttons. Persistent until dismissed.
Quando usarWhen to use
Use alerts quandoUse alerts when
Exibir uma mensagem contextual: resumo de validação de formulário, status do sistema, confirmação de ação ou aviso. Alerts são persistentes até o usuário dispensá-los.Displaying a contextual message: form validation summary, system status, action confirmation, or warning. Alerts are persistent until the user dismisses them.
Não use alerts quandoDon't use alerts when
O feedback e transitorio (use Toast — futuro), se refere a um erro de campo único (use Form Field), ou fornece feedback inline (use texto auxiliar).The feedback is transient (use Toast — future), relates to a single field error (use Form Field), or provides inline feedback (use helper text).
| TipoType | Use paraUse for | ÍconeIcon |
|---|---|---|
| Success | Ação concluída: salvo, publicadoCompleted action: saved, published | check_circle |
| Warning | Não bloqueante: sessão expirando, depreciaçãoNon-blocking: session expiring, deprecation | warning |
| Error | Ações falharam: pagamento falhou, acesso negadoFailed actions: payment failed, access denied | error |
| Info | Neutro: nova funcionalidade, manutencaoNeutral: new feature, maintenance | info |
AnatomiaAnatomy
Success
Your changes have been saved.
1 Container (
2 Ícone (
3 Conteúdo (
4 Título (
5 Descrição (
6 Fechar (
2 Icon (
3 Content (
4 Title (
5 Description (
6 Close (
.ds-alert) — background, border-radius, padding.2 Ícone (
.ds-alert__icon) — Lucide icon específico do tipo, reforça o significado além da cor.3 Conteúdo (
.ds-alert__content) — wrapper para título e descricao.4 Título (
.ds-alert__title) — negrito, 1-3 palavras.5 Descrição (
.ds-alert__description) — o que aconteceu + o que fazer.6 Fechar (
.ds-alert__close) — button de dispensar com aria-label="Dismiss alert".1 Container (.ds-alert) — background, border-radius, padding.2 Icon (
.ds-alert__icon) — type-specific Lucide icon, reinforces meaning beyond color.3 Content (
.ds-alert__content) — wrapper for title and description.4 Title (
.ds-alert__title) — bold, 1-3 words.5 Description (
.ds-alert__description) — what happened + what to do.6 Close (
.ds-alert__close) — dismiss button with aria-label="Dismiss alert".
Variantes SolidSolid Variants
Success
Your changes have been saved successfully.
Warning
Your session will expire in 5 minutes.
Error
Unable to process your request. Please try again.
Information
A new version is available. Refresh to update.
<div class="ds-alert ds-alert--success ds-alert--solid" role="alert">
<span class="ds-alert__icon">
<i data-lucide="circle-check" class="ds-icon"></i>
</span>
<div class="ds-alert__content">
<p class="ds-alert__title">Success</p>
<p class="ds-alert__description">Your changes have been saved successfully.</p>
</div>
</div>
<div class="ds-alert ds-alert--warning ds-alert--solid" role="alert">
<span class="ds-alert__icon">
<i data-lucide="triangle-alert" class="ds-icon"></i>
</span>
<div class="ds-alert__content">
<p class="ds-alert__title">Warning</p>
<p class="ds-alert__description">Your session will expire in 5 minutes.</p>
</div>
</div>
<div class="ds-alert ds-alert--error ds-alert--solid" role="alert">
<span class="ds-alert__icon">
<i data-lucide="circle-alert" class="ds-icon"></i>
</span>
<div class="ds-alert__content">
<p class="ds-alert__title">Error</p>
<p class="ds-alert__description">Unable to process your request.</p>
</div>
</div>
<div class="ds-alert ds-alert--info ds-alert--solid" role="alert">
<span class="ds-alert__icon">
<i data-lucide="info" class="ds-icon"></i>
</span>
<div class="ds-alert__content">
<p class="ds-alert__title">Information</p>
<p class="ds-alert__description">A new version is available.</p>
</div>
</div>Variantes SubtleSubtle Variants
Success
Your profile has been updated.
Warning
Storage is almost full. Consider upgrading your plan.
Error
Payment failed. Please update your billing information.
Information
Maintenance is scheduled for this weekend.
<div class="ds-alert ds-alert--success ds-alert--subtle" role="alert">
<span class="ds-alert__icon">
<i data-lucide="circle-check" class="ds-icon"></i>
</span>
<div class="ds-alert__content">
<p class="ds-alert__title">Success</p>
<p class="ds-alert__description">Your profile has been updated.</p>
</div>
</div>
<!-- Subtle style uses a border-left accent -->
<div class="ds-alert ds-alert--error ds-alert--subtle" role="alert">
<span class="ds-alert__icon">
<i data-lucide="circle-alert" class="ds-icon"></i>
</span>
<div class="ds-alert__content">
<p class="ds-alert__title">Error</p>
<p class="ds-alert__description">Payment failed.</p>
</div>
</div>Com button de fecharWith Close Button
Tip
You can customize your dashboard by dragging and dropping widgets.
Saved
All changes have been saved.
<div class="ds-alert ds-alert--info ds-alert--solid" role="alert">
<span class="ds-alert__icon">
<i data-lucide="info" class="ds-icon"></i>
</span>
<div class="ds-alert__content">
<p class="ds-alert__title">Tip</p>
<p class="ds-alert__description">You can customize your dashboard.</p>
</div>
<button class="ds-alert__close" aria-label="Dismiss alert">
<i data-lucide="x" class="ds-icon"></i>
</button>
</div>Com actionsWith actions
Actions são opcionais e compõem até dois Buttons Ghost Small dentro do conteúdo do Alert. Actions are optional and compose up to two Small Ghost Buttons inside the Alert content.
Sessão prestes a expirar
Salve o trabalho ou renove a sessão.
<div class="ds-alert ds-alert--warning ds-alert--subtle" role="alert">
<span class="ds-alert__icon">...</span>
<div class="ds-alert__content">
<p class="ds-alert__title">Sessão prestes a expirar</p>
<p class="ds-alert__description">Salve o trabalho ou renove a sessão.</p>
<div class="ds-alert__actions">
<button class="ds-button ds-button--ghost ds-button--sm"><span class="ds-button__label">Salvar</span></button>
<button class="ds-button ds-button--ghost ds-button--sm"><span class="ds-button__label">Renovar sessão</span></button>
</div>
</div>
</div>Boas práticasBest practices
Saved
Changes saved successfully.
Faça
Sempre inclua um ícone — ele reforça o tipo além da cor (WCAG 1.4.1).Always include an icon — it reinforces the type beyond color (WCAG 1.4.1).
Saved
Changes saved successfully.
Não faça
Depender apenas da cor para transmitir o tipo do alert.Rely on color alone to convey the alert type.
Error
Payment failed.
Tip
Try a different card.
Faça
Use solid para mensagens de alta prioridade, subtle para informativas.Use solid for high-priority messages, subtle for informational ones.
Error
Payment failed.
Warning
Card expiring soon.
Note
Try a different card.
Não faça
Múltiplos alerts solid diluem a urgencia e sobrecarregam o usuário.Multiple solid alerts dilute urgency and overwhelm the user.
Diretrizes de conteúdoContent guidelines
| RegraRule | ExemploExample |
|---|---|
| Título: 1-3 palavras, sentence caseTitle: 1-3 words, sentence case | "Payment failed", "Changes saved" |
| Descrição: o que aconteceu + o que fazerDescription: what happened + what to do | "Your session expired. Please log in again." |
Button de fechar deve ter aria-labelClose button must have aria-label | aria-label="Dismiss alert" |
Mapeamento de tokensToken mapping
Tokens mostrados para a variante success. Outros tipos (warning, error, info) seguem o mesmo padrão com seus respectivos grupos de cor de feedback.Tokens shown for the success variant. Other types (warning, error, info) follow the same pattern with their respective feedback color groups.
| PropriedadeProperty | Token | Variável CSSCSS variable |
|---|---|---|
| bg (success solid) | component.alert.bg.success.solid | --ds-alert-bg-success-solid |
| bg (success subtle) | component.alert.bg.success.subtle | --ds-alert-bg-success-subtle |
| border (success subtle) | component.alert.border-color.success.subtle | --ds-alert-border-color-success-subtle |
| text (success solid) | component.alert.description.color.success.solid | --ds-alert-description-color-success-solid |
| text title (subtle) | component.alert.title.color.subtle | --ds-alert-title-color-subtle |
| text description (subtle) | component.alert.description.color.subtle | --ds-alert-description-color-subtle |
| root padding | component.alert.padding.default | --ds-alert-padding-default |
| root gap | component.alert.gap.default | --ds-alert-gap-default |
| root radius | component.alert.radius.default | --ds-alert-radius-default |
| root border-width | component.alert.border-width.default | --ds-alert-border-width-default |
| icon size | component.alert.icon.size.default | --ds-alert-icon-size-default |
| content gap | component.alert.content.gap.default | --ds-alert-content-gap-default |
| title typography | component.alert.title.*.default | --ds-alert-title-*-default |
| description typography | component.alert.description.*.default | --ds-alert-description-*-default |
| close icon size | component.alert.close.icon-size.default | --ds-alert-close-icon-size-default |
| close target size | component.alert.close.size.default | --ds-alert-close-size-default |
| actions layout | component.alert.actions.{gap|padding-top}.default | --ds-alert-actions-* |
| action color | component.alert.action.color.* | --ds-alert-action-color-* |
Classes CSSCSS classes
| ClasseClass | DescriçãoDescription |
|---|---|
ds-alert | Container base do alertBase alert container |
ds-alert--solid | Estilo com fundo solid; modifier recomendadoSolid background style; recommended modifier |
ds-alert--filled | Legado/deprecated: alias compatível de ds-alert--solidLegacy/deprecated: compatibility alias for ds-alert--solid |
ds-alert--subtle | Estilo sutil com fundo claro e borda ao redor (1px)Subtle style with light background and full border (1px) |
ds-alert--success | Variante success (verde)Success variant (green) |
ds-alert--warning | Variante warning (amarelo)Warning variant (yellow) |
ds-alert--error | Variante error (vermelho)Error variant (red) |
ds-alert--info | Variante info (azul)Info variant (blue) |
ds-alert__icon | Container do íconeIcon container |
ds-alert__content | Wrapper de conteúdo para título e descricaoContent wrapper for title and description |
ds-alert__title | Título do alert (negrito)Alert title (bold) |
ds-alert__description | Texto de descricao do alertAlert description text |
ds-alert__actions | Container opcional para até dois Buttons Ghost SmallOptional container for up to two Small Ghost Buttons |
ds-alert__close | Button de dispensar/fecharDismiss/close button |
Interação por tecladoKeyboard interaction
| TeclaKey | AçãoAction |
|---|---|
Tab | Move o foco para o button de fecharMoves focus to the close button |
Enter | Ativa o button de fecharActivates the close button |
Space | Ativa o button de fecharActivates the close button |
AccessibilityAccessibility
| Critério WCAGWCAG criterion | RequisitoRequirement | Status |
|---|---|---|
| 4.1.3 Status Messages (AA) | role="alert" para mensagens urgentes, role="status" para não urgentesrole="alert" for urgent messages, role="status" for non-urgent | ✓ |
| 1.4.1 Use of Color (A) | Ícone + texto complementam a cor — nunca cor sozinhaIcon + text supplement color — never color alone | ✓ |
| 2.4.11 Focus Appearance (AA) | Button de fechar tem focus ring visívelClose button has visible focus ring | ✓ |
| 4.1.2 Name, Role, Value (A) | Button de fechar tem aria-label="Dismiss alert"Close button has aria-label="Dismiss alert" | ✓ |
Resumo de atributos ARIAARIA attributes summary
role="alert" — para mensagens urgentes/erros que devem ser anunciadas imediatamente por leitores de tela.role="status" — para mensagens informativas não urgentes (anuncio educado).aria-label="Dismiss alert" — obrigatorio no button de fechar.role="alert" — for urgent/error messages that should be announced immediately by screen readers.role="status" — for non-urgent informational messages (polite announcement).aria-label="Dismiss alert" — required on the close button.