Form Design

Form Design

Forms are where users give the product data. Every unnecessary obstacle between the user and a completed form is a failure. The design goal is to make correct input easy and incorrect input obvious — before the user submits.

---

The Three Guidance Layers

Each layer serves a distinct purpose. Do not collapse them.

Layer 1 — Helper Text

Explains what to enter. Appears below the input, always visible, in small secondary text.

Email address
[                              ]
Use the email you signed up with.

• Write in plain language from the user's perspective
• Keep it to one sentence — if you need more, the field is too complex or misnamed
• Do not repeat the label ("Enter your email" below a label that says "Email" is redundant)
• Helper text is not a replacement for a label — the label is still required

Layer 2 — Placeholder

Shows the format or an example value. Appears inside the input, disappears on typing.

[jane@example.com              ]

• Use a realistic example, not a description: +358 40 123 4567 not Enter phone number
• Never use placeholder as a label — it disappears and leaves the user without context
• Keep it grey (--color-text-secondary) and lighter than actual input text
• Optional — not every field needs a placeholder

Layer 3 — Validation

Confirms whether the input is correct. The most important layer.

Email address
[jane@           ] ← invalid
✗ Enter a valid email address.

Validation timing:

• On blur (leaving the field): default for most fields — validates once the user has finished
• Real-time (on input): use when the format is complex or the error is likely — password strength, IBAN, VAT number, URL, regex-heavy fields
• On submit: catches anything missed, scrolls to the first error

Real-time validation must be forgiving at the start — do not show an error the instant the user starts typing. Show it after a short debounce (300–500ms) or after the first character that makes the input definitively wrong.

---

Submit Button State

The submit button enables when the form is valid. This is one of the clearest affordance signals in form design — the user sees the goal and knows when they have reached it.

[Submit]   ← disabled, low contrast, cursor: not-allowed
           (fields incomplete or invalid)

[Submit]   ← enabled, full colour, cursor: pointer
           (all required fields valid)

Implementation:

Submit

For long or complex forms where real-time validation is not practical, do not disable the submit — validate on submit and scroll to errors instead. Disabled submit on a long form frustrates users who cannot tell what is missing.

Loading state on submit: Replace label with spinner, disable the button. Prevent double-submission.

---

Field Anatomy

[Label]                           [Optional badge if optional]
[Input field                                                  ]
[Helper text — what to enter, format, constraints            ]
[Error message — appears below helper text on validation fail ]

  VAT number Optional
  
  Finnish VAT numbers start with FI followed by 8 digits.
  Enter a valid Finnish VAT number (e.g. FI12345678).

---

Required vs Optional

Mark the minority. If most fields are required, mark the optional ones. If most are optional, mark the required ones.

• Do not rely on colour alone — add a text label ("Required" or asterisk with legend)
• Place the required/optional indicator in the label, not only in the placeholder or helper text

Email *

Phone Optional

---

Grouping with Fieldset

Related fields belong in a ` with a `. This is semantic HTML and helps screen readers announce the group context.

  Billing address
  Street
  City
  Postal code

Use fieldsets for:

• Address groups
• Payment details
• Radio button groups
• Checkbox groups

---

Input Types

Use the correct type — browsers provide free validation, appropriate keyboards, and autofill.

| Data | Input type | |---|---| | Email | type="email" | | Phone | type="tel" | | URL | type="url" | | Number | type="number" | | Password | type="password" | | Date | type="date" | | Search | type="search" | | Colour | type="color" |

On mobile, type="email" shows the email keyboard, type="tel" shows the numpad. These are free UX improvements.

---

Autofill Support

Allow browsers to autofill. Do not disable it unless there is a security requirement.

Correct autocomplete values reduce friction dramatically for returning users and on mobile.

---

Review Checklist

• [ ] Every field has a visible label (not just placeholder)
• [ ] Helper text is below the input and explains what to enter
• [ ] Placeholder shows format or example, not a description
• [ ] Validation triggers on blur for simple fields, real-time for complex ones
• [ ] Error message is adjacent to the field that failed
• [ ] Error message is associated via aria-describedby
• [ ] Required/optional marked on the minority of fields
• [ ] Submit button is disabled when form is invalid (for short forms)
• [ ] Submit button shows a loading state and prevents re-submission
• [ ] Related fields are grouped in ` with `
• [ ] Correct type attribute on all inputs
• [ ] autocomplete attributes set on address, contact, and payment fields

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: dembrandt
• Source: dembrandt/dembrandt-skills
• License: MIT

Install and usage instructions live in the source repository linked above.