Request: The "Notes on ARIA use in HTML" for example would be good introduction and maybe would be better placed at the top of the document. 

Fix: The paragraph intro is standard to w3c documents, and necessary given that this is only one of several important w3c WAI ARIA documents, and it has a specific "hands on" scope... the intro paragraph explains what the document is and what it is not. If there are specific suggestions on how the first section could be improved while retaining the necessary qualities of an w3c introduction we would be glad to hear suggestions.

Request: Under the first rule of ARIA use - the "circumstances" section should have the bullet item "If the feature is available in HTML but it is not implemented or it is implemented, but accessibility support is not." first IMO - as this is a big reason why many devs will use ARIA in the first place. 

Fix: Moved it to first bullet in list

Request: In the section "Adding an ARIA role overrides the native role semantics" - maybe this should clarify by stating that it /only/ overrides the native role semantics and leave the the "behaviours, states and properties of the host element" intact. This is implied in the text but could be made clearer.
For example. In the section "What adding a role does not do?
Maybe it could be clearer that you are talking about "Adding an ARIA role does not change the behaviours, states and properties of the host element but only the native role semantics." - or similar.

Fix:Rewrote the note adding to it
Note: likewise, changing the role of an element does not add behaviors, properties or states to the role used. ARIA does not change the way it looks or acts in a browser. For instance, when links are used to behave like buttons, adding role="button" alone is not sufficient. It will also be necessary to make it look and act like a button, including add a key event handler that listens for the Space key which native buttons do.


Request: I think the inline link context in some cases could be improved but rewording. Take the link "add those yourself" the context is in the previous sentence, (unless you add some ARIA or course ;-))

added to the note:
Note: likewise, changing the role of an element does not add behaviors, properties or states to the role used. ARIA does not change the behavior or visual layout of an HTML element in a browser. For instance, when links are used to behave like buttons, adding role="button" alone is not sufficient. It will also be necessary to make it look and act like a button, including add a key event handler that listens for the Space key which native buttons do.


Request: The section "Add ARIA inline or via script?
If the ARIA role or aria-* attribute does not rely on scripting to provide interaction behaviour, then it is safe to include the ARIA markup inline. For example, it is fine to add ARIA landmark roles or ARIA labelling and describing roles inline. If the content and interaction is only supported in a scripting enabled browsing context, for example Google docs applications require JavaScript enabled to work, so it is safe for them to include the ARIA markup inline." is a little confusing. It seems to say the same thing that it is safe to add ARIA inline in both scripted/non-scripted environments. If this is the case, fine. If there are distinctions, they need to be made a little clearer.  If they are the same changing the last sentence to "If the content and interaction is only supported in a scripting enabled browsing context, for example Google docs applications that require JavaScript enabled to work, it is also safe to include the ARIA markup inline." The Excel SpreadSheet graphic seems a little random and when advising to add ARIA via scripting it would be good to either include an example in the doc of how to do that and/or a link to resource where you can find out more.

Fix: Amended the section with your suggestion and added a sentence for clarity:
Otherwise insert, change and remove ARIA via scripting. For instance, a collapsed section of a tree widget might look like this:

<li role="treeitem" aria-expanded="false" ... 

It is changed using JavaScript to this when the user opens the section:

<li role="treeitem" aria-expanded="true" ..

Request:On 'ARIA Validation' it may be a good idea to add something along the lines of "these validation errors will often be in no way indicative of ARIA creating any real world accessibility issues or resulting in a negative user experience but are merely the result of automated validation tests that cannot accommodate ARIA accessibility annotations" - or similar.

Fix: These validation errors in versions of HTML prior of HTML5 are in no way indicative of ARIA creating any real world accessibility problems nor do they mean there will be a negative user experience. They are merely the result of old automated validation tests that do not accommodate ARIA accessibility annotations.

In "Use of role=presentation" section it may be best to say:

"Adding role=presentation removes the role semantics from its parent element"  - sounds better than "the element it is on". Also it ties back to your previous point. If behaviors, states and properties are maintained - mention that here also as this ties back to your earlier point and will reinforce prior learning (as such).

I would change the example:

This:

<h1 role=presentation>text</h1>

becomes this:

<>text</>

because, are you suggesting this is desirable or something that a dev would do? I think give an example that represents a real use case - or better use case. This is partially because reading it does give the impression that adding ARIA role 'breaks' the parent element. I think this is down to the empty angle brackets (<>text</>). Maybe explaining the net impact of these <> in the doc would help? If it just means that the element is then parsed as a text string for example, then spell that out for the reader (in particular as they appear a lot later on in the document).

Fix: Added a sentence

In other words, it is just reported in the accessibility tree as a text string with no semantic meaning. [Need to check if flat text is reported to the accessibility tree] 

In the sentence" For elements with no required children, any elements nested inside the element with role=presentation preserve their semantics." it would be better to spell it out. What persevered semantics  - if state, properties etc then make that clear.

Fix: added sentence "In other words, it is just reported in the accessibility tree as a text string with no semantic meaning."

Request: >WRT "aria-labelledby and aria-describedby" we are working in the WCAG TF on ARIA techniques that may be useful here, when they are ready for prime time I'll let you know. Finally, when you say "Abstract roles "Do not use the following abstract roles as they do not do anything!" It would be good to clarify what you mean (as the first question may be - why are they there, why do they exist etc?).

Fix: Added a sentence from the ARIA spec "The following roles are used to support the WAI-ARIA role taxonomy for the purpose of defining general role concepts. Abstract roles are used for the ontology. Authors MUST NOT not use abstract roles in content."

This can now be closed