Utilising semantic tags to provide better structure for screen readers by smallsaucepan · Pull Request #1464 · MLTSHP/mltshp-patterns

smallsaucepan · 2026-03-08T02:24:08Z

Overview

Utilising semantic tags (main, header, article, nav, etc) instead of divs and reordering content in HTML to header, "content", aside, footer to provide better structure for screen readers. Subset of intended changes seeking feedback on approach. Will make further commits based on feedback.

Screenshots

Only visual change should be to alignment of Older and Newer pagination buttons on mobile. They have been moved closer to edge of screen and should line up with edge of image content.

Testing

Have only done a subset of screens initially. Seeking feedback before converting them all. Main ones done are:

Base
- Layouts
Components
- Image
  - List View
  - Lengthy Content
  - Comments Open
- Pagination
Areas
- FAQ
- Find Shakes
- Incoming
- Legal
- Relationships
- Settings
- Shake

Pages should look and behave as they currently do, albeit with different behind the scenes markup.

Some design decisions worth noting:

Previously a list of image posts consisted of alternating header and content sibling divs. Each post (header and content) has been wrapped in an article tag to identify it as self contained content.
With paginated results the list being paginated no longer displays a trailing divider (assumes there will be pagination). Instead the pagination control takes responsibility for placing a preceding divider.

…ontent in HTML to header, "content", aside, footer to provide better structure for screen readers. Subset of intended changes seeking feedback on approach.

spaceninja

Heya! Just wanna say that overall I think this is a good change, and I'm happy to see it.

That said, you've made two changes at the same time that make this PR difficult to review — You've made simple markup changes (div to main, followers-list class, updating some profiles, etc), and you've reordered some markup (moving the main body content first, with the sidebar following). I like these both, but when they both happen in the same file, the diff becomes useless, because there's just one huge chunk of changes from the order change, and any other changes are hidden.

Can you tease these apart and make one PR with the order changes and another with the markup changes? I'm happy to approve them both, but for the PR where you're moving the code around, please don't make any other changes, so the review is simply "this block of code moved down the page"

… sidebar to end of file) to allow for easier diffing of this PR. Will re-apply in a subsequent PR.

smallsaucepan · 2026-03-11T11:02:37Z

Easy done. Have rolled back the reordering changes to be reapplied in a subsequent PR.

spaceninja

Thank you for breaking this apart, it was much easier to review.

This is looking good! A few nitpicks and then I'm happy to merge.

Also, could you add an UNRELEASED section to the top of the changelog file listing all the breaking markup changes that will need to be applied in the MLTSHP app? (Or you can do that in the followup PR, if that makes more sense, but it'll need to be done before we bump the version)

spaceninja · 2026-03-11T17:24:08Z

-		<a class="btn btn-secondary btn-shadow" href="#">Newer »</a>
-	</div>
-</div>
+<nav class="linear-navigation" aria-label="Timeline">


Why is this the only one with an aria-label?

This was the most obvious one to me where a label would help. Not meant to be an exhaustive list though - just an example and conversation starter for this PR.

spaceninja · 2026-03-11T17:29:52Z

 	}

