zersiax/umbraco 8 accessibility notes.md

## umbraco 8 accessibility notes.md

      
    Raw
  

              umbraco 8 accessibility notes.md
            
          
    Umbraco 8 Basic Website Tutorial: Accessibility/UX notes

Intro

This is a stream of consciousness-style list of notes I put down while trying to go through the Umbraco 8 Basic Site tutorial. Accessibility hurdles will be noted, nitpicky as they may be.
This test is run using the dev/v8 branch on the 18th of September 2019.
Installer


In the first screen, the button to customize the installation is a link (  tag). This is confusing as links and buttons do different things and a user hopping from button to button will outright miss this control.
On the page to select if you want a starter kit or not, the link to accept the starter kit has the link text of "Loading".
On the installer progress page, the heading structure is broken; the progress is denoted by a heading 3, with a "Did you know?" heading level 2 above it. There's two things wrong with this, namely:

This indicates the progress has something to do with the did you know above it. A relationship between the two, tenuous at best, would work the other way around, but I would say this is really grasping at straws.
The progress doesn't need to be, and actually shouldn't be a heading at all. If you want to makr it up semantically, put another heading level 2 (perhaps an invisible one) above the progress and make the progress itself normal text augmented with CSS to make it bigger, do not misuse headings for this purpose.


The progress text of the installer would be a good candidate for a live region; a bit of content marked up with aria-live to tell the screen reader that the content was updated dynamically and that this is important enough to alert the user about, even if that element doesn't currently have focus.

Initial visit to installed website


Visually, when loading the website for the first time, a dialog pops up explaining about the tour of Umbraco. This dialog is not semantically separated from the rest of the page, is not marked up as a dialog or modal and doesn't take focus. All this together makes it hard to reach; in fact, a screen reader user might be forgiven to not even know the dialog is there at first.
To fix:

Visually, this dialog is in the foreground and it's hard to ignore. So, in this case, it is permissible to both trap the focus in the dialog and bring it there when the dailog opens. This is a common ARIA design pattern and is, for example, documented here: https://bitsofco.de/accessible-modal-dialog/
Generally it is a good idea to section your pages into semantically coherent structures. Two tools that exist for this purpose are headings (be it visible or sr-only invisible) and landmarks, which are things like role=navigation, role=footer and their implicit HTML5 tags nav and footer etc.


When mysession expired and I had to log in again, I noticed that the label for the Password field is currently "password new password". That is both a bit too verbose as well as slightly odd; why new password? This is not a password reset form.
The error you get for incorrectly entering your user details refers to a username, while the field is actually labeled email. This is a low-hanging fruit, one I happen to see is already being fixed in a PR.
The content tree is currently not semantically separated from the rest of the page. This would be fine if it was an actual semantic treeview, but it isn't , which makes it completely impossible for a screen reader user to 4even deduce it's the content tree they are looking at. For a screen reader, this is the sequence of elements:

Right past the buttons to open the help, search and profile options we have a list with 1 item, this item being a heading level 5, with a link in it that says content.
Next, we have a button that has no textual label.
Then, we have an element that the screen reader will report as simply "clickable", as it has no role and no textual value. This could literally be anything.
Next, a link that says "Recycle bin" , followed by another button with no textual label. Will it expand the node? Cause worldwide floods? Stay tuned for the next exciting episode.


Tutorial

At this point, we have Umbraco up and running, let's get the tutorial and start building.
Intro


What I find interesting in the introduction is a seeming disparity between what this tutorial says and what the installer a while ago states.
In the installer, it is said that a starter kit is a great way to learn how Umbraco works.
In the tutorial, the starter kit is not used, because it doesn't give a good view of the basics of Umbraco.
I understand that the nuance here is that how something works and learning it's basics are two slightly different things, but it is still a somewhat interesting difference between the two resources.

Creating your first document type


