erika/docs/adr/0001-form-response-ux.md

ADR 0001: Form response UX and answer representation

• Status: Accepted
• Date: 2026-07-24

Context

The form flow supports one Discord-linked submission per person, local draft recovery, response updates, deletion, role-based access, and four question types. The previous interface blurred local drafts and server submissions, hid role-gated forms behind a 404 before login, front-loaded long descriptions, and represented checkbox answers as comma-separated text.

Decision

1. Authentication happens before authorization. Anonymous visitors to a valid direct form link see the Discord login prompt; authenticated visitors without permission continue to receive the not-found state.
2. Drafts remain browser-local and are explicitly described as saved on this device. Draft storage contains both normal answers and free text entered for “Other”.
3. Long form descriptions remain available in full but start collapsed behind a clearly labelled rules disclosure.
4. The UI distinguishes a new answer, an editable submitted answer, and a closed form. When a form closes, an existing response is read-only but can still be deleted.
5. Question text programmatically labels its control. Radio and checkbox choices use semantic fieldsets, and image enlargement uses a keyboard-accessible button.
6. Checkbox answers are stored as JSON arrays in the existing text column. Readers retain a fallback for legacy comma-separated values, so no database migration is required.
7. Server Actions independently validate authentication, form access, required answers, question ownership, answer shape, and allowed choices.

Consequences

• Existing checkbox answers remain readable, while new answers can safely contain commas.
• Local drafts do not follow a person to another device; the interface says so.
• Users must authenticate before seeing form questions.
• Closing a form prevents new submissions and updates but does not prevent a person from deleting their existing response.
• A future cross-device draft feature should introduce a server-side draft entity rather than changing the meaning of the current local draft.