The Field Kit

Codex: The Form

The mechanics, in one place

Hierarchy

A form has a structure and the spacing should say it before any label is read. Sections separated by the large gap; fields inside a section by the medium gap; label, input, helper and validation as one unit with the small gap. Field groups (first/last name; country/postcode; street/apartment) sit tighter than unrelated fields, same row where possible.

Validation

Validation is the outcome layer of the feedback contract, applied to a field.

When it fires. On blur is the default: the person finishes the field, moves on, and learns at once while it's still in attention. On change for fields where real-time help is genuine (password strength, character counter, a slug previewing its URL), never for fields that always look invalid mid-typing (an email). On submit is the last resort: the whole form, then a list at the top, the context gone.

Where it appears. Beside the field that caused it, below it, in its column, replacing or next to the helper text, with the field's state changed visibly. Not at the top. Not in a toast.

What it says. What happened and what to do. Enter an email in the form name@example.com, not Invalid input. Test: can the reader immediately know what to type? (See The System's Voice.)

Progressive disclosure

Show a field only when its condition is true; hidden-until-relevant beats disabled-until-relevant, which beats always-visible. For long forms, reveal section by section, but never hide the scope: the person should always know roughly how much remains, or the form has become a dark pattern. Smart defaults (locale → country, today's date, remembered values) are disclosure too: the probable answer, offered for confirmation.

Dependencies

When a controlling field changes (country), dependent fields (region) must update their options, clear values that are no longer valid, and say so, with a brief indicator or highlight. The silent cascade is the common failure: the region clears, nothing signals why, the person reselects an invalid value and learns at submit.

The submit button

Three promises. Label: the person's verb, never Submit (Create account, Send message, Save changes). State: disabled while the form isn't ready, and never silently; say why (Complete the required fields to continue). Feedback: acknowledge on click (loading state), then the outcome. The first click always produces a visible response.

Multi-step forms are navigation

Each step with its own address, so a person can return to it, share it, and use Back to go back a step. Inputs persist between steps; Back never means "start that step over". Progress indicators tell the truth: never Step 2 of 5 when conditional steps 6–8 are waiting.

Judged by someone outside

When the object a form makes will be judged by something outside the product (a WhatsApp template goes to Meta for approval; a subject line meets a spam filter; a listing must clear a marketplace's policy), the form is also a compliance surface. Teach the rules in place while the object is being built: the character limit as a live counter in the field, variable syntax inline where variables go, the policy boundary as a warning that wakes as the person approaches it. Never a rejection an hour later that doesn't say what to change.

Mixed screens

Most real screens mix the two kinds per field. A job posting's salary and location are plain data; its description wants a live preview because how it renders changes how it should be written. Choose per field, on purpose: live-edit the fields with visible consequences, plain inputs for the rest. The mistake is defaulting the whole screen to one habit.

Before designing a single field

1. What is the output: a thing, a state, or an event? Does the person need to see it while making it? 2. What's the scope: how many fields, sections, steps; what's the minimum honest ask? 3. What are the dependencies, and how are cascades shown? 4. What are the constraints (limits, formats, valid sets, outside judges), and are they taught in place? 5. When does validation fire, where does it appear, what does it say? 6. The submit button's label, disabled logic, and feedback. 7. Is this navigation? Steps, addresses, what persists. 8. What input does each field earn, by task not by resemblance? 9. Which fields are siblings, which share a section, which gap does each get?