Skip to content

fix(dashboard): tell assistive technology whether a question takes one answer or several - #24865

Merged
KiroCrewCaptain merged 1 commit into
mainfrom
fix/question-card-selection-rule-15571
Oct 27, 2026
Merged

KiroCrewCaptain merged 1 commit into
mainfrom
fix/question-card-selection-rule-15571

Conversation

@CrysisDeu

Copy link
Copy Markdown
Contributor

Problem / Motivation

Goal: A screen-reader user can tell whether an ask_question card takes one answer or several.

QuestionCard renders both selection modes as the same set of toggle buttons. aria-pressed gives each option's state. But nothing on the options or the question carries multiSelect: the multi-select checkbox is aria-hidden, and the options sit in a plain div. So assistive technology can read whether an option is selected, but not the rule for choosing.

Why it matters

A user who cannot see the checkbox has to guess. They may press a second option on a multi-select card and not know the first one stayed on. Or they may never try a second option because nothing says they can.

Not a goal

Intended? / Repro

Intended? No. #9507 added aria-pressed and explicitly left group semantics out of scope; nothing in the component or its tests says the selection rule should be hidden. The option comment at website/src/components/QuestionCard.tsx (the aria-pressed block) explains why it is not a radio, not why the rule goes unannounced.

Repro (code read on current main): in QuestionCard.tsx, the options render inside <div className="pt-2.5 flex flex-col gap-1.5">, with no role, aria-labelledby or aria-describedby. The question text is a bare <span> with no id. The only multiSelect cue is the checkbox span, which is aria-hidden="true". Render a card with multiSelect: false and another with multiSelect: true. In the accessibility tree both show the same list of toggle buttons with aria-pressed, and neither exposes its one-choice or many-choice rule.

What changed (motivation → approach → change)

Symptom: the selection rule is visual only. Cause: no element in the accessibility tree carries multiSelect. Change: the options' container becomes a named, described group.

  • website/src/components/QuestionCard.tsx:
    • The options container is role="group", aria-labelledby the question text and aria-describedby a visually hidden rule sentence (sr-only).
    • The sentence follows multiSelect: "Choose one option. Choose it again to clear it." or "Choose one or more options." The first one also says a second press clears the pick, which is the behavior a radio group would hide.
    • The ids come from useId().
  • Two new keys, components.questionCard.select_one_rule and select_many_rule, in en.manual.json (beside the other hand-authored questionCard strings) and in all eleven translations. en-XA.json was regenerated with scripts/gen-pseudolocale.mjs.

Backwards compatibility

Compatible: the buttons, their aria-pressed, their names and their behavior are unchanged. The change only adds a group role, a name and a description around them.

Removes nothing: no element, attribute, key or behavior is removed.

Tests

website/src/test/QuestionCard.test.tsx:

  • names the single-select options group by its question and describes its one-choice rule: getByRole('group', { name: <question> }) has the description "Choose one option. Choose it again to clear it." and contains the options.
  • describes the multi-select options group with its many-choice rule: the description is "Choose one or more options."

Both fail on main, where no element has role="group".

Proof: not provable -- frontend test

Manual verification

No screen reader was run. Static gates run locally: eslint and tsc --noEmit on the website, and scripts/i18n-check.mjs (all diff-scoped checks pass). The tests run in CI.

Screenshots / video

Why no screenshot: the only added element is an sr-only sentence plus ARIA attributes on an existing container, so nothing on screen changes.

Related Issues

Fixes #15571

Sibling sweep

Swept: git grep -ln "multiSelect" -- website/src/components
Siblings: none -- QuestionCard is the only component that renders ask_question options; PendingQuestionCard renders QuestionCard itself

Pattern harvest

Not generalizable: one component whose selection mode was shown only by an aria-hidden checkbox.

Checklist

  • At most two commits (one is the norm), with a Conventional Commits title (feat|fix|docs|style|refactor|perf|test|chore|ci|build|revert: ...)
  • Existing tests pass and new tests added for new functionality
  • Self-review completed; code follows project style guidelines
  • Documentation updated (if applicable)
  • No secrets, credentials, or internal references in the diff

Contribution License Agreement

Contributed under the project's Apache-2.0 license.

@CrysisDeu
CrysisDeu requested review from a team and KiroCrewCaptain as code owners October 27, 2026 11:10
@github-actions github-actions Bot added the readiness: checking Automated validation is still running label Oct 27, 2026
@github-actions

github-actions Bot commented Oct 27, 2026 •

Copy link
Copy Markdown
Contributor

Design Review (Opus 5.5) — ✅ PASS

Design-level review of 94f5dea2f02fba73ba85b11ae617f63b135facd6 — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS does not.

Design-Verdict: PASS

Nothing on screen changes: the PR adds only a hidden sentence and ARIA attributes, and the plain role="group" with a description fits the toggle-button choice made in #9507.

[DESIGN-REVIEWED] 94f5dea

Description read

[DESCRIPTION-READ] ffa52f3b95a3eeb8cf07c511d175ae325a6204ad1ccc6f62ebacae4660c7deb5

That sha256 names everything this verdict read: the PR description, plus the 1 evidence file(s) the workflow collected from it and handed this review. It covers that evidence because the media strip replaces every attachment URL with the same placeholder, so an edit swapping one attachment for another would leave the description's captured text identical while what this review judged changed. Recompute it with .github/scripts/pr-description-capture.sh over the same inputs; if it differs, the description or that evidence changed after this verdict was formed and any finding drawn from either is unproven.

