Mention FoUC + WFoD, and more on ATs

- Mention the browser-AT relation.
- Mention symbol names versus appearance.
- Also throw in a doc-tip

content/posts/website-best-practices.gmi

@@ -83,7 +83,6 @@ While "script-src" restricts script loading, "sandbox" can also restrict script
 If you're able to control your HTTP headers, then use headers instead of a <meta http=equiv> tag. In addition to not supporting certain directives, a CSP in a <meta> tag might let some items slip through:
 
 > At the time of inserting the meta element to the document, it is possible that some resources have already been fetched. For example, images might be stored in the list of available images prior to dynamically inserting a meta element with an http-equiv attribute in the Content security policy state. Resources that have already been fetched are not guaranteed to be blocked by a Content Security Policy that's enforced late.
-
 => https://html.spec.whatwg.org/multipage/semantics.html#attr-meta-http-equiv-content-security-policy HTML Living Standard, Content Security Policy state
 
 ### If you must enable scripts
@@ -176,13 +175,9 @@ Google's answer to this problem is "Core Web Vitals" containing metrics such as
 These metrics aren't useless, but they are incredibly naive.
 
 > SpeedIndex is based on the idea that what counts is how fast the visible part of the website renders. It doesn't matter what's happening elsewhere on the page. It doesn't matter if the network is saturated and your phone is hot to the touch. It doesn't matter if the battery is visibly draining. Everything is OK as long as the part of the site in the viewport appears to pop into view right away.
->
 > Of course, it doesn’t matter how fast the site appears to load if the first thing the completed page does is serve an interstitial ad. Or, if like many mobile users, you start scrolling immediately and catch the 'unoptimized' part of the page with its pants down.
->
 > There is only one honest measure of web performance: **the time from when you click a link to when you've finished skipping the last ad.**
->
 > Everything else is bullshit.
-
 => https://idlewords.com/talks/website_obesity.htm Maciej Cegłowski, The Website Obesity Crisis
 
 A supplementary metric to use alongside download size is **round trips.** Estimate the number of bytes and round-trips it takes to do the following:
@@ -275,7 +270,6 @@ I address the issue by not using any SVG images on my hidden service:
 Lazy loading may or may not work. Some browsers, including Firefox and the Tor Browser, disable lazy-loading when the user turns off JavaScript. Turning it off makes sense because lazy-loading, like JavaScript, is a fingerprinting vector. Specifically, it identifies idiosyncratic scrolling patterns:
 
 > Loading is only deferred when JavaScript is enabled. This is an anti-tracking measure, because if a user agent supported lazy loading when scripting is disabled, it would still be possible for a site to track a user's approximate scroll position throughout a session, by strategically placing images in a page's markup such that a server can track how many images are requested and when.
-
 => https://developer.mozilla.org/en-US/docs/Web/HTML/Element/img#attr-loading <img>: The Image Embed element on MDN, the loading attribute
 
 If you can’t rely on lazy loading, your pages should work well without it. If pages work well without lazy loading, is it worth enabling?
@@ -344,7 +338,6 @@ Long pages with many DOM nodes may benefit from CSS containment, a more recently
 CSS containment allows authors to isolate sub-trees of the DOM. Combined with a property like "content-visibility", it enables browsers to defer rendering of less essential below-the-fold content. Try to avoid the "hidden" parameter when "auto" is better:
 
 > content-visibility: auto is a more complex value than hidden; rather than being similar to display: none, it adaptively hides/displays an element’s contents as they become relevant to the user. It also doesn’t hide its skipped contents from the user agent, so screen readers, find-in-page, and other tools can still interact with it.
-
 => https://drafts.csswg.org/css-contain/#using-cv-auto CSS Containment Module
 
 Leveraging containment is a progressive enhancement, so there aren't any serious implications for older browsers. I use it for my site footers and endnotes.
@@ -466,7 +459,6 @@ Alt text should be limited to describing content of the image. It lacks context.
 Blind users might struggle to view images in context; they can't easily scan the text before and after an image non-linearly if there's no semantic connection between them.
 
 > Try reading your screen through a drinking straw for an hour to get an idea of the limited context that a blind user has. You simply cannot scan the entire page at a glance with a screenreader - you have to listen to the structure of it carefully and remember all that, or read through the entire thing to find stuff, unless there are explicit associations such as longdesc.
