fmaury/seirdy.one
1
0
Fork 0
mirror of https://git.sr.ht/~seirdy/seirdy.one synced 2024-11-13 01:02:10 +00:00
Code Issues Projects Releases Wiki Activity

Shorter alts, formatting, redundant links, cleanup

Browse source 
- Shrink some excessive alt text
- Remove some redundant links
- Screenreaders that split elements up aren't just on touchscreens
- Mention ChromeVox in list of screen readers
- Move TOC higher in page
- Spelling
- Drop more unused classes
This commit is contained in:
Rohan Kumar 2022-04-09 08:59:12 -07:00
parent 8be0fae481
commit 3200333424
No known key found for this signature in database
GPG key ID: 1E892DB2A5F84479
5 changed files with 35 additions and 29 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

20
content/posts/website-best-practices.gmi
View file

@ -433,17 +433,21 @@ font: 100%/1.5 sans-serif;
Expect some readers to have images disabled or unloaded. Examples include: Expect some readers to have images disabled or unloaded. Examples include:
* Blind readers * Blind readers
* Users of metered connections: sometimes they disable all images, and other times they only disable images above a certain size * 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 only manage to load a few resources * People experiencing packet loss who fail to download some images
* Users of textual browsers * 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: 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 => 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: 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: 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. 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: 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: 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 ### 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. 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 ### 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. 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.

36
content/posts/website-best-practices.md
View file

