Files
kandev/docs/specs/ui/system-design/clarification-submit-feedback.md
T
2026-08-30 13:36:48 +00:00

120 lines
5.7 KiB
Markdown

---
status: current
system: ui
requirements:
- 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](#components-and-responsibilities), [Control flow](#control-flow), [Responsive and accessible presentation](#responsive-and-accessible-presentation), and [Failure and recovery](#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.