-
 => https://lists.w3.org/Archives/Public/public-html/2008Feb/0069.html -- Charles McCathieNevile on the W3C's public-html mailing list
 
 Being sighted and loading images can introduce issues of its own. Sometimes, sighted readers might focus on the *wrong* part of an image. How can you give readers the missing context and tell them what to focus on?
@@ -498,7 +490,6 @@ I personally try to maintain the flow of an article even if its figures and capt
 
 > When a figure is referred to from the main content of the document by identifying it by its caption (e.g., by figure number), it enables such content to be easily moved away from that primary content, e.g., to the side of the page, to dedicated pages, or to an appendix, without affecting the flow of the document.
 > If a figure element is referenced by its relative position, e.g., "in the photograph above" or "as the next figure shows", then moving the figure would disrupt the page's meaning. Authors are encouraged to consider using labels to refer to figures, rather than using such relative references, so that the page can easily be restyled without affecting the page's meaning.
-
 => https://html.spec.whatwg.org/multipage/grouping-content.html#the-figure-element HTML specification, the figure element
 
 ### Image transcripts
@@ -603,7 +594,6 @@ Color overrides go well beyond simple foreground and background color changes. W
 > Some stuff will disappear in Win HCM, some won’t. Best advice is to use semantic HTML to keep things visible.
 > You can use transparent outline to keep things visble like focus indicators and surface boundaries or use currentColor to maintain SVG fill colors in Win HCM.
 > You can use a special media query combined with special CSS color keywords to give elements the user defined colors.
-
 => https://accessabilly.com/accessibility-issues-concerning-windows-high-contrast-mode/ Accessibility issues concerning Windows HCM
 
 In fact, the CSS Working Group is working on a specification for re-coloring websites:
@@ -658,6 +648,8 @@ If you can't bear the thought of parting with your solid-black background, worry
 
 I personally like a foreground and background of "#eee" and "#0e0e0e", respectively. These shades seem to be as far apart as possible without causing accessibility issues: "#0e0e0e" is barely bright enough to create a soft "glow" capable of minimizing halos among slightly astigmatic users, but won't ruin contrast on cheap displays. I also support a "prefers-contrast: less" media query which lightens the background to "#222".
 
