# Contact Form

## Objective

Give visitors a reliable way to reach you that does not lose their message.

A public contact form that stores each submission as a record and emails a notification, with spam filtering and an admin view of past messages.

## 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. Write the submission to the database first, then send the email. The stored record is the source of truth; the email is a notification about it.
2. Build the form on the app's existing Form Field Shell and validation patterns so errors, labels, and required-field markers look and behave like every other form in the app.
3. Send through the app's existing transactional email setup rather than adding a second mail path, and reuse Idempotent Form Submission so a double-click or a browser retry does not create two records.
4. Give staff a simple list of submissions with a read and unread state, so a message is not lost when the notification email is filtered into a spam folder.
5. Do not put a visible puzzle in front of the form. Use a hidden field bots fill in, a minimum time-to-submit, and server-side rate limiting by address, and reserve a challenge for the case where those stop working.

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

- Bots will submit this form within days of it going live. Silently accept and discard obvious bot submissions rather than showing an error, so the bot does not learn what triggered the rejection.
- A validation failure must return the form with every field still populated. A visitor who has written four paragraphs and gets an empty form back does not retype them.
- If the mail send fails, the submission must still be stored and the visitor must still see success. Queue the notification for retry rather than showing an error for a message you actually received.
- The notification email's reply-to must be the visitor's address while the from address stays a domain you control. Putting the visitor's address in the from field will get the mail rejected by authentication checks.
- Message bodies arrive with pasted markup, links, and control characters. Escape on output in both the admin view and the email body, and never render submitted content as trusted markup.
- A visitor who submits an address with a typo gets no reply and assumes they were ignored. Check the address format and warn on common misspelled domains before accepting.
- The form collects personal data. State what happens to it, restrict who can read submissions, and set a retention period rather than keeping them forever.
- An oversized message or an attachment field with no server-side size limit is a denial-of-service vector. Cap the body length and reject anything larger before parsing it.

## 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 submission is stored as a record before any email is attempted.
- [ ] A failed mail send does not lose the message or show the visitor an error, and the notification is retried.
- [ ] Validation failures return the form with all typed input preserved.
- [ ] The notification email sets reply-to to the sender and from to a domain the app controls.
- [ ] Bot submissions are rejected without presenting the visitor a puzzle.
- [ ] Submitted content is escaped everywhere it is displayed.
- [ ] Staff can browse past submissions and see which are unread.
- [ ] 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.