Modal

Quando usarWhen to use

Use modals quandoUse modals when

Uma ação requer confirmação (deletar, descartar), uma tarefa curta pode ser concluída sem perder contexto (editar perfil), ou conteúdo focado precisa ser apresentado (termos de serviço, etapas de onboarding).An action requires confirmation (delete, discard), a short task can be completed without losing context (edit profile), or focused content needs to be presented (terms of service, onboarding steps).

Não use modals quandoDon't use modals when

A tarefa e complexa ou multi-etapas — use uma página dedicada. Para feedback não bloqueante, use Alert ou Toast. Nunca aninhe modals dentro de outros modals.The task is complex or multi-step — use a dedicated page instead. For non-blocking feedback, use an Alert or Toast. Never nest modals inside other modals.

AnatomiaAnatomy

1 2 3 4 5 6 7

1 Overlay (.ds-modal-overlay) — backdrop em tela cheia que bloqueia interação com a página.
2 Container (.ds-modal) — superfície elevada com border-radius e sombra.
3 Header (.ds-modal__header) — contem título e button de fechar.
4 Título (.ds-modal__title) — vinculado via aria-labelledby.
5 Button de fechar (.ds-modal__close) — dispensa o modal.
6 Corpo (.ds-modal__body) — área de conteúdo com scroll.
7 Rodape (.ds-modal__footer) — buttons de ação alinhados a direita.1 Overlay (.ds-modal-overlay) — full-screen backdrop that blocks page interaction.
2 Container (.ds-modal) — elevated surface with border-radius and shadow.
3 Header (.ds-modal__header) — contains title and close button.
4 Title (.ds-modal__title) — linked via aria-labelledby.
5 Close button (.ds-modal__close) — dismisses the modal.
6 Body (.ds-modal__body) — scrollable content area.
7 Footer (.ds-modal__footer) — action buttons aligned right.

Pequeno (400px)Small (400px)

<div class="ds-modal-overlay">
  <div class="ds-modal ds-modal--sm" role="dialog"
       aria-modal="true" aria-labelledby="modal-title">
    <div class="ds-modal__header">
      <h3 id="modal-title">Delete item</h3>
      <button class="ds-btn ds-btn--ghost ds-btn--sm ds-btn--icon-only"
              aria-label="Close modal">&times;</button>
    </div>
    <div class="ds-modal__body">
      <p>Are you sure? This action cannot be undone.</p>
    </div>
    <div class="ds-modal__footer">
      <button class="ds-btn ds-btn--ghost ds-btn--sm">Cancel</button>
      <button class="ds-btn ds-btn--danger ds-btn--sm">Delete</button>
    </div>
  </div>
</div>

Medio (520px)Medium (520px)

<div class="ds-modal-overlay">
  <div class="ds-modal ds-modal--md" role="dialog"
       aria-modal="true" aria-labelledby="modal-title">
    <div class="ds-modal__header">
      <h3 id="modal-title">Edit profile</h3>
      <button aria-label="Close modal">&times;</button>
    </div>
    <div class="ds-modal__body">
      <p>Update your personal information.</p>
      <input type="text" placeholder="Full name">
    </div>
    <div class="ds-modal__footer">
      <button class="ds-btn ds-btn--ghost">Cancel</button>
      <button class="ds-btn ds-btn--brand">Save changes</button>
    </div>
  </div>
</div>

Grande (640px)Large (640px)

<div class="ds-modal-overlay">
  <div class="ds-modal ds-modal--lg" role="dialog"
       aria-modal="true" aria-labelledby="modal-title">
    <div class="ds-modal__header">
      <h3 id="modal-title">Terms of service</h3>
      <button aria-label="Close modal">&times;</button>
    </div>
    <div class="ds-modal__body">
      <p>Please read and accept the terms...</p>
    </div>
    <div class="ds-modal__footer">
      <button class="ds-btn ds-btn--ghost ds-btn--lg">Cancel</button>
      <button class="ds-btn ds-btn--brand ds-btn--lg">Accept terms</button>
    </div>
  </div>
</div>

Boas práticasBest practices

Faça

Ação principal a direita, Cancel a esquerda. Use outline/ghost para secundário.Primary action right, Cancel left. Use outline/ghost for secondary.

Não faça

Dois buttons Brand no footer criam confusão sobre prioridade.Two Brand buttons in footer creates confusion about priority.

Modal pequeno para confirmacoesSmall modal for confirmations

Faça

Use o menor tamanho que cabe. Small para confirmacoes, medium para formulários, large para conteúdo longo.Use the smallest size that fits. Small for confirmations, medium for forms, large for long content.

Modal large para "Tem certeza?"Large modal for "Are you sure?"

Não faça

Modals large para confirmacoes simples desperdicam espaco e adicionam peso visual desnecessário.Large modals for simple confirmations waste space and add unnecessary visual weight.

Foco preso dentro + retorna ao fecharFocus trapped inside + returns on close

Faça

Retorne o foco ao elemento que disparou o modal ao fechar. Feche com Escape e clique no backdrop para ações não destrutivas.Return focus to the trigger element on close. Close on Escape and backdrop click for non-destructive actions.

