# Form controls

Form controls share label, help, error, disabled, loading, and focus behavior even when their runtime implementations remain application-owned.

## Text and multiline input

- Keep a persistent visible label.
- Place help or validation text directly after the control and connect it with `aria-describedby`.
- Use a textarea for meaningful multiline content; do not make a single-line input visually taller.

## Choice controls

- **Checkbox:** select any number of independent options.
- **Radio group:** choose exactly one option from a visible, small set.
- **Switch:** change an immediately applied binary setting. Do not use a switch for values that only take effect after Save.
- Make the entire label row clickable and include explanatory text when the consequence is not obvious.

## Date and time

The canonical date picker follows the established Superviso pattern: a localized text field, a calendar button inside the trailing edge, and a calendar popup aligned below the field.

### Field anatomy

- Keep the label visible and use a text field so the displayed date can follow the user's locale.
- Place a calendar icon button inside the trailing 40px of the control. Give it the accessible name `Pick date`.
- Opening the field or icon displays the popup and focuses the selected date, or today when no value exists.
- Store an unambiguous `YYYY-MM-DD` value even when the field displays a localized value such as `August 9, 2026`.
- Allow typed input when practical. Validate on commit and keep the error directly below the field.

### Calendar popup

- Use `--calendar-width` (288px), seven equal columns, and `--calendar-cell-size` (32px).
- The header contains Previous month, the visible month and year, and Next month.
- Weekday labels are concise and localized. A full accessible date name belongs on every day button.
- Outside-month dates remain available but use subdued text.
- The selected date uses the inverse filled treatment. Today receives a secondary structural marker when it is not selected.
- Close after selection, outside click, or Escape, and return focus to the field or trigger.

### Keyboard

- Arrow Left and Right move one day; Arrow Up and Down move one week.
- Home and End move to the start and end of the current week.
- Page Up and Page Down move one month while retaining the day when possible.
- Enter or Space selects the focused day. Escape closes without changing the value.

### Responsive and product boundary

- Keep the popup within the viewport. On narrow screens, align it to the available edge without shrinking day targets below 32px.
- Date ranges need explicit From and To labels and independent accessible names.
- Product-specific disabled dates, scheduling rules, timezone conversion, month/year jump views, and runtime libraries remain application-owned.

## Files and attachments

- State accepted file types and maximum size before selection.
- Keep the chosen filename visible and allow replacement or removal before submission.
- Upload progress belongs to the file row, not a global spinner.
- Validation identifies the affected file and preserves other selected files.

## Identity and tags

- Identity controls pair an avatar or initials with a primary name and optional secondary identifier.
- A status badge communicates state; a tag classifies a record; a removable chip represents user input or an active filter.
- Never use a removable chip as a passive status label.