Utilising semantic tags to provide better structure for screen readers

CHANGELOG.md

@@ -7,6 +7,87 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## Unreleased
 
+### Visual changes
+
+- Move Older and Newer buttons on small screens to align their outer edges with the outer edges of the content above. Brings into line with larger screen sizes
+- Always horizontally align like + save buttons with the stats tabs. Currently if there is an originally posted by the like + save buttons are aligned with that instead. Improves layout consistency and simplifies markup
+- On posts that the user can edit the alt text is shown by default (the user doesn't have to toggle it visible). This simplifies the markup, styles, and javascript, and also helps to highlight to post authors if they have no alt text defined yet
+- Moved the "remove from shake" button to be within the post header (used to be in the right hand gutter beside the header). Simpler markup and looks better
+- Right aligned some buttons in the conversations view. Allows for a less cluttered layout without wasting heaps of vertical space
+
+### Use semantic tags on the outermost layers of most pages e.g.
+
+- `<div class="content">` -> `<main class="content">`
+- `<div class="header">` -> `<header class="page-header">`
+- `<div class="sidebar">` -> `<aside class="sidebar">`
+
+### Restructure image list container
+
+Instead of flat pairs of alternating divs making up each shared image, all wrapped in a normal
+div ...
+
+```html
+<div class="image-content-list">
+	<div class="image-title" />
+	<div class="image-content" />
+	<div class="image-title" />
+	<div class="image-content" />
+	...
+</div>
+```
+
+... wrap each image (post) in a top level article to encapsulate it as a self
+contained piece of content, and then wrap those is a properly constructed
+unordered list.
+
+```html
+<ul class="image-content-list">
+  <li>
+    <article class="post" />
+      <header class="post__title" />
+      <div class="post__content" />
+      <div class="post__footer" />
+    </article>
+  </li>
+  <li>
+    <article class="post">
+      <header class="post__title" />
+      <div class="post__content" />
+      <div class="post__footer" />
+    </article>
+  </li>
+  ...
+```
+
+### Restructure individual shared images
+
+Elected to BEM-ify post and comment components.
+
+- Rename `<div class="image-title" ` to `<header class="post__title" `
+- Move "remove from shake" button into header
+- Rename `<div class="image-content" ` to `<div class="post__content" `
+- Hoist `<div class="image-content-footer" ` to follow `<div class="post__content" ` as a sibling
+- Move `<div class="alt-text" ` into `<div class="post__content" ` after `<div class="the-image" `, and rename to `<div class="post__alt-text" `
+- Move `<div class="description" ` into `<div class="post__content" ` after `<div class="post__alt-text" `, rename to `<div class="post__description" `, and remove the `<div class="the-description" ` wrapper
+- Move `<div class="originally-posted-by" ` into `<div class="post__content" ` after `<div class="post__description" `, and rename to `<div class="post__originally-by" `
+- Rename `<div class="image-interactions" ` to `<div class="post__interactions" `
+- Rename `<div class="inline-meta" ` to `<div class="post__meta" `
+- Rename `<div class="stats" ` to `<div class="post__meta-stats" `
+- Wrap `<div class="post__interactions" ` and `<div class="post__meta" ` in a new element `<div class="post__meta-interactions" `. This new element should be the first child of `<div class="post__footer" `
+- Unwrap the like and save buttons in `<div class="post__interactions" ` from their containing divs and just put the `like-this` and `save-this` classes directly on the `<form>` element
+- Rename `<div class="inline-details" ` to `<div class="post__comments" `, `<div class="post__likes" `, or `<div class="post__saves" `, depending on what you intend to display. Clicking the tabs above (in `<div class="post__meta-stats" ` dictates which one is displayed.
+- Rename `<div class="avatar" ` to `<article class="comment__avatar" `, and wrap each comment inside a `<li>` within `<ul class="post__comments" `
+- Rename `<div class="avatar" ` to `<div class="comment__avatar" `
+- Rename `<div class="comment-body" ` to `<div class="comment__body" `
+- Rename `<div class="meta" ` to `<div class="comment__meta" `
+- Rename `<div class="comment-body-text" ` to `<div class="comment__text" `
+- Remove `<div class="post-comment-inline">` from `<form class="post-comment-form">` and rename to `<form class="post__new-comment-form">` moving it to the `<li>` in the comment list
+- Move `<form class="image-edit-title-form" ` to be a sibling following `<header class="post__title" ` and rename to `<form class="post__title-editor" `
+- Move `<form class="alt-text-edit-form" ` to be a sibling following `<header class="post__alt-text" ` and rename to `<form class="post__alt-text-editor" `
+- Move `<form class="description-edit-form" ` to be a sibling following `<header class="post__description" ` and rename to `<form class="post__description-editor" `
+- Make use of `post__description--editable`, `post__description--editing` (and similar for title and alt-text) to control visibility of display and editor controls for each editable section
+- Update javascript so all class based interactions work e.g. saving and cancelling alt text editing, displaying likes, saves, and comments, adding comments, showing additional comments
+
 ## [4.1.0] - 2025-08-22
 
 - Added a tab order friendly hide and show mechanism for comment reply-to and

src/_includes/page.webc

@@ -70,21 +70,19 @@ scripts:
 			</nav>
 		</header>
 
-		<main class="site-main">
-			<div class="content content-with-sidebar">
-				<div class="header page-header">
+			<main class="site-main content content-with-sidebar">
+				<header class="header page-header">
 					<h2 @text="title"></h2>
+				</header>
+				<div class="body styleguide-body">
+					<template webc:nokeep @raw="content"></template>
 				</div>
-				<div class="sidebar">
+				<aside class="sidebar">
 					<styleguide-nav-group
 						:items="eleventyNavigation($data.collections.all)"
 						:page-url="page.url"
 					></styleguide-nav-group>
-				</div>
-				<div class="body styleguide-body">
-					<template webc:nokeep @raw="content"></template>
-				</div>
-			</div>
+				</aside>
 		</main>
 
 		<footer class="site-footer"></footer>

src/areas/developer/examples/api-access.html

@@ -5,7 +5,7 @@
 
 <div class="page">
 	<div class="wrapper">
-		<div class="content content-narrow">
+		<main class="content content-narrow">
 			<h1>Allow Access?</h1>
 			<p>Do you want to let this app read and write to your account?</p>
 			<form class="api-accept">
@@ -23,6 +23,6 @@ <h1>Allow Access?</h1>
 				/>
 			</form>
 			<div class="clear"></div>
-		</div>
+		</main>
 	</div>
 </div>