form-design

Original：🇺🇸 English

Translated

Forms have three layers of guidance: helper text below the input explains what to enter, placeholder shows the expected format, and validation confirms correctness. Real-time validation for complex inputs. Submit enables only when the form is valid. Use when designing or reviewing any form, input field, or data entry UI.

4installs

Sourcedembrandt/dembrandt-skills

Added on2026-05-28

NPX Install

npx skill4agent add dembrandt/dembrandt-skills form-design

SKILL.md Content

View Translation Comparison →

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:

html

<button type="submit" disabled={!isFormValid}>Submit</button>

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 ]

html

<div class="field">
  <label for="vat">VAT number <span class="optional">Optional</span></label>
  <input
    id="vat"
    type="text"
    placeholder="FI12345678"
    aria-describedby="vat-helper vat-error"
    aria-invalid="true"
  >
  <p id="vat-helper" class="helper-text">Finnish VAT numbers start with FI followed by 8 digits.</p>
  <p id="vat-error" class="error-text" role="alert">Enter a valid Finnish VAT number (e.g. FI12345678).</p>
</div>

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

html

<label>Email <abbr title="Required">*</abbr></label>
<!-- or -->
<label>Phone <span class="badge">Optional</span></label>

Grouping with Fieldset

Related fields belong in a

<fieldset>

with a

<legend>

. This is semantic HTML and helps screen readers announce the group context.

html

<fieldset>
  <legend>Billing address</legend>
  <label>Street</label><input type="text">
  <label>City</label><input type="text">
  <label>Postal code</label><input type="text">
</fieldset>

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.

html

<input type="text"  autocomplete="name">
<input type="email" autocomplete="email">
<input type="tel"   autocomplete="tel">
<input type="text"  autocomplete="street-address">
<input type="text"  autocomplete="postal-code">
<input type="text"  autocomplete="cc-number">    <!-- credit card -->
<input type="password" autocomplete="new-password">

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
```
<fieldset>
```
with
```
<legend>
```
Correct
```
type
```
attribute on all inputs
```
autocomplete
```
attributes set on address, contact, and payment fields

form-design

NPX Install

Tags

SKILL.md Content

Form Design

The Three Guidance Layers

Layer 1 — Helper Text

Layer 2 — Placeholder

Layer 3 — Validation

Submit Button State

Field Anatomy

Required vs Optional

Grouping with Fieldset

Input Types

Autofill Support

Review Checklist