# Field State Matrix

## Objective

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

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

## Before You Begin

This feature is being added to an application that already exists and already
works. Do not scaffold a new project, and do not assume a blank slate.

Inspect the codebase first and establish:

- The existing application structure and where code of this kind already lives.
- The framework and version in use.
- The existing design system — colours, spacing, typography, and component conventions.
- Existing UI components you can reuse instead of writing new ones.
- The existing database structure, if this feature needs to persist anything.
- The existing authentication and authorization system, if this feature is user-scoped.
- Dependencies already installed, so you don't add a library that duplicates one.
- The existing test setup and conventions.

Only start writing code once you understand the above. If the application
already implements part of this feature, extend it rather than replacing it.

## Implementation Instructions

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.

## UI and UX Requirements

Match the application's existing design system exactly. Reuse its components,
spacing, and typography. This feature should look like it was always there.

## Responsive Requirements

Works on mobile, tablet, and desktop. Touch targets are large enough to hit on a
phone, and nothing overflows horizontally at 320px.

## Accessibility Requirements

- Fully keyboard navigable.
- Correct semantic elements and ARIA roles.
- Visible focus states.
- Meets WCAG AA contrast.
- Dynamic changes are announced to screen readers.
- Respects prefers-reduced-motion.

## Edge Cases

- 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.

## Testing

Exercise the feature end to end in the running application. Cover every edge case
above, then run the existing test suite and confirm nothing regressed.

## Acceptance Criteria

- [ ] 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.

## Adaptation Rules

- Match the existing design system. Do not introduce a new colour palette,
  spacing scale, or component library.
- Reuse existing components and utilities wherever they fit.
- Follow the naming, file layout, and code style already present.
- Do not upgrade, replace, or remove existing dependencies to make this
  feature fit. Adapt the feature to the app, not the app to the feature.
- Do not break existing functionality. If a change is genuinely required in
  existing code, make the smallest one that works and say so.
- If something in these instructions conflicts with how the application is
  built, follow the application and explain the deviation.

## Final Verification

Before you report the work as done:

1. Re-read the acceptance criteria above and check each one against what you
   actually built.
2. Run the application and exercise the feature end to end.
3. Run the existing test suite and confirm you have broken nothing.
4. Check the feature on mobile, tablet, and desktop widths.
5. Check keyboard navigation and focus handling.
6. Summarize what changed: files added, files modified, and anything you
   deliberately did differently because of how this application is built.

If any acceptance criterion is unmet, fix it before reporting completion.