Add Practice Page for Supporting Color Contrast Settings

[mcking65]

Part of the resolution of issue #2864.

Preview Links

• Preview revised practices page in compare branch
• Preview color contrast settings practice page in compare branch

---

WAI Preview Link (Last built on Mon, 20 Apr 2026 01:29:27 GMT).

[jongund]

@mcking65
This is ready for review, I think it would be great if James Nurthen could review it.

[css-meeting-bot]

The ARIA Authoring Practices (APG) Task Force just discussed New high contrast practice page.

The full IRC log of that discussion

<Jem> Topic:New high contrast practice page
<Jem> github:PR 2991 - Add Practice Page for Supporting High Contrast
<dmontalvo> s/:New/: New/
<Jem> github:https://github.com//pull/2991
<dmontalvo> Matt_King: Big thanks to jongund, this is great
<dmontalvo> ... In the PR there is a link to the preview
<Jem> https://deploy-preview-315--aria-practices.netlify.app/aria/apg/practices/high-contrast/
<dmontalvo> ... At this point in the drafting process we have very good and useful info. Now I am thinking that we probably want to focus a bit on information architecture
<dmontalvo> ... Think about our audience will learn from this page, we have different audiences
<dmontalvo> ... We have not covered testing techniques here yet
<dmontalvo> ... We had said if there is already a resource in the WAI website we could use
<dmontalvo> Daniel: Maybe Easy Checks, not clear on specific
<dmontalvo> Matt_King: Can we open an issue to that and then link from our pages?
<dmontalvo> Daniel: We could, that's under EO
<dmontalvo> Matt_King: We can start drafting it here, then open an issue to Easy Checks, and based on traction we could eventually remove it from here
<dmontalvo> jongund: I could do that
<dmontalvo> Matt_King: It seems to me there is something really valuable that you learned from James. I don't think EO would have included this information, they have more general contrast testing tools
<dmontalvo> ... I documented how to test this color contrast issues
<dmontalvo> Matt_King: Probably it's on our own wiki under accessibility testing
<Jem> https://github.com/w3c/aria-practices/wiki/Pull-Request-Review-Process
<dmontalvo> Daniel: Probably that's out of scope for Easy Checks, we'd have to include this ourselves
<dmontalvo> CurtBellew: Are we saying this is too complicated?
<dmontalvo> Matt_King: No, just out of sccope for the Easy Checks project
<dmontalvo> jongund: It's not that complicated to put Windows or Linux in high contrast mode
<siri> q+
<dmontalvo> Matt_King: Under operating system, high contrast features, do you know if we could provide links to the Microsoft, Apple, and Google documentation about those features?
<dmontalvo> Jem: Wouldn't it be changing?
<dmontalvo> Matt_King: I'd hope they have stable information about accessibility features
<Jem> https://support.microsoft.com/en-us/windows/change-color-contrast-in-windows-fedc744c-90ac-69df-aed5-c8a90125e696#:~:text=Select%20the%20Start%20button%2C%20and,colors%20on%20the%20screen%20change.
<dmontalvo> Matt_King: Our current info is not very useful. Without any documentation to help people turn it on and off, I don't think it's actionable information
<dmontalvo> ... One solution to that is for us to provide a link to their documentation about the feature
<dmontalvo> jongund: Probably these days the accessibility links are more stable than they were
<dmontalvo> Matt_King: Also if a link breaks, our link checker will ick it up
<dmontalvo> Jem: Good idea
<dmontalvo> jongund: I don't have a recent Android device
<dmontalvo> Matt_King: Anybody in this group can find the appropriate info
<dmontalvo> Matt_King: Also, where we are talking about the use of specific CSS properties, it would be great to link to the spec
<dmontalvo> s/to the spec/directly to the spec or to MDN/
<dmontalvo> Matt_King: I am going to spend a bit on time on this PR, to focus on what using these things does, for people to understtand the "Why"
<dmontalvo> jongund: Do you think the screenshots are useful?
<dmontalvo> Matt_King: Love the idea of making things more visual, I can't comment on those though
<Jem> System Colors
<Jem> "The following table identifies the current system colors defined in CSS Color Module Level 4. System colors are supported in all major browsers, but the actual colors they render may vary between browsers and operating systems based on default and user theme and contrast settings."
<dmontalvo> jongund: What about the table on the system colors section that explain how browsers deal with ach of the colors
<dmontalvo> ... In Windows, it changes the colors used by the OS, i mac it just filters them out and transforms the bitmap
<dmontalvo> ... If you are taking a screenshot on the mac you are getting that without high contrast
<dmontalvo> Matt_King: That is actionable information
<dmontalvo> ... For sccreen reader users the sample column is blank. I understand it's just a color in there
<dmontalvo> ... Should be try to put something in there?
<dmontalvo> Matt_King: Should we put an ARIA label on the td?
<dmontalvo> jongund: Sample accent color
<dmontalvo> Matt_King: I think it'd be cool to have the name of the color
<dmontalvo> jongund: The actual color varies depending on the setting
<dmontalvo> Jem: But you have the hex code
<dmontalvo> Matt_King: We don't want hex code in the label, just the name that corresponds to it
<dmontalvo> Jem: I think it's possible
<dmontalvo> rrsagent, draft minutes
<RRSAgent> I have made the request to generate https://www.w3.org/2024/06/04-aria-apg-minutes.html dmontalvo
<dmontalvo> Meeting: ARIA APG Teleconference
<dmontalvo> Chair: Mat
<dmontalvo> rrsagent, draft minutes
<RRSAgent> I have made the request to generate https://www.w3.org/2024/06/04-aria-apg-minutes.html dmontalvo
<dmontalvo> zakim, bye
<Zakim> leaving. As of this point the attendees have been CurtBellew, curt_bellew, Arie
<dmontalvo> rrsagent, bye
<RRSAgent> I'm staying, dmontalvo; no access has been specified for the meeting record
<Jem> rrsagent, make minutes
<RRSAgent> I have made the request to generate https://www.w3.org/2024/06/04-aria-apg-minutes.html Jem
<Jem> regret+ Mike
<Jem> rrsagent, make minutes
<RRSAgent> I have made the request to generate https://www.w3.org/2024/06/04-aria-apg-minutes.html Jem
<Jem> MEETING: ARIA APG