@github-actions

github-actions Bot commented Oct 27, 2026 •

Copy link
Copy Markdown
Contributor

First Principles Review (Opus 5.5) — ✅ PASS

Premise-level review of 94f5dea2f02fba73ba85b11ae617f63b135facd6 — why this exists and whether the shipped surface is the smallest honest version. Updated in place on each push. A BLOCK verdict blocks PR readiness; PASS does not.

First-Principles-Verdict: PASS

Nothing to check.

What this change ships

Inventory (4 items) — 4 justified

Intent: A screen-reader user can tell whether a question card takes one answer or several. This is a FIX (#15571).

  1. Screen readers now announce each question's option list as a group named by the question text. Justified.
  2. Screen readers now hear the rule: "Choose one option. Choose it again to clear it." or "Choose one or more options." Justified.
  3. The two new rule strings are translated in all locales, and the pseudolocale was regenerated. Justified.
  4. Two tests pin the group's name and its description. Justified.

[FIRST-PRINCIPLES-REVIEWED] 94f5dea

Description read

[DESCRIPTION-READ] f084237c11b1080181c57acaa970a0ac6c44dc15cff62693c414017334a04c64

That sha256 names the PR description this verdict read. Recompute it with .github/scripts/pr-description-capture.sh; if it differs, the description changed after this verdict was formed and any finding drawn from the description is unproven.

@github-actions

github-actions Bot commented Oct 27, 2026 •

Copy link
Copy Markdown
Contributor

UX Review (Opus 5.5) — ✅ PASS

UX-level review of 94f5dea2f02fba73ba85b11ae617f63b135facd6 — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS does not.

UX-Verdict: PASS

Nothing visible changes: the diff adds only an sr-only sentence and ARIA attributes on the existing options container, so no screenshot is needed.

Notes

  • The sr-only rule <span> sits inside the role="group" it describes. In browse mode a screen reader can read "Choose one option…" twice: once as the group's description and again as plain text before the first option. Moving the span just outside the group still lets aria-describedby find it, and it is read only once.

[UX-REVIEWED] 94f5dea

Description read

[DESCRIPTION-READ] f9f50cf7439764f99ae24a579387f379315eff81e294eae132a68fd6585fcb27

That sha256 names everything this verdict read: the PR description, plus the 3 evidence file(s) the workflow collected from it and handed this review. It covers that evidence because the media strip replaces every attachment URL with the same placeholder, so an edit swapping one attachment for another would leave the description's captured text identical while what this review judged changed. Recompute it with .github/scripts/pr-description-capture.sh over the same inputs; if it differs, the description or that evidence changed after this verdict was formed and any finding drawn from either is unproven.

@github-actions

github-actions Bot commented Oct 27, 2026 •

Copy link
Copy Markdown
Contributor

Opus 5.5 Review — ✅ no blocking findings

Reviewed 94f5dea2f02fba73ba85b11ae617f63b135facd6 — this comment is updated in place on each push.

Review details

No findings.

[OPUS-REVIEWED] 94f5dea

Verdict parsed from the review's SHA-scoped output markers for commit 94f5dea2f02fba73ba85b11ae617f63b135facd6.

False positive or not applicable? A repository writer can comment:
/ai-review override fable 94f5dea2f02fba73ba85b11ae617f63b135facd6 false-positive: <reason, 20 to 500 characters>

@github-actions

github-actions Bot commented Oct 27, 2026 •

Copy link
Copy Markdown
Contributor

GPT 6.1 Review — ✅ no blocking findings

GPT 6.1 completed its review of 94f5dea2f02fba73ba85b11ae617f63b135facd6 and found no blocking issues.

This comment is updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] 94f5dea

False positive or not applicable? A repository writer can comment:
/ai-review override gpt 94f5dea2f02fba73ba85b11ae617f63b135facd6 false-positive: <reason, 20 to 500 characters>

@github-actions github-actions Bot added readiness: action required A blocking check or review needs attention and removed readiness: checking Automated validation is still running labels Oct 27, 2026
@CrysisDeu
CrysisDeu force-pushed the fix/question-card-selection-rule-15571 branch from 043eecc to 94f5dea Compare October 27, 2026 12:53
@github-actions github-actions Bot added readiness: checking Automated validation is still running readiness: passed Eligible automated validation passed for the current revision and removed readiness: action required A blocking check or review needs attention readiness: checking Automated validation is still running labels Oct 27, 2026
@KiroCrewCaptain
KiroCrewCaptain enabled auto-merge (squash) October 27, 2026 15:07

@KiroCrewCaptain KiroCrewCaptain left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Tier 1 auto-approve: fix (15 files). Criteria: no conflict, no requested changes, security path denylist clean, design-doc gate clean, security checklist all-NO, no reviewer-lane findings, readiness signal fresh for this head SHA, declared category matches the diff. Category: names the question card's option group and describes its one-or-many selection rule for assistive technology; locale strings and tests.

@KiroCrewCaptain
KiroCrewCaptain merged commit 2def93a into main Oct 27, 2026
108 checks passed
@KiroCrewCaptain
KiroCrewCaptain deleted the fix/question-card-selection-rule-15571 branch October 27, 2026 15:10
@github-actions github-actions Bot removed the readiness: passed Eligible automated validation passed for the current revision label Oct 27, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

ask_question does not expose single-select versus multi-select semantics

2 participants