forms

name	forms
description	Design, structure, or improve form interfaces for clarity, completion rates, and user confidence. Use when the user asks to build a form, redesign a form flow, improve form conversion, add multi-step forms, fix form UX, or structure field layouts and validation.
metadata	{"argument-hint":"[form or flow]"}

Build forms that users complete without confusion, anxiety, or abandonment. The goal is not to collect every possible field; it is to remove every unnecessary obstacle between the user and their goal.

Consult the form validation patterns reference for validation timing, error placement, multi-field dependencies, async validation, recovery design, conversion measurement, field-level drop-off, and field-by-field optimization guidance. Consult the live validation UX reference for blur-vs-real-time timing, reward-early/punish-late behavior, and copy-paste-friendly validation. Consult the error recovery reference for what happens after validation or submission fails. Consult the disabled buttons UX reference when deciding whether to block submit buttons or keep them enabled with error explanation. Consult the component anatomy reference for button, input, checkbox, radio, toggle, dropdown, and textarea anatomy guidance. Consult the self-evident interface design reference when a form depends on too much helper text, instructions, or onboarding; prefer clearer grouping, defaults, constraints, examples, and inline feedback.

MANDATORY PREPARATION

Users start this workflow with /forms. Once this skill is active, load $frontend-design — it contains design principles, anti-patterns, and the Context Gathering Protocol. Follow that protocol before proceeding — if no design context exists yet, you MUST load $setup first. Additionally gather: what goal the user is trying to achieve, which fields are truly required, and what causes abandonment in the current flow.

Assess Form Needs

Understand the form's purpose and context:

1. User goal: What does the user get by completing this form? The clearer the payoff, the higher the completion rate.
2. Field necessity: Every field you add drops completion rates. Challenge each field: is it required now, or can it be collected later?
3. Context of use: Is the user rushed, distracted, using a compact viewport or coarse pointer, or in a stressful situation? Stressful contexts need simpler forms.
4. Failure points: Where do users currently drop off? Long forms, unclear labels, and unexpected validation are common culprits.
5. Data use: Which fields are actually used after submission? If sales, support, or onboarding does not use a field, remove it, infer it, or collect it later.
6. Measurement: Do analytics show form views, first field focus, field completion, validation errors, submit attempts, successful submissions, and mobile vs desktop completion?

Form Structure

Field order

• Ask easy questions first to build momentum
• Group related fields visually (name fields together, address fields together)
• Place optional fields at the end or mark them clearly
• Separate billing and shipping only when they are genuinely different

Label design

• Use clear, scannable labels above the input (not inside as placeholder text)
• Sentence case is easier to read than Title Case
• Be specific: "Card number" not "Payment info"
• Helper text should explain format requirements, not repeat the label
• Before adding helper text, ask whether input type, width, placeholder example, prefix/suffix, default, or grouping can make the field self-evident

Input design

• Match input width to expected content (postal code fields should not be full-width)
• Use the appropriate input type (type="email", type="tel", type="date") for better browser keyboards, autofill, and validation hints
• Show formatting hints as the user types (credit card spacing, phone number grouping)
• Autofill-friendly: use standard name and autocomplete attributes
• Use field-specific affordances: email typo suggestions, phone country handling, searchable selects for long option lists, radio buttons for fewer than five choices, and expandable textareas for longer messages
• Normalize browser autofill visuals when custom input surfaces are dark, translucent, or heavily branded. Use Tailwind utilities for the normal field state first, then add a small CSS layer for browser pseudo-classes that Tailwind cannot express cleanly:

@import "tailwindcss";

@layer components {
  .input:-webkit-autofill,
  .input:-webkit-autofill:hover,
  .input:-webkit-autofill:focus,
  .input:-webkit-autofill:active {
    border-color: color-mix(in oklab, white 40%, transparent);
    caret-color: var(--color-white);
    -webkit-text-fill-color: var(--color-white);
    -webkit-box-shadow: 0 0 0 1000px color-mix(in oklab, white 20%, transparent) inset;
    transition: background-color 5000s ease-in-out 0s;
  }

  .input:autofill {
    border-color: color-mix(in oklab, white 40%, transparent);
    caret-color: var(--color-white);
  }
}