Ok ...I said I was going to nitpick and here is my first one. The top menu at the top are not marked up as being a menu, a menubar or a navigation, and have no ARIA markup indicating that some of these have submenus. I don't know if they visually do, though, as on clicking the Settings button some things become apparent.
We now see that the heading 5 with the link in it that previously said "Content", now says "Settings". This is evidently meant to tell you where in the UI you are, which slightly disproves a thing I said earlier. The content tree is in fact semantically separated from the rest of the content ...sorta kinda.
The content treeview is ...gone now, I think, and has been replaced by the settings UI which ..is also a tree? Guessing here.
Looking through the tree, we see a recurring pattern:

First, a clickable item that could be anything. Assuming this is an icon.
Next, the name of that particular settings category, which is a link.
Third, an unlabeled button. I will spare you the suspense and reveal that this does not in fact cause floods, it opens the actions menu for that particular category. Something I found out by pressing it ...guess I'm glad it wasn't a DeleteEverythingTeeHee button.
Finally, and this is a rather recent addition, a button that expands the children of that particular category. I think it also collapses them again, but the button doesn't say as much and there's no ARIA-expanded for me to be sure right now.


ONWARD. Tutorial says to hover over the Document Types option and to click the three dots. From investigations earlier, this would be the unlabeled button next to Document Types which might very well have an icon of three dots on it, but no textual three dots or indeed any textual content. Tis a mystery. Let's click it.
Ok, the world didn't explode, I clicked the {Document Type} button as instructed and gave the thing a name. In the name field, it seems we have a placeholder that has a GUID of some variety in it. Slightly distracting, but not a showstopper. Onward.'
We are instructed to click the {Save} button to save the template. I did, and purely by accident I noticed there was a little popup that indicated the successful saving of the document, which after a number of seconds dismisses itself. I did not know that was there until I just now accidentally landed on it, this right here is where role=alert or aria-live is really important.
Ok, this is where things get interesting. We have to give this document type an icon, and we do that by clicking the "white document icon next to the name field". I see something, a clickable element without a role, labeled "icon-document', that is probably what is meant. Let's change it to a house icon as instructed.
Done. The colors and icons have a textual label of 'icon-house' and, for example, 'color-cyan". I approve; I think this is miles ahead of a lot of other similar systems I've seen.
Now, we have to set the {Allow as Root} permission.We click the Permissions button, which is a semantic button tag, and look for "Allow as root". Uh oh ...

Heading structure kaput: the permission headings are at the same level as everything in this part of the screen, which is level 5, while there is no 4, 3, 2 and1 to precede and incapsulate it.
The text above (for me above) the checkbox explains what the checkbox does, so the fact that the checkbox itself doesn't have a label is somewhat mittigated, but there are some more issues with this widget:

Tabbing through these controls reports "Button", which is both wrong and not helpful; this isn't a button and there is no label so it could literally do anything at this point. While this doesn't happen all that often (tabbing through a UI only), the same will happen if you use screen reader commands to jump from button to button, which is far more common.
This isn't a button, it's a checkbox or a toggle. Because it is marked up as a button, without proper ARIA markup to, for example, make it appear "pressed", it is currently impossible for a screen reader user to see if this toggle is on or off.


With some logical thinking we can deduce that the button following the text about "Allow as Root" is the checkbox that governs that setting, and that it is currently off, because a default of "on" would be weird, but this isn't always deduceable. It also helps that the tutorial said to check it, so it's probably off right now. Onward.
Next, we have to create a group "content". I am pretty sure this is a relatively recent addition, either that or I just missed it the last time I readthis tutorial. What's interesting about this one is that everything we've done so far is pretty much through the use of buttons, while "add new group" is actually a link,  tag. Also, the alt attribute on the screenshot showing this step is still referring to these as "tabs" , which I think is a leftover from Umbraco v7.
Clicking through the creation oof the first property, this is where losing track of where you are in the UI can become a problem. First, we have a name field for the group, which is Content. Then, a similarly labeled name field , this time for the property you're adding. When we add an editor we have to click "Submit" to save the editor choice, and then "Submit" , another "Submit" that is, again to save ...something, which saves the datatype. I think.
Next, we are instructed to make a number of properties. What confused me to no end the first time is that this table of properties has a column "tab:" , which I now know refers to "group". In this table it tells you to create some properties for a "Footer" tab, remember to add this! ...add what? huh? Where even are these tabs?
Through the pwoer of repetition and a helpful push in the right direction though,  I now know what to do here so excuse me while I add these properties, hope I don't screw up.
A few things about this process:

It takes a lot of concentration to keep track of where everything is in this UI. The groups , semantically, are unordered list tags without any semantic information, which means i get the group name from theedit field that has that information.
Adding an editor is seemingly not always the same; the textbox requires two submit button clicks, while the RichText editor only seems to need one.
When creating a new group and pressing enter after typing the group name does something odd, it took me to the name field of my very first property and opened the property settings (not quite sure what those are) of that property.
In the DOM, after saving a property, whereas the name comes before the alias when adding the property, the name field seems to move past the alias field when actually viewing this property, and is now called "Label".

We are done creating the document type. Onward!
Creating your first template and Content Node

Template

First, we expand the options under Settings -> Templates. This button expands, but also collapses, that content, although the button currently only says it expands it and aria-expanded isn't used to report the opposite. Clicking the homepage template gives no problems and also editing templates is, at least for this basic scenario, smooth sailing.
Content Node

We go to the Content section by clicking the button ...which is actually a lik ... labeled Content in the top menu. Next, we , like before, "hover over the grey text that says CONTENT".
I guess this is our heading 5 that says content, as next to it is one of those unlabeled could-be-anything buttons. Clicking it reveals the Homepage type as we created, so I would say that is correct so far.
Clicking and adding content is reasonably easy. The jump to x links to jump to a particular group don't actually scroll me to the required group, and the group headers aren't semanitcally marked up to be headings. This makes the only way to get to the next group quickly the usage of the "" Next form element" key in a screen reader, which is impractical if a group has a large amount of fields.
We are told to click the green Publish button. In my DOM, there's no such thing; we have save, and we have Save and Publish. Opting for the second one, here we go.
Doing this does replace the default Umbraco  page with the Retrospect index page. I was sort of wondering if our content would show up yet, it doesn't, I guess we wwill get to that later. First, CSS and JavaScript. My favorite!
CSS and Javascript

Just kidding. This is literally putting a bunch of files in the right places, no comment, move along, move along...
Outputting Document Type Properties

Time to put the editor through it's paces a bit more. We will add the documenttype props in the actual Retrospect template's index template. let's see.
So, the proper way to do this, is to highlight the text to be replaced and click Insert,then Value,then the right value. This ...doesn't work. namely:

When highlighting text, tab no longer takes you out of the editor, which makes it tedious to even click the Insert... button. Consider making a hotkey of some variety for this.
The menu items for the insert button show up atthe bottom of the DOM and I am pretty sure there are some keyboard navigation challenges there as well. I had to direct my screenreader to the very last line of the page and arrow upwards to find the "Value" option.
At least for a screen reader, the menu stays in view after having picked an option, and no notification is given that a new menu or popout was opened. This briefly gave me the impression nothing happened, which would have indicated that these options don't respond to pressing enter on them. Fortunately, they do.

Overall I would say that with all these challenges, learning the syntax to just do this in code would be more efficient. Fortunately, Umbraco gives you that code in the add value dialog.
The rest of this process is just rince and repeat; although I opted to just type the code out by hand for the two missing fields.
Creating Master Template, part 1

Most of this is old hat by now. Could-be-apocalypse buttons to open the menu and create a new template, then click the No Master button and pick the master template from the list similar to the icon picker. Given this actually seemingly just changes one line of code, doing this by hand might be quicker.
Creating Master Template, part 2

Again, not much of note here, we are using the same interaction patterns we have been using the entire time. However, one thing does break:

When trying to create a Simple Content Page under the home page, without allowing this to be a child node, no feedback is given by a screen reader that anything actually happened. Regularly, when opening a menu like this, focus jumps to the first option. I guess in this case since there is no first option, nothing happens, but it made it seem like nothing happened for a while and I needed to go scroll all over the page to find the error message as it has no semantic markup to set it apart, e.g. a landmark or a heading above it.

Also there's another few reference to tabs here where groups are meant.
Fixing the navigation menu

