Orders 7874 accessibility create return page

[bc-vivekaggarwal]

What?

Add accessibility support on create return page.
A/C:

• Improve Lighthouse accessibility score.
• All interactive controls are keyboard-operable (Tab, Shift+Tab, Enter/Space, arrow keys where appropriate)
• All form controls have programmatically associated labels; no unlabelled controls
• Validation errors announced via live region; individual errors linked to their fields
• Loading/in-flight and success states communicated non-visually
• Focus managed correctly on page load and after errors

Requirements

• CHANGELOG.md entry added (required for code changes only)

Tickets / Documentation

ORDERS-7874

Screenshots (if appropriate)

Manual Testing:

Before implementation:

Lighthouse score:

Behavior:

• Improper navigation focusing on top level links instead of functionality on the page
• No navigation to disabled buttons that can announce the reason for being disabled
• No announcement during loading/in-fligh state
• Navigation focus doesn't change to alerts and continue from last action button(Submit button here).

Screen.Recording.2026-07-22.at.11.55.53.am.mov

• No announcement of success message on landing on success page.

Screen.Recording.2026-07-22.at.4.19.52.pm.mov

After implementation:

Lighthouse score(this will further be improved by implementation of ORDERS-7945):

Navigation Behavior(starts with return heading and goes into items first):
https://github.com/user-attachments/assets/69b44efb-c37f-40c8-a805-2e48717f8e59

e2e behavior:
https://github.com/user-attachments/assets/3ffe1b68-8267-4e95-9f71-bf2b50f0895a

---

Note

Low Risk
Changes are limited to create-return template, JS, SCSS, and strings; no auth, payments, or shared checkout paths. Submit gating now relies on aria-disabled plus JS, which is intentional but worth a quick regression pass on keyboard submit.

Overview
Improves keyboard and screen-reader support on the account create return page so tab order, labels, and status announcements match WCAG-oriented expectations.

Focus and announcements: On load, focus moves to the page h1 (newReturn-heading). Submitting sets aria-busy on the form, speaks a submitting message via an assertive live region, and on failure focuses the error alert; on success focus lands on the confirmation heading.

Submit control: The submit button stays in the tab order using aria-disabled (not native disabled), with hidden hints that explain what’s missing vs. when submit is ready; JS blocks submit when aria-disabled is true.

Markup and labels: Order line items are a semantic ul/li list. Quantity selects use aria-labelledby tying labels to product names. Decorative dividers and the arrow on the policy link are hidden from assistive tech. Header layout is adjusted so order date placement matches mobile/desktop flex order.

Styles: Secondary text uses darker grey for contrast; focus-visible outlines target WCAG 2.2 focus appearance; invalid submit styling reflects aria-disabled.

New strings in lang/en.json: submit_hint, submit_ready, submitting.

^{Reviewed by Cursor Bugbot for commit 448ea39. Bugbot is set up for automated code reviews on this repo. Configure here.}

[Copilot]

Pull request overview

Improves accessibility on the account Create Return page by adding screen-reader announcements, keyboard focus management, and more descriptive labeling/semantics for return line items and submit behavior.

Changes:

• Adds focus management (initial focus on heading, focus on error alert, focus on confirmation heading) and an assertive live region announcement during submission.
• Updates markup semantics for line items (list structure) and introduces aria-disabled + hint text for the submit control.
• Adjusts styling for contrast, DOM/visual ordering, aria-disabled button appearance, and :focus-visible outlines; adds new English strings and a changelog entry.

Reviewed changes

Copilot reviewed 5 out of 5 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
templates/pages/create-return.html	Adds live region, focusable headings/alerts, list semantics, and new ARIA labeling/hints for form controls.
assets/js/theme/create-return.js	Implements focus-on-load, live-region announcements, aria-disabled submit gating, and success/error focus behavior.
assets/scss/components/stencil/createReturn/_createReturn.scss	Improves contrast and focus styling; styles aria-disabled buttons; supports new list wrapper.
lang/en.json	Adds new accessibility-related strings for submit hints and submission status.
CHANGELOG.md	Records the accessibility improvements for the create return page.

Comments suppressed due to low confidence (3)

templates/pages/create-return.html:97

• The resolution is labelled via aria-labelledby pointing at a that is display:none at most breakpoints (.newReturn-controlLabel). If that label is not exposed, the control’s accessible name may omit the “Request” label text. <label class="newReturn-controlLabel" id="newReturn-resolutionLabel-{{id}}" for="resolution-{{id}}">{{lang 'account.returns.request'}}</label> <select class="form-select form-select--small" id="resolution-{{id}}" aria-labelledby="newReturn-resolutionLabel-{{id}} newReturn-itemName-{{id}}"> templates/pages/create-return.html:104 The reason is labelled via aria-labelledby pointing at a that is display:none at most breakpoints (.newReturn-controlLabel). Hidden labels can be dropped from the accessibility tree, leaving the control without the “Reason” label text in its accessible name.

                    <label class="newReturn-controlLabel" id="newReturn-reasonLabel-{{id}}" for="reason-{{id}}">{{lang 'account.returns.reason_header'}}</label>
                    <select class="form-select form-select--small" id="reason-{{id}}" aria-labelledby="newReturn-reasonLabel-{{id}} newReturn-itemName-{{id}}">

templates/pages/create-return.html:34

• The error summary markup nests a

  inside another

  (invalid HTML). Browsers will auto-close the first

  , which can lead to inconsistent DOM/announcement behavior for the alert content.

        <p class="alertBox-message" data-return-error-message>
            {{lang 'common.generic_error'}}
            {{#if ../settings.phone_number}}
            <p class="alertBox-message">
                {{lang 'account.returns.contact_merchant' phone_number=../settings.phone_number }}

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[bc-vivekaggarwal]

aria-labelledby includes the referenced element's text even when it's display:none

[bc-vivekaggarwal]

Updated

[denis-bc]

\nit
to keep comments connected and not new-lined mid sentence or with one word left:

// aria-disabled (not the native disabled attr) keeps the button keyboard/SR reachable while invalid.
// the described-by hint swaps between "what to select" and "press Enter to submit".

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, have a team admin enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 6d85e39. Configure here.}

[cursor]

Disabled submit keeps hover styles

Low Severity

Replacing native disabled with aria-disabled left the submit control under .button--primary hover and active styles. Only opacity and cursor are overridden, so the control still looks interactive on pointer hover even though activation is blocked in JS.

 

^{Reviewed by Cursor Bugbot for commit 6d85e39. Configure here.}

[bc-vivekaggarwal]

This is for accessibility features so user can go to the button and understand why a button is disabled