Dialog: reconsider title/header workflow and add aria-label when header is hidden
Closed, ResolvedPublic3 Estimated Story Points
Actions

Assigned To

Authored By

	AnneT
	Jan 5 2023, 2:29 PM

Description

Currently, we offer the following configuration options for the Dialog title and header:

title: a mandatory prop, since we need to label the dialog per the ARIA APG spec
hideTitle: a boolean prop that can be set to true to visually hide the title in the header.
closeButtonLabel: a string prop for the visually-hidden label for the close button. If empty, the close button will not display
If hideTitle is true and no closeButtonLabel is provided, the entire dialog header will be hidden

There are a couple of issues with this:

The last bullet point is not well-explained in the docs, and whether the close button or the entire header should display is not explicit. We should reconsider this workflow and see if we can make it clearer.
If the header is hidden, the title is not included anywhere. It should be included as an aria-label when the header is not included.

Acceptance criteria

Discuss a better workflow for whether the dialog header should be displayed
Include an aria-label when the header is not displayed

Details

	Subject	Repo	Branch	Lines +/-
	Dialog: Allow custom header and footer content	design/codex	main	+381 -145

Customize query in gerrit

Related Objects

Mentioned Here: T324708: Dialog: support header and footer customization

Event Timeline

AnneT created this task.Jan 5 2023, 2:29 PM

Restricted Application added a project: Design-System-Team. · View Herald TranscriptJan 5 2023, 2:29 PM

Restricted Application added a subscriber: Aklapper. · View Herald Transcript

@AnneT how do you feel about just always providing an aria-label attribute on the dialog element that has the title as a value? This would save us the trouble of having to introduce extra logic that needs to determine whether to use aria-label or aria-labelledby based on whether the dialog has a visible title inside the header. This would also eliminate the risk that users of the header slot might forget to properly set up this attribute when providing their own content.

See https://w3c.github.io/aria/#aria-label:

In the cases where DOM content or a tooltip is undesirable, authors MAY set the accessible name of the element using aria-label, if the element does not prohibit use of the attribute.

By ensuring that the main dialog element (with role=dialog) always has an aria-label attribute which matches the title prop (regardless of any customizations the user makes to the appearance), I think we will avoid a lot of potential headaches.

Change 864862 had a related patch set uploaded (by Eric Gardner; author: Eric Gardner):

[design/codex@main] Dialog: Allow custom header and footer content

https://gerrit.wikimedia.org/r/864862

gerritbot added a project: Patch-For-Review.Jan 5 2023, 7:06 PM

@egardner I agree that always having the aria-label is the safest way to ensure that the attribute is set even if there's custom header slot content

egardner changed the task status from Open to In Progress.Jan 5 2023, 8:37 PM

egardner claimed this task.

egardner edited projects, added Design-System-Team (Design-System-Sprint); removed Design-System-Team.

egardner set the point value for this task to 3.

egardner moved this task from Committed to In Development on the Design-System-Team (Design-System-Sprint) board.

Volker_E moved this task from In Development to Code Review on the Design-System-Team (Design-System-Sprint) board.Jan 6 2023, 10:50 PM

Moving this to blocked while T326319: Dialog: reconsider title/header workflow and add aria-label when header is hidden gets figured out.

If necessary I can split out the part of my patch which solves this particular issue, but my understanding is that this also needs some design clarification (do we want to hide the header by default? etc).

egardner changed the task status from In Progress to Stalled.Jan 18 2023, 9:03 PM

egardner removed egardner as the assignee of this task.

egardner moved this task from Code Review to Blocked ⛔ on the Design-System-Team (Design-System-Sprint) board.

CCiufo-WMF claimed this task.Jan 23 2023, 6:14 PM

CCiufo-WMF removed CCiufo-WMF as the assignee of this task.Jan 23 2023, 9:34 PM

CCiufo-WMF subscribed.

ldelench_wmf triaged this task as High priority.Jan 27 2023, 4:21 PM

egardner moved this task from Inbox to Proposed Component Updates on the Codex board.Feb 21 2023, 11:38 PM

Change 864862 abandoned by Eric Gardner:

[design/codex@main] Dialog: Allow custom header and footer content

Reason:

Abandoned in favor of https://gerrit.wikimedia.org/r/c/design/codex/+/893808

https://gerrit.wikimedia.org/r/864862

Maintenance_bot removed a project: Patch-For-Review.Mar 13 2023, 6:10 PM

This task ended up being handled as part of the work around T324708: Dialog: support header and footer customization. Based on the latest Dialog updates, we now have a process that looks like this:

Dialog title is required. By default, a <h2> element containing this title is displayed in the Dialog header. This <h2> element has an auto-generated ID, and the main dialog element of the component (the one with role=dialog) has an aria-labelledby attribute that uses this ID.
If the user overrides the default dialog header by providing their own content via the header slot, the main dialog element gives itself an aria-label attribute instead. The value of this attribute is the value of the Dialog's title prop.

This ensures that customized dialogs will still get meaningful ARIA labels applied without the user having to take any additional actions.

Dialog: reconsider title/header workflow and add aria-label when header is hiddenClosed, ResolvedPublic3 Estimated Story PointsActions