Add “expandable card/region” example to disclosure pattern

[adampage]

Resolves #3215.

Preview of Example Disclosure (Show/Hide) Card | APG | WAI | W3C

---

WAI Preview Link (Last built on Wed, 18 Jun 2025 20:35:03 GMT).

[adampage]

Heya @mcking65, here’s an initial PR for the expandable region pattern.

There are a number of linting errors I’ll need to resolve, but I may not have time to do that before I head out early next week. @howard-e, could you let me know if the preview build failure is being caused by those linting errors? If so, I’ll do my best to get those fixed before I leave.

In the meantime, please feel free to review and share feedback for this standalone Codepen.

[adampage]

I’m suspicious of these HTML linting errors. 🤔

1. Element “p” not allowed as child of element “hgroup” in this context

   I think the validator might be out of date with the HTML spec on this? But also, this expandable region pattern certainly doesn’t require an hgroup to be present 😅 , I was just incorporating some semantics to fit the IRL scenario.

2. Bad value “image” for attribute “role” on element “svg”

   Ditto, but with the ARIA 1.3 spec, which introduced image as a synonym for img. If it’s not possible to update our validator here, I’ll be happy to update the pattern to use img instead.

3. Attribute “inert” not allowed on element “div” at this point

   I can’t find anything in HTML’s inert spec that should prohibit it here? 🤔

cc: @howard-e / @mcking65

[css-meeting-bot]

The ARIA Authoring Practices (APG) Task Force just discussed PR 3251 - New expandable region pattern.

The full IRC log of that discussion

