Spec — Text fields

Facet Visual do Koder Design. Material parity: https://m3.material.io/components/text-fields.

2 variants

Pick one per surface — don't mix in the same form.

Anatomy

[leading icon?]  Label (floating)         [trailing icon?]
                                          [counter?]
┌──────────────────────────────────────────────────────┐
│  [icon?]  Input value here                  [icon?]  │
└──────────────────────────────────────────────────────┘
  Helper text or error message      [chars/max]

• Container: 56 px height (default), 48 px (compact)
• Label: body-large floating (above when focused/filled)
• Input text: body-large
• Helper / error: body-small below
• Counter: body-small right-aligned below (when maxLength)
• Icons: 24 px, leading + trailing optional

R1 — Label behavior

Two label modes:

1. Floating (default) — label sits inside container at rest; floats up when focused or has value
2. Always-above — label permanently above the container

Floating is Material standard; always-above is gnome/carbon_ibm preset convention.

R2 — States

Per interaction/states.kmd:

R3 — Single-line vs multi-line

• Single-line: 56 px height default, scrolls horizontally
• Multi-line: starts at 56 px, grows to a max (configurable; default max 5 lines), then scrolls vertically inside
• <input type="text"> vs <textarea> semantics in HTML

R4 — Specialized input types

R5 — Helper text + error

Below the input container, single line:

Filled state:    "Used for sign-in and password reset"   (text-muted)
Error state:     "Email must include @"                  (error color)
Filled + counter:"123/200"                               (text-muted, right)

When error: helper text replaced by error message. Both styled with body-small role. Error must be associated via aria-describedby linking input → error element.

Error format per errors/user-facing-messages.kmd: humanized, specific, no "Invalid" / "Wrong".

R6 — Validation

NEVER validate on first keystroke for format-based rules (annoying; "a" → "Invalid email" before user can type more).

R7 — Leading + trailing icons

• Leading icon: signals input type (mail icon for email, search icon for search) — decorative, no interaction
• Trailing icon: actionable (clear X, show/hide password, voice input mic, calendar picker open) — <button> element with aria-label

Tap target on trailing icon: 24 px visible, 40 px hit zone.

R8 — Accessibility

• <label for="id"> connection MANDATORY (or aria-label/aria-labelledby)
• Helper text linked via aria-describedby
• Error linked via aria-describedby + aria-invalid="true" on the input
• Required fields: aria-required="true" (don't rely on * alone)
• Autocomplete attribute set for personal data (email, name, address)
• Screen readers announce label → value → state on focus

R9 — Forbidden patterns

• ❌ Input without visible label (placeholder is NOT a label)
• ❌ Placeholder containing format example ("user@example.com") shown only until user types — use helper text instead (or both)
• ❌ Custom validation messages that contradict spec (errors/user-facing-messages.kmd)
• ❌ Inputs that look like text but aren't focusable (use a real <button> if action)
• ❌ Disabling submit until valid (use clear error reveal on submit instead)

R10 — Per-preset variation

Cross-link

• interaction/states.kmd — hover/focus/error visuals
• themes/color-roles.kmd — accent / error / text-muted bindings
• errors/user-facing-messages.kmd — error message format
• foundations/ux-writing.kmd — label + helper text style
• foundations/elements.kmd — Control family