diff --git a/content/posts/website-best-practices.gmi b/content/posts/website-best-practices.gmi index 85f22d1..bb78366 100644 --- a/content/posts/website-best-practices.gmi +++ b/content/posts/website-best-practices.gmi @@ -433,17 +433,21 @@ font: 100%/1.5 sans-serif; Expect some readers to have images disabled or unloaded. Examples include: * Blind readers -* Users of metered connections: sometimes they disable all images, and other times they only disable images above a certain size -* People experiencing packet loss who only manage to load a few resources +* Users with metered connections: sometimes they disable all images, and other times they only disable images above a certain size +* People experiencing packet loss who fail to download some images * Users of textual browsers -Accordingly, follow good practices for alt-text. Concisely summarize the image content the best you can, without repeating the surrounding content. Don't include significant information that isn't present in the image; I'll cover how to handle supplementary information in the next subsections. +Accordingly, follow good practices for alt-text: + +* Concisely summarize the image content the best you can, without repeating the surrounding content. +* Images with a low information density should usually have alt-text under 120 characters. +* Don't include significant information that isn't present in the image; I'll cover how to handle supplementary information in the next subsections. The W3C's Web Accessibility Initiative (WAI) offers a decision tree for writing alt-text. It's a little lacking in nuance, but makes for a good starting point: => https://www.w3.org/WAI/tutorials/images/decision-tree/ An "alt" Decision Tree -Alt-text is a good start, but we don't have to stop there. +Remember that guidelines and "good practices" always have exceptions. Note: this section does not include examples of its own. If you wish to see examples, look at the blockquotes, code snippets, and linkd images in the official version of this Gemini page. You're probably on it right now; if not, here's the canonical location: @@ -508,7 +512,7 @@ The recommended way to link to a transcript is by hyperlinking the image (i.e., The xkcd comic included earlier in the page had this alt-text: ``` -Comic illustrating how if books worked like infinite-scrolling webpages, we'd have to turn pages carefully or risk losing the page. Follow link for transcript. +Comic: if books had infinite-scroll, we'd have to turn pages carefully or risk losing the page. Transcript in caption. ``` Image transcripts also help users relying on machine-translation, since translation tools rely on textual content (OCR is error-prone). These users won't read alt-text; have an alternative way to discover a transcript. Wherever you put the transcript, ensure it's semantically connected to the image. I linked a transcript in the figure caption. @@ -519,7 +523,7 @@ I describe best practices for preparing pictures of text in the "Pictures of tex Some users' browsers set default page colors that aren't black-on-white. For instance, Linux users who enable GTK style overrides might default to having white text on a dark background. Websites that explicitly set foreground colors but leave the default background color (or vice-versa) end up being difficult to read. The same phenomenon occurs on pages with text on top of background images. Don't strain your eyes trying to read this example: -=> gemini://seirdy.one/misc/website_colors.png Screenshot of a website with gray text on a darker grey background. Details below. +=> gemini://seirdy.one/misc/website_colors.png Screenshot of a website with gray text on a darker gray background. Details below. This is an unreadable screenshot of a website promoting browser style overrides: @@ -1053,7 +1057,7 @@ This section focuses on ways to improve screen reader support that have not alre ### Split elements and possessive hyperlinks -Some screen readers for touchscreen devices split up sections by HTML elements. This means HTML elements in the middle of a sentence will trigger pauses. The problem comes up frequently on sites that use excessive inline formatting. +Some screen readers split up sections by HTML elements. This means HTML elements in the middle of a sentence will trigger pauses. The problem comes up frequently on sites that use excessive inline formatting. This is especially concerning on my website, where I tend to hyperlink peoples' names (a common practice on the IndieWeb): making names possessive with an "apostrophe + s" creates pronunciation issues. "Seirdy's Home" could be read as "Seirdy. Link. S. Home" if the word "Seirdy" is a hyperlink. @@ -1081,7 +1085,7 @@ The best solution for possessive nouns is to include the "apostrophe + s" inside ### Other tips -Designers already test their websites with multiple browser engines to ensure cross-browser compatibility. Screen readers deserve the same treatment. Orca, NVDA, VoiceOver, and TalkBack all have unique behavior and varying levels of support for HTML and ARIA. +Designers already test their websites with multiple browser engines to ensure cross-browser compatibility. Screen readers deserve the same treatment. Orca, NVDA, VoiceOver, TalkBack, and ChromeVox all have unique behavior and varying levels of support for HTML and ARIA. Screen readers on touch screen devices are also quite different from their desktop counterparts, and typically feature fewer capabilities. Be sure to test on both desktop and mobile. diff --git a/content/posts/website-best-practices.md b/content/posts/website-best-practices.md index 702b527..b433dfe 100644 --- a/content/posts/website-best-practices.md +++ b/content/posts/website-best-practices.md @@ -25,6 +25,8 @@ If you find the article too long, just read the introduction and conclusion. The +{{}} +
Intro­duction {#introduction} @@ -44,8 +46,6 @@ I'll cite the Web Accessibility Initiative's ( -{{< picture name="infinite_scrolling" alt="Comic illustrating how if books worked like infinite-scrolling webpages, we'd have to turn pages carefully or risk losing the page. Follow link for transcript.">}} +{{< picture name="infinite_scrolling" alt="Comic: if books had infinite-scroll, we'd have to turn pages carefully or risk losing the page. Transcript in caption.">}}
@@ -466,11 +466,17 @@ Note: this section does not include examples of its own. If you wish to see exam Expect some readers to have images disabled or unloaded. Examples include: * Blind readers -* Users of metered connections: sometimes they disable all images, and other times they only disable images above a certain size -* People with packet loss who only manage to load a few resources +* Users with metered connections: sometimes they disable all images, and other times they only disable images above a certain size +* People experiencing packet loss who fail to download some images * Users of textual browsers -Accordingly, follow good practices for alt-text. Concisely summarize the image content the best you can, without repeating the surrounding content. Don't include significant information that isn't present in the image; I'll cover how to handle supplementary information in the next subsections. The WAI provides some guidelines in [An `alt` Decision Tree](https://www.w3.org/WAI/tutorials/images/decision-tree/). It's a little lacking in nuance, but makes for a good starting point. +Accordingly, follow good practices for alt-text: + +* Concisely summarize the image content the best you can, without repeating the surrounding content. +* Images with a low information density should usually have alt-text under 120 characters. +* Don't include significant information that isn't present in the image; I'll cover how to handle supplementary information in the next subsections. + +The WAI provides some guidelines in [An `alt` Decision Tree](https://www.w3.org/WAI/tutorials/images/decision-tree/). It's a little lacking in nuance, but makes for a good starting point. Remember that guidelines and "good practices" always have exceptions. ### Putting images in context @@ -560,7 +566,7 @@ The recommended way to link to a transcript is by hyperlinking the image (i.e., The xkcd comic included earlier in the page had this alt-text:
-> Comic illustrating how if books worked like infinite-scrolling webpages, we'd have to turn pages carefully or risk losing the page. Follow link for transcript. +> Comic: if books had infinite-scroll, we'd have to turn pages carefully or risk losing the page. Transcript in caption. @@ -574,9 +580,7 @@ About custom colors Some users' browsers set default page colors that aren't black-on-white. For instance, Linux users who enable GTK style overrides might default to having white text on a dark background. Websites that explicitly set foreground colors but leave the default background color (or vice-versa) end up being difficult to read. The same phenomenon occurs on pages with text on top of background images. Don't strain your eyes trying to read this example:
- -{{< picture name="website_colors" alt="Screenshot of a website with gray text on a darker grey background. Details in the caption." >}} - +{{< picture name="website_colors" alt="Screenshot of a website with gray text on a darker gray background. Details in caption." >}}
This is an unreadable screenshot of a [website promoting browser style overrides](http://bettermotherfuckingwebsite.com/) (specifically, the "A little less contrast" section). I had set my browser foreground and background colors to white and dark gray, respectively. The website overrode the foreground colors while assuming that everyone browses with a white background. @@ -909,7 +913,7 @@ Another example: outside the Web, I prefer indenting code with tabs instead of s Small phones typically support display rotation. When phones switch to landscape-mode, vertical space becomes precious. Fixed elements (e.g. dickbars) become a major usability hazard. Ironically, the WCAG's own interactive Techniques reference is a perfect example of how fixed elements impact usability on short screens.
-{{< picture name="wcag_quickref" alt="Website with banner covering top half of screen." >}} +{{< picture name="wcag_quickref" alt="Website with banner covering top half of screen." sf=1.2 >}}
When filtering criteria on [the Quickref Reference page](https://www.w3.org/WAI/WCAG22/quickref/?currentsidebar=%23col_customize&showtechniques=134%2C124&levels=a&technologies=js%2Cserver%2Csmil%2Cpdf%2Cflash%2Csl), a dickbar lists active filters. I increased the zoom level; you may have to add more filters to fill the screen with a smaller font. @@ -935,7 +939,7 @@ For now, I've decided to keep the indents on list elements (`
    `, `
    `, `
@@ -1019,7 +1023,7 @@ For example: machine translation will leave `` and `` blocks as-is. Consider the implications of translating between left-to-right (LTR) and right-to-left (RTL) languages. Do a search through your stylesheets for keywords like "left" and "right" to ensure that styles don't depend too heavily on text direction. Once you've cleared the low-hanging fruit, try translating the page to a language like Arabic. -Websites following this page's layout advice shouldn't need much adjustment. {{}} [RTL Styling 101](https://rtlstyling.com/posts/rtl-styling/) is a comprehensive guide to what can go wrong and how to fix issues. +Websites following this page's layout advice shouldn't need much adjustment. {{}} [RTL Styling 101](https://rtlstyling.com/posts/rtl-styling/) is a comprehensive guide to what can go wrong and how to fix issues. Screen reader improve­ments {#screen-reader-improvements} ------------------------------- @@ -1028,7 +1032,7 @@ This section focuses on ways to improve screen reader support that have not alre ### Split elements and possessive hyperlinks -Some screen readers for touchscreen devices split up sections by HTML elements. This means HTML elements in the middle of a sentence will trigger pauses. The problem comes up frequently on sites that use excessive inline formatting. +Some screen readers split up sections by HTML elements. This means HTML elements in the middle of a sentence will trigger pauses. The problem comes up frequently on sites that use excessive inline formatting. This is especially concerning on my website, where I tend to hyperlink peoples' names (a common practice on the IndieWeb): making names possessive with an "apostrophe + s" creates pronunciation issues. "Seirdy's Home" could be read as "Seirdy. Link. S. Home" if the word "Seirdy" is a hyperlink. @@ -1064,7 +1068,7 @@ The best solution for possessive nouns is to include the "apostrophe + s" inside ### Other tips -Designers already test their websites with multiple browser engines to ensure cross-browser compatibility. Screen readers deserve the same treatment. Orca, NVDA, VoiceOver, and TalkBack all have unique behavior and varying levels of support for HTML and ARIA. +Designers already test their websites with multiple browser engines to ensure cross-browser compatibility. Screen readers deserve the same treatment. Orca, NVDA, VoiceOver, TalkBack, and ChromeVox all have unique behavior and varying levels of support for HTML and ARIA. Screen readers on touch screen devices are also quite different from their desktop counterparts, and typically feature fewer capabilities. Be sure to test on both desktop and mobile. @@ -1203,7 +1207,7 @@ Also see [Motherfucking Website](https://motherfuckingwebsite.com/). Motherfucki The [Web Bloat Score calculator](https://www.webbloatscore.com/) is a JavaScript app that compares a page's size with the size of a PNG screenshot of the full page content, encouraging site owners to minimize the ratio of the two. -One resource I found useful (that eventually featured this article!) was the "Your page content" section of {{}} comprehensive guide to [setting up your personal website](https://www.billdietrich.me/YourPersonalWebSite.html#PageContent). +One resource I found useful (that eventually featured this article!) was the "Your page content" section of {{}} comprehensive guide to [setting up your personal website](https://www.billdietrich.me/YourPersonalWebSite.html#PageContent). If you've got some time on your hands, I _highly_ recommend reading the [Web Content Accessibility Guidelines (WCAG) 2.2](https://www.w3.org/TR/WCAG22/). The WCAG 2 standard is technology-neutral, so it doesn't contain Web-specific advice. For that, check the [How to Meet WCAG (Quick Reference)](https://www.w3.org/WAI/WCAG22/quickref). It combines the WCAG with its supplementary [list of techniques](https://www.w3.org/WAI/WCAG22/Techniques/). diff --git a/layouts/_default/single.html b/layouts/_default/single.html index c7cdbe8..12d8053 100644 --- a/layouts/_default/single.html +++ b/layouts/_default/single.html @@ -6,8 +6,7 @@ Posted - - by {{- partial "indieweb-author.html" -}} on his Website + by {{- partial "indieweb-author.html" -}} on his Website {{ with .OutputFormats.Get "gemtext" -}} and Gemini capsule {{- end -}} diff --git a/layouts/partials/processed-content.html b/layouts/partials/processed-content.html index f88555b..eb0d9d9 100644 --- a/layouts/partials/processed-content.html +++ b/layouts/partials/processed-content.html @@ -8,7 +8,7 @@

%s

` ($heading) -}} -{{ $endnote := `(role="doc-endnote"|class="footnote-ref")` }} +{{ $endnote := `(role="doc-endnote"|class="footnote-(back)?ref")` }} {{ $noEndnote := printf "" }} diff --git a/layouts/posts/single.html b/layouts/posts/single.html index 68bf2c6..00ad95d 100644 --- a/layouts/posts/single.html +++ b/layouts/posts/single.html @@ -6,8 +6,7 @@ Posted - - by {{- partial "indieweb-author.html" -}} on his Website + by {{- partial "indieweb-author.html" -}} on his Website {{ with .OutputFormats.Get "gemtext" -}} and Gemini capsule {{- end -}}