Clique no backdrop fecha modal destrutivoBackdrop click closes destructive modal

Não faça

Deixar o foco escapar do modal. Fechar com clique no backdrop para ações destrutivas (o usuário pode perder dados acidentalmente).Let focus escape the modal. Close on backdrop click for destructive actions (user might lose data accidentally).

Diretrizes de conteúdoContent guidelines

RegraRule	ExemploExample
Título: ação + objetoTitle: action + object	"Delete project" — não "Warning" ou "Confirm""Delete project" — not "Warning" or "Confirm"
Corpo: 1-3 frases, explique consequenciasBody: 1-3 sentences, explain consequences	"This action cannot be undone. All data will be permanently removed."
Button primario: corresponda ao verbo do títuloPrimary button: match title verb	Título "Delete project" -> button "Delete"Title "Delete project" -> button "Delete"
Button secundário: sempre "Cancel"Secondary button: always "Cancel"	"Cancel" — não "Go back" ou "Close""Cancel" — not "Go back" or "Close"
Ações destrutivas: use button DangerDestructive actions: use Danger button	`ds-btn--danger` para delete, remove, revokefor delete, remove, revoke

Mapeamento de tokensToken mapping

PropriedadeProperty	Token (semantic)	Variavel CSSCSS variable
overlay background	`semantic.background.overlay`	`--ds-background-overlay`
surface	`semantic.surface.elevated`	`--ds-surface-elevated`
shadow	`foundation.shadow.xl`	`--ds-shadow-xl`
z-index (overlay)	`foundation.z.50`	`--ds-z-50`
border-radius	`component.modal.border-radius`	`--ds-modal-border-radius` (valor: `--ds-radius-16`, 16px)(value: `--ds-radius-16`, 16px)
padding	`semantic.space.inset.lg`	`--ds-space-lg`

Classes CSSCSS classes

ClasseClass	DescricaoDescription
`ds-modal-overlay`	Overlay backdrop em tela cheiaFull-screen backdrop overlay
`ds-modal`	Container do diálogo modalModal dialog container
`ds-modal--sm`	Tamanho pequeno (max-width 400px)Small size (max-width 400px)
`ds-modal--md`	Tamanho médio (max-width 520px)Medium size (max-width 520px)
`ds-modal--lg`	Tamanho grande (max-width 640px)Large size (max-width 640px)
`ds-modal__header`	Área de header com título e button de fecharHeader area with title and close button
`ds-modal__title`	Texto do título do modalModal title text
`ds-modal__close`	Button de fechar no headerClose button in the header
`ds-modal__body`	Área de conteúdo do corpo com scrollScrollable body content area
`ds-modal__footer`	Área de rodapé para buttons de açãoFooter area for action buttons

Interação por tecladoKeyboard interaction

TeclaKey	AçãoAction
`Tab`	Cicla o foco dentro do modal (focus trap)Cycles focus inside the modal (focus trap)
`Shift+Tab`	Cicla o foco para tras dentro do modalCycles focus backwards inside the modal
`Escape`	Fecha o modalCloses the modal
`Enter`	Ativa o button focadoActivates the focused button

O foco deve ser preso dentro do modal enquanto estiver aberto. Quando o modal fechar, o foco deve retornar ao elemento que o disparou.Focus must be trapped inside the modal while it is open. When the modal closes, focus must return to the element that triggered it.

AccessibilityAccessibility

Criterio WCAGWCAG criterion	RequisitoRequirement	Status
2.4.3 Focus Order (A)	O foco move para dentro do modal ao abrir, fica preso dentro e retorna ao trigger ao fecharFocus moves into the modal on open, is trapped inside, and returns to the trigger on close	✓
2.4.11 Focus Appearance (AA)	Focus ring visível em todos os elementos interativos dentro do modalFocus ring visible on all interactive elements inside the modal	✓
4.1.2 Name, Role, Value (A)	`role="dialog"`, `aria-modal="true"`, `aria-labelledby` apontando para o título`role="dialog"`, `aria-modal="true"`, `aria-labelledby` pointing to the title	✓
1.4.11 Non-text Contrast (AA)	Button de fechar tem pelo menos 3:1 de ratio de contraste contra a superfície do modalClose button has at least 3:1 contrast ratio against the modal surface	✓

Resumo de atributos ARIAARIA attributes summary

role="dialog" — identifica o modal como um diálogo.
aria-modal="true" — informa a tecnologia assistiva que o conteúdo atras do modal esta inerte.
aria-labelledby — referencia o id do elemento de título do modal.
aria-label="Close modal" — obrigatorio no button de fechar.role="dialog" — identifies the modal as a dialog.
aria-modal="true" — informs assistive technology that content behind the modal is inert.
aria-labelledby — references the modal title element's id.
aria-label="Close modal" — required on the close button.

Quando usarWhen to use

AnatomiaAnatomy

Pequeno (400px)Small (400px)

Medio (520px)Medium (520px)

Grande (640px)Large (640px)

Boas práticasBest practices

Diretrizes de conteúdoContent guidelines

Mapeamento de tokensToken mapping

Classes CSSCSS classes

Interação por tecladoKeyboard interaction

AccessibilityAccessibility

RelacionadosRelated