<jugglinmike> Topic: PR 3251 - New expandable region pattern
<jugglinmike> github: https://github.com/w3c/aria-practices/pull/3251
<jugglinmike> Matt_King: Did we want this to be a separate pattern, or would it be another form of disclosure?
<jugglinmike> Matt_King: It could be one example that's under the "disclosure" pattern, but if it is a truly distinct pattern, then I'm happy to have a separate page for it
<jugglinmike> Matt_King: ...in that case, as howard-e was explaining, we need to have a "pattern" file and a sub-directory for the example, and an example file
<jugglinmike> Matt_King: Though even then, we will probably make a note that it is related to the "disclosure" pattern
<jugglinmike> Adam_Page: It hadn't occurred to me to add it as an example of an existing pattern
<jugglinmike> Adam_Page: I don't have a strong opinion on this one. I added it as a pattern only because it was originally pitched that way. I don't think we ever really discussed if that was the best option
<jugglinmike> Adam_Page: I've updated this with howard-e's help so that it builds as it should
<jugglinmike> Adam_Page: Basically, I did the initial implementation and that was it. I am mainly looking for feedback on the example itself, knowing that I will need to go back and fill out the documentation (and image, etc.) accordingly
<Jem> https://deploy-preview-396--aria-practices.netlify.app/aria/apg/patterns/expandable-region/examples/expandable-region/
<jugglinmike> Adam_Page: There is some appeal to me in making this another example within the "disclosure" pattern. It really is a disclosure
<jugglinmike> Adam_Page: Again, I don't have strong opinions on this, and I wasn't present for the original discussion
<jugglinmike> Adam_Page: But if I understand the impetus, this was intended as a sort of preferable way for the use case that many people were satisfying by stuffing a lot of stuff into buttons
<Jem> Jaws has imposter syndrom. LOL
<jugglinmike> Matt_King: When I tried to collapse, JAWS lost its place. It went to "impostor syndrome". The performance isn't great, either
<jugglinmike> Matt_King: I don't know what JAWS is doing here, actually...
<jugglinmike> Adam_Page: I haven't tested in JAWS. I developed in Mac and used VoiceOver. It all seems to be working, there
<jugglinmike> Matt_King: Calling this an "expandable region" is kind of interesting to me
<jugglinmike> Matt_King: There's a region, and it has a little bit of content inside of it, and it has this option to make the content inside the region bigger
<jugglinmike> Siri: It looks like an accordion, no?
<jugglinmike> Adam_Page: It really is, fundamentally, a disclosure--like, an accordion
<jugglinmike> Adam_Page: The quirk is that the thing that visually is inviting the user to expand is structurally rich. We're using JavaScript to enlarge the clickable region
<jugglinmike> Jem: I don't think this is an accordion design pattern. This is a disclosure.
<jugglinmike> Matt_King: I don't understand why it has anything to do with the region
<jugglinmike> Matt_King: The "details" button feels like an ordinary disclosure
<jugglinmike> Matt_King: So there's something about the visual presentation that says you can click on a larger area
<jugglinmike> Matt_King: If I wanted to code this, I would say, "here is a landmark region that says 'fire to flare'" and then within that region, I would place a disclosure
<jugglinmike> Siri: If we have to provide a region for the container inside, I don't think we need to go into that much detail
<jugglinmike> Matt_King: It feels to me like this goes in the "disclosure" pattern
<jugglinmike> Adam_Page: It certainly has a lot in common with "disclosure". If we were to make it its own page, then that new page would have a lot in common with "disclosure". It would maybe be redundant
<jugglinmike> Adam_Page: Maybe we just call it a "rich disclosure". The differentiating factor is that the thing which expand the disclosure is rich--it is visually showing much more
<jugglinmike> Matt_King: Right, but from a screen reader user's point of view, there is no difference
<jugglinmike> Adam_Page: Yeah
<jugglinmike> Adam_Page: That's where I was interested to get some feedback on the example. That's where I made some editorial decisions about what the screen reader should be
<jugglinmike> Jem: What screen reader user experience are you referring to?
<jugglinmike> Matt_King: It's different from the accordion because there, we use a heading and make the whole heading clickable.
<jugglinmike> Matt_King: You can do the same thing with the accordion pattern. You could show more content than the heading in its collapsed state.
<jugglinmike> Matt_King: That's feasible, and it's covered in the pattern
<jugglinmike> Matt_King: In this case, this is a region with some content in it. A region that contains a heading and some text. And then following the text, there is a disclosure button. As a screen reader user, it doesn't feel any different from any other instance of a disclosure
<jugglinmike> Matt_King: The reason they wanted it in the APG has to do with the approach to coding it, where you have a "section" element, and the idea is that everything inside of that section is clickable.
<jugglinmike> Adam_Page: I think it was especially a reaction to how, in the real world, people are stuffing tons of stuff full of stuff that they shouldn't (and risking access issues) just to make that entire surface clickable
<jugglinmike> Matt_King: So the alternative is that some people might use a button where you have a section?
<jugglinmike> Adam_Page: Yes, that some people might stuff everything in my regions into a button
<Daniel> q+
<jugglinmike> Matt_King: So the idea is to replace the button with a clickable section, and say "here's how you do it"
<jugglinmike> Adam_Page: And to do that without inventing anything new for ARIA or HTML--just to solve the use case with things that already exist
<jugglinmike> Matt_King: It looks to me like what you have for the details is a button element that doesn't look at all different from any of our "disclosure" buttons that we already have in APG
<jugglinmike> Adam_Page: Yes, that's right
<jugglinmike> Matt_King: When Scott presented this, I had the impression that there was something simpler or different about the coding than having to make a button. I guess not
<jugglinmike> Adam_Page: Scott made a code pen really early on when he made the issue for APG. I referenced that, taking it an beefing it up
<jugglinmike> Adam_Page: I will investigate what's going on with JAWS
<jugglinmike> Matt_King: I am using a pre-release version of JAWS, so it may be due to that
<jugglinmike> Matt_King: This is really just a different visual design for a disclosure that has a bigger click target
<jugglinmike> Adam_Page: Yes, I think that's a fair summary
<jugglinmike> Matt_King: Is the issue here about naming and helping people understand that they can have large, rich click targets?
<jugglinmike> Matt_King: Maybe we call this a "disclosure region" instead of a "disclosure button"
<Daniel> q?
<jugglinmike> Adam_Page: Jem called out that there is the Bootstrap "Card". That is a common UX paradigm
<jugglinmike> Matt_King: So maybe we call it an "expandable card"
<jugglinmike> Adam_Page: That could work
<jugglinmike> Matt_King: I think the first step is to move it into the "disclosure" example directory
<jugglinmike> Matt_King: Then we can avoid creating a whole new pattern
<jugglinmike> Adam_Page: Sounds good
<jugglinmike> Matt_King: We ought to be able to get this into the next publication. I'll see if I can mess around with words
<Daniel> https://github.com/w3c/aria-practices/issues/3215#issuecomment-2626979811
<jugglinmike> ask Daniel
<jugglinmike> ack Daniel
<Jem> +q
<jugglinmike> Daniel: I put a comment for us to think about what we want the screen reader user's experience to be
<jugglinmike> Daniel: As you arrow down through the things, you could press "enter" to expand. Making this go to the button and then hitting "enter" on that--maybe we should consider efficiency
<jugglinmike> Daniel: And for what it's worth, I don't experience any lag when testing with NVDA (though I'm using an NVDA beta)
<jugglinmike> Matt_King: If you're reading this with a screen reader, even if you knew that there was something expandable inside of this region before you got to this button, how would you know that you want to expand it before getting to the button? I'm presuming that you would want to read the content...
<jugglinmike> Matt_King: I'm trying to grasp what the alternatives might be and why they might be desirable
<jugglinmike> Adam_Page: I have to confess that the "clickable" announcement is a little mysterious to me, still. I don't know if it happens in VoiceOver at all
<jugglinmike> Adam_Page: Are JAWS and NVDA trying to be "smart" in the sense that if they see a "click" event listener on an element that is not typically focusable, do they bubble that information up?
<jugglinmike> Daniel: NVDA has that behavior enabled by default, but I turn it off
<jugglinmike> Matt_King: I do, too
<jugglinmike> Daniel: There's a setting in NVDA where you can actually turn it on or off whether you want "clickable" items announced
<jugglinmike> Daniel: As Adam_Page was saying, it's whenever they find a "click" event listener
<jugglinmike> Jem: Daniel shared that as a comment to issue 3215
<jugglinmike> Matt_King: JAWS and VoiceOver don't announce "clickable" by default, and a lot of NVDA users turn it off
<Jem> https://github.com/w3c/aria-practices/issues/3215
<jugglinmike> Matt_King: Thank you for the excellent discussion! This is great
<jugglinmike> Adam_Page: For my next step, I will do some JAWS testing and update the pull request to make this an example of the disclosure pattern
<jugglinmike> Matt_King: Awesome, thank you!
<jugglinmike> Zakim, end the meeting

[adampage]

Regarding my earlier notes about the HTML linter errors, I found two related issues:

• https://github.com/validator/validator/pull/1467
• https://github.com/validator/validator/issues/1771

[css-meeting-bot]

The ARIA Authoring Practices (APG) Task Force just discussed PR 3251 - New expandable region pattern.

The full IRC log of that discussion

<jugglinmike> Topic: PR 3251 - New expandable region pattern
<jugglinmike> github: https://github.com/w3c/aria-practices/pull/3251
<jugglinmike> Matt_King: Adam added a comment about some linting problems
<jugglinmike> Matt_King: It says that there are related issues in the linter. "Allow paragraphs in group" and "false positive for a valid role=image"
<jugglinmike> Matt_King: I wonder if those are the two things that are failing here
<jugglinmike> Matt_King: It says "some checks not successful", but oh, there's five failing
<jugglinmike> Matt_King: The coverage report check is failing. I haven't seen that in a while. How does that happen?
<jugglinmike> Matt_King: index.html coverage... Is this index generation or coverage report generation?
<jugglinmike> jongund: Looks like someone tried to manually change the coverage report even though it's automatically generated
<jugglinmike> Matt_King: "13 files changed"... I honestly forget how we handle this in the build process. It's a little tricky
<jugglinmike> jongund: There must have been some manual changes to the coverage file...
<jugglinmike> jongund: He could just restore the original file from the "main" branch and see if it builds
<jugglinmike> Matt_King: We might want to take lessons learned from modifying the .vnurc file in the patch we considered earlier in this meeting
<jugglinmike> Matt_King: If the validator is this buggy, then it almost starts to seem like more trouble than it's worth! I'm mostly joking, though--the truth is, it catches a lot of potential errors

[css-meeting-bot]

The ARIA Authoring Practices (APG) Task Force just discussed PR 3251 - New expandable region pattern.

The full IRC log of that discussion

<jugglinmike> topic: PR 3251 - New expandable region pattern
<jugglinmike> github: https://github.com/w3c/aria-practices/pull/3251
<jugglinmike> Matt_King: This is Adam_Page's awesome pull request
<jugglinmike> Matt_King: Before Adam_Page left, we were discussing where to place this example
<jugglinmike> Adam_Page: Yes. As I recall, we decided to move it into the existing "disclosure" pattern
<jugglinmike> Adam_Page: I made that change. It is now a "disclosure" example. I updated the "patterns" page to link to it
<jugglinmike> Matt_King: Do we have an open issue related to our pinning of the version of the linter?
<jugglinmike> Matt_King: We had something pinned, if I recall correctly
<jugglinmike> howard-e: We do not have an issue, but I created a pull request two weeks ago
<jugglinmike> Matt_King: So you have a pull request to un-pin it. I wonder if we should land that before Adam_Page makes any more changes to the linting specific to his pull request
<jugglinmike> howard-e: It's pull request 3262 https://github.com/w3c/aria-practices/pull/3262
<jugglinmike> Matt_King: That says "all checks have passed" right now on this one
<jugglinmike> Matt_King: With this new validator--are the old exceptions still needed?
<jugglinmike> howard-e: I didn't confirm, but I can do so pretty quickly
<jugglinmike> Matt_King: You can decide and go ahead and merge this as appropriate
<jugglinmike> Matt_King: And then after this one is merged, Adam_Page, let's see if your errors still pop up
<jugglinmike> Adam_Page: Sounds great!
<jugglinmike> howard-e: thank you!
<jugglinmike> Adam_Page: I'll stay tuned
<jugglinmike> Adam_Page: Ill also check in on NVDA
<jugglinmike> s/Ill/I'll/
<jugglinmike> Matt_King: Maybe we should finish the documentation before we seek additional feedback
<jugglinmike> Adam_Page: For what it's worth, before I pushed up my initial Pull request months ago, I chatted with Scott, and he endorsed my work
<jugglinmike> Matt_King: So you called it "disclosure card"?
<jugglinmike> Adam_Page: Yeah, I did, but it's not a strong opinion
<jugglinmike> Matt_King: Do you think that we should give it an alternative name in parenthesis, as we do in other places? E.g.. "(expandable region)"
<jugglinmike> Adam_Page: Maybe, "Disclosure (show card)" ?
<Adam_Page> Disclosure (Show/Hide) Card
<jugglinmike> Matt_King: I'm looking at the list of disclosure examples on the patterns page
<jugglinmike> Matt_King: In these, the HTML element that is the region--what is the element? Is it a "div" with the "role" region?
<jugglinmike> Adam_Page: The HTML element I'm using is "section" and I give it an accname with aria-labeledby
<jugglinmike> Adam_Page: That wasn't a strong opinion, either. I just did that because this was an expandable region from the get-go
<jugglinmike> Adam_Page: I may have complicated this because I chose to make multiple cards and to place them in a semantic ordered list
<jugglinmike> Adam_Page: That seems like a valid use-case, but it may be a distraction for this example
<jugglinmike> Matt_King: I guess that if we thought it was really important to show it as a collection of cards, then maybe. But maybe it would be better as an individual
<jugglinmike> Adam_Page: Yeah. And cards are often presented as a collection. That's why they're cards. From that perspective, it does feel appropriate to present them as a collection. And if it is a collection, it seems appropriate to present it as a semantic list
<jugglinmike> Matt_King: We have two levels of lists here
<jugglinmike> Adam_Page: That's because the fiction of the example is a conference with talks spanning multiple days
<jugglinmike> Adam_Page: The content is silly--it's tongue-in-cheek that I added hastily. I will swap in more straightforward content
<jugglinmike> Matt_King: From the perspective of testing in the ARIA-AT context, it would be good to bring it down to a single list. That would simplify the semantics
<jugglinmike> Adam_Page: And I don't think it would limit the example's utility in the APG. I can make that simplification
<jugglinmike> Matt_King: This is unlike accordion where you normally have one region exposed. If someone took this and ran with it, they could end up with many regions exposed.
<jugglinmike> Matt_King: I think "article" would be a better use. Articles are great for regions--they don't clutter the navigation

[howard-e]

Hey @adampage you can pull the latest vnu validator changes from main now to check how the html linting result changes here. From my quick check, looks like the Bad value “image” for attribute “role” on element “svg” error alone remains.

The pull should also clear up the intermittent link checker errors.

For the coverage report error, doing an npm run coverage-report and pushing the changed files should resolve it.

[howard-e]

@adampage running npm run reference-tables locally and committing and pushing that change will clear that remaining "Check examples/index.html" error.

Weird that lint-staged isn't catching that for you. Seems it should, just glancing at the file changes.

[adampage]

Sweet! Thanks for all your help, @howard-e. 🙏🏻

I’ve finished resolving all the checks, including an update to vnurc to suppress the svg[role="image"] error. Once validator/validator#1771 is resolved, we could remove that.

[adampage]

Hi @mcking65, I’ve finished up with the tweaks we discussed in our last weekly call. I also did some benchtesting with Chrome plus Narrator, NVDA, and JAWS 2024, as well as macOS VoiceOver. All of those combinations seem to behave well.

I’m keeping my fingers crossed that the JAWS performance issue you experienced in the previous version won’t be present in the latest commit. 🤞🏻 If it’s still there, please let me know and I’ll investigate that more deeply.

[css-meeting-bot]

The ARIA Authoring Practices (APG) Task Force just discussed PR 3251.

The full IRC log of that discussion

<Adam_Page> TOPIC: PR 3251
<Adam_Page> GitHub: https://github.com/w3c/aria-practices/pull/3251
<Siri> scribe+
<Siri> Matt: Thank you Adam for awesome updates
<Siri> Example is really good, performance issue, expansion and collapse is not working
<Siri> with JAWS
<Siri> Documentation update is required for FAQ content
<Siri> Adam will take care of it
<Siri> The way the pointer/focus ring/hover effect that will let people know they can click anywhere in the card
<Siri> Adam: With in card, there is visible button label, details, when user hover over tghe card , the details will get underline to indicate that what they say when they click a card
<Siri> Matt: Also add why we use Aritical over group/region in A11y features
<Siri> Article is used for rotor/quick nav navigate
<Siri> Also tell why we don't use region in this case
<Siri> Once Adam adds documentation, group will iterate on it
<Siri> High contrast, if system colors is used
<Siri> Adam: Built in HCM using some system colors
<Siri> Used Jon's PR content
<Siri> This example uses system colors instead of forced colors

[adampage]

Heya @mcking65 / @howard-e / @shirsha, I’ve just written a first draft of the supporting documentation for this example. Please have a look and let me know what you think?

[css-meeting-bot]

The ARIA Authoring Practices (APG) Task Force just discussed PR 3251 - New example demonstrating expandable cards/regions.

The full IRC log of that discussion

<howard-e> TOPIC: PR 3251 - New example demonstrating expandable cards/regions
<howard-e> github: https://github.com/w3c/aria-practices/pull/3251
<howard-e> Matt_King: Feeling like we're close to final review here. What do you think Adam_Page?
<howard-e> Adam_Page: I think so too. I made small quality of life changes to the code. I added preferred motion handling and mainly, I add a support draft of documentation for the pattern. So I think we're ready
<howard-e> Matt_King: Great. I haven't gotten to read through it all as yet
<howard-e> Matt_King: I was thinking we can expand the about just a bit .. to say "create an expandable card". So I'm wondering if we might provide a slightly more colorful description, mainly if people were searching for some word other than "card". I'm thinking of terms like "creating a card or region that can expanded or collapsed"
<howard-e> Matt_King: And maybe we highlight in the about section, that it can be expanded or collapsed by clicking anywhere within the card
<howard-e> Adam_Page: I think I did write a bit on that
<howard-e> Matt_King: I missed that, the "Authors sometimes ..."
<howard-e> Matt_King: This is pretty great
<howard-e> Matt_King: I'm thinking a bit that we haven't made such a statement in the APG or at least phrased in this way but I'm kinda liking it. Re: "To achieve this, authors may be tempted to nest the entirety of the rich summary within the disclosure button itself, but this can make the button’s accessible label cumbersome, inaccurate, or disorienting."
<howard-e> Matt_King: We might just want to break this into a couple of sentences
<howard-e> Adam_Page: I could turn it into a list "Authors may be tempted to do: bulleted list items"
<howard-e> Matt_King: I like that. What we're saying here is that people might want to do things here that are still html-legal. Does html permit headings inside buttons?
<howard-e> Adam_Page: I think it does
<howard-e> Matt_King: I just don't want us to note things authors may be tempted to do that aren't actually permitted
<howard-e> Adam_Page: In other words, we want to call out consequences that aren't valid in the first place?
<howard-e> Matt_King: Moreso, the pattern that breaks acecssibility. Guarding against that is a different kind of space for the APG to walk in
<howard-e> Adam_Page: also, checking the html spec, headings in buttons aren't permitted
<howard-e> Matt_King: However, it does mean that phrasing content is allowed to look like a heading
<howard-e> Matt_King: So what you could do here in your negatives is to say this doesn't permit things in your semantic headings markup
<howard-e> Matt_King: So things like not permitting links, making the label long and difficult to understand ... this is really good and I think we're getting somewhere here
<howard-e> Matt_King: So if you want to restructure that, I can come in and do more editorial changes
<howard-e> Adam_Page: Sounds good. And FWIW the about section is what I worked on the least. The bulk of what i did was in the accessibility section
<howard-e> Adam_Page: So definitely seeking some feedback as I have many details there so worried about overexplaining or leaving anything out
<howard-e> Matt_King: In the accessibility section, we typically cover the things that are non-obvious. For instance, I assume the reduced motion is in this list. The high contrast stuff is also non-obvious
<howard-e> Matt_King: Most of these explain the problems we're solving. The 3rd bullet talks about ... and brevity
<howard-e> Matt_King: So thinking we don't need the 1st bullet, the 2nd is a maybe. The 3rd we want to restructure to talk about the goal
<howard-e> Matt_King: This 4th I think is really important (the hover events)
<howard-e> Matt_King: Is there any accessibility thinking behind the choices you've made here that distinguishes your implementation from others that may be considered less accessible?
<howard-e> Adam_Page: Not really. The main motivation was to display a reaction and mostly on the side of UX
<howard-e> Matt_King: In some other examples like jongund's, we can borrow some of the wording like what was done in the radiobutton. This is similar to that work, right?
<howard-e> jongund: Yep, this is similar concept
<howard-e> Matt_King: So Adam_Page, you may just want to look there to borrow some of the wording for how this matters to accessibility
<howard-e> Matt_King: So pointing these things out is important to designers. What's missing is the reason why we did these things, to support accessibility. That's to help people understand why these are important elements of the design
<howard-e> Adam_Page: It's becoming clear as we go through this, that some of these decisions were done out of instinct, rather than the accessible reasoning
<howard-e> Matt_King: Well that's the difference with you who is honed in this work and the folks that come here without that seeking the guidance and why that's the guidance
<howard-e> Matt_King: So I think you have the breadth of feedback request here. I can plug some commits here and there to assist
<howard-e> Matt_King: Now also thinking we could push back the publication to the 19th so we could land this. It feels very close. This is ready for code and design review. But do we have regression tests?
<howard-e> Adam_Page: We have no regression tests
<howard-e> Matt_King: do you have any experience there?
<howard-e> Adam_Page: No but I would love some assistance there. I haven't had any experience writing from scratch
<howard-e> Matt_King: We have ids associated with each row in the role, property, state and index attributes
<howard-e> jongund: if you also look at the setup of the other disclosure examples, you could probably copy a lot of what's there because these are similar
<howard-e> jongund: I'd offer to help but I won't be available over the next week
<howard-e> Adam_Page: I can try to get that done. A little worried I won't be able to wrap it by publishing but will try
<howard-e> Matt_King: Another thing we can do after learning the aria-at examples aren't dependent on the publication is to even push out the date of the publication
<howard-e> Matt_King: We're potentially flexible on that
<howard-e> Matt_King: I think some folks would out there would be happy to see this get in. So maybe we should wait til next week to assign those reviewers
<howard-e> Adam_Page: Well the design and code is ready for folks to review
<howard-e> Matt_King: CurtBellew, would you be available to check out the code and design after the call?
<howard-e> Matt_King: So I'll assign jongund and CurtBellew as reviewers right now
<howard-e> jongund: just note as well if your css adds light-dark, it might mess with your page
<howard-e> Adam_Page: got it, is dark theme on the APG roadmap?
<howard-e> jongund: one way to do is to create your own web component. But just an idea
<howard-e> Matt_King: I think if we support light-dark, it would be APG wide and that would be dependent on the WAI resources templates
<howard-e> jongund: Makes sense. The main thing may be to try and show how one would support it in APG examples. So that may be a separate question on if we want to support it

[adampage]

Thanks very much for the review, @jongund!

I think the visual design looks good, just would like to change the focus border colors to use the same colors as the WAI website. The details button could also use the same colors as buttons in the WAI template.

I grabbed the focus state color from the WAI template and just pushed up a commit for that. Is that what you had in mind?

In other APG examples prefix CSS selectors with #ex1 to make sure styling for the example does not modify the template styling and it also helps provide more specific selectors for making sure the example is styled correctly..

I searched the repo for #ex1 inside CSS files and didn’t find any occurrences, but I’m still getting familiar with the APG code base. Could you orient me to an example for that elsewhere in the APG? I did see that the JS test files do scope their selectors using #ex1, so I’ll be sure to follow suit when I write the tests.

The CSS looks a little noisy to me, maybe you could do another pass to trim the CSS to the bare minimum to what is need for the card example.

I’m did already take a few passes at the CSS to remove unused styles, but I’ll take another look and see if I can refactor or reorganize that any further. If you have any suggestions, please let me know.

[css-meeting-bot]

The ARIA Authoring Practices (APG) Task Force just discussed PR 3251 - New example demonstrating expandable cards/regions.

The full IRC log of that discussion

<jugglinmike> Topic: PR 3251 - New example demonstrating expandable cards/regions
<jugglinmike> github: https://github.com/w3c/aria-practices/pull/3251
<jugglinmike> Matt_King: This is the new "Expandable card"/"expandable region" pattern
<jugglinmike> Matt_King: Last week, we discussed how it is essentially the example (all the code) is complete (except for the tests). Code-complete and design-complete
<jugglinmike> Matt_King: jongund gave some feedback on the design and on the CSS
<jugglinmike> Matt_King: As far as design feedback goes, Adam's last comment... It looks like Adam updated the focus state
<jugglinmike> jongund: I just returned, so I will take a look at it
<jugglinmike> Matt_King: It also looks like there was something related to the way he wrote selectors. jongund provided some feedback, and he didn't see any examples that mimic the feedback that you were providing
<jugglinmike> jongund: The thing that threw me was using an event handler on the document and then filtering the events. In our other examples, we were using querySelectAll to find elements that match and applying events to those
<jugglinmike> jongund: For me, it's harder to understand why there is an event handler on the whole document
<jugglinmike> Matt_King: I think your feedback sounds logical. In terms of how it would be easier to understand what we're looking for and filtering here
<jugglinmike> jongund: Maybe that's the way people write event handlers, now
<jugglinmike> jugglinmike: There are some technical reasons to prefer Adam's approach in production settings, but they generally don't apply to the patterns as we implement them for APG
<jugglinmike> Matt_King: Is this distinction important? Is it worth while to be consistent here?
<jugglinmike> jugglinmike: I'm generally in favor of consistency always, personally, but I think this is a editorial question
<jugglinmike> Matt_King: As an editor, I think I should only ask for changes if we specifically call them out in our code guide for consistency reasons. Otherwise, we should let it slide
<jugglinmike> jugglinmike: That sounds fair to me
<jugglinmike> Matt_King: In this case, the "altitude" of the event listener (if we can say this) is not something we're going to be picky about
<jugglinmike> jongund: I'll look at this some more and try to give more feedback
<jugglinmike> howard-e: I can review the tests before I go out-of-office
<jugglinmike> Matt_King: And I'm still on the hook for editorial feedback

[css-meeting-bot]

The ARIA Authoring Practices (APG) Task Force just discussed PR 3251 - New example demonstrating expandable cards/regions.

The full IRC log of that discussion

<jugglinmike> Topic: PR 3251 - New example demonstrating expandable cards/regions
<jugglinmike> github: https://github.com/w3c/aria-practices/pull/3251
<jugglinmike> Matt_King: This is what we've been calling the "expandable region" or the "disclosure card"
<jugglinmike> Matt_King: I'm going to finish my review of the editorial content this afternoon
<jugglinmike> Matt_King: I know jongund did a code review
<jugglinmike> Adam_Page: I've pushed changes for all the feedback I've received so far
<jugglinmike> Matt_King: jongund, do you have the time to review again?
<jugglinmike> jongund: Sure
<jugglinmike> Matt_King: Awesome. I'll request another review from you
<jugglinmike> howard-e: I reviewed the tests and some of the code changes. I had no issues
<jugglinmike> Matt_King: we had siri and CurtBellew on this one, as well
<jugglinmike> Jem: siri isn't here today, but CurtBellew is here
<jugglinmike> Matt_King: as I recall, CurtBellew was going to review the design and functionality
<jugglinmike> CurtBellew: Yes, I'll do that today
<jugglinmike> Matt_King: great, that will help today
<jugglinmike> Adam_Page: I made some minor tweaks to the CSS and to the documentation
<jugglinmike> Jem: Usually, when we have an example with links, we have a blank page as a placeholder
<jugglinmike> Matt_King: The link should do something
<jugglinmike> Matt_King: We decided that we weren't going to create a bunch of "dummy" pages
<jugglinmike> Matt_King: What do the links in the Tree Grid do?
<jugglinmike> Jem: They are "mailto:" links
<jugglinmike> Matt_King: There are some links in some of the dialogs. Those might open up a JavaScript alert
<jugglinmike> Adam_Page: What does the print button do?
<jugglinmike> Jem: It opens a modal dialog
<jugglinmike> Matt_King: The probably doesn't impact the tests because we're not testing the keyboard functionality of buttons or links. Only the "expand/collapse" functionality
<jugglinmike> Matt_King: We should have a regression test for each keyboard command that's documented
<jugglinmike> Adam_Page: Yes, we have that
<jugglinmike> Adam_Page: In the CSS, I'm using an experimental feature called "interpolate size". It's purely cosmetic. It is supported by Chrome and Edge, and Firefox may support it behind a flag.
<jugglinmike> Matt_King: Does it have a bad side effect if it's not supported?
<jugglinmike> Adam_Page: No. It is still functional without it
<Jem> https://github.com/w3c/aria-practices/pull/3251#discussion_r2155596977
<jugglinmike> Jem: If it doesn't have any bad impact when unsupported, I think we can keep it
<jugglinmike> Adam_Page: That sounds fine to me
<jugglinmike> Matt_King: I'm aligned with it as well
<jugglinmike> howard-e: I'm also fine with it (and I think I said as much in my review)
<Jem> https://www.w3.org/WAI/ARIA/apg/practices/read-me-first/
<jugglinmike> howard-e: I wonder if the "read this first" statement covers things like this. In the future, it could enhance the experience if an experimental feature is used, but it could be detrimental if absent
<jugglinmike> Jem: I'm sharing the "read this first" page. There, we have a section about "browser and assistive technology support"
<jugglinmike> Matt_King: as a code guide practice, I don't know if this is really experimental because it is already spec'd and being implemented. If we had doubt about the feature being broadly supported or if it could have a negative impact on the accessible experience
<jugglinmike> Adam_Page: For what it's worth, I gated this behind a "prefers reduced motion" media query
<jugglinmike> Matt_King: Great

[adampage]

Hi @a11ydoer and @mcking65, I found an instance of alert() feedback in the Feed pattern and imitated it here. Please let me know what you think!

[adampage]

Thanks, @mcking65. I’ve replaced my previous accessibility feature for article with your suggested text.

I also added the article role to the R/S/P table along with your suggested usage text. Does that all look correct?

[mcking65]

@adampage

I also pushed some changes to the about section to simplify and clarify wording. You may want to double check my work there.

[css-meeting-bot]

The ARIA Authoring Practices (APG) Task Force just discussed PR 3251 - New example demonstrating expandable cards/regions.

The full IRC log of that discussion

<jugglinmike> Topic: PR 3251 - New example demonstrating expandable cards/regions
<jugglinmike> github: https://github.com/w3c/aria-practices/pull/3251
<jugglinmike> Matt_King: Both Adam_Page and I were pushing changes today. I think those were minor and that we have sufficient approving reviews
<jugglinmike> Matt_King: There was one piece of "spin off" feedback regarding the character casing in JavaScript
<jugglinmike> Adam_Page: I don't think there is any other feedback that we haven't addressed.
<jugglinmike> Adam_Page: There might be some open questions remaining from earlier reviews... Nope, it looks like everything is resolved
<Daniel> q+
<jugglinmike> ack Daniel
<jugglinmike> Daniel: Do we want to add two phrases for the example to help explain the last paragraph?
<jugglinmike> Matt_King: We could make the last paragraph more specific
<jugglinmike> Daniel: There's another audience that visit APG to know how things work. And we have pages that are more explanatory for them
<jugglinmike> Matt_King: What do you have in mind? Maybe, "Instead, by modifying the structure to be a card that contains a button rather than a heading where all of its content is a button"
<jugglinmike> Adam_Page: We're distinguishing it from a vanilla disclosure
<jugglinmike> Matt_King: Ah, but the vanilla disclosure doesn't have a heading
<jugglinmike> Matt_King: "We modify the disclosure so that instead of the entire disclosure being a button containing plain test, we make it a card with the 'article' role"
<jugglinmike> Matt_King: There's a lot of stuff inside of the card besides just the button
<jugglinmike> Adam_Page: Right. And that interesting stuff--there's a lot of it in both the "summary" as well as the expanded form
<jugglinmike> Matt_King: I'm happy to help doing a little wordsmithing, if you like
<jugglinmike> Adam_Page: I can take a whack at it, but I feel like you have a better handle on the essence of what we need to communicate here. If you can offer a suggest, then I can wordsmith it
<jugglinmike> Matt_King: Yeah, I can do that.
<jugglinmike> Jem: When you search with the "filter", when does this example show up?
<jugglinmike> Jem: It's under "disclosure"
<jugglinmike> s/Jem:/Matt_King:/
<jugglinmike> Matt_King: We didn't include the words "region" or "expandable" in the final draft because we're not using the "region" role and because the card is more generic
<jugglinmike> Matt_King: We don't have a "card" pattern of any kind
<jugglinmike> Matt_King: If were to ever add a "card collection" pattern, we would probably used his code as an example of that
<jugglinmike> Matt_King: This almost demonstrates a "card collection" pattern. Adam_Page included three cards--that's a collection!
<jugglinmike> Matt_King: We have an open issue for search--we never implemented search

[mcking65]

@adampage

Here is my proposal. Replace the following text:

Instead, by slightly modifying the structure of the basic disclosure pattern and adding some light JavaScript event handling, it’s possible to create the desired experience in a valid, accessible way.

With the following:

This example avoids these problems by modifying the structure of the basic disclosure pattern. instead of having the entire summary contained within a button that controls a separate details container, it nests the expand and collapse disclosure button within an article element that presents a card. When the card is collapsed, it presents a rich summary and the disclosure button. When the card is expanded, its content also includes the additional details content. This structure allows the summary to include headings, links, or any other type of rich content while also enabling the disclosure button to have a concise, understandable accessible name. Finally, some light JavaScript makes the entire card clickable, so its pointer interactions are similar to the summary of a basic disclosure.

[adampage]

Thank you, @mcking65, this reads great to me. I’ve integrated your proposed text into our introduction.

[mcking65]

@adampage

Thank you. Looks great. It seems like the netlify preview is not building, but it shows up in my local and the preview looks perfect locally. I'll merge now.