@ -25,6 +25,8 @@ If you find the article too long, just read the introduction and conclusion. The
</div> </div>
{{<toc>}}
<section role="doc-introduction"> <section role="doc-introduction">
Intro&shy;duction {#introduction} Intro&shy;duction {#introduction}
@ -44,8 +46,6 @@ I'll cite the Web Accessibility Initiative's (<abbr title="Web Accessibility Ini
</section> </section>
{{<toc>}}
Security and privacy Security and privacy
-------------------- --------------------
@ -334,7 +334,7 @@ Another common offender is infinite-scrolling. In addition to requiring JavaScri
<figure> <figure>
<a href="https://explainxkcd.com/1309/#Transcript"> <a href="https://explainxkcd.com/1309/#Transcript">
{{< 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.">}}
</a> </a>
<figcaption> <figcaption>
@ -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: Expect some readers to have images disabled or unloaded. Examples include:
* Blind readers * Blind readers
* Users of metered connections: sometimes they disable all images, and other times they only disable images above a certain size * Users with 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 * People experiencing packet loss who fail to download some images
* Users of textual browsers * 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 <abbr title="Web Accessibility Initiative">WAI</abbr> provides some guidelines in <cite>[An `alt` Decision Tree](https://www.w3.org/WAI/tutorials/images/decision-tree/)</cite>. 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 <abbr title="Web Accessibility Initiative">WAI</abbr> provides some guidelines in <cite>[An `alt` Decision Tree](https://www.w3.org/WAI/tutorials/images/decision-tree/)</cite>. 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 ### 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 <a href="#related-issues">included earlier in the page</a> had this alt-text: The xkcd comic <a href="#related-issues">included earlier in the page</a> had this alt-text:
</figcaption> </figcaption>
> 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.
</figure> </figure>
@ -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: 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:
<figure> <figure>
<a href="http://bettermotherfuckingwebsite.com/"> {{< picture name="website_colors" alt="Screenshot of a website with gray text on a darker gray background. Details in caption." >}}
{{< picture name="website_colors" alt="Screenshot of a website with gray text on a darker grey background. Details in the caption." >}}
</a>
<figcaption> <figcaption>
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. 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. 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.
<figure> <figure>
{{< 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 >}}
<figcaption> <figcaption>
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. 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 (`<ol>`, `<dl>`, `<ul
<figure> <figure>
{{<picture name="touch_targets" alt="Phone screen with three \"touch target\" rectangles on top of each other, separated by blank sections labeled \"space\"">}} {{<picture name="touch_targets" alt="Phone screen with three \"touch target\" rectangles on top of each other, separated by blank sections labeled \"space\"">}}
<figcaption> <figcaption>
Image credit: <a href="https://axesslab.com/hand-tremors/">Axess Labs</a> Image credit: <a href="https://axesslab.com/hand-tremors/">Axess Lab</a>
</figcaption> </figcaption>
</figure> </figure>
@ -1019,7 +1023,7 @@ For example: machine translation will leave `<code>` and `<samp>` 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. 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. {{<indieweb-person first-name="Ahmed" last-name="Shadeed" url="https://ishadeed.com/" appendString="'s">}} <cite>[RTL Styling 101](https://rtlstyling.com/posts/rtl-styling/)</cite> 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. {{<indieweb-person first-name="Ahmed" last-name="Shadeed" url="https://ishadeed.com/" appendString="’s">}} <cite>[RTL Styling 101](https://rtlstyling.com/posts/rtl-styling/)</cite> is a comprehensive guide to what can go wrong and how to fix issues.
Screen reader improve&shy;ments {#screen-reader-improvements} Screen reader improve&shy;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 ### 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. 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 ### 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. 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. 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 {{<indieweb-person first-name="Bill" last-name="Dietrich" url="https://www.billdietrich.me" appendString="'s">}} 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 {{<indieweb-person first-name="Bill" last-name="Dietrich" url="https://www.billdietrich.me" appendString="’s">}} 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 <cite>[Web Content Accessibility Guidelines (WCAG)&nbsp;2.2](https://www.w3.org/TR/WCAG22/)</cite>. The WCAG 2 standard is technology-neutral, so it doesn't contain Web-specific advice. For that, check the <cite>[How to Meet WCAG (Quick Reference)](https://www.w3.org/WAI/WCAG22/quickref)</cite>. It combines the WCAG with its supplementary [list of techniques](https://www.w3.org/WAI/WCAG22/Techniques/). If you've got some time on your hands, I _highly_ recommend reading the <cite>[Web Content Accessibility Guidelines (WCAG)&nbsp;2.2](https://www.w3.org/TR/WCAG22/)</cite>. The WCAG 2 standard is technology-neutral, so it doesn't contain Web-specific advice. For that, check the <cite>[How to Meet WCAG (Quick Reference)](https://www.w3.org/WAI/WCAG22/quickref)</cite>. It combines the WCAG with its supplementary [list of techniques](https://www.w3.org/WAI/WCAG22/Techniques/).

3
layouts/_default/single.html
View file

@ -6,8 +6,7 @@
<span class="dateline"> <span class="dateline">
Posted <time itemprop="datePublished" class="dt-published published" datetime="{{ .Date.Format "2006-01-02T15:04:05Z07:00" }}" title="{{ .Date.Format "2006-01-02T15:04:05Z07:00" }}">{{ .Date.Format "2006-01-02" }}</time> Posted <time itemprop="datePublished" class="dt-published published" datetime="{{ .Date.Format "2006-01-02T15:04:05Z07:00" }}" title="{{ .Date.Format "2006-01-02T15:04:05Z07:00" }}">{{ .Date.Format "2006-01-02" }}</time>
</span> </span>
<span class="byline"> by {{- partial "indieweb-author.html" -}} on his <a rel="canonical" itemprop="mainEntityOfPage" class="u-url url" href="https://seirdy.one{{ .RelPermalink }}">Website</a>
by {{- partial "indieweb-author.html" -}}</span> on his <a rel="canonical" itemprop="mainEntityOfPage" class="u-url url" href="https://seirdy.one{{ .RelPermalink }}">Website</a>
{{ with .OutputFormats.Get "gemtext" -}} {{ with .OutputFormats.Get "gemtext" -}}
and <a rel="syndication" class="u-syndication" href="{{replace .Permalink "/gemini" "" 1 | safeURL}}">Gemini capsule</a> and <a rel="syndication" class="u-syndication" href="{{replace .Permalink "/gemini" "" 1 | safeURL}}">Gemini capsule</a>
{{- end -}} {{- end -}}

2
layouts/partials/processed-content.html
View file

@ -8,7 +8,7 @@
<h2 id="note-hd">%s</h2>` ($heading) -}} <h2 id="note-hd">%s</h2>` ($heading) -}}
<!--Remove deprecated DPUB-ARIA role and unused classes--> <!--Remove deprecated DPUB-ARIA role and unused classes-->
{{ $endnote := `(role="doc-endnote"|class="footnote-ref")` }} {{ $endnote := `(role="doc-endnote"|class="footnote-(back)?ref")` }}
{{ $noEndnote := printf "" }} {{ $noEndnote := printf "" }}
<!--Add tabindex to all <pre> elements, inc. those that aren't generated by Goldmark--> <!--Add tabindex to all <pre> elements, inc. those that aren't generated by Goldmark-->

3
layouts/posts/single.html
View file

@ -6,8 +6,7 @@
<span class="dateline"> <span class="dateline">
Posted <time itemprop="dateCreated datePublished" class="dt-published published" datetime="{{ .Date.Format "2006-01-02T15:04:05Z07:00" }}" title="{{ .Date.Format "2006-01-02T15:04:05Z07:00" }}">{{ .Date.Format "2006-01-02" }}</time> Posted <time itemprop="dateCreated datePublished" class="dt-published published" datetime="{{ .Date.Format "2006-01-02T15:04:05Z07:00" }}" title="{{ .Date.Format "2006-01-02T15:04:05Z07:00" }}">{{ .Date.Format "2006-01-02" }}</time>
</span> </span>
<span class="byline"> by {{- partial "indieweb-author.html" -}} on his <a rel="canonical" itemprop="mainEntityOfPage" class="u-url url" href="https://seirdy.one{{ .RelPermalink }}">Website</a>
by {{- partial "indieweb-author.html" -}}</span> on his <a rel="canonical" itemprop="mainEntityOfPage" class="u-url url" href="https://seirdy.one{{ .RelPermalink }}">Website</a>
{{ with .OutputFormats.Get "gemtext" -}} {{ with .OutputFormats.Get "gemtext" -}}
and <a rel="syndication" class="u-syndication" href="{{replace .Permalink "/gemini" "" 1 | safeURL}}">Gemini capsule</a> and <a rel="syndication" class="u-syndication" href="{{replace .Permalink "/gemini" "" 1 | safeURL}}">Gemini capsule</a>
{{- end -}} {{- end -}}