[FE-112] Boundary Enterprise a11y audit- User details form #2977

venusang · 2025-08-28T15:35:40Z

Description

This updates the input fields on the User details page so that they are readonly instead of disabled. Additionally it changes the edit button text from Edit form to Edit User details so that it is more descriptive. Lastly, aria-describedby was also added to the button so that it is a11y compliant.

🎟️ FE-112

Screenshots (if appropriate)

How to Test

Navigate to a User in the Users list. Verify that the input fields are readonly (you should be able to highlight the text with your mouse) and that the submit button reflects the text changes shown in the after screenshot.

Checklist

I have added before and after screenshots for UI changes
I have added JSON response output for API changes
I have added steps to reproduce and test for bug fixes in the description
I have commented on my code, particularly in hard-to-understand areas
My changes generate no new warnings
I have added tests that prove my fix is effective or that my feature works
I have added a11y-tests label to run a11y audit tests if needed

PCI review checklist

I have documented a clear reason for, and description of, the change I am making.
If applicable, I've documented a plan to revert these changes if they require more than reverting the pull request.
If applicable, I've documented the impact of any changes to security controls.
Examples of changes to security controls include using new access control methods, adding or removing logging pipelines, etc.

vercel · 2025-08-28T15:35:55Z

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Preview	Comments	Updated (UTC)
boundary-ui	Ready	Preview	Comment	Sep 9, 2025 11:36pm
boundary-ui-desktop	Ready	Preview	Comment	Sep 9, 2025 11:36pm

cameronperera

LGTM

This adds edit user details translations so the User detail form submit button is a11y compliant ✅ Closes: FE-112

Per a11y audit, this changes the input fields to readonly instead of disabled. It also updates the submit button text so that it is context based and has an aria-label for screenreaders. ✅ Closes: FE-112

This moves the User detail action translation to resources/en-us.yaml since it is specific to the user resource and is not a generic form action. ✅ Closes: FE-112

ZedLi · 2025-08-28T20:47:01Z

ui/admin/app/components/form/user/index.hbs

+      @enableEditText={{t 'resources.user.actions.edit-details.button.text'}}
+      aria-label={{t 'resources.user.actions.edit-details.button.aria-label'}}


I'm just curious, do we need both these changes? It seems like it would be one or the other since a screen reader reads both now?

Also, the aria-label is attaching to the HDS::ButtonSet instead of the actual button it looks like.

boundary-ui/addons/rose/addon/components/rose/form/actions/edit-toggle/index.hbs

Line 6 in 9b1f052

<Hds::ButtonSet class='rose-form-actions' ...attributes>

I implemented this based on the recommendations outlined in the ticket here.

8.2 “Edit Form” button text
Issue: Due to the structure of the page content, it was really difficult to tell what form I would be editing while using only a screen reader to navigate the page. I would consider adding the form name to the button so that it would be more informative for the user. Suggest adding an aria-label attribute to the button, where the value is “edit form: users”. Note that the visible button label matches the first part of the aria-label attribute value, conforming to WCAG Success Criterion 2.5.3 Label In Name.

Hit enter too soon! But you bring up a good point wrt to the aria-label not being applied to the actual submit button. I will try and update this.

So, it turns out <Hds::Button /> only allows us to set the aria-label on a button if isIconOnly is true. So with that said, I went ahead and refactored this so that we are only updating the button text.

https://github.com/hashicorp/design-system/blob/main/packages/components/src/components/hds/button/index.hbs#L16C3-L17C2

aria-label={{if this.isIconOnly this.text null}}

I took the ticket to mean to add an aria-label to make the existing Edit form button more descriptive for screen readers such that Edit form: users now properly describes the existing button. I also assume just changing the text of the button without an aria label would have accomplished that but it sounds like the recommendation is to add the label.

But either way reading the linked WCAG success criteria it seems like this change would now violate it:

