Codestyle for accessibility: semantic HTML

Development
1

Hello!
I just realized a few minutes ago that we lacked a very important rule in our HTML codestyle. This rule would make sure we don’t regress on fundamental accessibility, and it also serves the progressive enhancement principles, SEO and overall code quality/readability. I propose to add it to our HTML & CSS Code Style:

Use semantic HTML.

Semantic HTML is one thing automatic accessibility tests can’t catch on, since they rely on the semantic basis to analyse the pages. If the fundations of the tests are rotten, they will not work properly and let plenty of accessibility mishaps go by unnoticed.

So far, this rule is respected on xwiki-platform.

Do you agree with adding this rule to our HTML codestyle? Do you think it should redirect to another resource than the MDN Web docs definition of semantic HTML?

Thank you for taking the time to read this proposal,
Lucas C.

2

I’m very surprised by this statement as I’m pretty sure we’re using DIVs in lots of places where a semantic alternative would be possible.

Maybe we need to better clarify what “semantic HTML” means? I feel it would be best to provide some examples in the written rule about it. That’s always easier to understand something.

Thanks

3

For example, I’d be surprised that we use <aside>, <details>, etc ( see Semantic HTML5 Elements Explained for more) everywhere.

4

Yes :slight_smile: (for both questions)

Some better links (IMO):

5

+1

Thanks,
Marius

6

Now we do use <aside> in most places a regular user could expect them. AFAIK we don’t use <details> yet since it has implementation problems with some screen readers / browser combinations.

Semantics on interactive elements are really important. Missing or false semantics can completely change the way an interactive element is presented to an assistive techs user and prevent them from interacting with it properly.
I did think of this proposal more as a recommendation regarding landmarks: we should use them, but it’s not a regression if some new UI is added without a landmark. The way landmarks are defined is based on interpretation, so I think it makes sense to leave it as a recommendation.

Here is the updated text for the proposal:

Semantic HTML must be used. ARIA landmarks should be used. Examples:

  • images must be <img> and not spans with a fancy background.
  • buttons must be <button> and not divs with custom javascript.
  • section headers must be <h*> and not <p> with a custom style
  • Content blocks not directly related to the main content of the page should be <aside>.
  • Blocks containing mulitple links to other pages should be <nav>.

Learn more about semantic HTML: [1] [2] [3]

Thanks for your feedback!
Lucas

7

typo

What about the other semantic HTML tags (like header, main, nav, etc)? Are we also using these consistently?

Shouldn’t this be mentioned in your proposal text? What about all the other semantic HTML tags, can they all be used?

I believe this should be part of the proposal text.

This should also be part of the proposal text.

It’s missing a lot of semantic tags:

  • <article>
  • <details> (to say we should not use it)
  • <figcaption>
  • <figure>
  • <footer>
  • <header>
  • <main>
  • <mark>
  • <section>
  • <summary>
  • <time>

PS: I’ve quickly checked and I don’t see the use of time at XWiki.PageAuthorsUIX for example

thanks