:-webkit-autofill covers Chromium and Safari. :autofill is the standards-facing selector for compatible browsers. Keep both, include hover/focus/active, and test actual saved-password and saved-address flows instead of trusting static screenshots.

Multi-step forms

Break long forms into steps when:

• There are more than 6-8 fields
• The form covers distinct topics (account info, payment, confirmation)
• Users need to review before final submission

Step design:

• Show progress ("Step 2 of 4") so users know what remains
• Allow navigation back to previous steps
• Preserve entered data if the user leaves and returns
• Validate each step before allowing progression, but do not block navigation backward

Conversion-sensitive forms

When a form captures a lead, demo request, quote request, application, or checkout intent:

• put the value proposition immediately above or beside the form
• state what happens after submit, including response time when relevant
• start with low-friction fields such as email or name before sensitive fields
• ask phone, company size, budget, or detailed requirements only when they materially improve follow-up
• use progressive profiling for returning users instead of asking everything up front
• add privacy assurance near sensitive fields, not buried in a footer
• offer alternative contact paths when the form is high intent, such as chat, email, phone, or calendar booking

Validation Strategy

Timing

• Validate on blur for clearly completed fields (email, phone, format-required fields)
• Validate on input only for immediate feedback that helps (password strength, character count)
• Validate on submit for everything else, especially cross-field dependencies
• Never validate a pristine field; it creates anxiety

Error design

• Place error messages directly below the field
• Explain what went wrong and how to fix it
• Use aria-invalid and aria-describedby for screen reader association
• Preserve all user input when validation fails
• Move focus to the first error after failed submission

Success states

• Subtly confirm valid fields with a checkmark or green border
• Remove success indicators when the user edits the field again
• Do not celebrate every valid field; it becomes noise

Responsive Form UX

• Ensure coarse-pointer targets are at least 44×44px
• Use appropriate input types for optimized keyboards
• Minimize scrolling by breaking into steps or using progressive disclosure
• Show the numeric keyboard for number fields, email keyboard for email fields
• Avoid dropdowns for short lists; use radio buttons or segmented controls instead

Accessibility

• Associate every input with a label using for/id
• Use fieldset and legend for grouped fields
• Announce form-level errors with role="alert" or aria-live="polite"
• Ensure error messages are programmatically associated with fields
• Test keyboard navigation through the entire form
• Do not rely on color alone for error indication

Anti-Patterns

• Too many fields: Every additional field reduces completion rates
• Placeholder as label: Disappears when the user types; bad for memory and accessibility
• Validate on load: Pristine fields showing errors feel accusatory
• Vague errors: "Invalid input" without explanation leaves users guessing
• Clearing fields on error: Losing typed data is deeply frustrating
• Disabled submit without guidance: A grayed-out button with no visible errors is a dead end
• Multi-step without progress indicator: Users do not know how much remains
• Inconsistent validation timing: Some on blur, some on submit, with no clear logic
• Ignoring input semantics: Using type="text" for phone numbers prevents browsers from showing the best available keyboard and autofill behavior
• No save-and-resume: Long forms that cannot be saved mid-progress punish interruptions

Verify Form Quality

Before shipping:

• Every field is justified; optional fields are clearly marked
• Labels are clear, specific, and above the input
• Validation does not trigger on pristine fields
• Errors explain what went wrong and how to fix it
• Input is preserved when validation fails
• Focus moves to the first error after failed submission
• Multi-step forms show progress and allow backward navigation
• Browser keyboards, autofill, and validation hints are optimized per field type
• The form is fully keyboard-navigable
• Color is not the only indicator of error or success