-	> * {
-		min-width: 0; // https://github.com/philipwalton/flexbugs/issues/39


Did you confirm that word-wrap works properly in flex containers in Firefox now?

No, will probably have to add this back in. However existing selector was causing problems with restructured HTML as it is.

Question stands

Have added back in.

smallsaucepan · 2026-03-17T11:17:48Z

Have addressed the feedback as best I can for now. Should I proceed like so from here?

finalise any remaining semantic tag changes (minus section reordering) and commit to this PR
submit reordered sections as a second PR
submit odds and ends (like word-wrap in flex containers) as a third PR

Suspect there will be things to tidy up after reordering, hence third PR.

spaceninja · 2026-03-17T17:14:33Z

Sounds like a great plan! Ping me when you're ready for another review on this PR. 🎉

…stead defer to the container to do that e.g. image-content-list li elements. Hoisted image-content-list exceptions out of image-content and image-title (letting the image itself not worry about that). Flattened out image-content section to avoid unnecessary nesting e.g. div > form, when we can just use form. More use of flex gap on containers instead of individual components setting their own margins.

…tags. Reworked a fair bit of CSS too to use flexbox more, retire some floats and clear fixes, and move responsibility for spacing between individual components to the wrapping elements.

smallsaucepan · 2026-04-01T02:10:22Z

Latest round of updates:

BEM-ified a few top level components - post, comment
Flattened some areas (like title + title editor now siblings rather than parent child) so we can have identical markup for title whether on editable page or not
Where possible stripped singleton components back to not worry about setting their own spacing in lists - let the container do that
Added some example comments in a few areas (incoming, shake) to make sure they work properly in those contexts

Diagrams below might help visualise intended structure:

Post

Comment

spaceninja

I ran out of time to review in the browser, but wanted to share some code review feedback first.

Also, one request: Since this PR is making so many breaking markup changes, I'd like to see you document them in the changelog to ensure the changes are documented. I know you'll likely be the one implementing the changes in the main repo, but it's good practice to document changes like this. I'd expect something like:

Change <div class="main"> to <main>
Change <div class="sidebar"> to <aside>
Replace old-class with new-class
etc

Oh, and you've got a CI failure due to linting. If it's prettier, you can probably auto-fix by running npm run lint

spaceninja · 2026-04-01T23:19:46Z

No objections to these changes, but just so you're aware, the API documentation is automatically generated, so these changes may or may not be something we have control over. I think the pattern library page should accurately reflect the markup on the site, so it might be worth checking in the main repo if that's something we can control or not before updating it here.

Thanks, I'll double check.

The patterns API page currently embeds the entire page, including wrapper and page footer. Should that be pared back to what other areas include? It seems to be the exception at the moment.

That's fine — I think I just copy-pasted the whole thing for ease of maintenance. As long as we can see the markup in the pattern library so we can review CSS styles, that's all that really matters.

I'll trim it back then to just the content to bring it in line with all the others. To leave it means extra wrapper markup that might go stale.

If the generated html needs to adjust to meet the styles half way will take care of that in the mltshp repo.

spaceninja · 2026-04-01T23:41:44Z

+		box-shadow: none;
+	}
+
+	&--blank {


As a general rule of thumb, I'd prefer that we avoid using Sass to construct selectors like this — it doesn't save much typing, and it makes maintenance harder, because you can no longer search for the class. The other changes in this file are fine, but please change these to the full class name.

Easy done. Will fix these up.

spaceninja · 2026-04-01T23:45:27Z

-		a {
-			@include links.link-primary;
-		}
+	&--blank {


Same concern about constructed selectors. Please use the full class name to allow for search.

spaceninja · 2026-04-01T23:48:43Z

-.image-edit-title:focus,
-.image-edit-title-hover {
-	background-color: var(--color-status-edit);
+	&--editable:hover,


As above, please don't use Sass to construct selectors.

spaceninja · 2026-04-01T23:49:35Z

 	}

-	> * {
-		min-width: 0; // https://github.com/philipwalton/flexbugs/issues/39


Question stands

smallsaucepan · 2026-04-02T06:00:16Z

Sure. I'll flesh out the changes in the changelog on this PR.

Correct. CI build was a minor linting issue. Felt it could wait until next commit to avoid complicating any reviewing.

…es that will be required to mltshp repo. Addressed some scss usage, as well as re-enabling uniqueness check in 11ty. Also identified a few issues highlighted by proceeding (in dev) with making the changes to the mltshp code proper.

spaceninja · 2026-04-03T16:56:52Z

Since browser review is time-consuming, I'll hold off on any further review for now. Broadly speaking, you're heading in the right direction. Looking good!

…er the areas specific to that page.

smallsaucepan · 2026-04-04T23:26:31Z

That's probably it for this PR then (if we're going to leave re-ordering sections for a subsequent one).

Rather than merging this in to main and moving on to the next step, how about we create a new branch and work there until it's all ready to go? Means you could still release minor fixes from main, and keeps this work insulated.

dev-v5 or something along those lines?

spaceninja · 2026-04-08T17:16:15Z

Rather than merging this in to main and moving on to the next step, how about we create a new branch and work there until it's all ready to go? Means you could still release minor fixes from main, and keeps this work insulated.

Sounds good to me

spaceninja · 2026-05-22T00:01:43Z

@smallsaucepan What's the status here? No pressure, just trying to make sure you're not blocked by me failing to do something?

smallsaucepan · 2026-05-24T02:12:04Z

All good @spaceninja. I'll merge this onto the dev branch and go from there. There's also MLTSHP/mltshp#865 in play, which would have some overlap with this (classnames, etc).

Utilising semantic tags (main, header, article, etc) and reordering c…

5ae6195

…ontent in HTML to header, "content", aside, footer to provide better structure for screen readers. Subset of intended changes seeking feedback on approach.

smallsaucepan requested a review from spaceninja March 8, 2026 02:26

spaceninja requested changes Mar 9, 2026

View reviewed changes

Reverting changes that only re-order large HTML chunks (mainly moving…

3684d57

… sidebar to end of file) to allow for easier diffing of this PR. Will re-apply in a subsequent PR.

spaceninja requested changes Mar 11, 2026

View reviewed changes

Removing redundant <hr> tags as linear nav has its own border anyway.

e7c19c2

spaceninja reviewed Mar 24, 2026

View reviewed changes

Comment thread src/components/images/partials/_image-footer.scss

smallsaucepan added 2 commits April 1, 2026 12:56

Next round of changes to page and component structure using semantic …

2b385aa

…tags. Reworked a fair bit of CSS too to use flexbox more, retire some floats and clear fixes, and move responsibility for spacing between individual components to the wrapping elements.

Converting a couple of comments to preferred footnote style.

7377350

spaceninja requested changes Apr 1, 2026

View reviewed changes

Trimmed site header and footer from api example - only need to consid…

858038a

…er the areas specific to that page.

smallsaucepan requested a review from spaceninja April 4, 2026 23:26

Merge branch 'main' into macro-semantic-tags

202d391

smallsaucepan changed the base branch from main to dev-v5 April 12, 2026 23:23

smallsaucepan merged commit 51be5dd into MLTSHP:dev-v5 May 24, 2026
6 checks passed

Uh oh!

Conversation

smallsaucepan commented Mar 8, 2026

Overview

Screenshots

Testing

Uh oh!

spaceninja left a comment • 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!

smallsaucepan commented Mar 11, 2026

Uh oh!

spaceninja left a comment • 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!

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!

smallsaucepan commented Mar 17, 2026

Uh oh!

spaceninja commented Mar 17, 2026

Uh oh!

Uh oh!

smallsaucepan commented Apr 1, 2026

Post

Comment

Uh oh!

spaceninja left a comment • 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!

smallsaucepan Apr 2, 2026 • 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!

smallsaucepan Apr 4, 2026 • 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!

Uh oh!

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!

smallsaucepan commented Apr 2, 2026

Uh oh!

spaceninja commented Apr 3, 2026

Uh oh!

smallsaucepan commented Apr 4, 2026

Uh oh!

spaceninja left a comment •

edited

Loading

spaceninja left a comment •

edited

Loading

spaceninja left a comment •

edited

Loading

smallsaucepan Apr 2, 2026 •

edited

Loading

smallsaucepan Apr 4, 2026 •

edited

Loading