Files
bible/rules/patterns/forms-validation/contract.md
T

2.1 KiB

Contract: Forms + Validation + Suggestions

Version: 1.2

This contract owns validation UX and multi-step flow rules for all form surfaces, including modals (modal-workflows adds only modal-specific mechanics).

Form Structure

  • Group fields semantically and keep labels explicit.
  • Inputs requiring suggestions may use datalist or equivalent autocomplete UI.
  • Suggestion sources must represent the full relevant scope (not only visible rows from paginated tables).
  • Size fields by expected content: a short identifier/date beside a flexible name field is preferable to equal-width columns. Align read-only metadata with adjacent editable values.
  • Group editable child rows under the requirement/parent they satisfy, with indentation or light connector lines. Label row controls even when repeated visible labels are omitted.
  • Collapse field groups on narrow screens; retain horizontal scrolling for genuinely tabular child editors. A fixed desktop width must not make the Save action unreachable.

Validation

  • Validate on submit server-side. Client-side validation is optional progressive enhancement only.
  • Surface validation errors inline near fields and in a form-level summary when helpful.
  • Validation messages must be human-readable and action-oriented: "Serial number is required" — not "serial_number: cannot be null".
  • Do not hide required-field errors behind generic submit failures.

Multi-Step Flow

Recommended stages:

  1. edit
  2. review
  3. confirm/submit
  4. result

Rules:

  • Users must be able to return from review to edit without losing entered values.
  • The confirm step must summarise what will happen before a destructive or irreversible action.
  • Destructive or irreversible actions require explicit confirmation.
  • Query- or state-driven step transitions should be deterministic and testable.

File Inputs in Forms

  • If a workflow includes upload, the file control should be clearly labeled and the supported formats explicit.
  • Import parsing/preview may be delegated to a dedicated import/export pattern, but the form contract must remain clear.