kandev/docs/specs/ui/system-design/clarification-submit-feedback.md

status, system, requirements

status	system	requirements
current	ui	REQ-UI-CLARIFICATION-SUBMIT-FEEDBACK-001

Clarification Submit Feedback System Design

Purpose and boundaries

The UI system owns the visible in-flight feedback for the shared clarification overlay. The task and clarification services continue to own the pending question, response endpoint, winner selection, and resume lifecycle. This design changes no backend contract, persisted state, or WebSocket event.

Requirement mapping

Requirement	Design section
REQ-UI-CLARIFICATION-SUBMIT-FEEDBACK-001	Components and responsibilities, Control flow, Responsive and accessible presentation, and Failure and recovery

Components and responsibilities

• useClarificationGroup remains the owner of the local submitState and the single in-flight request guard. It synchronously enters submitting before awaiting the response.
• ClarificationInputOverlay derives isSubmitting from that state and passes it to the existing shared header and question controls.
• ClarificationHeaderActions renders one design-system Spinner immediately before ClarificationSkipButton while isSubmitting is true. This position exists for both single-question and multi-question bundles, and the spinner remains exposed to assistive technology for both bundle types.
• The multi-question Submit button retains its translated pending label and disabled behavior, but keeps the normal translated submit label as its accessible name while the pending label changes visually. It does not render a second spinner, and its idle completion check is absent while the request is pending.
• Task chat and Quick Chat continue to compose the same ClarificationPanelSection, so they receive identical behavior without surface-specific state or handlers.

Data and contracts

No wire or persistence contract changes. The presentation consumes the existing SubmitState values idle, submitting, ok, and error through the current isSubmitting boolean.

The header spinner receives the existing translated task:submitting value as its accessible name and remains announced for every bundle. The multi-question Submit button receives the normal translated task:submit value as a stable accessible name while its visible label changes to the pending value. A stable clarification-submitting-status test identifier anchors component and Playwright assertions without using translated text as a selector.

Control flow

1. A single-question option or custom-text action calls submitCollected immediately, or a fully answered multi-question bundle calls it from the explicit Submit action.
2. runClarificationRequest sets submitState to submitting before awaiting the response.
3. React re-renders the expanded header with the submitting status before the Skip control. Answer controls remain protected by the current disabled and in-flight guards.
4. A successful response applies the existing resolved status and closes the clarification. An error returns submitState to error, which removes the spinner and restores the existing retry path.

Responsive and accessible presentation

The existing header composition remains shared across viewport classes. On fine-pointer desktop, the small non-interactive status joins the compact action cluster without changing the dimensions of Skip, Collapse, or the multi-question Submit button. On coarse pointers, the existing 44px Skip and Collapse targets and the full-width multi-question action row remain intact. The status occupies its own flex item immediately before Skip and must not become a touch target.

The design-system spinner keeps role="status", and its accessible name uses the translated submitting label for every bundle. The multi-question Submit button keeps a stable accessible name with the normal translated submit label, so the visible pending-label change does not compete with the header status announcement. Rendered desktop and Pixel 5 tests verify its order, containment, and absence of document-level horizontal overflow.

Failure and recovery

Network and non-success responses continue to produce the existing error state. The header status is conditional only on submitting, so it stops without a separate cleanup path. Existing answer state and retry behavior remain unchanged.

Collapsing the clarification while a request is pending retains today's compact header behavior; this design does not project submit state into that collapsed surface.

Verification strategy

• A focused component test holds a single-question response and verifies that the status appears before Skip, uses the translated accessible label, and is removed outside the in-flight state.
• A focused component test verifies that a multi-question status remains announced and that its Submit button keeps a stable accessible name while a failed request removes the status and re-enables Skip.
• Desktop Playwright coverage holds a single-question response to prove the status is visible in the expanded header before the Skip control, then releases the response and verifies normal resolution.
• Existing desktop multi-question coverage moves its spinner assertion from the Submit button to the shared header while retaining disabled-label and idle-check assertions.
• Pixel 5 coverage proves the same single-question feedback, control order, touch-target preservation, and lack of horizontal overflow. Existing multi-question geometry coverage is updated for the new spinner location.

Security

The change introduces no new input, authorization decision, data exposure, or external side effect.