+If you use JavaScript: avoid setting colors, especially dark-mode colors, using JavaScript. Using JavaScript to set a styles risks introducing a "Flash of Unstyled Content" (FOUC). In the case of a dark theme, this FoUC manifests as a "White Flash of Death" (WFoD). A WFoD is incredibly irritating for dark-mode users; at worst, it could put photosensitive epileptic users at risk. CSS is a render-blocking resource for a reason.
+
 ### Contrast is complex
 
 When setting colors, especially for a dark background, I recommend checking your page's contrast using Advanced Perceptual Contrast Algorithm (APCA) values. You can do so in an online checker or Chromium's developer tools (you might have to enable them in a menu for experimental preferences.
@@ -706,7 +698,6 @@ I disagree. One reason is that underlines make it easy to separate multiple cons
 Underlines also make it easy for color-blind readers to distinguish both the beginnings and ends of links. A basic WCAG Level A requirement is for information to not be conveyed solely through color:
 
 > Color is not used as the only visual means of conveying information, indicating an action, prompting a response, or distinguishing a visual element.
-
 => https://www.w3.org/TR/WCAG22/#distinguishable WCAG 2.2, section 1.4.1
 
 Readers already expect underlined text to signify a hyperlink. Don't break fundamental affordances for aesthetics.
@@ -1059,7 +1050,6 @@ On lists without visible bullets, I dropped the default indentation. I had to fi
 Increasing the line-spacing a bit will make tap targets larger and improve comprehension by readers with cognitive disabilities. A WCAG AAA Success Criterion is to allow 1.5 space units between lines.
 
 > Line spacing (leading) is at least space-and-a-half within paragraphs, and paragraph spacing is at least 1.5 times larger than the line spacing.
-
 => https://w3c.github.io/wcag/guidelines/22/#visual-presentation WCAG 2.2 Success Criterion 1.4.8: Visual Presentation
 
 The WAI's Cognitive and Learning Disabilities Accessibility Task Force recommends changing this level, finding it too important to be relegated to AAA status:
@@ -1248,7 +1238,6 @@ This is especially concerning on my website, where I tend to hyperlink peoples'
 A workaround is to use the "text" ARIA role to remove the semantics of elements.
 
 > To force a screen reader to interpret the heading as one object, I wrapped the text inside the heading in a span and added role=”text”.
-
 ```
 <h1>
   <span role="text">Digital accessibility, <br>
@@ -1256,7 +1245,6 @@ A workaround is to use the "text" ARIA role to remove the semantics of elements.
   </span>
 </h1>
 ```
-
 => https://axesslab.com/text-splitting/ Axess Lab on text splitting
 
 If you're unfamiliar with ARIA, always remember the first rule of ARIA:
@@ -1269,13 +1257,21 @@ 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, TalkBack, and ChromeVox 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, VoiceOver, NVDA, Narrator, JAWS, TalkBack, and ChromeVox all have unique behavior. In addition, different browsers--even different Chromium forks--expose content to screen readers differently. You'll need to test multiple screen readers in multiple browsers, and keep track of updates to both. See why standards compliance is important?
+
+Beware of "display" and "visibility" CSS properties; they can interfere with content reported to screen readers. Whenever you use one of those properties, re-test with screen readers just to be safe.
+
+> Sometimes doing this can have an unintended effect of nuking the semantics of the elements, as conveyed to screen reading software, in the browser accessibility tree. Screen readers and other assistive tech, in general, do not have direct access to the HTML DOM, they are provided access to a subset of information in the HTML DOM via Accessibility APIs. Sometimes what an element represents in the HTML DOM is not how it is represented in the accessibility tree.
+> If what is represented in the accessibility tree does not represent the developer’s intended UI, it’s either (wittingly/unwittingly) the fault of the developer or the browser. But what we can be sure of, in these cases, is that it is not the fault of the screen reader.
+=> https://www.tpgi.com/short-note-on-what-css-display-properties-do-to-table-semantics/ Short note on what CSS display properties do to table semantics
 
 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 reader implementations often skip punctuation marks like the exclamation point ("!"). Ensure that meaning doesn't rely too heavily on such punctuation.
 
-Screen readers have varying levels of verbosity. The default verbosity level doesn't always convey inline emphasis, such as <em>, <code>, or <strong>. Ensure that your meaning carries through without these semantics.¹² It does, however, convey symbols and emoji. Use symbols and emoji judiciously, since they can get pretty noisy if you aren't careful. Use "aria-label" on symbols when appropriate; I used labels to mark my footnote backlinks, which would otherwise be read as "right arrow curving left".
+Screen readers have varying levels of verbosity. The default verbosity level doesn't always convey inline emphasis, such as <em>, <code>, or <strong>. Ensure that your meaning carries through without these semantics.¹²
+
+Default verbosity does, however, convey symbols and emoji. Use symbols and emoji judiciously, since they can get pretty noisy if you aren't careful. Use "aria-labelledby" on symbols when appropriate; I used labels to mark my footnote backlinks, which would otherwise be read as <samp>right arrow curving left</samp>. If you have to use a symbol or emoji, first test how assistive technologies announce it; the emoji name may not communicate what you expect.
 
 ## Testing
 

content/posts/website-best-practices.md

@@ -19,11 +19,11 @@ title: An opinionated list of best practices for textual websites
 ---
 <div role="doc-preface">
 
-_The following applies to minimal websites that focus primarily on text. It does not apply to websites that have a lot of non-textual content. It also does not apply to websites that focus more on generating revenue or pleasing investors than being inclusive._
+The following applies to minimal websites that focus primarily on text. It does not apply to websites that have a lot of non-textual content. It also does not apply to websites that focus more on generating revenue or pleasing investors than being inclusive._
 
 This is a "living document" that I add to as I receive feedback. See the updated date and changelog after the post title.
 
-If you find the article too long, just read the introduction and conclusion. The table of contents should help you skim.
+<p role="doc-tip">If you find the article too long, just read the introduction and conclusion. The table of contents should help you skim.<p role="doc-tip">
 
 </div>
 
@@ -676,6 +676,8 @@ If you can't bear the thought of parting with your solid-black background, worry
 
 I personally like a foreground and background of `#eee` and `#0e0e0e`, respectively. These shades seem to be as far apart as possible without causing accessibility issues: `#0e0e0e` is barely bright enough to create a soft "glow" capable of minimizing halos among slightly astigmatic users, but won't ruin contrast on cheap displays. I also support a `prefers-contrast: less` media query which lightens the background to `#222`.
 
+If you use JavaScript: avoid setting colors, especially dark-mode colors, using JavaScript. Using JavaScript to set a styles risks introducing a "Flash of Unstyled Content" (<abbr title="Flash of Unstyled Content">FOUC</abbr>). In the case of a dark theme, this FoUC manifests as a "White Flash of Death" (<abbr title="White Flash of Death">WFoD</abbr>). A WFoD is incredibly irritating for dark-mode users; at worst, it could put photosensitive epileptic users at risk. CSS is a render-blocking resource for a reason.
+
 ### Contrast is complex
 
 Color is a nuanced topic that deserves more attention than current guidelines give.
@@ -1231,15 +1233,29 @@ 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, TalkBack, and ChromeVox 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, VoiceOver, NVDA, Narrator, JAWS, TalkBack, and ChromeVox all have unique behavior. In addition, different browsers--even different Chromium forks--expose content to screen readers differently. You'll need to test multiple screen readers in multiple browsers, and keep track of updates to both. See why standards compliance is important?
+
+Beware of `display` and `visibility` CSS properties; they can interfere with content reported to screen readers. Whenever you use one of those properties, re-test with screen readers just to be safe.
+
+<figure itemscope itemtype="https://schema.org/Quotation">
+<blockquote itemprop="text">
+<p>Sometimes doing this can have an unintended effect of nuking the semantics of the elements, as conveyed to screen reading software, in the <a href="https://www.tpgi.com/the-browser-accessibility-tree/">browser accessibility tree</a>. Screen readers and other assistive tech, in general, do not have direct access to the HTML DOM, they are provided access to a subset of information in the HTML DOM via <a href="https://www.w3.org/TR/wai-aria-1.1/#dfn-accessibility-api">Accessibility APIs</a>. Sometimes what an element represents in the HTML DOM is not how it is represented in the accessibility tree.</p>
+<p>If what is represented in the accessibility tree does not represent the developer’s intended UI, it’s either (wittingly/unwittingly) the <strong>fault of the developer or the browser</strong>. But what we can be sure of, in these cases, is that it is <strong>not the fault of the screen reader</strong>.</p>
+</blockquote>
+{{< quotecaption partOfType="BlogPosting" >}}
+{{<indieweb-person first-name="Steve" last-name="Faulkner" url="https://twitter.com/stevefaulkner" itemprop="author" org="TPGi" org-url="https://www.tpgi.com/" >}},
+{{<cited-work name="Short note on what CSS display properties do to table semantics" url="https://www.tpgi.com/short-note-on-what-css-display-properties-do-to-table-semantics/" extraName="headline">}}
+{{< /quotecaption >}}
+</figure>
+
 
 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 reader implemen&shy;tations often skip punctuation marks like the exclamation point ("!"). Ensure that meaning doesn't rely too heavily on such punctuation.
 
-Screen readers have varying levels of verbosity. The default verbosity level doesn't always convey inline emphasis, such as `<em>`, `<code>`, or `<strong>`. Ensure that your meaning carries through without these semantics.[^13] It does, however, convey symbols and emoji. Use symbols and emoji judiciously, since they can get pretty noisy if you aren't careful. Use `aria-label` on symbols when appropriate; I used labels to mark my footnote backlinks, which would otherwise be read as <samp>right arrow curving left</samp>.
+Screen readers have varying levels of verbosity. The default verbosity level doesn't always convey inline emphasis, such as `<em>`, `<code>`, or `<strong>`. Ensure that your meaning carries through without these semantics.[^13]
 
-I'll be adding more tips here shortly; watch this space.
+Default verbosity does, however, convey symbols and emoji. Use symbols and emoji judiciously, since they can get pretty noisy if you aren't careful. Use `aria-labelledby` on symbols when appropriate; I used labels to mark my footnote backlinks, which would otherwise be read as <samp>right arrow curving left</samp>. If you have to use a symbol or emoji, first test how assistive technologies announce it; the emoji name may not communicate what you expect.
 
 Testing
 -------