Documentation

Validation

Build clear, consistent form feedback that helps users recover quickly and complete tasks.

Core Principles

  • Always pair inline field errors with a form-level error summary on submit.
  • Show errors after interaction, not on first render.
  • Use specific error text that tells users what to change.
  • Do not clear entered values when validation fails.

Field State Matrix

All fields should explicitly define these states: Default, Error Found, and Disabled.

Default
Error Found
Disabled

Input

As shown on ID.

Enter an email address in the correct format

Optional

Textarea

Keep this concise.

Add at least 2 clear steps

Read only in this step.

Checkbox

Required before submission.

You must accept the terms to continue.

Managed automatically by the system.

Message Hierarchy

Helper

Token: text-muted-foreground

Use before interaction to clarify what users should enter.

Success

Token: text-success

Use after criteria are met and confirmation improves confidence.

Warning

Token: text-warning

Use for non-blocking risk where users can still continue.

Error

Token: text-destructive

Use for blocking issues and include the exact next action.

Content Quality

Do

  • Start with an action: “Enter your email address”.
  • Match wording to the field label.
  • Use specific errors (format, length, missing value).

Avoid

  • Generic text like “An error occurred”.
  • Blameful language (“you forgot”, “invalid user”).
  • Reliance on color alone without text cues.

When to Validate

On blur

Default for most fields. Validate after users leave a field.

On submit

Show form-level summary and focus the first invalid field.

Live validation

Use only for high-risk or format-critical inputs.

Accessibility Checklist

  • Link helper/error text to fields using aria-describedby.
  • Set aria-invalid="true" when a field fails validation.
  • Add a visible and programmatic error indicator (for example, “Error:” prefix).
  • Use a form-level alert region for submit-time summaries.