What HTML should I use for a rated theatre review?

Question

I'm authoring a reusable widget, in HTML, that reflects a common pattern often seen in theatre reviews. The widget is quite simple, with minimal components, namely:

1. A star rating,
2. The review itself
3. The reviewer (an individual/publication/website etc)

My main concern is that it's accessible to site visitors using screen readers, and so I'm wondering what the ideal mark-up would be. Currently, I'm using the following pattern:

<article>
    <header>
        <div aria-label="Rated n out of 5 stars">
            <span aria-hidden="true">★</span>
            ...
            <span aria-hidden="true">★</span>
        </div>
        <h3>Reviewer name</h3>
    </header>
    <p>Review contents...</p>
</article>

I'm fairly certain an article at the root is correct, but I'd love to know if anyone has any thoughts on how to improve this.

Answer 1

When you ask about HTML specifics, it becomes more of a StackOverflow.com type question instead of a UX question so you might have to post there instead.

But I can still comment on what you have since I'm in both forums.

It's good to have a "text alternative" for your star rating so that it can be conveyed to assistive technology such as screen readers and Braille devices, but specifying an aria-label on a <div> is often not honored. See "2.10 Practical Support: aria-label, aria-labelledby and aria-describedby", in particular, the third last bullet point:

Don't use aria-label or aria-labelledby on a span or div unless its given a role.

In your case, you can probably treat your star rating as an "image" even if it isn't graphical, although you can peruse all the possible roles here - https://www.w3.org/TR/wai-aria/#role_definitions. You could even give it an image role but give it a more descriptive definition of the role by using aria-roledescription. But I would probably keep it simple:

<div role="img" aria-label="Rated n out of 5 stars">
    <span aria-hidden="true">★</span>
    ...
    <span aria-hidden="true">★</span>
</div>

Note that the actual role name is "img" and not "image".

Hiding the actual star characters with aria-hidden is good.

Just for fun, I also tried:

<div role="img" aria-label="Rated n out of 5 stars" aria-roledescription="this is a theater review">

It's sounds good with NVDA on Firefox but that's a very minimal test. You'd want to try other browsers (Chrome), other screen readers (JAWS), and other platforms (VoiceOver on Mac and iOS).