Forms

The form family covers the field shell that wraps every input, form-scope feedback, and compound form patterns. Three layers build on each other: the Field family handles a single label/control/message stack; FieldGroup composes multiple fields with consistent spacing and responsive orientation support; FormMessage renders non-field (form-scope) errors as a consolidated Alert.

Token surface: Color palette: light tokens.css-token:border, Color palette: light tokens.css-token:destructive, Color palette: light tokens.css-token:muted-foreground, Color palette: light tokens.css-token:ring, Semantic radius tokens.css-token:vueda-control-radius.

This page is the visual contract the default theme guarantees. Use it as the target spec when you re-skin: every cell shown here should still read as the same surface after a customization, even if its color, density, or spacing shifts. If a cell breaks, the change has crossed from skin into design language.

For the mechanics of overriding any of this, see Customize VUEDA Appearance. Values belong in CSS tokens; compositions belong in theme keys.

Field shell: anatomy

Field is the layout container. It groups a FieldLabel, a FieldContent column (which holds the control, optional FieldDescription, and any FieldMessage), and an optional required indicator. The orientation prop switches between vertical (default), horizontal, and responsive.

Theme keys: Field, FieldLabel, FieldContent, FieldDescription.

Field: validation states

FieldMessage handles both error and warning severity beneath the control. Error messages render in text-destructive; warning messages render in amber. Multiple messages automatically switch to a bulleted list. The invalid border on the input (aria-invalid="true") comes from the Input theme key, not the field shell.

Theme keys: FieldMessage. Token surface: Color palette: light tokens.css-token:destructive.

Form-level feedback

FormMessage renders non-field (form-scope) errors as a single Alert. When multiple messages arrive, they appear as a list inside one Alert rather than a stack of separate alerts. The type="message" prop switches the Alert variant to warning for non-blocking feedback.

Theme key: FormMessage. Token surface: Color palette: light tokens.css-token:destructive, Color palette: light tokens.css-token:warning.

Long-form layout: new customer

Section headers and a 2-column grid compose multi-section forms. A vk-form-section-title header groups related fields, and a divider separates sections. Repeating contact rows (FieldSet machinery) belong with the ObjectsGrid pass.

Auth patterns

Auth forms use a centered card on a flat neutral surface. The login form uses a w-[35rem] card with standard field layout. The authorizing form (2FA, change password) uses the same card in a narrower configuration. Both are composed from the same field primitives as any other form — the difference is only the page shell.

ActionForm: bulk action panel

ActionForm sits inline above the list of selected records — no overlay, no drawer. It frames a summary of the action, the affected records, and confirm/cancel buttons. The theme keys map 1:1: root, inner, list, buttons. The form-scope feedback block (for dry-run failures) uses the same consolidated Alert pattern as any other form.

Customization surface

The field shell is the most frequently customized part of VUEDA's theme. The highest-value keys for structural change are:

• Field: root — gap between label and content, flex direction per orientation, invalid color cascade.
• FieldLabel: root — font-weight, size, checked-state highlight on inline checkbox/radio labels.
• FieldContent: root — gap between control, description, and message lines.
• FieldDescription: root — text color, size, link decoration.
• FieldMessage: root — error text color; list — multi-message bullet list layout.
• FormMessage: root — margin around the consolidated Alert; list — list layout inside Alert.
• FieldGroup: root — gap between fields, container-query scope for responsive orientation.