F Kitchen Sink

UX audit rules

Form labels and error summary

Rule handbook metadata

Rule
DET.FORM.LABEL_ERROR_SUMMARY · lane deterministic
Page status
current
page_version
ff733229fa88cc37c75e966866c1f02f28af0b0ff4bf873f3065ae00584bd0d3
generated_at
2026-08-13T02:31:57.071Z
registry_fingerprint
aef1de6082cf0f50d463783c843dee0ffb9132fbd5ed4ea6e5bb3f031f359c72

How this rule is fixed

Pilot deterministic fixer: plan_only · harness mode standalone · verify expect_rule_clean.

See fixer module for plan_only in lib/ux-deterministic-fixers/.

Detection module: docs/design/ux-audit/deterministic-design-rules.md#det-form-label-error-summary. Scroll down for Before / After examples and Evidence and remediation steps.

Purpose

Governed enterprise forms must not rely on placeholder-only labels or scattered inline errors alone. Operators need visible labels, field-level errors tied to inputs, and on multi-field submit failures an error summary region listing what to fix—especially in ForgeGovernedForm / Swz flows (ENT.APP.04).

Passing signals

  • Every required input has a visible <label> or aria-label / aria-labelledby.
  • Required fields are marked in text—not color alone.
  • Invalid fields set aria-invalid="true" and reference error text via aria-describedby.
  • On failed submit, a summary region (e.g. role="alert" or aria-live="assertive") lists errors with links or focus moves to the first invalid field.
  • Primary submit stays enabled only when validation policy allows; disabled submit shows reason (DET.APP.DISABLED_REASON).

Failing signals

  • Placeholder text is the only label.
  • Errors appear only in a toast with no field association.
  • Multiple invalid fields with no summary heading on submit.
  • Error text conveyed by border color only.
  • Summary duplicates toast but fields lack aria-describedby.

Before example

Before (failing example)

Invalid amount

After example

After (passing example)

Cost center is required.

Amount must be a positive number.

Evidence and remediation

  • DOM: count inputs without labels; detect submit without #form-errors-summary or equivalent when ≥2 aria-invalid.
  • Remediation: use createFormController + Swz step validation; add summary region at form top; wire DET.APP.DISABLED_REASON on gated submit.
  • ENT.APP.04 contract: docs/design/enterprise-app/rules/ENT.APP.04.yaml.
  • Run tools/website-ux-auditor/auditor-tests/invoke-det-ruleset-harness.sh --only-rule DET.FORM.LABEL_ERROR_SUMMARY when harness wired.