[jongund]

@mcking65
I have edited the color settings to simplify the section on supporting Windows high contrast settings.

[jugglinmike]

The ARIA Authoring Practices (APG) Task Force just discussed this issue.

The full log of that discussion

Matt_King: This is a giant pull request, and it’s been open for a long time. I recently merged the “main” branch back into it to make sure there are no conflict
Matt_King: It may be trying to do too much
Matt_King: jongund and I are the primary authors. jongund did a lot to pull together the relevant information, including a survey of blog posts. We were trying to hit the bar of being practical.
Matt_King: I think what might be most helpful right now is to get some general feedback right now. High-level feedback on whether it is organized in a way that we believe will be helpful to a reader who is interested in this topic. Also, are we covering useful information?
Matt_King: I’m trying to figure out: what’s the best way to move this forward? I don’t want to put something in APG if it’s hard to maintain but not actually useful.
jongund: My biggest concern is that in the APG, we don’t do much of any of this.
jongund: Putting it in makes it look like it’s important to do, but we don’t do it
jongund: We have some examples that demonstrate doing some of these things
jongund: But from a practicality standpoint: should I implement contrast?
Matt_King: That’s a good point. What we would do in the APG or what we wouldn’t do in the APG does suggest something about the importance of each item
Matt_King: Are these things that people don’t do because they don’t have to? Or because they don’t prioritize it?
Matt_King: What should the APG cover in this space?
jongund: People see these things, so we should say something about them. Saying nothing discounts them to other people. Readers will see these things out there and wonder if they should do something about them.
Adam_Page: At Hilton, we are generally pretty aware and savvy about the techniques that are described here. We use them as little as possible because we want things to just work”. We don’t want them to get in the way of default behavior
Adam_Page: We do have some pretty specific scenarios where we use “high contrast” mode, eg. in our “tab panel” implementation (our “active tab” includes some high-contrast-mode specificity to ensure that the visual indication of the active tab shows up there)
Matt_King: is that in the system colors?
Adam_Page: Yes
Matt_King: Another company out there that doesn’t have your awareness is including things based on the APG. If you’re doing styling that disappears if someone is using these accessibility settings, then this is important. That’s kind of a prioritization statement.
Matt_King: Are there any automated checks out there that say, “you ARE doing automated styling” and that will disappear if these features are in use?
Adam_Page: Not that I’ve seen.
Matt_King: Computed style is available to all the checkers
Adam_Page: Yes, but I haven’t seen any checker that attempts to deduce that the style is informative
Matt_King: Ah, right. Recognizing the problems from specific properties applied in specific ways is not necessarily deterministic.
Adam_Page: right
Adam_Page: I think this is really useful. It’s interesting that we’re considering it in APG because ARIA figures into it so lightly
Matt_King: Yes, that’s true.
Adam_Page: It’s probably no coincidence that the one place at Hilton where we DO do something is in an ARIA feature (the tab-set). Otherwise, we try to rely on native semantics.
Matt_King: I wonder if it would be useful to state something along those lines in the into
Matt_King: How do you do something at the top of this that say, “for you, this is interesting and here’s why” so that for everyone else, they recognize that it’s safe to ignore the page.
Matt_King: So from your point of view, Adam_Page, this still seems potentially valuable in the APG
Adam_Page: Definitely
jongund: What about color scheme (light/dark modes)?
Adam_Page: Hilton doesn’t support them in our web applications (though we do in our native mobile apps)
jongund: Does the W3 support it?
daniel: The specifications do. I’m not sure about the WAI website
joe: I think it would be useful to see these considerations in one place. I’ve seen each topic in separate areas, so collecting them together is great.
joe: Having considerations against each method (perhaps in a new column of the table) would be nice
joe: It would be nice to have “things to look out for” when using high-contrast mode. Just to sort of walk people through that process.
Matt_King: Can that table handle another column? It feels wide to me, but I can’t see it.
joe: Visually, it does look quite large on the page. I’m not sure
Matt_King: Were you suggesting that near the beginning, we add some text?
joe: Something about what people should check for when it comes to what visual information will be perceivable
Adam_Page: On the “quantity spin button” example I built last year, I did do some high-contrast work. I don’t remember specifically what I did, though
Adam_Page: Quantity Spin Button example and mention of forced colors https://www.w3.org/WAI/ARIA/apg/patterns/spinbutton/examples/quantity-spinbutton/#:~:text=When%20forced%20colors%20are%20enabled%2C%20system%20color%20keywords%20are%20used%20to%20ensure%20visibility%20and%20sufficient%20contrast%20for%20the%20spin%20button%E2%80%99s%20content%20and%20interactive%20states.
Matt_King: What would the problem be if people did NOT do that? Is that the kind of guidance we’re looking for?
Adam_Page: I think one active state might not show up
Matt_King: The fact that you can’t remember even after reading what we’ve written is a little concerning. Maybe we should update the wording to describe the specific situation
jongund: There are some broken parts to contrast themes, e.g. with pseudo-elements
Matt_King: It sounds like there is some value in continuing this work
Matt_King: It sounds like we need some kind of introductory statement that describes when/how this is useful
Matt_King: And a comment on the “quantity spin button” that explains “this is what would have happened if we didn’t implement high-contrast” would be helpful
jongund: There is a section at the end about SVG versus bitmap graphics
Matt_King: Maybe that doesn’t belong. That may be another future discussion
Adam_Page: I have time to read through this.
Adam_Page: I can start by doing exactly what you suggested regarding adding some explanatory text (it has to do with visually making three buttons appear as one. I used “Highlight” to do that (https://github.com/w3c/aria-practices/blob/main/content/patterns/spinbutton/examples/css/quantity-spinbutton.css#L17). It may have been somewhat uninformed at the time)
Matt_King: If we have an example like this, in other parts of the article, we have screenshots to depict what the failure state looks like in high-contrast mode (along with screenshots to depict the “normal” visual rendering). That demonstrates the kind of problem that authors need to be aware of
Matt_King: If we could knock this one out in the next couple months, it would be great to get it out of the backlog!

[joelamyman]

I think I put myself forward to have a read through this and provide any feedback, although I can't see that in the minutes, so please feel free to dismiss this feedback if I've got this issue confused with another 😅

This is a really great piece and does such a great job at consolidating these different colour-related settings, and providing guidance around how they work, how to develop for them, and how to test them. I think this is a fantastic resource, and would be great for people trying to understand the topic.

I've left a few minor points of feedback, but one other thing I wanted to mention is around the structure of the document. It seems like it might have changed a few times with content moving around a little bit, and is ever so slightly inconsistent.

When we looked at the page during the previous APG task force call, I thought it could do with information about authoring practices for each colour setting, however, after reviewing the page I now see that this is not needed as every section has this.

To help make the structure more clear, I wonder if each section could be separated in to:

<h2><Name of the setting></h2>
  <h3><Name of the setting> Example</h3>
  <h3>Supporting <Name of the setting></h3>
  <h3>Testing <Name of the setting></h3>

I note that most sections follow this, but having it consistent would make this really clear.

For the suggested “Supporting…” heading, I don't think this needs additional content, but my suggestion is more to move any applicable content from each setting’s intro paragraph, and put it under a dedicated heading to make it easy to find, given how important it is.

To this effect, I also wondered if the “SVG graphics” section and “Testing for Contrast Theme Support” headings, could fall under the “Contrast Themes” h2 to also help improve the structure.

[joelamyman]

I checked this a few times, and I wonder if this line is relating to the "Browser System Color Support" table later on in the page. Maybe it's been moved since this content was first written, as the next table after this text relates to the switch example. Therefore, I wondered if we wanted to add a link in this text, to allow people to jump to the "Browser System Color Support" table.

[jongund]

If you were looking in the pull request you won't see it, it is a generated table that is visible in preview mode.

[joelamyman]

The “HTML range slider” link doesn’t seem to redirect anywhere. I wasn’t sure where this should point to, or whether this content needs removing?

[jongund]

I have removed this section, I do not think we should do to much about using media queries for custom colors, do many bugs.

[mcking65]

@joelamyman really like your suggestion for the structure of the content.

[css-meeting-bot]

The ARIA Authoring Practices (APG) Task Force just discussed PR 2991: Add Practice Page for Supporting Color Contrast Settings by mcking65.

The full IRC log of that discussion

<jugglinmike> subtopic: PR 2991: Add Practice Page for Supporting Color Contrast Settings by mcking65
<jugglinmike> github: https://github.com//pull/2991
<jugglinmike> Matt_King: jongund_ do you want to implement this feedback, or should I?
<jugglinmike> jongund_: I can take care of it
<jugglinmike> Matt_King: Thank you! I think most of this feedback is pretty straightfoward
<jugglinmike> Matt_King: One part concerns the whole structure. Thanks to JoeLamyman for bringing a holistic perspective
<jugglinmike> Matt_King: That is a clear and well-thought-out suggestion, so I think it's worth incorporating

[css-meeting-bot]

The ARIA Authoring Practices (APG) Task Force just discussed PR 2991: Add Practice Page for Supporting Color Contrast Settings by mcking65.

The full IRC log of that discussion

<jugglinmike> subtopic: PR 2991: Add Practice Page for Supporting Color Contrast Settings by mcking65
<jugglinmike> github: https://github.com//pull/2991
<jugglinmike> Matt_King: We had a review from Joe, who suggested some changes
<jugglinmike> Matt_King: And this morning, jongund pushed a commit
<jugglinmike> jongund: Yeah, I've been re-organizing the heading structure based on those suggestions
<jugglinmike> jongund: I'm going to work on updating some of the content, too. We've been missing a section for testing
<jugglinmike> jongund: So this is in-progress
<jugglinmike> jongund: I'll send an e-mail to the list when this is ready
<jugglinmike> Matt_King: Sounds like good progress! Thank you!

[daniel-montalvo]

Discussed in 29 April meeting

[css-meeting-bot]

The ARIA Authoring Practices (APG) Task Force just discussed PR 2991: Add Practice Page for Supporting Color Contrast Settings by mcking65.

The full IRC log of that discussion

<jugglinmike> Subtopic: PR 2991: Add Practice Page for Supporting Color Contrast Settings by mcking65
<jugglinmike> github: https://github.com//pull/2991
<jugglinmike> Matt_King: Here, jongund has made updates, so it's ready for the next round of review
<jugglinmike> jongund: Yeah, I'm caught up on all the feedback I've received to date
<jugglinmike> Matt_King: We're looking for feedback from a few people
<jugglinmike> Matt_King: The person who last requested changes was Adam
<jugglinmike> Matt_King: jongund, if you've responded to those changes, then I think I should re-request review from Adam. I've done that just now
<jugglinmike> Matt_King: We haven't had participation from Sarah in a while. I wonder if she could look again because she had a lot of input before...
<jugglinmike> Matt_King: It would be great if we could get Sarah's input on the current state
<jugglinmike> Matt_King: howard-e is also on the list of reviewers
<jugglinmike> Matt_King: CurtBellew and JoeLamyman, both of your names are on here. Are you able to do those reviews?
<jugglinmike> JoeLamyman: Yes
<jugglinmike> CurtBellew: Yes
<jugglinmike> Matt_King: I think all of your feedback has been incorporated, JoeLamyman
<jugglinmike> JoeLamyman: Awesome, thank you
<jugglinmike> Matt_King: It seems like I should reach out to people directly and find out if they are available (and remove them from the "reviewers" list if they are not)