Field State Matrix

Decide once how every field looks and behaves in every state, before screens improvise.

moderate Forms & Input

What it adds

A defined and documented set of visual and behavioural states covering every input type in the app.

What your agent is told to do

1
Enumerate the app's input types and cross them against every state they can enter: empty, filled, focused, hovered, invalid, valid, disabled, read-only, loading, and browser-autofilled.
2
Define disabled and read-only as genuinely different states — a read-only field shows a real value the user may select and copy, a disabled field is inert and excluded from submission.
3
Define the loading state so the field is visibly busy and not editable, and say what happens to a keystroke that arrives mid-load rather than letting it be silently swallowed.
4
Specify what happens to user input when the server rejects a submission: the values stay, the field is marked invalid, and the message names the field's own problem.
5
Do not encode any state in colour alone. Invalid, disabled, and busy each need a second signal — an icon, text, or a border treatment — because a colour-blind user reading a red border sees a border.

Edge cases it handles

Disabled and read-only are routinely conflated; the difference matters because a read-only value is often the thing the user came to copy, and a disabled field is excluded from the submitted payload.
A rejected submission must never blank the form. Losing twenty fields of typed input because the server returned a validation error is the single worst failure this matrix exists to prevent.
A field in the loading state must be non-editable and must show it, because a value typed into a field that is about to be overwritten by a server response is lost without warning.
The browser's autofill styling overrides the app's background and text colours and must be handled explicitly, or autofilled fields will look broken in the dark theme.
Every combination that can co-occur needs a defined result — invalid and disabled, filled and read-only, focused and busy — rather than whichever style happens to be declared last.
State changes must be exposed programmatically as well as visually, so a field that becomes invalid or disabled is reported to assistive technology.
This entry defines the states; the structure that renders label, description, and error around them belongs to Form Field Shell, and the required marker to Required Field Indicator.

Definition of done

Every input type has a defined rendering for empty, filled, focused, hovered, invalid, valid, disabled, read-only, loading, and autofilled.
Disabled and read-only differ visually and behaviourally, and only one of them submits a value.
A rejected submission returns with the user's input intact and the offending fields marked.
Loading fields are visibly busy and reject input.
Autofilled fields respect the app's theme in both light and dark.
No state is signalled by colour alone, and every state change is exposed to assistive technology.
The feature matches the existing design system.
No existing functionality is broken.

Related features

Unit Converter

Code Editor Field

Voice Dictation

How it works

1

Copy the link

Grab the Markdown instruction URL for this feature.
2

Give it to your AI

Paste it into Claude Code, Cursor, v0, Lovable — whatever you build with.
3

It inspects, then implements

Your agent reads your existing app first, then adds the feature to fit it.

Works with your stack

These instructions are written to adapt. They tell the agent to detect your framework, match your existing design system, and reuse what you already have — rather than assuming a particular stack.

Need it tighter than that? Customize the feature and tell it exactly what you're running.