Accessible name matches visible label: The accessible name and visible label of a control match.
Accessible name starts with visible label: The accessible name "Search for a value" begins with the text of the visible label, "Search".

Since the text is now Edit user details and the label is Edit form: users, they don't match and the accessible name doesn't start with the visible label (as opposed to Edit form: users just being a more descriptive match of the original text).

I think we should be okay now that the button is more descriptive and not have an aria-label. For some reason I thought the ticket was suggesting to do both (descriptive and aria-label). But as mentioned, turns out we cannot update the aria-label anyway since this is not an iconOnly button 🤷‍♀️ , but if we could, I understand your point wrt the aria-label being a mismatch if we used edit form:users. I put a comment in the JIRA ticket and I'll confirm with Melanie if updating the button to be more descriptive is enough in this case.

This was not sending the aria-label down to the Edit Users detail button. However, taking a look further at Hds::Button, this component does not allow aria-label to be set unless it is an icon only button. With that said, this cleans up the translation structure and removes the aria-label translation and mark-up. ✅ Closes: FE-112

ZedLi

Looks good! Thanks for the update

hashicc

Thanks for helping us with our a11y!

Since we cannot apply aria-label to an Hds::Button when it has text, we can alternatively apply the aria-describedby attribute instead. Its value must match the id of the form. With that said, a form id value was also added. ✅ Closes: FE-112

ZedLi · 2025-09-10T15:29:18Z

