Input
Campos de texto permitem que usuários insiram e editem texto. Usa um padrão de wrapper com um elemento de campo interno para estilização consistente.Text inputs allow users to enter and edit text. Uses a wrapper pattern with an inner field element for consistent styling.
Quando usarWhen to use
Use quandoUse when
O usuário precisa inserir um valor de texto curto, de uma única linha: nome, email, telefone, URL, consulta de busca, senha.The user needs to enter a short, single-line text value: name, email, phone, URL, search query, password.
Não use quandoDon't use when
A entrada esperada é multilinha (use Textarea), o usuário deve escolher de um conjunto fixo de opções (use Select, Checkbox ou Radio), ou o valor é binário liga/desliga (use Toggle).The expected input is multi-line (use Textarea), the user must pick from a fixed set of options (use Select, Checkbox, or Radio), or the value is binary on/off (use Toggle).
| SituaçãoSituation | Use em vez dissoUse instead |
|---|---|
| Texto multilinhaMulti-line text | Textarea |
| Escolher de uma listaChoosing from a list | Select |
| Sim/não ou liga/desligaYes/no or on/off | Toggle ou Checkbox |
| Busca com autocompleteSearching with autocomplete | Componente de busca customizado (futuro)Custom search component (future) |
AnatomiaAnatomy
4
1
2
mail
3
5
We'll never share your email.
6
Please enter a valid email.
1 Wrapper (
2 Ícone (opcional,
3 Campo (
4 Label (
5 Texto auxiliar (
6 Mensagem de erro (
2 Icon (optional,
3 Field (
4 Label (
5 Helper text (
6 Error message (
.ds-input) — container com borda, radius e background.2 Ícone (opcional,
.ds-input__icon) — ícone decorativo à esquerda.3 Campo (
.ds-input__field) — o elemento nativo <input>.4 Label (
.ds-field__label) — externo, via Form Field.5 Texto auxiliar (
.ds-field__helper) — externo, via Form Field.6 Mensagem de erro (
.ds-field__error) — externa, via Form Field.
1 Wrapper (.ds-input) — container with border, radius and background.2 Icon (optional,
.ds-input__icon) — decorative leading icon.3 Field (
.ds-input__field) — the native <input> element.4 Label (
.ds-field__label) — external, via Form Field.5 Helper text (
.ds-field__helper) — external, via Form Field.6 Error message (
.ds-field__error) — external, via Form Field.
PadrãoDefault
<div class="ds-input">
<input type="text" class="ds-input__field" placeholder="Enter text...">
</div>TamanhosSizes
<div class="ds-input ds-input--sm">
<input type="text" class="ds-input__field" placeholder="Small (32px)">
</div>
<div class="ds-input ds-input--md">
<input type="text" class="ds-input__field" placeholder="Medium (40px)">
</div>
<div class="ds-input ds-input--lg">
<input type="text" class="ds-input__field" placeholder="Large (48px)">
</div>Com íconeWith Icon
search
visibility
mail
close
<!-- Leading icon -->
<div class="ds-input">
<span class="ds-input__icon material-symbols-outlined">search</span>
<input type="text" class="ds-input__field" placeholder="Leading icon">
</div>
<!-- Trailing icon -->
<div class="ds-input">
<input type="text" class="ds-input__field" placeholder="Trailing icon">
<span class="ds-input__icon material-symbols-outlined">visibility</span>
</div>
<!-- Both sides -->
<div class="ds-input">
<span class="ds-input__icon material-symbols-outlined">mail</span>
<input type="text" class="ds-input__field" placeholder="Both sides">
<span class="ds-input__icon material-symbols-outlined">close</span>
</div>EstadosStates
Error
<div class="ds-field ds-field--error">
<label class="ds-field__label" for="email">Email address</label>
<div class="ds-input ds-input--error">
<input type="email" class="ds-input__field" id="email"
value="invalid-email" aria-invalid="true"
aria-describedby="email-error">
</div>
<span class="ds-field__error" id="email-error">Please enter a valid email address.</span>
</div>Disabled
<div class="ds-input">
<input type="text" class="ds-input__field" value="Disabled input" disabled>
</div>Readonly
<div class="ds-input">
<input type="text" class="ds-input__field" value="Read-only value" readonly>
</div>Com Form FieldWith Form Field
<div class="ds-field">
<label class="ds-field__label" for="name">Full name</label>
<div class="ds-input">
<input type="text" class="ds-input__field" id="name" placeholder="John Doe">
</div>
<span class="ds-field__helper">Enter your first and last name.</span>
</div>
<div class="ds-field ds-field--error">
<label class="ds-field__label" for="email">Email<span class="ds-field__required">*</span></label>
<div class="ds-input">
<input type="email" class="ds-input__field" id="email" aria-invalid="true" aria-describedby="email-error">
</div>
<span class="ds-field__error" id="email-error">Please enter a valid email address.</span>
<span class="ds-field__helper">We'll never share your email.</span>
</div>Boas práticasBest practices
Faça
Sempre use dentro de um wrapper Form Field com um label visível.Always use inside a Form Field wrapper with a visible label.
Não faça
Usar placeholder como único label — ele desaparece quando o usuário começa a digitar.Use a placeholder as the only label — it disappears when the user starts typing.
Faça
Ajuste o tamanho do input ao comprimento esperado do conteúdo. Use largura total para emails, larguras menores para CEPs.Match the input size to the expected content length. Use full-width for emails, shorter widths for zip codes.
Não faça
Usar todos os inputs com a mesma largura independente do conteúdo.Make all inputs the same width regardless of content.
Faça
Mostre o estado de erro com
ds-input--error E ds-field--error, com aria-invalid="true" e uma mensagem de erro clara.Show error state with ds-input--error AND ds-field--error, with aria-invalid="true" and a clear error message.Não faça
Mostrar estilização de erro sem uma mensagem de erro — o usuário precisa saber o que deu errado.Show error styling without an error message — the user needs to know what went wrong.
Diretrizes de conteúdoContent guidelines
| RegraRule | ExemploExample |
|---|---|
| O texto do placeholder deve ser um valor de exemplo, não uma instruçãoPlaceholder text should be an example value, not an instruction | "john@example.com" — não "Enter your email""john@example.com" — not "Enter your email" |
| Labels devem ter 1-3 palavras, substantivo ou frase nominalLabels should be 1-3 words, noun or noun phrase | "Email address", "Phone number" |
| Texto auxiliar é opcional, use para dicas de formatoHelper text is optional, use for format hints | "Deve ter pelo menos 8 caracteres""Must be at least 8 characters" |
| Mensagens de erro devem dizer o que deu errado E como corrigirError messages should say what went wrong AND how to fix it | "Email é obrigatório. Insira um endereço de email válido.""Email is required. Enter a valid email address." |
| Campos obrigatórios: adicione indicador de obrigatório ao labelRequired fields: add required indicator to the label | <span class="ds-field__required">*</span> |
Mapeamento de tokensToken mapping
Tokens consumidos pelo componente Input em seus estados.Tokens consumed by the Input component across its states.
| PropriedadeProperty | Token (semantic) | Variável CSSCSS variable |
|---|---|---|
| background | semantic.surface.default | --ds-surface-default |
| border-color (default) | semantic.border.default | --ds-border-default |
| border-color (focus) | semantic.border.focus | --ds-border-focus |
| border-color (error) | semantic.feedback.error.border-default | --ds-feedback-error-border-default |
| text color | semantic.content.default | --ds-content-default |
| placeholder color | semantic.content.tertiary | --ds-content-tertiary |
| icon color | semantic.content.tertiary | --ds-content-tertiary |
| border-radius | semantic.radius.component | --ds-radius-md |
| focus ring | semantic.focus.ring.* | --ds-focus-ring-width, --ds-focus-ring-offset, --ds-focus-ring-color |
| height (sm) | semantic.size.control.sm | --ds-size-lg (32px) |
| height (md) | semantic.size.control.md | --ds-size-xl (40px) |
| height (lg) | semantic.size.control.lg | --ds-size-2xl (48px) |
| padding-x (sm) | semantic.space.control.padding-x.sm | --ds-space-md |
| padding-x (md) | semantic.space.control.padding-x.md | --ds-space-lg |
| padding-x (lg) | semantic.space.control.padding-x.lg | --ds-space-xl |
| font-size (sm) | semantic.typography.control.font-size.sm | --ds-control-font-size-sm |
| font-size (md) | semantic.typography.control.font-size.md | --ds-control-font-size-md |
| font-size (lg) | semantic.typography.control.font-size.lg | --ds-control-font-size-lg |
Classes CSSCSS classes
| ClasseClass | DescriçãoDescription |
|---|---|
ds-input | Elemento wrapper do inputWrapper element for the input |
ds-input__field | O elemento nativo <input>The native <input> element |
ds-input__icon | Ícone à esquerda dentro do wrapperLeading icon inside the wrapper |
ds-input--sm | Tamanho pequeno (altura 32px)Small size (32px height) |
ds-input--md | Tamanho médio (altura 40px, padrão)Medium size (40px height, default) |
ds-input--lg | Tamanho grande (altura 48px)Large size (48px height) |
ds-input--error | Estado de erro com borda vermelhaError state with red border |
ds-input--disabled | Estado desabilitado (ou use o nativo disabled)Disabled state (or use native disabled) |
ds-input--readonly | Estado somente leitura (ou use o nativo readonly)Readonly state (or use native readonly) |
ds-field | Wrapper de campo de formulário com label, auxiliar e erroForm field wrapper with label, helper, and error |
ds-field__label | Label do campoField label |
ds-field__helper | Texto auxiliar abaixo do inputHelper text below the input |
ds-field__error | Mensagem de erro (exibida quando ds-field--error está definido)Error message (shown when ds-field--error is set) |
ds-field--error | Estado de erro no wrapper do campoError state on the field wrapper |
ds-field__label-row | Linha horizontal com label e asterisco de obrigatórioHorizontal row with label and required asterisk |
ds-field__required | Asterisco * em feedback/error/default (decorativo, aria-hidden)Asterisk * in feedback/error/default (decorative, aria-hidden) |
ds-field--no-label | Oculta o label row quando Show Label = falseHides the label row when Show Label = false |
ds-field--no-helper | Oculta o helper text quando Show Helper Text = falseHides helper text when Show Helper Text = false |
Propriedades FigmaFigma properties
| PropriedadeProperty | TipoType | PadrãoDefault | DescriçãoDescription |
|---|---|---|---|
Show Label | Boolean | true | Exibe ou oculta o label row (incluindo asterisco de obrigatório)Shows or hides the label row (including required asterisk) |
Label | Text | "Rótulo" | Texto do label (label/md)Label text (label/md) |
Required | Boolean | false | Exibe o asterisco * em feedback/error/default ao lado do labelShows * in feedback/error/default next to the label |
Show Helper Text | Boolean | true | Exibe ou oculta o texto auxiliar abaixo do controleShows or hides the helper text below the control |
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 dentro / fora do inputMoves focus into / out of the input |
| Qualquer caractereAny character | Digita no campoTypes into the field |
Escape | Remove o foco (padrão do navegador)Clears focus (browser default) |
AccessibilityAccessibility
| Critério WCAGWCAG criterion | RequisitoRequirement | Status |
|---|---|---|
| 1.3.1 Info and Relationships (A) | Label associado via for/idLabel associated via for/id | ✓ |
| 1.3.5 Identify Input Purpose (AA) | Use o atributo autocomplete para campos de dados pessoaisUse autocomplete attribute for personal data fields | ✓ (when implemented) |
| 2.4.11 Focus Appearance (AA) | Focus ring 2px + offset de 2pxFocus ring 2px + 2px offset | ✓ |
| 3.3.1 Error Identification (A) | Estado de erro + mensagem via aria-invalid + aria-describedbyError state + message via aria-invalid + aria-describedby | ✓ |
| 3.3.2 Labels or Instructions (A) | Label visível sempre presenteVisible label always present | ✓ |
| 4.1.2 Name, Role, Value (A) | O <input> nativo fornece o roleNative <input> provides role | ✓ |
Resumo de atributos ARIAARIA attributes summary
for / id — sempre associe <label> com <input> usando atributos correspondentes.aria-invalid="true" — definido no input nativo quando em estado de erro.aria-describedby — vincule o input ao ID do elemento de mensagem de erro para que leitores de tela anunciem o erro.autocomplete — use valores apropriados (name, email, tel, etc.) para campos de dados pessoais.for / id — always pair <label> with <input> using matching attributes.aria-invalid="true" — set on the native input when in error state.aria-describedby — link the input to the error message element ID so screen readers announce the error.autocomplete — use appropriate values (name, email, tel, etc.) for personal data fields.
Required e label invisívelRequired and invisible label
Quando Required = true, adicione aria-required="true" no <input> — o asterisco visual (.ds-field__required) é decorativo (aria-hidden="true"). Quando Show Label = false, use aria-label no <input>. O Helper Text deve ser vinculado via aria-describedby.When Required = true, add aria-required="true" to the <input> — the visual asterisk (.ds-field__required) is decorative (aria-hidden="true"). When Show Label = false, use aria-label on the <input>. Helper Text should be linked via aria-describedby.