This is purely a change in the already existing code. Nothing to see here.
Articles Parent and Article Items


Name field for the Document Type Collection Parent and Child are not properly labeled, label is not associated with it's designated field which causes this field name not to be read when tabbing into the field. Workaround is to switch modes to browse mode and arrow up, but this is annoying and really not necessary as it is a one-line fix.
Again a bunch of references to tabs, instead of groups

The tutorial states that after saving the Articles Main document type, I should see a list view where I can quickly add new children. This didn't appear for me and only showed up after hard refreshing the page (ctrl+r).
Having to add multiple fields that are somewhat similar in name I can better appreciate the use ofthe GUI to add these values. Fortunately I found that shift+alt+v brings up the dialog to add those. Taking the focus to the dropdown to pick a value would be a big time saver, as would bringing focus back to the editor when the value has been inserted which happens some of the time.
Next part of the tour is the query builder. Sadly, for this part of the tutorial, an image shows what parameters I am supposed to be using for thisquery builder, which makes this part of the tutorial useless to me. Let's see how far we get, though.
The query builder has some interesting quirks:

As is common with Umbraco "sub-windows", nothing separates them from the rest of the page semantically, at this point I tend to just hammer my "Next Button" or "Next Form Element" key a number of times to get there quickly.
The main parts of the interface are ok; I can pick what items I want (although I wonder how keyboard-accessible that part is). There are some unlabeled buttons, generally I think these are the common ... buttons, to pick certain things. I also see two  tags that have the label of Umbraco, I have no idea what these do.

I am uncertain why, but at this point, my query actually returns zero results. Everything looks ok to me, will have to ask someone who knows Umbraco what it is I broke :-)
NOTE FROM THE FUTURE It turns out that what I broke was the "My Website" portion of the query in the query builder. Pressing this button makes the content tree pop up visually, but this is not reported (through ARIA or a similar mechanism) to screen readers, making me think the button was simply inoperable in the current context.
Adding Language Variants

Adding a language was easy enough. I added Dutch, simply because I speak it and Ik spreek geen Deens, daar is ieder het mee eens :P
Finding the gear icon for altering the property editor settings proves more problematic. Clicking one of the many "clickables" on the page gave me something I could either Confirm or Cancel. Feeling daring, I clicked Confirm.
Now ...all fields in my document type are gone. So much for a lucky streak. For the future:

Icons without textual labels are bad for you. Extremely bad. Stop that.
If I am confirming something, it would be lovely to see what it is I am actually confirming. :-)

Now I will have to recreate the three or so fields I just nuked. Be right back.
Ok ...so recreated the fields and can't seem to reproduce how I did that, but what I did find is that hitting enter on the textbox opens the property ettings where the varying cultures can be allowed. This, however, does not work for the rich text editor. I think this is the first actual complete showstopper for today, I can't fix this without a working pair of eyes clicking an icon.
Oh well, moving on.

The language picker in the content tree is not keyboard reachable, and accessibility-wise, it is visible in the sense that I see a language name and clicking it shows me more language names, but this is not a proper pattern for any kind of dropdown and honestly looks kinda hacky.
I will now go and add hostnames to the nodes as is demonstrated here image . In other words ...this is where I do my own thing again. I will also need to right-click a node to do it, let's see if it just shows up in the apocalypse-button menu.

It does not. However, fortunately, shift+f10 is in this case seen as right-clicking. I never knew there was a menu like that, huh ...
In this dialog, we have a table containing the domains. Pressing apocalypse buttons in the rows that contain them ...deletes the given row. Good to know. :-)
Finally, it says that by mouse-overing a language, I can open it in a splitBox view. Not sure how useful that is/would be, as I can't seem to access this functionality at all using a keyboard.
Final thoughts

Although not a huge amount of showstoppers were not encountered, it was still quite a slog at times to do what is essentially a rather simple process. I hope this bunch of text (I really can't call it anything more glorious) at least shows that much.
However, it is clear a lot of things were fixed over the last few months, making this far lesss painful than it could have been or, indeed, has been. H5yr to all contributors, and let's keep this good momentum going.