WIP: Add CSS-AAM editor’s draft #2673

ZoeBijl · 2025-11-13T05:14:09Z

This description is a stub, please help expand it.

The creation of a CSS-AAM came up again during the tueseday ARIA session at TPAC (minutes for this session). @jcsteh and I voulunteerd to be editors for this document.

There’s still work that needs to be done before this can be merged:

@spectranaut, @ZoeBijl, and (optionally) @jcsteh should chat with Rahim and Scott about taking over this work
@daniel-montalvo should discuss with strategy team, make sure were on the same page
@ZoeBijl should create an overview of existing work done around this (issues, discussions, etc)
- Can be found on the CSS-AAM wiki
@ZoeBijl should clean up the old repository: w3c/css-aam (pending chore: prepare repository for new CSS-AAM css-aam#12 and chore: clean out gh-pages css-aam#13)
- Purge issues
- Purge PR
- Purge branches
Copy conformance section from core-aam

based on Daniel’s feedback

netlify · 2025-11-13T05:14:19Z

✅ Deploy Preview for wai-aria ready!

Name	Link
🔨 Latest commit	`6e4d275`
🔍 Latest deploy log	https://app.netlify.com/projects/wai-aria/deploys/69271e0948d7c300078d6fb9
😎 Deploy Preview	https://deploy-preview-2673--wai-aria.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify project configuration.

ZoeBijl · 2025-11-17T09:31:06Z

Could someone look at why the roleinfo check is failing?

jcsteh

Thanks so much for getting this started. Sorry it took me a while to get to this.

jcsteh · 2025-11-25T06:07:38Z

css-aam/README.md

+
+CSS Accessibility API Mappings (css-aam) developed by the [Accessible Rich Internet Applications Working Group](https://www.w3.org/WAI/ARIA/) (previously the [Web Applications Working Group](https://www.w3.org/2019/webapps/)).
+
+This specification was part of the [ARIA suite](https://www.w3.org/WAI/ARIA/deliverables). General information about editing the specification is in the [main ARIA repository readme](https://github.com/w3c/aria/).


nit: Should this be "is" instead of "was"?

I don't believe CSS AAM was every published by the web apps working group. HTML AAM was for a time, which I assume is where this text came from. But, CSS AAM wasn't worked on at all during the period web apps wg had html aam

remove the second paragraph.

jcsteh · 2025-11-25T06:10:24Z

css-aam/index.html

+                //previousMaturity: "WD",
+                //previousPublishDate: "2012-10-25",
+                //previousURI: "http://www.w3.org/TR/",
+                copyrightStart: "2016",


nit: Are we keeping anything from the old doc? if not, should this be 2025?

We’re starting fresh, so yea let’s change to 2025.

change to 2025

css-aam/index.html

jcsteh · 2025-11-25T06:19:15Z

css-aam/index.html

+                <strong>This document is subject to change without notice.</strong>
+            </p>
+            <p>
+                This document was initially developed by and with the approval of the <a href="https://www.w3.org/WAI/APA/task-forces/css-a11y/">CSS Accessibility Task Force</a>, a collaboration of


Are we keeping anything from the original document? (Was there anything to keep?) If not, should we drop mention of the older collaboration that didn't bear fruit?

remove collaboration

jcsteh · 2025-11-25T06:31:32Z

css-aam/.editorconfig

+charset = utf-8
+end_of_line = lf
+indent_style = space
+indent_size = 4


Should we use indent_size = 2 for consistency with the other ARIA specs?

i’d like to discuss this tonight during the editor’s meeting. i prefer 4 spaces for readability but not a hill i’d like to die on. @jcsteh do you have a preference?

I tend to prefer 2 spaces, but same here: not a hill I'd like to die on. I figured consistency would be best though, which just happens (as a total coincidence) to support my preference. 😉

jcsteh · 2025-11-25T06:34:23Z

css-aam/index.html

+                <h3>General Rules for Exposing WAI-ARIA Semantics</h3>
+            </section>
+            <section id="css-property-mappings">
+                <h3>CSS Property mappings</h3>


nit: Title case.

Suggested change

<h3>CSS Property mappings</h3>

<h3>CSS Property Mappings</h3>

jcsteh · 2025-11-25T06:34:41Z

css-aam/index.html

+                <h3>CSS Property mappings</h3>
+            </section>
+            <section id="css-pseudo-element-mappings">
+                <h3>CSS Pseudo-element mappings</h3>


nit: Title case.

Suggested change

<h3>CSS Pseudo-element mappings</h3>

<h3>CSS Pseudo-element Mappings</h3>

jcsteh · 2025-11-25T06:55:07Z

css-aam/index.html

+        </section>
+        <section>
+            <h2>Mapping CSS to Accessibility APIs</h2>
+            <section id="css-mapping">


Suggested change

<section id="css-mapping">

<section id="mapping_general">

jcsteh · 2025-11-25T07:08:13Z

css-aam/index.html

+        <section>
+            <h2>Mapping CSS to Accessibility APIs</h2>
+            <section id="css-mapping">
+                <h3>General Rules for Exposing WAI-ARIA Semantics</h3>


I initially thought about removing this section altogether. Even though the whole point of this spec is to map CSS to accessibility APIs, almost none of it can be expressed in terms of default ARIA semantics. Anchor positioning might have been one case (mapping to aria-details), but the consensus seems to be to scrap that. However, I can think of one exception: pseudo-elements can have a default ARIA role of "image" if they have image content and alt text. So I guess that means we need this section after all?

Suggested change

<h3>General Rules for Exposing WAI-ARIA Semantics</h3>

<h3>General Rules for Exposing WAI-ARIA Semantics</h3>

<p>

Most CSS accessibility API mappings cannot be expressed in terms of WAI-ARIA semantics. However, there are some exceptions such as a pseudo-element which has generated content and alternative text. Where a CSS property or pseudo-element specifies default WAI-ARIA semantics, it MUST be exposed to the platform <a class="termref">accessibility APIs</a> in a way that conforms to

<a class="core-mapping" href="#mapping_general">General rules for exposing WAI-ARIA semantics</a> in the [[[core-aam-1.2]]].

</p>

I think if there’s an exception we could have the section and say what you said: “generally there are no default mappings except for x and y.”

I edited my diff suggestion above to incorporate your suggestion and also fix a copy/paste error.

jcsteh · 2025-11-25T07:39:21Z

css-aam/index.html

+                <h3>CSS Pseudo-element mappings</h3>
+            </section>
+            <section id="css-pseudo-element-mappings">
+                <h3>CSS Mapping pseudo-class selectors</h3>


Suggested change

<h3>CSS Mapping pseudo-class selectors</h3>

<h3>Mapping CSS Pseudo-class Selectors</h3>

<p>

CSS pseudo-class selectors are not directly exposed to accessibility APIs and have no direct impact on the <a class="termref">accessibility tree</a>. However, when a pseudo-class selector matches, this may cause additional CSS properties or pseudo-elements to apply. These must be exposed to accessibility APIs as described in other sections of this specification. In addition, many pseudo-class selectors match based on element states; e.g. the enabled, disabled, required and focused states. These should be mapped as described in the Accessibility API Mappings specification for the host language such as [[HTML-AAM]].

</p>

Co-authored-by: James Teh <[email protected]>

daniel-montalvo · 2025-11-26T18:00:32Z

@daniel-montalvo should discuss with strategy team, make sure were on the same page

Great to have this work started and progressed on during this Charter period, but in order for this to become either CR or REC we'd have to recharter. Our current charter is too strict that we'd be doing this under HTML-AAM

In any case, taking this to REC in one year would be challenging anyway, so I think we are good if we publish an FPWD and get this ready for CR by the time we recharter.

pkra · 2025-11-26T18:58:12Z

Could someone look at why the roleinfo check is failing?

@ZoeBijl I just filed #2683 to look into it.

ZoeBijl added 2 commits November 12, 2025 16:55

feat: add core-css skeleton

843e43a

chore: update css-aam github workflow

9187e51

based on Daniel’s feedback

ZoeBijl requested review from daniel-montalvo, rahimabdi, scottaohara and spectranaut November 13, 2025 05:14

ZoeBijl assigned jcsteh and ZoeBijl Nov 13, 2025

ZoeBijl added the Needs consensus label Nov 13, 2025

chore: implement feedback based on TPAC session

755ad0d

ZoeBijl added this to ARIA Editors Nov 21, 2025

ZoeBijl moved this to Agenda+ in ARIA Editors Nov 21, 2025

jcsteh requested changes Nov 25, 2025

View reviewed changes

correct Jamie’s details

6e4d275

Co-authored-by: James Teh <[email protected]>

pkra mentioned this pull request Nov 26, 2025

roleinfo action false positives #2683

Open


		CSS Accessibility API Mappings (css-aam) developed by the [Accessible Rich Internet Applications Working Group](https://www.w3.org/WAI/ARIA/) (previously the [Web Applications Working Group](https://www.w3.org/2019/webapps/)).

		This specification was part of the [ARIA suite](https://www.w3.org/WAI/ARIA/deliverables). General information about editing the specification is in the [main ARIA repository readme](https://github.com/w3c/aria/).

	<h3>CSS Property mappings</h3>
	<h3>CSS Property Mappings</h3>

	<h3>CSS Pseudo-element mappings</h3>
	<h3>CSS Pseudo-element Mappings</h3>

-                <h3>CSS Mapping pseudo-class selectors</h3>
+                <h3>Mapping CSS Pseudo-class Selectors</h3>
+                <p>
+                    CSS pseudo-class selectors are not directly exposed to accessibility APIs and have no direct impact on the <a class="termref">accessibility tree</a>. However, when a pseudo-class selector matches, this may cause additional CSS properties or pseudo-elements to apply. These must be exposed to accessibility APIs as described in other sections of this specification. In addition, many pseudo-class selectors match based on element states; e.g. the enabled, disabled, required and focused states. These should be mapped as described in the Accessibility API Mappings specification for the host language such as [[HTML-AAM]].
+                </p>

WIP: Add CSS-AAM editor’s draft #2673

Are you sure you want to change the base?

WIP: Add CSS-AAM editor’s draft #2673

Conversation

ZoeBijl commented Nov 13, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

netlify bot commented Nov 13, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

✅ Deploy Preview for wai-aria ready!

Uh oh!

ZoeBijl commented Nov 17, 2025

Uh oh!

jcsteh 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!

Choose a reason for hiding this comment

Uh oh!

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!

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!

jcsteh Nov 25, 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!

daniel-montalvo commented Nov 26, 2025

Uh oh!

pkra commented Nov 26, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

6 participants

ZoeBijl commented Nov 13, 2025 •

edited

Loading

netlify bot commented Nov 13, 2025 •

edited

Loading

jcsteh Nov 25, 2025 •

edited

Loading