ui/admin/app/components/form/user/index.hbs

  {{#if (can 'save model' @model)}}
    <form.actions
-      @enableEditText={{t 'actions.edit-form'}}
+      @ariaDescribedBy={{t


I'm not sure I understand why we linked the ID of the form itself, what text are we trying to descriptively add to this by using aria-describedby? It also seems weird to use a translated text as the ID when the element itself should have the translated text

I pinged you in the JIRA ticket comment but adding reference here for good measure.

(taking a screenshot so it has more context versus copy paste):

https://hashicorp.atlassian.net/browse/FE-112?focusedCommentId=828913

Going off @MelSumner thoughts in the JIRA ticket, I set the form ID value to be user-details versus users since to me it seems to make better sense that the form is specific to the user-details. Users did not seem to make sense to me but maybe I am misunderstanding the purpose here.

It also seems weird to use a translated text as the ID when the element itself should have the translated text

@ZedLi from what I am getting here, it sounds like the form ID value should be semantic versus the ember generated ID. Maybe Melanie could provide some clarity here for both of us. I'm not all that familiar with aria-describedby prior to working on this.

Right, I think all those choices make sense but it sounds like we just need to pick one choice? It seems we could leave the button as Edit form if we're adding one of the aria attributes.

With regards to the current implementation with 3, I was specifically pointing out the fact that it's currently pointing to the form ID instead of something with descriptive text (which melanie suggests as the form title):

where the value is the ID of the form title element (in this case, the element with the text “Users”)

Though that looks like it has some extra text which would pulled in as part of the helper doc link text.

you wouldn't need to translate the element's id attribute value.

Assuming this is what we are talking about:

<button class="hds-button hds-button--color-primary hds-button--size-medium" type="button"> <span class="hds-button__text">Button text</span> <span aria-description="some description" /> </button>

How would we do this with <Hds::Button />?

https://github.com/hashicorp/design-system/blob/main/packages/components/src/components/hds/button/index.hbs#L42-L44

aria-description would be an attribute on the actual element itself, in this case the button in your example. We wouldn't be passing in a separate element but instead be passing the attribute to the button itself.

i.e.

<button class="hds-button hds-button--color-primary hds-button--size-medium" type="button" aria-description="some description"> <span class="hds-button__text">Button text</span> </button>

My only question is if aria-description is OK to use? The docs mention:

Note: aria-description is still in W3C Editor's Draft for ARIA 1.3. For the time being, continue to use aria-describedby, which has been supported since ARIA 1.1.

@MelSumner Do you happen to know if this is something that is just a formality and we're OK to use or we should avoid for now?

fwiw, we can actually pass in aria-description into <Hds::Button /> (see ...attributes). I'll wait for @MelSumner to verify whether the code example that @ZedLi provided is acceptable. But I could use some help on what the description should be if we want to go in this direction.

venusang requested a review from a team as a code owner August 28, 2025 15:35

github-actions bot added ui addons admin labels Aug 28, 2025

venusang mentioned this pull request Aug 28, 2025

[FE-112] Boundary Enterprise a11y audit - User details form #2972

Closed

10 tasks

venusang self-assigned this Aug 28, 2025

cameronperera previously approved these changes Aug 28, 2025

View reviewed changes

venusang added 3 commits August 28, 2025 09:36

refactor: 💡 add edit-user-details translations

ed04192

This adds edit user details translations so the User detail form submit button is a11y compliant ✅ Closes: FE-112

refactor: 💡 change inputs to readonly and update submit button

f7082ea

Per a11y audit, this changes the input fields to readonly instead of disabled. It also updates the submit button text so that it is context based and has an aria-label for screenreaders. ✅ Closes: FE-112

refactor: 💡 move translation to resources for user

334e7d6

This moves the User detail action translation to resources/en-us.yaml since it is specific to the user resource and is not a generic form action. ✅ Closes: FE-112

venusang force-pushed the fe-112-boundary-admin-a11y-user-deets branch from a40d4ac to 334e7d6 Compare August 28, 2025 16:36

vercel bot deployed to Preview – boundary-ui-desktop August 28, 2025 16:37 View deployment

vercel bot deployed to Preview – boundary-ui August 28, 2025 16:37 View deployment

ZedLi reviewed Aug 28, 2025

View reviewed changes

venusang dismissed cameronperera’s stale review via d86805c August 29, 2025 15:25

vercel bot deployed to Preview – boundary-ui-desktop August 29, 2025 15:26 View deployment

vercel bot deployed to Preview – boundary-ui August 29, 2025 15:27 View deployment

ZedLi previously approved these changes Aug 29, 2025

View reviewed changes

hashicc previously approved these changes Aug 29, 2025

View reviewed changes

cameronperera previously approved these changes Sep 2, 2025

View reviewed changes

venusang dismissed stale reviews from cameronperera, hashicc, and ZedLi via 2ec32be September 9, 2025 23:35

venusang requested a review from ZedLi September 9, 2025 23:35

github-actions bot added the styles-addon label Sep 9, 2025

venusang requested review from cameronperera and hashicc September 9, 2025 23:35

vercel bot deployed to Preview – boundary-ui-desktop September 9, 2025 23:36 View deployment

vercel bot deployed to Preview – boundary-ui September 9, 2025 23:36 View deployment

ZedLi requested changes Sep 10, 2025

View reviewed changes

		@enableEditText={{t 'resources.user.actions.edit-details.button.text'}}
		aria-label={{t 'resources.user.actions.edit-details.button.aria-label'}}

[FE-112] Boundary Enterprise a11y audit- User details form #2977

Are you sure you want to change the base?

[FE-112] Boundary Enterprise a11y audit- User details form #2977

Uh oh!

Conversation

venusang commented Aug 28, 2025 • edited by sohail-hashicorp Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Screenshots (if appropriate)

How to Test

Checklist

PCI review checklist

Uh oh!

vercel bot commented Aug 28, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

cameronperera left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

venusang Aug 29, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ZedLi left a comment

Choose a reason for hiding this comment

Uh oh!

hashicc left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

MelSumner Sep 10, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

venusang Sep 10, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

venusang commented Aug 28, 2025 •

edited by sohail-hashicorp

Loading

vercel bot commented Aug 28, 2025 •

edited

Loading

venusang Aug 29, 2025 •

edited

Loading

MelSumner Sep 10, 2025 •

edited

Loading

venusang Sep 10, 2025 •

edited

Loading