Toggle
Toggles (switches) permitem que o usuário ative ou desative uma configuração instantaneamente. Construido com um checkbox nativo estilizado e role="switch".Toggles (switches) let users turn a setting on or off instantly. Built with a styled native checkbox and role="switch".
Quando usarWhen to use
Use toggles quandoUse toggles when
O usuário precisa ativar/desativar uma configuração com efeito imediato. Modo escuro, notificações, feature flags, preferencias de salvamento automatico.The user needs to turn an on/off setting that takes effect immediately. Dark mode, notifications, feature flags, auto-save preferences.
AnatomiaAnatomy
1
2
3
4
1 Input (
2 Track — fundo CSS que muda de cor conforme o estado checked.
3 Thumb — pseudo-elemento CSS que desliza esquerda/direita.
4 Label (
2 Track — CSS background that changes color based on checked state.
3 Thumb — CSS pseudo-element that slides left/right.
4 Label (
.ds-toggle) — <input type="checkbox"> estilizado com role="switch".2 Track — fundo CSS que muda de cor conforme o estado checked.
3 Thumb — pseudo-elemento CSS que desliza esquerda/direita.
4 Label (
.ds-toggle-label) — envolve o toggle + texto descritivo.1 Input (.ds-toggle) — styled <input type="checkbox"> with role="switch".2 Track — CSS background that changes color based on checked state.
3 Thumb — CSS pseudo-element that slides left/right.
4 Label (
.ds-toggle-label) — wraps toggle + descriptive text.
PadrãoDefault
<label class="ds-toggle-label">
<input type="checkbox" class="ds-toggle" role="switch">
Notifications
</label>MarcadoChecked
<label class="ds-toggle-label">
<input type="checkbox" class="ds-toggle" role="switch" checked>
Dark mode enabled
</label>TamanhosSizes
<label class="ds-toggle-label">
<input type="checkbox" class="ds-toggle ds-toggle--sm" role="switch">
Small
</label>
<label class="ds-toggle-label">
<input type="checkbox" class="ds-toggle" role="switch">
Medium (default)
</label>
<label class="ds-toggle-label">
<input type="checkbox" class="ds-toggle ds-toggle--lg" role="switch">
Large
</label>DesabilitadoDisabled
<label class="ds-toggle-label">
<input type="checkbox" class="ds-toggle" role="switch" disabled>
Disabled off
</label>
<label class="ds-toggle-label">
<input type="checkbox" class="ds-toggle" role="switch" checked disabled>
Disabled on
</label>Boas práticasBest practices
Faça
Labels descrevem a configuração: "Dark mode", "Email notifications".Labels describe the setting: "Dark mode", "Email notifications".
Não faça
"Enable dark mode" e redundante com o estado do toggle."Enable dark mode" is redundant with the toggle state itself.
Faça
Posicione o toggle a direita do label. O efeito e imediato.Place toggle right of label. Effect is immediate.
Não faça
Não use toggle para ações que precisam de confirmação. Use um Button + dialog.Don't use toggle for actions needing confirmation. Use a Button + dialog instead.
Diretrizes de conteúdoContent guidelines
| RegraRule | ExemploExample |
|---|---|
| Use um substantivo para o labelUse a noun phrase for the label | "Dark mode", "Auto-save", "Email notifications" |
| Não use "Enable/Disable"Don't use "Enable/Disable" | "Notifications" — não "Enable notifications""Notifications" — not "Enable notifications" |
| Mantenha labels curtos (1-3 palavras)Keep labels short (1-3 words) | "Auto-save" — não "Automatically save my work every 5 minutes""Auto-save" — not "Automatically save my work every 5 minutes" |
Mapeamento de tokensToken mapping
| PropriedadeProperty | Token (semantic) | Variável CSSCSS variable |
|---|---|---|
| track (off) | semantic.border.control-default | --ds-border-control-default |
| track (on) | semantic.primary.background.default | --ds-primary-background-default |
| thumb (off) | semantic.content.secondary | --ds-content-secondary |
| focus ring | semantic.focus.ring.* | --ds-focus-ring-width, --ds-focus-ring-offset, --ds-focus-ring-color |
Classes CSSCSS classes
| ClasseClass | DescriçãoDescription |
|---|---|
ds-toggle | Switch estilizado (checkbox nativo)Custom styled switch (native checkbox) |
ds-toggle-label | Wrapper do label (envolve toggle + texto)Label wrapper (wraps toggle + text) |
ds-toggle--sm | Tamanho pequeno (28x16px)Small size (28x16px) |
ds-toggle--lg | Tamanho grande (44x24px)Large size (44x24px) |
ds-toggle__content | Frame vertical com label, description e helper textVertical frame stacking label, description, and helper text |
ds-toggle__label | Texto do label dentro do content frame (label/md)Label text inside content frame (label/md) |
ds-toggle__description | Texto descritivo multiline (body/sm, content/default)Multiline description text (body/sm, content/default) |
ds-toggle__helper | Texto auxiliar (caption/sm, content/secondary)Helper annotation (caption/sm, content/secondary) |
Propriedades FigmaFigma properties
| PropriedadeProperty | TipoType | PadrãoDefault | DescriçãoDescription |
|---|---|---|---|
Show Label | Boolean | true | Exibe ou oculta o label do controleShows or hides the control label |
Label | Text | "Rótulo" | Texto do label (label/md)Label text (label/md) |
Show Description | Boolean | false | Exibe texto descritivo abaixo do labelShows descriptive text below the label |
Description | Text | "Texto descritivo" | Texto multiline de descrição (body/sm)Multiline description text (body/sm) |
Show Helper Text | Boolean | false | Exibe texto auxiliar abaixo da descriptionShows helper text below the description |
Helper Text | Text | "Texto auxiliar" | Anotação em caption/sm (content/secondary)Caption/sm annotation (content/secondary) |
Interação por tecladoKeyboard interaction
| TeclaKey | AçãoAction |
|---|---|
Tab | Move o foco para o toggleMoves focus to the toggle |
Space | Alterna ligado/desligadoToggles on/off |
Enter | NÃO alterna (comportamento padrão de switch)Does NOT toggle (standard switch behavior) |
Toggles desabilitados ([disabled]) são removidos da ordem de tabulação automaticamente pelo navegador.Disabled toggles ([disabled]) are removed from tab order automatically by the browser.
AccessibilityAccessibility
| Critério WCAGWCAG criterion | RequisitoRequirement | Status |
|---|---|---|
| 4.1.2 Name, Role, Value (A) | role="switch" + aria-checked gerenciados pelo checkbox nativorole="switch" + aria-checked managed by native checkbox | ✓ |
| 2.4.11 Focus Appearance (AA) | Focus ring visível via :focus-visibleFocus ring visible via :focus-visible | ✓ |
| 2.5.8 Target Size min (AA) | Label estende a área de clique além do toggleLabel extends click target beyond the toggle itself | ✓ |
| 1.4.1 Use of Color (A) | Posição + cor comunicam o estado (thumb desliza esquerda/direita)Position + color both communicate state (thumb slides left/right) | ✓ |
Resumo de atributos ARIAARIA attributes summary
role="switch" — obrigatório no checkbox para que leitores de tela o anunciem como switch.aria-checked — gerenciado automaticamente pelo <input type="checkbox"> nativo.Um label visível deve sempre descrever o que o toggle controla.
role="switch" — required on the checkbox so screen readers announce it as a switch.aria-checked — managed automatically by the native <input type="checkbox">.A visible label should always describe what the toggle controls.
Label invisível — exige ARIA explícitoInvisible label — requires explicit ARIA
Quando Show Label = false e Show Description = true, vincule o <input> à descrição via aria-labelledby="id-da-description". Se nenhum dos dois estiver visível, use aria-label diretamente no <input>. O Helper Text deve sempre ser vinculado via aria-describedby="id-do-helper".When Show Label = false and Show Description = true, link the <input> to the description via aria-labelledby="description-id". If neither is visible, use aria-label directly on the <input>. Helper Text should always be linked via aria-describedby="helper-id".