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

Compare commits

base: fmaury:fc8eb8d7a67b8b1f3570c3f4a799a0b78183152f
Branches Tags
fmaury:master
fmaury:draft-searchengines
..
compare: fmaury:9ae1c8636e259a7bcbdffd8673b12da207f2b062
Branches Tags
fmaury:master
fmaury:draft-searchengines

No commits in common. "fc8eb8d7a67b8b1f3570c3f4a799a0b78183152f" and "9ae1c8636e259a7bcbdffd8673b12da207f2b062" have entirely different histories.
fc8eb8d7a6 ... 9ae1c8636e

33 changed files with 196 additions and 498 deletions
Show stats Expand all files Collapse all files

6
Makefile.online
View file

@ -7,14 +7,14 @@ SCHEME=https://
URL ?= $(SCHEME)$(DOMAIN)$(PAGE_PATH)
# latest bleeding-edge chromium snapshot
CHROME_DIR = /home/rkumar/Downloads/gitclone/chromium/thorium/latest
CHROME_PATH = $(CHROME_DIR)/thorium
CHROME_PATH = $(CHROME_DIR)/chrome
CHROMEDRIVER_PATH = $(CHROME_DIR)/chromedriver
CHROME_PROFILE ?= /tmp/chrome-lighthouse
JS_FLAGS=''
CHROME_FLAGS += --disable-extensions --no-default-browser-check --disable-client-side-phishing-detection --disable-component-update --disable-default-apps --disable-device-discovery-notifications --disable-domain-reliability --disable-background-timer-throttling --disable-breakpad --enable-blink-features=LayoutInstabilityAPI --no-first-run --disable-background-networking --user-data-dir=$(CHROME_PROFILE) --enable-quic --start-in-incognito --origin-to-force-quic-on=$(DOMAIN):443
CHROME_FLAGS_COMMA = 'disable-extensions,no-default-browser-check,disable-client-side-phishing-detection,disable-component-update,disable-default-apps,disable-device-discovery-notifications,disable-domain-reliability,disable-background-timer-throttling,disable-breakpad,no-first-run,disable-background-networking,js-flags=--jitless'
CPU_SLOWDOWN=15.0
LIGHTHOUSE_ARGS += --budget-path linter-configs/budget.json --output html --output json --output-file lighthouse-results --throttling-method=devtools --throttling.cpuSlowdownMultiplier=$(CPU_SLOWDOWN) --chrome-flags="$(CHROME_FLAGS)"
CPU_SLOWDOWN=2.8
LIGHTHOUSE_ARGS += --view --budget-path linter-configs/budget.json --output html --output json --output-file lighthouse-results --throttling.cpuSlowdownMultiplier=$(CPU_SLOWDOWN) --chrome-flags="$(CHROME_FLAGS)"
hint-online:
hint --config linter-configs/hintrc $(URLS)

144
assets/css/main.css
View file

@ -57,7 +57,7 @@ html {
* 108.75% is the minimum required to get superscripts to reach 14.5
* CSS pixels with most default stylesheets. At that size, my dark
* color palette has sufficient contrast.*/
font-size: 109%;
font-size: 108.75%;
/* Aligning to the center with space on both sides prevents accidental
* link activation on tablets, and is a common practice that users are
@ -67,8 +67,8 @@ html {
/* WCAG recommends a max line width. Not everyone can resize the
* viewport. This isn't for large blocks of text yet, so we don't have
* to go by SC 1.4.8.
* 40em = lowest acceptable width for titles, nav, footers, etc */
max-width: 40em;
* 45em = lowest acceptable width for titles, nav, footers, etc */
max-width: 42em;
/* Phone cases can cover the edges. Swipe-from-edge navigations
* should not conflict with the page elements. Focus outlines for
@ -90,7 +90,7 @@ html {
li[itemprop="dataFeedElement"],
.narrow {
margin: auto;
max-width: 34em;
max-width: 35em;
}
/* Enable containment, especially useful for achive pages with
@ -101,13 +101,11 @@ html {
/* We increase the target size of h2/h3 links in a way that would cause
* issues with content containment */
article > :not(h2):not(h3) {
contain: inline-size layout paint;
contain: content;
/* Add padding on both sides so that focus outlines don't escape their
* containers. This will let us enable CSS containment without
* clipping overflowing elements. */
padding: 0 .5em;
margin-top: .25em;
margin-bottom: .25em;
}
/* Align titular h1 with top nav and body text. */
@ -117,26 +115,8 @@ html {
/* Archive pages can get long. Allow them to get long without slowing
* down the browser by using content-visibility. */
h2,
h3,
aside > a,
footer,
dt,
a[role="doc-backlink"],
section[role="doc-endnotes"],
li article,
summary {
content-visibility: auto;
contain-intrinsic-size: auto 3em;
}
dt,
h3 {
contain-intrinsic-size: 1.5em;
}
footer,
li article {
content-visibility: auto;
contain-intrinsic-size: auto 16em;
}
@ -145,45 +125,30 @@ html {
contain-intrinsic-size: auto 36em;
}
.tall,
section[role="doc-endnotes"] {
.tall {
contain-intrinsic-size: auto 50em;
}
/* Full-width elements (e.g. display: block) have known widths, so
* contain their widths. */
html,
body,
main,
article,
h1,
h2,
h3,
pre,
dt,
summary,
section[role="doc-endnotes"] {
contain: inline-size layout paint;
}
p,
figure {
contain: inline-size layout;
}
article > h2 {
margin: .25em 0;
padding: .25em 0;
summary {
/* It's not obvious that a <summary> has button semantics.
* "cursor: pointer" is used on MDN, web.dev, GitHub, gov.uk, and
* others so it's not "novel" and won't surprise users. */
cursor: pointer;
}
/* If we have a list of disclosure widgets, we need some
* non-interactive space on the screen that's safe to tap. */
form,
details {
contain: inline-size layout;
li details {
margin: .5em 0;
}
/* Make superscripts a bit easier to tap. */
sup > a {
margin-left: .25em;
padding-bottom: .5em;
}
/* SC 2.5.5, Google a11y: Increase tap target size a bit
* - Summary is a tappable button
* - standalone links in lists are usually parts of collections of
@ -207,11 +172,9 @@ html {
* Also prevent overlapping outlines on focus */
/* We've increased the padding for dt > a, but dt without a link
* should take up as much space. Also: since it got
* content-visibility: auto previously, give it an intrinsic size. */
* should take up as much space. */
dt {
padding: 1em .5em;
margin: -.25em 0 -.25em -.5em;
margin: .75em 0;
}
/* <dt> should not be closer to the previous <dd> than the following <dd>.
@ -222,7 +185,6 @@ html {
dt > a,
aside > a {
contain: content;
margin: -.75em -.25em;
}
@ -233,6 +195,7 @@ html {
/* List items with direct hyperlink children should only have one
* hyperlink. */
li > a,
h3 > a,
aside > a,
nav ol a {
display: inline-block;
@ -240,30 +203,13 @@ html {
}
/* Increase tap-target size of title links. */
h2 > a {
contain: content;
display: inline-block;
/* Mis-alignment, I have no clue why it's there. */
margin: 0 .125em;
padding: .25em;
}
h2 > a,
h3 > a {
contain: content;
display: inline-block;
padding: .5em .25em;
}
article > h3 {
padding: .25em;
margin: 0 0 0 -.5em;
}
/* align h-feeds in sections; they typically follow articles. */
a[role="doc-backlink"],
section article p {
margin-left: -.5em;
}
@ -277,32 +223,24 @@ html {
}
/* Multiple consecutive <dt> that share a <dd> shouldn't have tap targets overlap */
dt + dt {
padding-top: .25em;
}
dt + dt > a {
padding-top: 0;
}
/* stylelint-disable selector-max-compound-selectors -- simplest way to describe link-lists */
:not(nav) > ul li > a,
nav:not([itemprop="breadcrumb"]) li,
ol li > a {
/* stylelint-enable selector-max-compound-selectors */
margin: .25em;
}
/* Increase backlink tap target size to at least 48x48 */
a[role="doc-backlink"] {
contain: content;
display: inline-block;
margin-left: -.5em;
padding: .75em .5em;
}
/* skip link: make it invisible until focused, and put it on the top. */
a[href="#h1"] {
contain: content;
content-visibility: auto;
padding: 0 .25em;
position: absolute;
top: -2em;
@ -313,22 +251,6 @@ html {
}
}
/* Make superscripts a bit easier to tap, and prevent consecutive
* superscripts from touching. */
sup > a {
margin-left: .25em;
padding-bottom: .5em;
}
/* Make superscript font size a bit larger so they cross some APCA color
* contrast thresholds on the dark theme. Also prevent them from messing
* with line-height. */
sup {
font-size: 0.85em;
line-height: 0;
}
/* narrow screens: reduce list indentation, hyphenate nested lists
* touch screens: lists of links should be easy to tap so give them
* some spacing (partial SC 2.5.5). There should be non-interactive
@ -362,13 +284,12 @@ nav ul {
nav[itemprop="breadcrumb"] ol,
nav[itemprop="breadcrumb"] li,
nav[itemprop="breadcrumb"] > span,
nav ul li,
dt > a {
nav ul li {
display: inline-block;
}
nav[itemprop="breadcrumb"] ol {
margin: -.25em;
margin: -.25em 0;
padding: 0;
}
@ -393,23 +314,13 @@ h1 {
/* Very narrow screens: full hyphenation.
* This is the typical width of a smart feature phone. */
@media (max-width: 250px) {
@media (max-width: 15em) {
body {
font-size: 100%;
-webkit-hyphens: auto;
hyphens: auto;
padding: 0 8px;
}
li > a,
nav[itemprop="breadcrumb"] a,
nav[itemprop="breadcrumb"] > span {
padding: .25em;
}
hr {
margin: .25em 0;
}
}
/* <kbd> should be distinguished from <code> and surrounding text
@ -485,6 +396,7 @@ span[itemtype="https://schema.org/Person"] {
/* Narrow screens: allow horizontal scroll in a pre block. */
pre {
contain: content;
overflow: auto;
padding: .5em;
}

7
assets/css/print.css
View file

@ -8,19 +8,19 @@
/* Hide screen-only content */
a[href="#h1"], /* Skip link */
a[role="doc-backlink"], /* can't navigate back on print. */
aside:not([role="note"]),
/* An un-opened summary inside an article has no use in print.
* Outside an article it's used in my webring list where it has some
* use, see below. */
article summary,
section[aria-labelledby="webmentions"],
/* You can't navigate across the site in a printout. */
/* You can't navigate in a printout. */
footer,
/* splitting up sections with <hr> is unnecesary if those
* sections are removed */
body > hr,
nav:not([itemprop="breadcrumb"]) a:not([rel="home"]) {
nav a:not([rel="home"]) span,
nav[itemprop="breadcrumb"] {
display: none;
}
}
@ -28,7 +28,6 @@
/* Print: don't break up self-contained items. */
figure,
section[itemprop="mentions"],
blockquote,
li {
break-inside: avoid;
}

25
content/about/uses.md
View file

@ -8,8 +8,7 @@ date: "2022-06-16T17:16:18-07:00"
---
Here's the software I use. I've recently started to reduce my use of <abbr title="Textual User Interfaces">TUIs</abbr> in favor of <abbr title="Command Line Interfaces">CLIs</abbr> for a variety of reasons. When possible, I try to use lightweight programs that can run on any machine, from a single-board computer to a giant desktop. I don't ever want to feel like I need to upgrade my hardware to do the same tasks as before: hardware upgrades should only be justified by my use-cases significantly changing, existing hardware being broken beyond repair, or upstream abandonment of security patches.[^1]
Hardware
--------
## Hardware
My main computer is a 2013 HP Elitebook 840 G1. It has an Intel i5-4300U CPU, with simultaneous multithreading disabled.
@ -202,31 +201,19 @@ I run these tools locally, on every applicable file. A full run takes under <tim
[IBM Equal Access accessibility-checker](https://github.com/IBMa/equal-access/blob/master/accessibility-checker/README.md)
: I use this just like axe-core: as a CLI utility to check every page on my sitemap for basic accessibility violations. I disable "potential-violations" checks because those have false-positives.
jq
: I use jq to ensure that all my JSON is valid. This includes my Web App Manifest file and Webfinger JSON. I also use jq to filter out false positives from the Nu HTML Checker.
[Feed Validator](https://github.com/w3c/feedvalidator)
: I validate my Atom feeds using this tool. Like always, I filter out false positives and report them upstream.
[htmltest](https://github.com/wjdp/htmltest) OR [html-proofer](https://github.com/gjtorikian/html-proofer)
: Two very similar tools. html-proofer is slow but supports more features; I run the faster htmltest more often. They check for broken links, markup errors, and valid icons.
[webhint](https://webhint.io)
: When all the aforementioned tests pass, my staging site deploys and webhint runs on every page in its sitemap. I skip its axe-based tests, since those are already covered by axe-core.
Webhint checks HTTP headers, validates the Web App Manifest, ensures caching and compression work, checks for compatibility issues, validates compliance with a performance budget, and looks for common HTML/CSS mistakes.
jq:
: I use jq to ensure that all my JSON is valid. This includes my Web App Manifest file and Webfinger JSON.
Tools I have yet to add to this section:
* Something to validate my Webfinger JSON against a schema
* A tool to validate microdata and RDFa. structured-data-linter or Schemarama could work.
* A tool to validate microformats.
* Something to validate my Web App Manifest and Webfinger JSON against a schema
* Validation for my Atom feeds
* Broken internal link checkers
### Server-side stuff
All my server daemons are statically-linked binaries, which makes sandboxing easier.
Nginx
: Specifically, [nginx-quic.](https://quic.nginx.org/) with the [headers_more](https://github.com/openresty/headers-more-nginx-module) and [ngx_brotli](https://github.com/google/ngx_brotli) modules. Statically linked against zlib-ng, BoringSSL, and musl libc; patched for dynamic TLS records, basic OCSP support, and HPACK compression.

4
content/meta/site-design.md
View file

@ -42,11 +42,10 @@ I also go further than WCAG in many aspects:
- I ensure at least one such 56-by-56&nbsp;px non-interactive region exists on the page, for users with hand tremors or or anyone who wants to tap the screen without clicking something.
- With the exception of in-text borders, I only set custom colors in response to the `prefers-color-scheme: dark` media query. These custom colors pass APCA contrast ratios, all being close to the ideal lightness contrast of 90. They are also autism- and overstimulation-friendly colors: the yellow links are significantly de-saturated to reduce harshness.
- With the exception of in-text borders, I only set custom colors in response to the `prefers-color-scheme: dark` media query. These custom colors pass APCA contrast ratios, all being close to the ideal lightness contrast of 90. They are also autism- and overstimulation-friendly colors: yellow links are significantly de-saturated to reduce harshness.
- I ensure that the page works on extremely narrow viewports without triggering two-dimensional scaling. It should work at widths well below 200 CSS pixels.
### Assessment and evaluation
I test each WCAG success criterion myself using the mainstream browser engines (Blink, Gecko, WebKit). I test using multiple screen readers: Orca (primary, with Firefox and Epiphany), NVDA (with Firefox and Chromium), Windows Narrator (with Microsoft Edge), Apple VoiceOver (with desktop and mobile Safari), and Android TalkBack (with Chromium).
@ -61,7 +60,6 @@ Finally, I supplement manual testing with the following automated tools:
- [WAVE Web Accessibility Evaluation Tool](https://wave.webaim.org/)
- [ARC Toolkit](https://www.tpgi.com/arc-platform/arc-toolkit/)
- [webhint](https://webhint.io/)
- [lighthouse](https://developer.chrome.com/docs/lighthouse/overview/)
WAVE reports no errors; AXE is unable to determine certain contrast errors, but it otherwise reports no errors; IBM Equal Access reports no errors but some items that need review.

2
content/notes/flatpak-and-web-browsers.md
View file

@ -5,7 +5,7 @@ replyURI: "https://floss.social/@alcinnz/108466919900074368"
replyTitle: "The outer layer will be via FlatPak"
replyType: "SocialMediaPosting"
replyAuthor: "Adrian Cochrane"
replyAuthorURI: "https://adrian.geek.nz/"
replyAuthorURI: "https://rhapsode.adrian.geek.nz/"
---
You might want to provision namespace-based isolation for your browsers. But that could throw a wrench into Flatpak-based distribution.

4
content/notes/new-search-box.md
View file

@ -3,6 +3,6 @@ title: "New search box"
date: 2022-05-26T17:42:09-07:00
---
I decided my site had enough content to warrant a search form, so I added one to the footer. I kanged the CSS from [gov.uk](https://www.gov.uk/); I liked how their search box was adaptive yet compatible with legacy browsers. This is a static site so I made it point to [Search My Site](https://searchmysite.net/), which regularly crawls my whole website.
I decided my site had enough content to warrant a search form, so I added one to the footer. I kanged the CSS from [gov.uk](https://www.gov.uk/); I liked how their search box was adaptive yet compatible with legacy browsers. This is a static site so I made it point to [Search My Site](https://searchmysite.net), which regularly crawls my whole website.
Eventually I'll add a dynamic page for search results (probably using the Search My Site API), and add an ATOM feed for posts and notes (I currently have an RSS feed for posts, and that's not going anywhere). If I get those two, I'll be ready for the next step of setting up [WebSub](https://www.w3.org/TR/websub/) and starting on [IndieMark 4](https://indieweb.org/IndieMark) (I've decided not to <abbr title="Publish on Own Site, Syndicate Elsewhere">POSSE</abbr> *all* my microblog posts, to maintain some separation between my "Rohan" and "Seirdy" identities).
Eventually I'll add a dynamic page for search results (probably using the Search My Site API), and add an ATOM feed for posts and notes (I currently have an RSS feed for posts, and that's not going anywhere). If I get those two, I'll be ready for the next step of setting up [WebSub](https://w3c.github.io/websub/) and starting on [IndieMark 4](https://indieweb.org/IndieMark) (I've decided not to <abbr title="Publish on Own Site, Syndicate Elsewhere">POSSE</abbr> *all* my microblog posts, to maintain some separation between my "Rohan" and "Seirdy" identities).

2
content/notes/resize-and-reflow.md
View file

@ -10,6 +10,6 @@ replyAuthorURI: "https://yatil.net"
This is a good article on the difference between SC 1.4.4 and 1.4.10. However, I don't think these criteria go far enough:
Even narrower viewports exist. KaiOS devices tend to have 240&nbsp;px viewports; smartwatches tend to have half the width of a phone while emulating a phone width (Apple Watches can be instructed not to do this with a proprietary `meta` tag). Of course, making sites watch-compatible is a stretch, but support for feature phones running KaiOS should be reasonable. I wrote about this more in <cite>[Best practices for inclusive textual websites]({{<relref "/posts/website-best-practices">}})</cite>.
Even narrower viewports exist. KaiOS devices tend to have 240&nbsp;px viewports; smartwatches tend to have half the width of a phone while emulating a phone width (Apple Watches can be instructed not to do this with a proprietary `meta` tag). Of course, making sites watch-compatible is a stretch, but support for feature phones running KaiOS should be reasonable. I wrote about this more in <cite>[Best practices for inclusive textual websites](https://seirdy.one/posts/2020/11/23/website-best-practices/)</cite>.
Another thing worth remembering is that users can change default fonts or override sire-set fonts. Don't just test with default default fonts; test with something wider. These criteria should specify some font metrics or (royalty free) representative wide fonts to use for testing.

2
content/notes/signal-security.md
View file

@ -2,7 +2,7 @@
title: "Signal security"
date: 2022-05-26T12:18:24-07:00
lastMod: 2022-05-26T12:18:24-07:00
replyURI: "https://web.archive.org/web/20220620162305/https://disqordia.space/notice/AJqmgRLFlyVENIXcDA"
replyURI: "https://disqordia.space/notice/AJqmgRLFlyVENIXcDA"
replyTitle: "europe wants to ban signal"
replyType: "SocialMediaPosting"
replyAuthor: "chjara"

2
content/posts/floss-security.gmi
View file

@ -123,7 +123,7 @@ It enumerates plenty of information about Zoom without access to its source code
To try this out yourself, use a sandbox designed for dynamic analysis. Cuckoo is a common and easy-to-use solution, while DRAKVUF is more advanced.
=> https://github.com/cuckoosandbox Cuckoo Sandbox: automated malware analysis
=> https://cuckoosandbox.org/ Cuckoo Sandbox: automated malware analysis
=> https://drakvuf.com/ DRAKVUF® Black-box Binary Analysis System
### Extreme example: the truth about Intel ME and AMT

2
content/posts/floss-security.md
View file

@ -132,7 +132,7 @@ Decompilers are seldom used alone in this context. Instead, they're typically a
These reverse-engineering techniques---a combination of tracing, packet sniffing, binary analysis, and memory dumps---make up the workings of most modern malware analysis. See [this example](https://www.hybrid-analysis.com/sample/1ef3b7e9ba5f486afe53fcbd71f69c3f9a01813f35732222f64c0981a0906429/5e428f69c88e9e64c33afe64) of a fully-automated analysis of the Zoom Windows installer. It enumerates plenty of information about Zoom without access to its source code: reading unique machine information, anti-VM and anti-reverse-engineering tricks, reading config files, various types of network access, scanning mounted volumes, and more.
To try this out yourself, use a sandbox designed for dynamic analysis. [Cuckoo](https://github.com/cuckoosandbox) is a common and easy-to-use solution, while [DRAKVUF](https://drakvuf.com/) is more advanced.
To try this out yourself, use a sandbox designed for dynamic analysis. [Cuckoo](https://cuckoosandbox.org/) is a common and easy-to-use solution, while [DRAKVUF](https://drakvuf.com/) is more advanced.
### Extreme example: the truth about Intel ME and AMT

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

@ -23,14 +23,10 @@ Restricted enhancement limits all enhancements to those that solve specific acce
I'd like to re-iterate yet another time that this only applies to websites that primarily focus on text. If graphics, interactivity, etc. are an important part of your website, less of the article applies. My hope is for readers to consider a subset of this page the next time they build a website, and address the trade-offs they make when they deviate. I don't expect--or want--anybody to follow all of my advice, because doing so would make the Web quite a boring place!
I'll cite the Web Accessibility Initiative's (WAI) "Techniques for WCAG 2.2" a number of times:
=> https://www.w3.org/WAI/WCAG22/Techniques/ Techniques for WCAG 2.2
Each "Success Criterion" (requirement) of the WCAG has possible techniques. Unlike the Web Content Accessibility Guidelines (WCAG), the Techniques document does not list requirements; rather, it serves to non-exhaustively educate authors about *how* to use specific technologies to comply with the WCAG. I don't find much utility in the technology-agnostic goals enumerated by the WCAG without the accompanying technology-specific techniques to meet those goals.
I'll also cite the WAI's "Making Content Usable for People with Cognitive and Learning Disabilities" document:
=> https://www.w3.org/TR/coga-usable/ "Making Content Usable for People with Cognitive and Learning Disabilities"
The document lists eight objectives. Each objective has associated personas, and can be met by several design patterns.
Unlike the Web Content Accessibility Guidelines (WCAG), the Techniques document does not list requirements; rather, it serves to non-exhaustively educate authors about *how* to use specific technologies to comply with the WCAG. I don't find much utility in the technology-agnostic goals enumerated by the WCAG without the accompanying technology-specific techniques to meet those goals.
Our goal: make a textual website maximally inclusive, using restricted enhancement.
@ -71,15 +67,15 @@ This is the CSP for my main website, with hashes removed for readability:
```
default-src 'none';
img-src 'self';
media-src 'self';
img-src 'self' data:;
style-src 'sha256-HASH';
style-src-attr 'none';
frame-ancestors 'none';
base-uri 'none';
form-action FORM_DESTS;
form-action 'none';
manifest-src 'self';
upgrade-insecure-requests;
sandbox allow-same-origin allow-forms
sandbox allow-same-origin
```
"default-src: 'none'" implies "script-src: 'none'", causing a compliant browser to forbid the loading of scripts. Furthermore, the "sandbox" CSP directive forbids a wide variety) of potentially insecure actions.
@ -160,7 +156,7 @@ The effect is especially pronounced on low-end phones and mechanical hard drives
One way to help browsers decide which disk-cached resources to prioritize is to use immutable assets. Include the `immutable` directive in your cache-control headers, and cache-bust modified assets by changing their URLs. You can also keep your asset counts low by combining textual assets (e.g. CSS) and inlining small resources.
I mark my website's assets as "immutable" and cache-bust them by including checksums in their filenames:
The only external assets on my pages are images and a web app manifest (for icons); I mark these assets as "immutable" and cache-bust them by including checksums in their filenames:
```
cache-control: max-age=31557600, immutable
@ -364,19 +360,18 @@ A similar image attribute that I *do* recommend is the "decoding" attribute. I t
=> https://developer.mozilla.org/en-US/docs/Web/HTML/Element/Img#attr-decoding <img> decoding on MDN
Long pages with many DOM nodes may benefit from CSS containment, a more recently-adopted part of the CSS specification.
Long pages with many DOM nodes may benefit from CSS containment, a more recently-adopted part of the CSS spec.
CSS containment allows authors to isolate sub-trees of the DOM. This lets browsers make more informed optimizations: they can delay painting off-screen content or reduce re-calculations when isolated nodes change. Combined with a property like "content-visibility", it enables browsers to defer all rendering of less essential below-the-fold content.
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 "content-visibility: 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 and "content-visibility" is a progressive enhancement, so there aren't any serious implications for older browsers. I use "content-visibility" to defer rendering off-screen entries in my archives. Doing so allows me to serve long archive pages instead of resorting to pagination, with page-length limited only by download size.
Leveraging containment is a progressive enhancement, so there aren't any serious implications for older browsers. I use it for long lists of posts in my archives, allowing browsers to skip rendering off-screen posts.
Using containment for content at the end of the page is relatively safe. Using it for content earlier in the page risks introducing layout shifts. Eliminate the layout shifts by calculating a value for the "contain-intrinsic-size" property. This is a comprehensive hide to calculating intrinsic size values, by Thijs Terluin of Teluin Webdesign:
=> https://www.terluinwebdesign.nl/en/css/calculating-contain-intrinsic-size-for-content-visibility/ Calculating 'contain-intrinsic-size' for 'content-visibility'
The benefits of containment are especially noticeable when injecting styles into a page. "Dark mode" extensions perform noticeably better when enough elements receive layout and paint containment.
=> https://www.terluinwebdesign.nl/en/css/calculating-contain-intrinsic-size-for-content-visibility/ Calculating 'contain-intrinsic-size' for 'content-visibility'
## In-page search
@ -447,7 +442,7 @@ Ultimately, surveillance self-defense on the web is an arms race full of trade-o
Browsers allow users to zoom by adjusting size metrics. Additionally, most browsers allow users to specify a minimum font size. Minimum sizes don't always work; setting size values in `px` can override these settings.
In your stylesheets, avoid using "px" where possible. Define sizes and dimensions using relative units (preferably "em"). Exceptions exist for rare items that that shouldn't scale with zoom (e.g. decoration, minimum margins).⁵ Set font size and line-spacing with a percentage and a unitless value, respectively:
In your stylesheets, avoid using "px" where possible. Define sizes and dimensions using relative units (preferably "em"). Exceptions exist for some decorations (e.g. borders),⁵ but they are uncommon. Set font size and line-spacing with a percentage and a unitless value, respectively:
```
font: 107.5%/1.5 sans-serif;
@ -465,7 +460,7 @@ Expect some readers to have images disabled or unloaded. Examples include:
Accordingly, follow good practices for alt-text:
* Concisely summarize the image content the best you can, without repeating the surrounding content.
* Images should usually have alt-text under 100 characters, excluding punctuation. Save longer descriptions for a caption or "aria-describedby". Exceptions exist; this is just a weak norm.
* Images should usually have alt-text under 100 characters, excluding punctuation. Save longer descriptions for a caption or "aria-describedby". Exceptions exist.
* 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:
@ -745,44 +740,24 @@ A basic WCAG Level A requirement is for information to not be conveyed solely th
### In defense of link underlines
Some typographers insist that underlined on-screen text is obsolete and hyperlinks are no exception.
=> https://practicaltypography.com/underlining.html Underlining | Butterick’s Practical Typography¹¹
I disagree. Readers already expect underlined text to signify a hyperlink. Don’t break fundamental affordances for aesthetics. Underlines are also necessary to distinguish the beginnings and ends of multiple consecutive links, especially among color-blind users.
I disagree. One reason is that underlines make it easy to separate multiple consecutive inline links:
It’s impossible to discern the number of links in a sequence without some sort of separator. Whitespace alone isn’t sufficient:
=> gemini://seirdy.one/misc/underlines.png A line of two consecutive hyperlinks with and without underlines
Moreover, several parts of "Making Content Usable for People with Cognitive and Learning Disabilities" recommend underlining links.
Underlines also make it easy for color-blind readers to distinguish both the beginnings and ends of links.
> Some users have trouble when controls have a different look, color, or shape than they have used before. For example, when links do not have underlines and blue or purple text some users will not know there is a link (even if this appears with focus).
=> https://www.w3.org/TR/coga-usable/#how-it-helps-3 "Making Content Usable for People with Cognitive and Learning Disabilities", section 4.2.5.3: Clearly Identify Controls and Their Use: How it Helps
Readers already expect underlined text to signify a hyperlink. Don't break fundamental affordances for aesthetics.
### Buttons versus links
Buttons are another type of interactive element. Users are accustomed to recognizing buttons by their visually distinct interactive region. While hyperlinks are only signified by color and a text underline, buttons are signified by a background-color change and/or a visible border. Do not conflate the two!
The purpose of a hyperlink is to navigate to a different location. If a button exists to do the same thing, it shouldn’t be a button; it should have both hyperlink semantics and presentation instead. Otherwise, the consequences of element activation are unclear.
The purpose of a hyperlink is specifically to navigate to a different location. If a button exists to do the same thing, it shouldn't be a button; it should have both hyperlink semantics and presentation instead. Otherwise, the consequences of element activation are unclear.
> Use a clear and recognizable design for controls. Make it clear what elements are controls and how to use them.
> This includes:
>
> Using a common style on controls (for example, links being underlined).
> Using common design patterns on links and controls (for example, clicking on a link takes you to the page).
> Making the borders of controls clear. Links in text do not need borders if identified properly (for example, a help icon has a border).
> Making controls large enough so that users can click on it and not the item next to it.
> Ensuring items that are not clickable do not look like links or controls.
>
> When this is not possible, provide instructions that explain how to use the control.
=> https://www.w3.org/TR/coga-usable/#what-to-do-3 Making Content Usable for People with Cognitive and Learning Disabilities, section 4.2.5.2: Clearly Identify Controls and Their Use: What to Do
One key difference between buttons and links is the cursor appearance. Buttons should not turn the cursor into a “hand” or “pointer” icon. This article covers both sides of the issue.
=> https://hidde.blog/some-pointers-on-default-cursors/ Some pointers on default cursors, by Hidde de Vries
Personally, I think it’s best to respect the convention of the browser and OS rather than break it.
### Visible non-interactive semantics
In addition to offering ample non-interactive space (see the prior "non-interactive space" section), ensure that non-interactive and interactive regions are visually distinct. Avoid making interactive elements with many children.
In addition to offering ample non-interactive space (see the prior "non-interactive space" section), ensure that non-interactive and interactive space regions are visually distinct. The backgrounds of regions containing multiple visible elements should be non-interactive.
GitHub's mobile website is a serious offender:
@ -809,7 +784,7 @@ Lossless or lossy JPEG compression. Note that JPEG is an inherently lossy format
The reference WebP encoder; has dedicated lossless and lossy modes. Lossy WebP compression isn't always better than JPEG, but lossless WebP consistently beats PNG.
=> https://github.com/AOMediaCodec/libavif avifenc (lossless or lossy), included in libavif
The reference AVIF encoder, included in libavif.¹² AVIF lossless compression is typically useless, but its lossy compression is pretty unique in that it leans towards detail removal rather than introducing compression artifacts. Note that AVIF is not supported by Safari or most WebKit-based browsers. It also seems unsupported in Microsoft Edge.
The reference AVIF encoder, included in libavif.¹² AVIF lossless compression is typically useless, but its lossy compression is pretty unique in that it leans towards detail removal rather than introducing compression artifacts. Note that AVIF is not supported by Safari or most WebKit-based browsers.
I put together a quick script to losslessly optimize images using these programs in my dotfile repo:
@ -937,9 +912,7 @@ The first or second heading in the DOM, and the highest heading level, should be
Remember that not all landmarks are announced by screen readers; for instance, many screen readers don't announce the ending of a <header> element in an article. An <hr> element is a good way to force the ending of a landmark to be visible: it introduces a thematic break between sections that is visible to assistive technologies and user-agents that don't support CSS.
Consider adding a "skip link" if some pages require many "Tab" keystrokes to reach the main content. Visually-impaired users generally prefer navigating by headings or landmarks, but screen reader beginners and motor-impaired users still benefit from a skip link. Skip links are especially helpful when pure heading- and landmark-based navigation isn't optimal.
Note: I say that a skip link is useful to reduce the amount of "Tab" keystrokes required, but I don't know a good "threshold number" to signify "too many keystrokes". If it takes ten keystrokes to reach the main content, you're probably overdue for a skip-link.
If this isn't possible, consider adding a "skip link" or two. Visually-impaired users generally prefer navigating by headings or landmarks, but screen reader beginners still benefit from a skip-link. Skip links are especially helpful when pure heading- and landmark-based navigation isn't optimal.
If your skip link toggles visibility states when focused, ensure that it doesn't move any existing content. If it appears over existing content, it needs to have a solid background; if you set the background color, set a foreground color too. See the "Layout shifts" and "About custom colors" sections for more details.
@ -1083,9 +1056,8 @@ Images do not reflow their text. When the viewport is narrower than the image di
1. Allow the image to exceed the viewport width, triggering two-dimensional scrolling for the whole page.
2. Shrink the image to fit the viewport, causing the text in the image to shrink with it.
3. Allow the image to horizontally overflow.
I already covered the first option in the prior subsection. If you expect viewers to read the text in the image and you don't link an image transcript, the second option isn't ideal. Overflow is almost never what we want.
I already covered the first option in the prior subsection. If you expect viewers to read the text in the image and you don't link an image transcript, the second option isn't ideal.
The best compromise is to ensure that the image isn't too wide, and can support large text on a narrow viewport. Lines of text in images should contain as few characters as possible. For a good exmple, see the "In defense of link underlines" section.
@ -1117,8 +1089,6 @@ Small phones typically support display rotation. When phones switch to landscape
When filtering criteria on the Quickref Reference page, 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.
Ensure that the most important content is visible above the fold. On an article like this, that content would include the article title, site title, and information about where in the site you can find the article (a breadcrumbs list).
## Spacing
The previous "small viewports" section may tempt you to make your content as dense as possible. Please don't overdo it.
@ -1508,30 +1478,27 @@ There are tons of ways to read a page; authors typically cater only to the mains
* Screen readers
* Switch access
* Navigating with the "Tab" key
* Caret navigation
* Content extractors or "Reader Mode"
* Keyboard navigation, with the "Tab" key or caret navigation
* Navigating with hand-tremors
* Content extraction (e.g. "Reader Mode")
* Low-bandwidth connections
* Unreliable, lossy connections
* Metered connections
* Hostile networks
* Using in-page search
* Downloading offline copies
* Extra-narrow viewports
* Very narrow viewports (much narrower than a phablet)
* Mobile devices in landscape mode
* Frequent window-resizers (e.g. users of tiled-window setups)
* Printouts with rationed paper or ink (common in schools)
* Printouts, esp. when paper and ink are rationed (common in schools)
* Textual browsers
* Disabling JavaScript
* The Tor Browser's "Safest" mode
* Non-mainstream browser engines
* Browsing without stylesheets
* Stylesheet alteration, injection, or replacement
* Uncommon graphical browsers
* the Tor Browser (separate from "uncommon browsers" because of how "safest" mode is often incompatible with progressive enhancement and graceful degradation)
* Disabling JavaScript (overlaps with the Tor Browser)
* Non-default color palettes
* Forced color palettes
* Adblockers, with a variety of filter-lists
* Blocking third-parties, frames, images, and cookies
* Aggressive content blocking (e.g. blocking all third-party content, frames, images, and cookies)
* User-selected custom fonts
* Stylesheet removal, alteration, or replacement
* Machine translators
Each of these may be dismissed as a "niche", especially given a profit motive (or worse, a growth imperative). Yet *many niches add up to a large population.* Every person who grows old becomes disabled; every long-distance traveller experiences poor connections.
@ -1613,11 +1580,6 @@ A special thanks goes out to GothAlice for the questions she answered in #webdev
² Some addons will have reduced functionality; for instance, Tridactyl can't create an <iframe> for its command window. I consider this to be worthwhile since the most important functionality is still available, and because authors shouldn't feel compelled to support security weakening. I say this as someone who uses Tridactyl often.
=> https://github.com/tridactyl/tridactyl Tridactyl
Moreover, the "sandbox" directive exposes some bugs in WebKit (i.e. Safari and most GTK-based browsers). On content governed by a "sandbox" directive without the "allow-same origin" and "allow-scripts" directives, some WebKit browser features won't work. One example is media controls. One page on my site has an "audio" element; I added "allow-scripts" to that page so it will work in WebKit-based browsers.
=> https://bugs.webkit.org/show_bug.cgi?id=237281 WebKit bug 237281 documents the general issue
=> https://bugs.webkit.org/show_bug.cgi?id=225865 WebKit bug 225865 documents the broken media player
=> https://bugs.webkit.org/show_bug.cgi?id=218086 WebKit bug 218086 documents broken event listeners
³ Here's an overview of PE and my favorite write-up on the subject.
=> https://en.wikipedia.org/wiki/Progressive_enhancement Progressive Enhancement (Wikipedia)
=> https://web.archive.org/web/20220316060312/https://whalecoiner.com/articles/progressive-enhancement Yes, progressive enhancement is a fucking moral argument

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

@ -51,9 +51,7 @@ Another focus is minimalism. [Progressive enhancement](https://en.wikipedia.org/
I'd like to re-iterate yet another time that this only applies to websites that primarily focus on text. If graphics, interactivity, etc. are an important part of your website, less of the article applies. My hope is for readers to consider a subset of this page the next time they build a website, and _address the trade-offs they make when they deviate._ I don't expect---or want---anybody to follow all of my advice, because doing so would make the Web quite a boring place!
I'll cite the Web Accessibility Initiative's (<abbr title="Web Accessibility Initiative">WAI</abbr>) {{<mention-work itemprop="citation" itemtype="TechArticle">}}{{<cited-work name="Techniques for WCAG 2.2" url="https://www.w3.org/WAI/WCAG22/Techniques/">}}{{</mention-work>}} a number of times. Each "Success Criterion" (requirement) of the WCAG has possible techniques. Unlike the <cite>Web Content Accessibility Guidelines</cite> (<abbr title="Web Content Accessibility Guidelines">WCAG</abbr>), the Techniques document does not list requirements; rather, it serves to non-exhaustively educate authors about _how_ to use specific technologies to comply with the WCAG. I don't find much utility in the technology-agnostic goals enumerated by the WCAG without the accompanying technology-specific techniques to meet those goals.
I'll also cite {{<mention-work itemid="https://www.w3.org/TR/coga-usable/" itemprop="citation" itemtype="TechArticle">}}{{<cited-work name="Making Content Usable for People with Cognitive and Learning Disabilities" url="https://www.w3.org/TR/coga-usable/">}}, by <span itemscope="" itemtype="https://schema.org/Organization" itemprop="publisher">the WAI</span>{{</mention-work>}}. The document lists eight objectives. Each objective has associated personas, and can be met by several design patterns.
I'll cite the Web Accessibility Initiative's (<abbr title="Web Accessibility Initiative">WAI</abbr>) <cite>[Techniques for WCAG&nbsp;2.2](https://www.w3.org/WAI/WCAG22/Techniques/)</cite> a number of times. Unlike the <cite>Web Content Accessibility Guidelines</cite> (<abbr title="Web Content Accessibility Guidelines">WCAG</abbr>), the Techniques document does not list requirements; rather, it serves to non-exhaustively educate authors about _how_ to use specific technologies to comply with the WCAG. I don't find much utility in the technology-agnostic goals enumerated by the WCAG without the accompanying technology-specific techniques to meet those goals.
Our goal: make a textual website maximally inclusive, using restricted enhancement.
@ -82,15 +80,14 @@ JavaScript and WebAssembly are responsible for the bulk of modern web exploits.
```figure {samp=true var1="HASH"}
default-src 'none';
img-src 'self';
media-src 'self';
img-src 'self' data:;
style-src 'sha256-HASH';
frame-ancestors 'none';
base-uri 'none';
form-action FORM_DESTS;
form-action 'none';
manifest-src 'self';
upgrade-insecure-requests;
sandbox allow-same-origin allow-forms
sandbox allow-same-origin
```
{{</codefigure>}}
@ -168,7 +165,7 @@ Requesting a high number of cached resources can decrease performance of the cac
One way to help browsers decide which disk-cached resources to prioritize is to use immutable assets. Include the `immutable` directive in your `cache-control` headers, and cache-bust modified assets by changing their URLs. You can also keep your asset counts low by combining textual assets (e.g. CSS) and inlining small resources.
{{<codefigure>}} {{< codecaption >}} I mark my website's assets as "immutable" and cache-bust them by including checksums in their filenames. {{< /codecaption >}}
{{<codefigure>}} {{< codecaption >}} The only external assets on my pages are images and a web app manifest (for icons); I mark these assets as "immutable" and cache-bust them by including checksums in their filenames. {{< /codecaption >}}
```figure {samp=true}
cache-control: max-age=31557600, immutable
@ -350,7 +347,6 @@ Moreover, determining the pages to prioritize for speculative pre-loading typica
I have two responses:
1. If an image isn't essential, don't include it in the page. If an image is essential, assume sighted users want to see it.
2. Yes, users could disable images. That's _their_ choice. If your page uses lazy loading, you've effectively (and probably unintentionally) made that choice for a large number of users.
Nonetheless, expect some readers to have images disabled. Refer to [the "Beyond alt-text" section](#beyond-alt-text) to see how to best support this case.
@ -403,9 +399,9 @@ Deferring network requests is a bad idea, but there are other ways to improve la
A similar image attribute that I _do_ recommend is the [`decoding` attribute](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/Img#attr-decoding). I typically use `decoding="async"` so that image decoding can be deferred.
Long pages with many DOM nodes may benefit from CSS containment, a more recently-adopted part of the CSS specification.[^10]
Long pages with many DOM nodes may benefit from CSS containment, a more recently-adopted part of the CSS spec.
<dfn>CSS containment</dfn> allows authors to isolate sub-trees of the DOM. This lets browsers make more informed optimizations: they can delay painting off-screen content or reduce re-calculations when isolated nodes change. Combined with a property like `content-visibility`, it enables browsers to defer all rendering of less essential below-the-fold content.
<dfn>CSS containment</dfn> 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:
{{<quotation>}}
@ -420,7 +416,7 @@ Long pages with many DOM nodes may benefit from CSS containment, a more recently
{{< /quotecaption >}}
{{</quotation>}}
Leveraging containment and `content-visibility` is a progressive enhancement, so there aren't any serious implications for older browsers. I use `content-visibility` to defer rendering off-screen entries in my archives. Doing so allows me to serve long archive pages instead of resorting to pagination, with page-length limited only by download size.
Leveraging containment is a progressive enhancement, so there aren't any serious implications for older browsers. I use it for long lists of posts in my archives, allowing browsers to skip rendering off-screen posts.
Using containment for content at the end of the page is relatively safe. Using it for content earlier in the page risks introducing [layout shifts](#layout-shifts). Eliminate the layout shifts by calculating a value for the `contain-intrinsic-size` property. {{<mention-work itemtype="TechArticle">}}{{<cited-work url="https://www.terluinwebdesign.nl/en/css/calculating-contain-intrinsic-size-for-content-visibility/" name="Calculating 'contain-intrinsic-size' for 'content-visibility'" extraName="headline">}}, by {{<indieweb-person first-name="Thijs" last-name="Terluin" url="https://www.terluinwebdesign.nl/en/about-us/thijs-terluin/" org="Teluin Webdesign" org-url="https://www.terluinwebdesign.nl/en/" itemprop="author">}}{{</mention-work>}}, is a comprehensive guide to calculating intrinsic size values.
@ -433,9 +429,7 @@ Searchability is a good reason to prefer conveying information textually, when p
Web pages that hide content behind "show content" widgets are difficult to search through: users need to toggle "show content" for each item they wish to search. Often, in-page search highlights are hidden; [Reddit's atrocious redesign](#reddit-redesign) is a serious offender. If you need to hide some content for performance reasons, I described a less hostile way to do so in [the "other ways to defer content" section](#other-ways-to-defer-content).
{{<image-figure id="reddit-redesign">}}
{{<picture name="find" alt="screenshots before/after clicking a \"see more\" link obscuring a search match.">}}
{{<image-figure id="reddit-redesign">}} {{<picture name="find" alt="screenshots before/after clicking a \"see more\" link obscuring a search match.">}}
<figcaption itemprop="caption">
@ -452,7 +446,7 @@ Moreover, some search implementations (such as the one built into Firefox) suppo
### Problematic overrides {#problematic-overrides}
Search is so essential to some users' ability to navigate that some desktop users enable "type-ahead" search, to automatically begin a search upon typing multiple characters.[^11] If you ignored my advice to avoid JavaScript, at least think twice before using it to define custom keyboard shortcuts which interfere with this type of functionality. I singled out type-ahead search, but there are countless other examples of uncommon keyboard behavior that JavaScript overrides interfere with.
Search is so essential to some users' ability to navigate that some desktop users enable "type-ahead" search, to automatically begin a search upon typing multiple characters.[^10] If you ignored my advice to avoid JavaScript, at least think twice before using it to define custom keyboard shortcuts which interfere with this type of functionality. I singled out type-ahead search, but there are countless other examples of uncommon keyboard behavior that JavaScript overrides interfere with.
Another problematic override is scroll-behavior. Enforcing smooth-scrolling (e.g., with the `scroll-behavior` CSS property) can interfere with the use of in-page search by slowing down jumps between matches. Rapidly darting around the page with smooth scrolling can cause motion sickness. Simply relying on users to override default behaviors violates the "inclusive by default" directive I encourage, since user preferences are fingerprintable and shift responsibility away from developers.
@ -485,7 +479,7 @@ Some people raised fingerprinting concerns when I suggested using the default "s
You can't do font enumeration or accurately calculate font metrics without JavaScript. Since text-based websites that follow these best-practices don't send requests after the page loads and have no scripts, they shouldn't be able to fingerprint via font identification.
Other websites can still fingerprint via font enumeration using JavaScript. They don't need to stop at seeing what sans-serif maps to: they can see available fonts on a user's system,[^12] the user's canvas fingerprint, window dimensions, etc. Some of these can be mitigated by [Firefox's protections against fingerprinting](https://support.mozilla.org/en-US/kb/firefox-protection-against-fingerprinting), but these protections understandably override user font preferences.
Other websites can still fingerprint via font enumeration using JavaScript. They don't need to stop at seeing what sans-serif maps to: they can see available fonts on a user's system,[^11] the user's canvas fingerprint, window dimensions, etc. Some of these can be mitigated by [Firefox's protections against fingerprinting](https://support.mozilla.org/en-US/kb/firefox-protection-against-fingerprinting), but these protections understandably override user font preferences.
Ultimately, surveillance self-defense on the web is an arms race full of trade-offs. If you want both privacy and customizability, the web is not the place to look; try Gemini or Gopher instead.
@ -493,7 +487,7 @@ Ultimately, surveillance self-defense on the web is an arms race full of trade-o
Browsers allow users to zoom by adjusting size metrics. Additionally, most browsers allow users to specify a minimum font size. Minimum sizes don't always work; setting size values in `px` can override these settings.
In your stylesheets, avoid using `px` where possible. Define sizes and dimensions using relative units (preferably `em`). Exceptions exist for rare items that that shouldn't scale with zoom (e.g. decoration, minimum margins).[^13]
In your stylesheets, avoid using `px` where possible. Define sizes and dimensions using relative units (preferably `em`). Exceptions exist for some decorations (e.g. borders),[^12] but they are uncommon.
{{<codefigure>}} {{< codecaption lang="CSS" >}}
@ -514,7 +508,7 @@ Expect some readers to have images disabled or unloaded. Examples include:
* Blind readers.
* Users with metered connections: sometimes they disable all images, and other times they only disable images surpassing a size.[^14]
* Users with metered connections: sometimes they disable all images, and other times they only disable images surpassing a size.[^13]
* People experiencing packet loss who fail to download some images.
@ -524,13 +518,13 @@ Accordingly, follow good practices for alt-text:
* Concisely summarize the image content the best you can, without repeating the surrounding content.
* Images should usually have alt-text under 100 ch.[^15] Save longer descriptions for a caption or <code>aria-<wbr />describedby</code>. Exceptions exist; this is just a weak norm.
* Images should usually have alt-text under 100 ch.[^14] Save longer descriptions for a caption or <code>aria-<wbr />describedby</code>. Exceptions exist.
* 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.
Alt text isn't just for blind readers; sighted readers who can't load an image will see alt-text in its place. This alt text might be confined to the image container, so small images should have shorter alt text.[^16]
Alt text isn't just for blind readers; sighted readers who can't load an image will see alt-text in its place. This alt text might be confined to the image container, so small images should have shorter alt text.[^15]
### Putting images in context
@ -600,7 +594,7 @@ A <dfn>`longdesc`</dfn> attribute used to be another way to reference an image t
The recommended way to link to a transcript is by hyperlinking the image (i.e., wrapping it with `<a>`) or semantically grouping the image with its transcript. Put a short summary in the alt-text, and mention the availability of a transcript in a visible caption.
A [StackOverflow thread about comic transcripts](https://stackoverflow.com/questions/65564539/what-is-the-semantically-correct-way-to-include-transcript-from-a-comic) outlines a good approach to semantically grouping images and transcripts, and my approach is similar. I group an image, alt-text, and caption in a `<figure>` element and follow it with a transcript in a `<details>` element. I use <code>aria-<wbr />describedby</code> to semantically link the figure and the transcript.[^17]
A [StackOverflow thread about comic transcripts](https://stackoverflow.com/questions/65564539/what-is-the-semantically-correct-way-to-include-transcript-from-a-comic) outlines a good approach to semantically grouping images and transcripts, and my approach is similar. I group an image, alt-text, and caption in a `<figure>` element and follow it with a transcript in a `<details>` element. I use <code>aria-<wbr />describedby</code> to semantically link the figure and the transcript.[^16]
An image, alt-text, figure caption, and transcript combine to form a complex relationship that should be grouped together in a single landmark. I put all three inside a `<section>` with a heading, and give the group an `aria-label` that indicates the presence of the three sub-elements. Using a `section` landmark ensures that the figure and caption remain together as a single unit. The [html code](#xkcd-html) for the [xkcd comic earlier in the page](#infinite-scrolling) is a representative example.
@ -684,7 +678,7 @@ Even if you set custom colors, ensure that the page is compatible with color ove
[This page's canonical location](https://seirdy.one/posts/2020/11/23/website-best-practices/) is an example application of Technique C25 (and the related [Technique G148](https://www.w3.org/WAI/WCAG22/Techniques/general/G148)). It only uses non-default colors when a user agent requests a dark color scheme (using the `prefers-color-scheme` CSS media query; see the next subsection) and for lightening borders. Any image with a solid background may match the page background; to ensure that their dimensions are clear, I surrounded them with borders. Most browsers will render these borders with the default foreground color, which should be visually distinct from the background. I included borders and/or horizontal rules to break up some sections, since heading-based delineation is either unavailable or insufficient for them. When overriding color schemes, the page layout remains clear.
Color overrides go well beyond simple foreground and background color changes. Windows High Contrast Mode (<abbr title="Windows High Contrast Mode">WHCM</abbr>) is perhaps the best example. [WHCM makes advanced modifications to color palettes](#win-hcm): it colors elements with a user-specified palette, all according to semantic markup while ignoring ARIA overrides.[^18]
Color overrides go well beyond simple foreground and background color changes. Windows High Contrast Mode (<abbr title="Windows High Contrast Mode">WHCM</abbr>) is perhaps the best example. [WHCM makes advanced modifications to color palettes](#win-hcm): it colors elements with a user-specified palette, all according to semantic markup while ignoring ARIA overrides.[^17]
<abbr title="Windows High Contrast Mode">WHCM</abbr> leads the standardization process for the `forced-colors` CSS media feature, but it isn't the only implementation of the underlying idea. If you navigate to <samp>about:preferences</samp> in Firefox and activate the <samp translate="yes">Colors</samp> button in the "Language and Appearance" section, you'll be presented with the option to override website palettes with [your own default colors](#default-colors).
@ -768,7 +762,7 @@ Accounting for halation, overstimulation, and high-contrast needs is hard to do
Color palettes need to be effective for different types of vision deficiencies (e.g. color blindnesses) and screens. Color blindness is a far more nuanced topic than "the inability to see some colors". {{<mention-work itemprop="citation" itemtype="BlogPosting">}}{{<indieweb-person itemprop="author" first-name="Rob" last-name="Pike" url="http://herpolhode.com/rob/">}} describes his experience in {{<cited-work name="Color blindness" extraName="headline" url="https://commandcenter.blogspot.com/2020/09/color-blindness-is-inaccurate-term.html">}}{{</mention-work>}}. Color blindness manifests in complex ways. Testing in grayscale is a great start, but it doesn't account for all kinds of color vision deficiencies.
Different screens and display-calibrations render color differently; what may look like a light-gray on a cheap monitor could look nearly black on a high-end OLED screen. Try to test on both high- and low-end displays, especially when designing a dark color scheme.[^19]
Different screens and display-calibrations render color differently; what may look like a light-gray on a cheap monitor could look nearly black on a high-end OLED screen. Try to test on both high- and low-end displays, especially when designing a dark color scheme.[^18]
Color schemes should also look good to users who apply gamma adjustments. Most operating systems and desktop environments bundle a feature to reduce the screen color temperature at night, while some individuals may select a higher one in the morning.
@ -788,9 +782,9 @@ Visible interactive semantics
A basic WCAG Level A requirement is for information to not be conveyed solely through color. Bothe the presence and type of interactivity need to be visually communicated by other means. Links should not look like buttons, and vice-versa.
### In defense of link underlines
### In defense of link underlines {#in-defense-of-link-underlines}
Some typographers insist that [underlined on-screen text is obsolete](https://practicaltypography.com/underlining.html),[^20] and that hyperlinks are no exception. I disagree.
Some typographers insist that [underlined on-screen text is obsolete](https://practicaltypography.com/underlining.html),[^19] and that hyperlinks are no exception. I disagree.
Readers already expect underlined text to signify a hyperlink. Don't break fundamental affordances for aesthetics. Underlines are also necessary to distinguish the beginnings and ends of multiple consecutive links, especially among color-blind users.
@ -803,55 +797,13 @@ It's impossible to discern the number of links in a sequence without some sort o
</figcaption>
{{</image-figure>}}
Moreover, several parts of {{<mention-work itemid="https://www.w3.org/TR/coga-usable/" itemprop="citation" itemtype="TechArticle">}}{{<cited-work name="Making Content Usable for People with Cognitive and Learning Disabilities" url="https://www.w3.org/TR/coga-usable/">}}{{</mention-work>}} recommend underlining links.
{{<quotation>}}
<blockquote itemprop="text">
Some users have trouble when controls have a different look, color, or shape than they have used before. For example, when links do not have underlines and blue or purple text some users will not know there is a link (even if this appears with focus).
</blockquote>
{{< quotecaption partOfType="TechArticle" >}}
<cite itemprop="name headline">Making Content Usable for People with Cognitive and Learning Disabilities</cite>, section 4.2.5.3:
<a href="https://www.w3.org/TR/coga-usable/#how-it-helps-3">Clearly Identify Controls and Their Use: How it Helps</a>
{{< /quotecaption >}}
{{</quotation>}}
### Buttons versus links
Buttons are another type of interactive element. Users are accustomed to recognizing buttons by their visually distinct interactive region. While hyperlinks are only signified by color and a text underline, buttons are signified by a background-color change and/or a visible border. Do not conflate the two!
The purpose of a hyperlink is to navigate to a different location. If a button exists to do the same thing, it shouldn't be a button; it should have both hyperlink semantics and presentation instead. Otherwise, the consequences of element activation are unclear.
The purpose of a hyperlink is specifically to navigate to a different location. If a button exists to do the same thing, it shouldn't be a button; it should have both hyperlink semantics and presentation instead. Otherwise, the consequences of element activation are unclear.
{{<quotation>}}
<blockquote itemprop="text">
Use a clear and recognizable design for controls. Make it clear what elements are controls and how to use them.
This includes:
- Using a common style on controls (for example, links being underlined).
- Using common design patterns on links and controls (for example, clicking on a link takes you to the page).
- Making the borders of controls clear. Links in text do not need borders if identified properly (for example, a help icon has a border).
- Making controls large enough so that users can click on it and not the item next to it.
- Ensuring items that are not clickable do not look like links or controls.
When this is not possible, provide instructions that explain how to use the control.
</blockquote>
{{< quotecaption partOfType="TechArticle" >}}
<cite itemprop="name headline">Making Content Usable for People with Cognitive and Learning Disabilities</cite>, section 4.2.5.2:
<a href="https://www.w3.org/TR/coga-usable/#what-to-do-3">Clearly Identify Controls and Their Use: What to Do</a>
{{< /quotecaption >}}
{{</quotation>}}
One key difference between buttons and links is the cursor appearance. Buttons should not turn the cursor into a "hand" or "pointer" icon. The article {{<mention-work itemtype="BlogPosting" itemprop="citation" role="doc-credit">}}{{<cited-work url="https://hidde.blog/some-pointers-on-default-cursors/" name="Some pointers on default cursors" extraName="headline">}} by {{<indieweb-person itemprop="author" name="Hidde de Vries" url="https://hidde.blog/about-me/">}}{{</mention-work>}} covers both sides of the issue. Personally, I think it's best to respect the convention of the browser and OS rather than break it.
### Visible non-interactive semantics
In addition to [offering ample non-interactive space](#non-interactive-space), ensure that non-interactive and interactive regions are visually distinct. Avoid making interactive elements with many children.
In addition to [offering ample non-interactive space](#non-interactive-space), ensure that non-interactive and interactive space regions are visually distinct. The backgrounds of regions containing multiple visible elements should be non-interactive.
GitHub's mobile website is a serious offender; see [this screenshot of the GitHub bug tracker](#gh-interactive) for an example. The background region of the visible issue is interactive, and so are its contents. However, the header of the issues list has a non-interactive background that looks the same. Visual appearance does not convey the difference between a button and a hyperlink. The "enhancement" link points to a unique location, yet it loses its interactivity on narrow viewports with no visual change; tapping it navigates to a different location depending on viewport width.
@ -883,7 +835,7 @@ Some image optimization tools I use:
: The reference WebP encoder; has dedicated lossless and lossy modes. Lossy WebP compression isn't always better than JPEG, but lossless WebP consistently beats PNG.
`avifenc`
: The reference AVIF encoder, included in [libavif](https://github.com/AOMediaCodec/libavif).[^21] AVIF lossless compression is typically useless, but its lossy compression is pretty unique in that it leans towards detail removal rather than introducing compression artifacts. Note that AVIF is not supported by Safari or most WebKit-based browsers. It also seems unsupported in Microsoft Edge.[^22]
: The reference AVIF encoder, included in [libavif](https://github.com/AOMediaCodec/libavif).[^20] AVIF lossless compression is typically useless, but its lossy compression is pretty unique in that it leans towards detail removal rather than introducing compression artifacts. Note that AVIF is not supported by Safari or most WebKit-based browsers.
I put together [a quick script](https://git.sr.ht/~seirdy/dotfiles/tree/3b722a843f3945a1bdf98672e09786f0213ec6f6/Executables/shell-scripts/bin/optimize-image) to losslessly optimize images using these programs. For lossy compression, I typically use [GNU Parallel](https://www.gnu.org/software/parallel/) to mass-generate images using different options before selecting the smallest image at the minimum acceptable quality. Users who'd rather avoid the command line while performing lossy compression can instead check out [Squoosh](https://squoosh.app/), a JavaScript app that bundles Web&shy;Assembly-compiled encoders; I've heard good things about it.
@ -892,18 +844,12 @@ You also might want to use the HTML `<picture>` element, using JPEG/PNG as a fal
Most of my images will probably be screenshots that start as PNGs. My typical flow:
1. Re-size and crop the PNG. Convert to grayscale if color isn't important.
2. Lossy compression with `pngquant`
3. Losslessly optimize the result with `oxipng` and its Zopfli backend (slow)
4. Also create a lossless WebP from the lossy PNG and a lossy WebP from the source image, using `cwebp`. Pick the smaller of the two.
5. Include the resulting WebP in the page, with a fallback to the PNG using a `<picture>` element.
6. Create a lossy AVIF image from the cropped full-color PNG, and include it in the `<picture>` element if it's smaller than the WebP. If color isn't important, use the YUV400 color space.
7. If the image is too light, repeat for a dark version of the image to display in response to a `prefers-color-scheme: dark` media query.
7. If the image is too light, repeat for a dark version of the image to display according to a `prefers-color-scheme: dark` media query.
In general, avoid loading images just for decoration. Only use an image if it has a clear purpose that significantly adds to the content in a way that text can't replace, and provide alt-text as a fallback. Any level of detail that isn't necessary for getting the point across should be removed by lossy compression and cropping.
@ -937,7 +883,6 @@ Most resources on image optimization recommend considering progressive rendering
These resources also encourage authors to include different image variants for different viewport sizes, screen resolutions, and pixel densities. They often skip the caveats:
* Using different image files for different viewport sizes can cause the page to request more images as users re-size their window.
* Sending requests dependent on viewport and display characteristics is a fingerprinting vector, allowing servers to identify users by these properties.
Rather than create separate lanes for different users, I prefer making the defaults as inclusive as possible. A single image should look good under a variety of downscaling algorithms. It should be as small as it can be without losing essential information.
@ -1001,7 +946,7 @@ The first or second heading in the DOM, and the highest heading level, should be
Remember that not all landmarks are announced by screen readers; for instance, many screen readers don't announce the ending of a `<header>` element in an article. An `<hr>` element is a good way to force the ending of a landmark to be visible: it introduces a thematic break between sections that is visible to assistive technologies and user-agents that don't support CSS.
Consider adding a "skip link" if some pages require many <kbd>Tab</kbd> keystrokes to reach the main content.[^23] Visually-impaired users generally prefer navigating by headings or landmarks, but screen reader beginners and motor-impaired users still benefit from a skip link. Skip links are especially helpful when pure heading- and landmark-based navigation isn't optimal.
If this isn't possible, consider adding a "skip link" or two. Visually-impaired users generally prefer navigating by headings or landmarks, but screen reader beginners still benefit from a skip-link. Skip links are especially helpful when pure heading- and landmark-based navigation isn't optimal.
If your skip link toggles visibility states when focused, ensure that it doesn't move any existing content; see [the "Layout shifts" section](#layout-shifts) for more details. If it appears over existing content, it needs to have a solid background; if you set the background color, set a foreground color too as described in [the "About custom colors" section](#about-custom-colors).
@ -1011,7 +956,7 @@ Users of <abbr title="assistive technology">AT</abbr>s such as screen readers pr
Try using a tool to view a list of all your link names. Just about every screen reader and some browser extensions should offer this functionality. Minimize links with ambiguous names, and ensure that identical link names have identical destinations.
Think twice before placing important content immediately after skippable content such as nested landmarks, long code snippets, figures, and large lists. AT users who wish to skip content may jump directly to the next heading, glossing over anything between the skippable content and subsequent heading; this is especially common on mobile devices.[^24] When it makes sense to do so, place skippable content in its own sections and/or at the end of its parent section.
Think twice before placing important content immediately after skippable content such as nested landmarks, long code snippets, figures, and large lists. AT users who wish to skip content may jump directly to the next heading, glossing over anything between the skippable content and subsequent heading; this is especially common on mobile devices.[^21] When it makes sense to do so, place skippable content in its own sections and/or at the end of its parent section.
### Single-column layout
@ -1032,7 +977,6 @@ Exceptions exist: one or two very simple responsive changes won't hurt. The main
Sidebars are probably unnecessary, and can be quite annoying to readers who re-size windows frequently. This is especially true for tiling window manager users like me: we frequently shrink windows to a fraction of their original size. When this happens to a website with a sidebar, one of two things happens:
1. The site's responsive design kicks in: the sidebar vanishes and its elements move elsewhere. This can be quite CPU-heavy, as the browser has to both re-wrap the text and handle a complex layout change. Frequent window re-sizers will experience lag and battery loss, and might need a moment to figure out where everything went.
2. The site doesn't use responsive design. The navbar and main content are now squeezed together. Readers will probably close the page.
Neither situation looks great.
@ -1098,7 +1042,7 @@ Users employing machine translation will not benefit from your soft hyphens, so
Where long inline `<code>` elements can trigger horizontal scrolling, consider a scrollable `<pre>` element instead. Making a single element horizontally scrollable is far better than making the entire page scrollable in two dimensions. Hard-wrap code blocks so that they won't horizontally scroll in most widescreen desktop browsers.
Be sure to test your hyphens with NVDA or Windows Narrator: these screen readers' pronunciation of words can be disrupted by poorly-placed hyphens. Balancing the need to adapt to narrow screens against the need to sound correctly to a screen reader is a complex matter.[^25] The best place to insert a hyphen is between compound words. For example, splitting "Firefighter" into "Fire-fighter" is quite safe. Beyond that, try listening to hyphenated words in NVDA to ensure they remain clear.
Be sure to test your hyphens with NVDA or Windows Narrator: these screen readers' pronunciation of words can be disrupted by poorly-placed hyphens. Balancing the need to adapt to narrow screens against the need to sound correctly to a screen reader is a complex matter.[^22] The best place to insert a hyphen is between compound words. For example, splitting "Firefighter" into "Fire-fighter" is quite safe. Beyond that, try listening to hyphenated words in NVDA to ensure they remain clear.
### Keeping text together
@ -1110,13 +1054,12 @@ One exception to the rules from <cite>Practical Typography</cite>: don't use a n
You should only use pictures of text when the visual presentation of the text is part of the information you're trying to convey. Always be sure to test how such an image looks on a narrow screen.
Images do not reflow their text. When the viewport is narrower than the image dimensions, you can instruct the browser to do one of three things:
Images do not reflow their text. When the viewport is narrower than the image dimensions, two options arise:
1. Allow the image to exceed the viewport width, triggering two-dimensional scrolling for the whole page.
2. Shrink the image to fit the viewport, causing the text in the image to shrink with it.
3. Allow the image to horizontally overflow.
I already covered the first option in the prior subsection. If you expect viewers to read the text in the image and you don't link an image transcript, the second option isn't ideal. Overflow is almost never what we want.
I already covered the first option in the prior subsection. If you expect viewers to read the text in the image and you don't link an image transcript, the second option isn't ideal.
The best compromise is to ensure that the image isn't too wide, and can support large text on a narrow viewport. Lines of text in images should contain as few characters as possible. For a good example, see the "[In defense of link underlines](#in-defense-of-link-underlines)" section.
@ -1151,29 +1094,6 @@ When filtering criteria on [the Quickref Reference page](https://www.w3.org/WAI/
</figcaption>
{{</image-figure>}}
Keeping the most important content above the fold (the part of the page that's visible without scrolling) is hard on small screens. Nonetheless, it's an important element of cognitive accessibility. Users may struggle to identify a page or navigate a site if the title and navigation links are below the fold. [The <abbr title="Web Accessibility Initiative">WAI's</abbr> mobile accessibility guidelines](https://www.w3.org/TR/mobile-accessibility-mapping/#positioning-important-page-elements-before-the-page-scroll) share this recommendation.
{{<quotation>}}
<blockquote itemprop="text">
Make important tasks and features on the site stand out and easy to find.
This includes:
- \[…\]
- Placing the tasks/features towards the top of the page so the user does not have to scroll to see them.
- Placing the tasks/features toward the top of the content so assistive technology finds them quickly.
- \[…\]
- Including key tasks at a top level of the main navigation.
</blockquote>
{{< quotecaption partOfType="TechArticle" >}}
<cite itemprop="name headline">Making Content Usable for People with Cognitive and Learning Disabilities</cite>, section 4.3.1:
<a href="https://www.w3.org/TR/coga-usable/#what-to-do-6">Make it Easy to Find the Most Important Tasks and Features of the Site</a>
{{< /quotecaption >}}
{{</quotation>}}
Spacing
-------
@ -1358,7 +1278,7 @@ On one hand, users who need enhanced focus visibility may override the default f
The WCAG [Success Criterion 2.4.12](https://w3c.github.io/wcag/guidelines/22/#focus-appearance-enhanced) recommends making focus indicators 2&nbsp;px thick. While this success criterion is only AAA-level, it's easy enough to meet and beneficial enough to others that we should all meet it.
You can use `:focus` and `:focus-visible` to highlight selected and keyboard-focused elements, respectively. Take care to only alter styling, not behavior: only keyboard-focusable elements should receive outlines. Modern browser stylesheets use `:focus-visible` instead of `:focus`; old browsers only support `:focus` and re-style a subset of focusable elements. Your stylesheets should do the same, to match browser behavior.[^26]
You can use `:focus` and `:focus-visible` to highlight selected and keyboard-focused elements, respectively. Take care to only alter styling, not behavior: only keyboard-focusable elements should receive outlines. Modern browser stylesheets use `:focus-visible` instead of `:focus`; old browsers only support `:focus` and re-style a subset of focusable elements. Your stylesheets should do the same, to match browser behavior.[^23]
{{<codefigure>}}
@ -1436,7 +1356,7 @@ Screen readers on touch screen devices are also quite different from their deskt
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.[^27]
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.[^24]
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.
@ -1465,7 +1385,7 @@ No matter how simple a page is, I don't think simplicity eliminates the need for
Automated tests---especially accessibility tests---are a supplement to manual tests, not a replacement for them. Think of them as time-savers that bring up issues for further research, containing both false positives and false negatives.
These are the tools I use regularly. I've deliberately excluded tools that would be redundant.[^28]
These are the tools I use regularly. I've deliberately excluded tools that would be redundant.[^25]
[Nu HTML checker](https://validator.nu/)
@ -1478,7 +1398,7 @@ These are the tools I use regularly. I've deliberately excluded tools that would
: An auditing tool by Google that uses the DevTools protocol in any Chromium-based browser. Skip the "Access&shy;ibility" category, since it just runs a subset of axe-core's audits. The most useful audit is the tap target size check in its "SEO" category. Note that your `sandbox` CSP directive will need to include `allow-scripts` for it to function.
[Webhint](https://webhint.io/)
: Similar to Lighthouse. Again, you can ignore the accessibility audits if you already use axe-core. I personally disagree with some of its hints: the "unneeded HTTP headers" hint ignores the fact that the CSP can have an effect on non-hypertext assets, the "HTTP cache" hint has an unreasonable bias against caching HTML, and the "Correct `Content-Type` header" recommends charset attributes a bit too agg&shy;ressively.[^29]
: Similar to Lighthouse. Again, you can ignore the accessibility audits if you already use axe-core. I personally disagree with some of its hints: the "unneeded HTTP headers" hint ignores the fact that the CSP can have an effect on non-hypertext assets, the "HTTP cache" hint has an unreasonable bias against caching HTML, and the "Correct `Content-Type` header" recommends charset attributes a bit too agg&shy;ressively.[^26]
[IBM Equal Access Accessibility Checker](https://www.ibm.com/able/toolkit/verify/automated/)
: Has a scope similar to axe-core. Its "Sensory Characteristics" audit seems unique.
@ -1508,7 +1428,7 @@ These tests begin reasonably, but gradually grow absurd. Once again, use your ju
1. Test in all three major browser engines: Blink, Gecko, and WebKit.
2. Evaluate the heaviness and complexity of your scripts (if any) by testing with your browser's <abbr title="just-in-time">JIT</abbr> compilation disabled.[^30]
2. Evaluate the heaviness and complexity of your scripts (if any) by testing with your browser's <abbr title="just-in-time">JIT</abbr> compilation disabled.[^27]
3. Test using the Tor Browser's safest security level enabled (disables JS and other features).
@ -1536,7 +1456,7 @@ These tests begin reasonably, but gradually grow absurd. Once again, use your ju
15. Try printing out your page in black-and-white from an unorthodox graphical browser.
16. Download your webpage and test how multiple word processors render and generate PDFs from it.[^31]
16. Download your webpage and test how multiple word processors render and generate PDFs from it.[^28]
17. Combine conversion tools. Combine an HTML-<wbr />to-<wbr />EPUB converter and an EPUB-<wbr />to-<wbr />PDF converter, or stack multiple article-extraction utilities. Be creative and enjoy breaking your site. When something breaks, examine the breakage and see if it's caused by an issue in your markup, or a CSS feature with an equivalent alternative.
@ -1597,32 +1517,28 @@ There are so many ways to read a page; authors typically cater only to the mains
* Screen readers
* Switch access
* Navigating with the <kbd>Tab</kbd> key
* Caret navigation
* Keyboard navigation, with the <kbd>Tab</kbd> key or caret navigation
* Navigating with hand-tremors
* Content extractors or "Reader Mode"
* Content extraction (e.g. "Reader Mode")
* Low-bandwidth connections
* Unreliable, lossy connections
* Metered connections
* Hostile networks
* Using in-page search
* Downloading offline copies
* Extra-narrow viewports
* Very narrow viewports (much narrower than a phablet)
* Mobile devices in landscape mode
* Frequent viewport-resizers
* Printouts with rationed paper or ink
* Frequent window-resizers (e.g. users of tiled-window setups)
* Printouts, especially when paper and ink are rationed (common in schools)
* Textual browsers
* Disabling JavaScript
* The Tor Browser's "Safest" mode
* Non-mainstream browser engines
* Browsing without CSS
* Altering, injecting, or replacing CSS
* Uncommon graphical browsers
* the Tor Browser (separate from "uncommon browsers" because of how "safest" mode is often incompatible with progressive enhancement and graceful degradation)
* Disabling JavaScript (overlaps with the Tor Browser)
* Non-default color palettes
* Forced color palettes
* Adblockers, with a variety of filter-lists
* Blocking third-parties
* Disabling frames, images, and cookies
* Aggressive content blocking (e.g. blocking all third-party content, frames, images, and cookies)
* User-selected custom fonts
* Stylesheet removal, alteration, or replacement
* Machine translators
Each of these may be dismissed as a "niche", especially given a profit motive (or worse, a growth imperative). Yet _many niches add up to a large population._ Every person who grows old becomes disabled; every long-distance traveller experiences poor connections.
@ -1643,23 +1559,16 @@ Parts of this page can be thought of as an extension to David Copeland's princip
{{<quotation itemprop="mentions">}}
<blockquote itemprop="text">
Raw content true to its construction:
1. Content is readable on all reasonable screens and devices.
2. Only hyperlinks and buttons respond to clicks.
3. Hyperlinks are underlined and buttons look like buttons.
4. The back button works as expected.
5. View content by scrolling.
6. Decoration when needed and no unrelated content.
7. Perfor&shy;mance is a feature.
<p>Raw content true to its construction:</p>
<ol>
<li>Content is readable on all reasonable screens and devices.</li>
<li>Only hyperlinks and buttons respond to clicks.</li>
<li>Hyperlinks are underlined and buttons look like buttons.</li>
<li>The back button works as expected.</li>
<li>View content by scrolling.</li>
<li>Decoration when needed and no unrelated content.</li>
<li>Perform&shy;ance is a feature.</li>
</ol>
</blockquote>
{{< quotecaption partOfType="WebSite" >}}
{{<indieweb-person first-name="David" last-name="Copeland" url="https://naildrivin5.com/" itemprop="author">}},
@ -1696,8 +1605,6 @@ A special thanks goes out to GothAlice for the questions she answered in <samp>#
[^2]: Some addons will have reduced functionality; for instance, [Tridactyl](https://github.com/tridactyl/tridactyl) can't create an `<iframe>` for its command window. I consider this to be worthwhile since the most important functionality is still available, and because authors shouldn't feel compelled to support security weakening. I say this as someone who uses Tridactyl often.
Moreover, the `sandbox` directive exposes some bugs in WebKit (i.e. Safari and most GTK-based browsers). On content governed by a `sandbox` directive without the `allow-same origin` and `allow-scripts` directives, some WebKit browser features won't work. One example is media controls. One page on my site has an `audio` element; I added `allow-scripts` to that page so it will work in WebKit-based browsers. [WebKit bug 237281 documents the general issue](https://bugs.webkit.org/show_bug.cgi?id=237281); [WebKit bug 225865](https://bugs.webkit.org/show_bug.cgi?id=225865) and [WebKit bug 218086](https://bugs.webkit.org/show_bug.cgi?id=218086) document specific instances.
[^3]: Here's an [overview of PE](https://en.wikipedia.org/wiki/Progressive_enhancement) and [my favorite write-up on the subject](https://web.archive.org/web/20220316060312/https://whalecoiner.com/articles/progressive-enhancement).
[^4]: Each of these flows can be visually displayed using a breadcrumbs list; doing so can meet the WCAG [Success Criterion 2.4.8: Location](https://w3c.github.io/wcag/understanding/location.html). I opted to meet the criterion a different way. Since all my pages are linked by my site's global navigation or my "posts" page (also in the global navigation), I just used `aria-current` and made the currently-relevant entry in my global navigation a `<strong>` element.
@ -1714,51 +1621,45 @@ A special thanks goes out to GothAlice for the questions she answered in <samp>#
[^9]: Ironically, that page doesn't load the main text without JavaScript despite citing a JavaScript requirement as a downside. If you can't load the page, the same issues with infinte scroll are outlined in the "Accessibility concerns for infinite scroll" section of {{<mention-work itemprop="citation" itemtype="BlogPosting">}}{{<cited-work url="https://addyosmani.com/blog/infinite-scroll-without-layout-shifts/" name="Infinite Scroll without Layout Shifts" extraName="headline">}} by {{<indieweb-person itemprop="author" first-name="Addy" last-name="Osmani" url="https://addyosmani.com/">}}{{</mention-work>}}.
[^10]: The benefits of containment are especially noticeable when injecting styles into a page. "Dark mode" and "userstyle" extensions perform noticeably better when enough elements receive layout and paint containment. Containment allows browsers to handle changes to an element independently of the rest of the DOM.
[^10]: Firefox users [can enable "find as you type"](https://website-archive.mozilla.org/www.mozilla.org/access/access/type-ahead/) by toggling a preference in <samp>about:<wbr />config</samp>. Chromium (and derivatives) users can [install an extension](https://github.com/Foxy/chrome-type-ahead); note that it requires full-page access and performs script injection to work.
[^11]: Firefox users [can enable "find as you type"](https://website-archive.mozilla.org/www.mozilla.org/access/access/type-ahead/) by toggling a preference in <samp>about:<wbr />config</samp>. Chromium (and derivatives) users can [install an extension](https://github.com/Foxy/chrome-type-ahead); note that it requires full-page access and performs script injection to work.
[^11]: Iterating through a list of font names to see if each one is available on a user's system is a slow but effective way to determine installed fonts without being granted permission to use the Font Access API. [Browser&shy;Leaks has a demo](https://browserleaks.com/fonts) of this approach. Warning: the page might hog your CPU for a while.
[^12]: Iterating through a list of font names to see if each one is available on a user's system is a slow but effective way to determine installed fonts without being granted permission to use the Font Access API. [Browser&shy;Leaks has a demo](https://browserleaks.com/fonts) of this approach. Warning: the page might hog your CPU for a while.
[^12]: Decoration is more than cosmetic. The [color overrides and accessibility](#color-overrides-and-accessibility) sub-section describes how some decorations, like borders, improve access&shy;ibility.
[^13]: Decoration is more than cosmetic. The [color overrides and accessibility](#color-overrides-and-accessibility) sub-section describes how some decorations, like borders, improve access&shy;ibility.
[^13]: uBlock Origin is a popular browser extension for content filtering; it's the most popular Firefox add-on. It includes a built-in feature to block all media elements exceeding a user-configurable size threshold.
[^14]: uBlock Origin is a popular browser extension for content filtering; it's the most popular Firefox add-on. It includes a built-in feature to block all media elements exceeding a user-configurable size threshold.
[^14]: [WebAIM](https://wave.webaim.org/api/docs?format=html) and the [University of Illinois](https://fae.disability.illinois.edu/rulesets/IMAGE_4_EN/) recommend 100 characters; [Tangaru](https://www.tanaguru.com/en/) recommends an even smaller limit of 80 characters. I sometimes exceed 100 characters for detailed images but usually stay below 80.
[^15]: [WebAIM](https://wave.webaim.org/api/docs?format=html) and the [University of Illinois](https://fae.disability.illinois.edu/rulesets/IMAGE_4_EN/) recommend 100 characters; [Tangaru](https://www.tanaguru.com/en/) recommends an even smaller limit of 80 characters. I sometimes exceed 100 characters for detailed images but usually stay below 80.
[^15]: Browser support for displaying alt-text in place of broken images seems good. More information about support for alt-text exposure can be found on {{<mention-work itemtype="BlogPosting">}}{{<cited-work name="Alternative Text for CSS Generated Content" extraName="headline" url="https://adrianroselli.com/2020/10/alternative-text-for-css-generated-content.html">}}{{</mention-work>}}. That post seems to indicate that Firefox 81 on macOS 10.15 didn't display alt-text, but [users report correct alt-text display](https://cybre.space/@nleigh/108688070682694730) in more recent Firefox versions.
[^16]: Browser support for displaying alt-text in place of broken images seems good. More information about support for alt-text exposure can be found on {{<mention-work itemtype="BlogPosting">}}{{<cited-work name="Alternative Text for CSS Generated Content" extraName="headline" url="https://adrianroselli.com/2020/10/alternative-text-for-css-generated-content.html">}}{{</mention-work>}}. That post seems to indicate that Firefox 81 on macOS 10.15 didn't display alt-text, but [users report correct alt-text display](https://cybre.space/@nleigh/108688070682694730) in more recent Firefox versions.
[^16]: Once it gains basic support across all browsers and screen readers, I might recommend using `aria-details` instead of <code>aria-<wbr />describedby</code> for more complex descriptions. At the time of writing, [`aria-details` is only supported by JAWS](https://a11ysupport.io/tech/aria/aria-details_attribute). {{<mention-work itemtype="TechArticle">}}{{<cited-work name="WAI-ARIA 1.2" url="https://www.w3.org/TR/wai-aria-1.2/#aria-details">}}{{</mention-work>}} describes `aria-details` with an example similar to the one I gave in [code snippet 5](#xkcd-html).
[^17]: Once it gains basic support across all browsers and screen readers, I might recommend using `aria-details` instead of <code>aria-<wbr />describedby</code> for more complex descriptions. At the time of writing, [`aria-details` is only supported by JAWS](https://a11ysupport.io/tech/aria/aria-details_attribute). {{<mention-work itemtype="TechArticle">}}{{<cited-work name="WAI-ARIA 1.2" url="https://www.w3.org/TR/wai-aria-1.2/#aria-details">}}{{</mention-work>}} describes `aria-details` with an example similar to the one I gave in [code snippet 5](#xkcd-html).
[^17]: Since <abbr title="Windows High Contrast Mode">WHCM</abbr> sets colors independently of explicitly-defined ARIA roles, it's a good way to test adherence to [the First Rule of ARIA](#first-rule-of-aria).
[^18]: Since <abbr title="Windows High Contrast Mode">WHCM</abbr> sets colors independently of explicitly-defined ARIA roles, it's a good way to test adherence to [the First Rule of ARIA](#first-rule-of-aria).
[^18]: When making an earlier version of this site's dark-mode color palette, I made the mistake of exclusively testing in cheap or poorly-calibrated displays with bright black points. I mistakenly thought that my `#0b0b0b` background was bright enough to [prevent halation](#halation). Only after testing on a better screen did I realize that it would look almost completely black; I subsequently lightened the background to `#111` to strike a good balance.
[^19]: When making an earlier version of this site's dark-mode color palette, I made the mistake of exclusively testing in cheap or poorly-calibrated displays with bright black points. I mistakenly thought that my `#0b0b0b` background was bright enough to [prevent halation](#halation). Only after testing on a better screen did I realize that it would look almost completely black; I subsequently lightened the background to `#111` to strike a good balance.
[^20]: {{<mention-work itemtype="Book">}}{{<cited-work name="Practical Typography" url="https://practicaltypography.com/">}}{{</mention-work>}} only renders invisible text without JavaScript. You can use a textual browser, screen reader, copy-paste the page contents elsewhere, use a reader-mode implementation, or "view source" to read it without enabling scripts. All of these options will ironically override the carefully-crafted typography of this website about typography.
[^19]: {{<mention-work itemtype="Book">}}{{<cited-work name="Practical Typography" url="https://practicaltypography.com/">}}{{</mention-work>}} only renders invisible text without JavaScript. You can use a textual browser, screen reader, copy-paste the page contents elsewhere, use a reader-mode implementation, or "view source" to read it without enabling scripts. All of these options will ironically override the carefully-crafted typography of this website about typography.
I find <cite>Practical Typography</cite> quite useful for printed works, and incorporated a more moderate version of its advice on soft-hyphens into this page. With a few such exceptions, I generally find it to be poor advice for Web content.
[^21]: libavif links against libaom, librav1e, and/or libsvtav1 to perform AVIF encoding and decoding. libaom is best for this use-case, particularly since libaom can link against libjxl to use its Butteraugli distortion metric. This lets libaom optimize the perceptual quality of lossy encodes much more accurately.
[^20]: libavif links against libaom, librav1e, and/or libsvtav1 to perform AVIF encoding and decoding. libaom is best for this use-case, particularly since libaom can link against libjxl to use its Butteraugli distortion metric. This lets libaom optimize the perceptual quality of lossy encodes much more accurately.
[^22]: I find it quite odd that Microsoft Edge doesn't support AVIF. Chromium has supported AVIF for a long time, and Edge is based on Chromium. AVIF is a royalty-free format; I don't know why Microsoft would remove support for it, especially since Microsoft allows adding AVIF support to Windows. I think Edge also removed Chromium's experimental, off-by-default support for JPEG-XL.
[^23]: I say that a skip link is useful to reduce the amount of <kbd>Tab</kbd> keystrokes required, but I don't know a good "threshold number" to signify "too many keystrokes". If it takes ten keystrokes to reach the main content, it's probably time to add a skip-link.
[^24]: ATs typically let users navigate by headings, landmarks, paragraphs, and links. Most users prefer skipping article content with heading-based navigation. Keyboard users can bind different keys to different modes of navigation, but mobile users can only access one navigation mode at a time.
[^21]: ATs typically let users navigate by headings, landmarks, paragraphs, and links. Most users prefer skipping article content with heading-based navigation. Keyboard users can bind different keys to different modes of navigation, but mobile users can only access one navigation mode at a time.
Mobile users wishing to temporarily switch modes have to stop, change their navigation mode, perform a navigation gesture, and switch back. Mobile users trying to skim an article don't always find this worth the effort and sometimes stick to heading-based navigation even when a different mode would be optimal.
[^25]: At least, it will be until [NVDA bug 9343](https://github.com/nvaccess/nvda/issues/9343) gets resolved.
[^22]: At least, it will be until [NVDA bug 9343](https://github.com/nvaccess/nvda/issues/9343) gets resolved.
[^26]: If you'd like to learn more, {{<mention-work itemtype="BlogPosting">}}{{< cited-work name="A guide to designing accessible, WCAG-compliant focus indicators" url="https://www.sarasoueidan.com/blog/focus-indicators/" extraName="headline" >}} by {{< indieweb-person url="https://www.sarasoueidan.com/" first-name="Sara" last-name="Soueidan" url="https://www.sarasoueidan.com/" itemprop="author">}}{{</mention-work>}} has far more details on making accessible focus indicators.
[^23]: If you'd like to learn more, {{<mention-work itemtype="BlogPosting">}}{{< cited-work name="A guide to designing accessible, WCAG-compliant focus indicators" url="https://www.sarasoueidan.com/blog/focus-indicators/" extraName="headline" >}} by {{< indieweb-person url="https://www.sarasoueidan.com/" first-name="Sara" last-name="Soueidan" url="https://www.sarasoueidan.com/" itemprop="author">}}{{</mention-work>}} has far more details on making accessible focus indicators.
[^27]: Screen readers aren't alone here. Several programs strip inline formatting: certain feed readers, search result snippets, and textual browsers invoked with the `-dump` flag are some examples I use every day.
[^24]: Screen readers aren't alone here. Several programs strip inline formatting: certain feed readers, search result snippets, and textual browsers invoked with the `-dump` flag are some examples I use every day.
[^28]: I excluded PageSpeed Insights and GTMetrix since those are mostly covered by Lighthouse. I excluded Security Headers, since its approach seems to be recommending headers regardless of whether or not they are necessary. It penalizes forgoing the <code>Permissions-<wbr />Policy</code> header even if the CSP blocks script loading and execution; see [Security Headers issue #103](https://github.com/securityheaders/securityheaders-bugs/issues/103). I personally find the <code>Permissions-<wbr />Policy</code> header quite problematic, as I noted in August 2021 on [webappsec-permissions-policy issue #189](https://github.com/w3c/webappsec-permissions-policy/issues/189#issuecomment-904783021).
[^25]: I excluded PageSpeed Insights and GTMetrix since those are mostly covered by Lighthouse. I excluded Security Headers, since its approach seems to be recommending headers regardless of whether or not they are necessary. It penalizes forgoing the <code>Permissions-<wbr />Policy</code> header even if the CSP blocks script loading and execution; see [Security Headers issue #103](https://github.com/securityheaders/securityheaders-bugs/issues/103). I personally find the <code>Permissions-<wbr />Policy</code> header quite problematic, as I noted in August 2021 on [webappsec-permissions-policy issue #189](https://github.com/w3c/webappsec-permissions-policy/issues/189#issuecomment-904783021).
[^29]: My site caches HTML documents for ten minutes and caches the RSS feed for several hours. I disagree with webhint's recommendations against this: cache durations should be based on request rates and how often a resource is updated. I also disagree with some of its `content-type` recommendations: you don't need to declare UTF-8 charsets for SVG content-type headers if the SVG is ASCII-only and called from a UTF-8 HTML document. You gain nothing but header bloat by doing so.
[^26]: My site caches HTML documents for ten minutes and caches the RSS feed for several hours. I disagree with webhint's recommendations against this: cache durations should be based on request rates and how often a resource is updated. I also disagree with some of its `content-type` recommendations: you don't need to declare UTF-8 charsets for SVG content-type headers if the SVG is ASCII-only and called from a UTF-8 HTML document. You gain nothing but header bloat by doing so.
[^30]: Consider disabling the JIT for your normal browsing too; doing so removes whole classes of vulnerabilities. In Firefox, navigate to <samp>about:<wbr />config</samp> and toggle some flags under <code>javascript<wbr />.options</code>.
[^27]: Consider disabling the JIT for your normal browsing too; doing so removes whole classes of vulnerabilities. In Firefox, navigate to <samp>about:<wbr />config</samp> and toggle some flags under <code>javascript<wbr />.options</code>.
<figure itemprop="hasPart" itemscope="" itemtype="https://schema.org/SoftwareSourceCode">
<figcaption>
@ -1774,6 +1675,6 @@ A special thanks goes out to GothAlice for the questions she answered in <samp>#
In Chromium and derivatives, run the browser with `--js-flags='--jitless'`; in the Tor Browser, set the security level to "Safer".
[^31]: LibreOffice can also render HTML but has extremely limited support for CSS. OnlyOffice seems to work best, but doesn't load images. If your page is CSS-optional, it should look fine in both.
[^28]: LibreOffice can also render HTML but has extremely limited support for CSS. OnlyOffice seems to work best, but doesn't load images. If your page is CSS-optional, it should look fine in both.

40
layouts/_default/bookmarks.html
View file

@ -23,30 +23,24 @@
</a>
</h2>
<p>
Bookmarked <time class="dt-published published" itemprop="datePublished" datetime="{{ dateFormat "2006-01-02 15:04:05Z07:00" $timestamp }}">{{ dateFormat "2006-01-02 15:04" $timestamp }}</time>
Bookmarked on: <time class="dt-published published" itemprop="datePublished" datetime="{{ dateFormat "2006-01-02 15:04:05Z07:00" $timestamp }}">{{ dateFormat "2006-01-02 15:04" $timestamp }}</time>
<br />Tags: <span itemprop="keywords">
{{- $start := 2 -}}
{{- $firstTag := (index $tags 1) -}}
{{- if (eq $firstTag "public") -}}
{{- $firstTag = (index $tags 2) -}}
{{- $start = 3 -}}
{{- end -}}
{{- printf "<span class=\"p-category\">%s</span>" $firstTag | safeHTML -}}
{{- range after $start $tags -}}
{{- $tag := . -}}
{{- if (ne $tag "public") -}}
{{- printf ", <span class=\"p-category\">%s</span>" $tag | safeHTML -}}
{{ end -}}
{{- end }}
</span>
</p>
<div>
<p>
Tags: <span itemprop="keywords">
{{- $start := 2 -}}
{{- $firstTag := (index $tags 1) -}}
{{- if (eq $firstTag "public") -}}
{{- $firstTag = (index $tags 2) -}}
{{- $start = 3 -}}
{{- end -}}
{{- printf "<span class=\"p-category\">%s</span>" $firstTag | safeHTML -}}
{{- range after $start $tags -}}
{{- $tag := . -}}
{{- if (ne $tag "public") -}}
{{- printf ", <span class=\"p-category\">%s</span>" $tag | safeHTML -}}
{{ end -}}
{{- end }}
</span>
</p>
<p class="e-summary entry-summary" itemprop="description">
{{ $bookmark.description | markdownify | replaceRE `\&rsquo;` `’` | replaceRE `\&nbsp;` `\&#160;` | replaceRE `\&ldquo;` `“` | replaceRE `\&rdquo;` `”` | replaceRE `\&hellip;` `—` | replaceRE `\&mdash;` `—` | replaceRE `\&shy;` `\&#173;` | replaceRE `&lsquo;` `‘` | safeHTML }}
</p>
</div>
<p class="e-summary entry-summary" itemprop="description">{{ $bookmark.description | markdownify | replaceRE `\&rsquo;` `’` | replaceRE `\&nbsp;` `\&#160;` | replaceRE `\&ldquo;` `“` | replaceRE `\&rdquo;` `”` | replaceRE `\&hellip;` `—` | replaceRE `\&mdash;` `—` | replaceRE `\&shy;` `\&#173;` | replaceRE `&lsquo;` `‘` | safeHTML }}</p>
</article>
</li>
{{- end }}

8
layouts/_default/list.atom.xml
View file

@ -76,11 +76,7 @@
{{- end -}}
<activity:object-type>http://activitystrea.ms/schema/1.0/{{ $type }}</activity:object-type>
<activity:verb>http://activitystrea.ms/schema/1.0/post</activity:verb>
{{ with .Params.image -}}
{{- $image := resources.Get (printf "/p/%s" . ) | resources.Fingerprint "md5" -}}
<media:thumbnail url="{{ $image.Permalink }}" width="{{ $image.Width }}" height="{{ $image.Height }}" />
{{- end }}
</entry>
{{- end -}}
{{- end }}
{{- end }}
{{ end }}
</feed>

2
layouts/_default/list.html
View file

@ -37,10 +37,8 @@
{{ partial "processed-content.html" . }}
</div>
{{- else }}
<div><!--Keep this attr-free div to make this part structurally identical.-->
<p class="p-summary entry-summary" itemprop="description">{{ .Description }}</p>
<p>{{- partial "wordcount.html" . -}}</p>
</div>
{{- end }}
</article>
</li>

2
layouts/about/list.html
View file

@ -26,10 +26,8 @@
, updated <time{{ if not (.Params.evergreen) }} itemprop="dateModified" class="dt-updated updated"{{ end }} datetime="{{ .Lastmod.Format "2006-01-02 15:04:05Z07:00" }}">{{ .Lastmod.Format "2006-01-02 15:04" }}</time>
{{- end }}
</p>
<div>
<p class="p-summary entry-summary" itemprop="description">{{ .Description }}</p>
<p>{{- partial "wordcount.html" . -}}</p>
</div>
</article>
</li>
{{- end }}

1
layouts/index.html
View file

@ -2,6 +2,7 @@
<main>
<h1 id="h1" tabindex="-1">Seirdy’s Home</h1>
<p itemprop="description">{{ .Site.Params.Description }}</p>
<hr />
<div class="narrow">
{{ partial "processed-content.html" . }}
{{ partial "posts.html" . }}

2
layouts/meta/list.html
View file

@ -26,10 +26,8 @@
, updated <time{{ if not (.Params.evergreen) }} itemprop="dateModified" class="dt-updated updated"{{ end }} datetime="{{ .Lastmod.Format "2006-01-02 15:04:05Z07:00" }}">{{ .Lastmod.Format "2006-01-02 15:04" }}</time>
{{- end }}
</p>
<div>
<p class="p-summary entry-summary" itemprop="description">{{ .Description }}</p>
<p>{{- partial "wordcount.html" . -}}</p>
</div>
</article>
</li>
{{- end }}

2
layouts/partials/breadcrumblist.html
View file

@ -3,7 +3,7 @@
<hr />
<nav aria-labelledby="bc-label"
itemscope="" itemprop="breadcrumb" itemtype="https://schema.org/BreadcrumbList">
<span id="bc-label">You are here:&#160;</span>
<span id="bc-label">You are here:</span>
<ol>
{{ template "breadcrumbnav" (dict "p1" . "p2" .) }}
</ol>

1
layouts/partials/head.html
View file

@ -81,6 +81,7 @@
{{ printf `<meta property="og:image" content="%s" />` $og_image.Permalink | safeHTML }}
<meta property="og:image:type" content="image/png" />
<meta property="og:image:height" content="{{ $og_image.Height }}" /><meta property="og:image:width" content="{{ $og_image.Width }}" />
<meta property="og:image:alt" content="{{ $og_image_alt }}" />
<meta property="og:url" content="{{ .Site.Params.CanonicalBaseURL }}{{ $canonicalRelPermalink }}" />
<meta property="og:description" content="{{ $description }}" />
</head>

2
layouts/partials/posts.html
View file

@ -25,10 +25,8 @@
{{- end }}
</p>
<div>
<p class="p-summary entry-summary" itemprop="description">{{ .Description }}</p>
<p>{{- partial "wordcount.html" . -}}</p>
</div>
</article>
</li>
{{- end }}

2
layouts/partials/reply-context.html
View file

@ -11,7 +11,6 @@
{{- $replyAuthorRel = "publisher" -}}
{{- end -}}
<aside role="note">
<p>
Reply to <span class="h-cite in-reply-to" itemprop="about" itemscope="" itemtype="https://schema.org/{{ $schemaType }}">
<cite itemprop="name" class="p-name">
<a class="u-url" itemprop="url" href="{{ .replyURI }}">{{ .replyTitle | safeHTML}}</a>
@ -21,5 +20,4 @@
<span itemprop="name" class="p-name fn n">{{ .replyAuthor }}</span></a>
</span>
</span>
</p>
</aside>

2
layouts/partials/webmentions.html
View file

@ -78,7 +78,7 @@
{{- if findRE `^https://brid.gy/[^/]*/mastodon` $webmention.source -}}
<p role="doc-tip" itemprop="accessibilitySummary">This comment may have major formatting errors that could impact screen reader comprehension.</p>
{{- end -}}
<p><q itemprop="text" class="p-content">{{ $webmention.content | replaceRE `^@Seirdy(@pleroma.envs.net)? ?` ""}}</q></p>
<p><q itemprop="articleBody" class="p-content">{{ $webmention.content | replaceRE `^@Seirdy(@pleroma.envs.net)? ?` ""}}</q></p>
{{- end -}}
{{- end }}
</dd>

2
layouts/partials/webrings.html
View file

@ -38,4 +38,4 @@
{{- end -}}
</ol>
</details>
<p>If you’re part of a webring and would like me to join, just ask.</p>
<p>If you’re part of a webring and would like me to join, just ask. I’ll probably accept if joining only requires me to add hyperlinks to this page (no scripts, external content, or images), and if the ring doesn’t seem to promote anything I find objectionable.</p>

4
layouts/shortcodes/mention-work.html
View file

@ -4,12 +4,12 @@
{{- end -}}
{{- if .Get "p" -}}
<p
class="h-cite{{ with .Get "reply" }} in-reply-to{{ end }}"{{ with .Get "itemid" }} itemid="{{ . }}"{{ end }} itemprop="{{ $itemprop }}"{{ with .Get "role" }} role="{{ . }}"{{ end }} itemscope="" itemtype="https://schema.org/{{ .Get "itemtype" }}">
class="h-cite{{ with .Get "reply" }} in-reply-to{{ end }}" itemprop="{{ $itemprop }}"{{ with .Get "role" }} role="{{ . }}"{{ end }} itemscope="" itemtype="https://schema.org/{{ .Get "itemtype" }}">
{{- .Inner | markdownify | safeHTML -}}
</p>
{{- else -}}
<span
class="h-cite{{ with .Get "reply" }} in-reply-to{{ end }}"{{ with .Get "itemid" }} itemid="{{ . }}"{{ end }} itemprop="{{ $itemprop }}"{{ with .Get "role" }} role="{{ . }}"{{ end }} itemscope="" itemtype="https://schema.org/{{ .Get "itemtype" }}">
class="h-cite{{ with .Get "reply" }} in-reply-to{{ end }}" itemprop="{{ $itemprop }}"{{ with .Get "role" }} role="{{ . }}"{{ end }} itemscope="" itemtype="https://schema.org/{{ .Get "itemtype" }}">
{{- .Inner | markdownify | safeHTML -}}
</span>
{{- end -}}

43
linter-configs/hintrc
View file

@ -15,26 +15,16 @@
"hints": {
"apple-touch-icons": "off",
"axe/aria": "off",
"axe/color": "off",
"axe/forms": "off",
"axe/keyboard": "off",
"axe/language": "off",
"axe/name-role-value": "off",
"axe/semantics": "off",
"axe/sensory-and-visual-cues": "off",
"axe/structure": "off",
"axe/tables": "off",
"axe/text-alternatives": "off",
"axe/time-and-media": "off",
"compat-api/css": [
"error",
{
"ignore": [
"filter",
"contain",
"contain-intrinsic-size",
"content-visibility: auto",
"image-rendering: pixelated",
"text-size-adjust: none"
"contain-intrinsic-size",
"content-visibility",
"text-size-adjust"
]
}
],
@ -59,32 +49,21 @@
"http-cache": [
"error",
{
"maxAgeTarget": 1200
"maxAgeTarget": 600
}
],
"http-compression": "off",
"https-only": "error",
"sri": "error",
"manifest-exists": "error",
"manifest-file-extension": "error",
"manifest-is-valid": "error",
"manifest-app-name": "error",
"minified-js": "off",
"meta-viewport": "error",
"no-bom": "error",
"no-p3p": "error",
"no-protocol-relative-urls": "error",
"no-friendly-error-pages": "error",
"no-vulnerable-javascript-libraries": "off",
"html-checker": "off",
"image-optimization-cloudinary": "off",
"no-disallowed-headers": "error",
"meta-charset-utf-8": "error",
"disown-opener": "error",
"content-type": ["error", {
".*\\.svg": "image/svg+xml"
}],
"no-html-only-headers": [ "error",
"no-html-only-headers": [ "warning",
{
"ignore": ["content-security-policy"]
}],
@ -95,16 +74,6 @@
"loadTime": 10
}
],
"css-prefix-order": "error",
"scoped-svg-styles": "error",
"button-type": "error",
"strict-transport-security": "error",
"x-content-type-options": "error",
"typescript-config/is-valid": "off",
"typescript-config/no-comment": "off",
"typescript-config/target": "off",
"typescript-config/strict": "off",
"typescript-config/import-helpers": "off",
"stylesheet-limits": [
"error",
{

4
linter-configs/vnu_filter.jq
View file

@ -18,10 +18,6 @@
.message == "CSS: “contain-intrinsic-size”: Property “contain-intrinsic-size” doesn't exist."
)
or
( # see https://github.com/w3c/css-validator/issues/370
.message == "CSS: “contain”: “inline-size” is not a “contain” value."
)
or
( # the search page has raw templates, let those slide. I validate the final dynamic search page manually.
.url | test ("/search/index.")
)

4
scripts/bin/check-whole-site
View file

@ -62,8 +62,8 @@ base_url="${1-http://localhost:8089}"
# HTML validation is already parallelized, so run that single-threaded.
make -j1 HUGO_FLAGS=-DF HUGO_BASEURL="$base_url" clean hugo xhtmlize validate-html
make -j "$jobs" -f Makefile.online HUGO_BASEURL="$base_url" all-extra URLS="$(curl -sSL "$base_url/sitemap.xml" | htmlq loc -t | rg -v '/search/$' | tr '\n' ' ')"
make deploy-staging -j "$jobs"
make -f Makefile.online hint-online URLS="$(curl -sSL --compressed https://staging.seirdy.one/sitemap.xml | htmlq loc -t | rg -v '/(?:search|wcag-is-a-starting-point)/$' | sort | tr '\n' ' ')"
make deploy-staging
make -f Makefile.online hint-online URLS="$(curl -sSL --compressed https://staging.seirdy.one/sitemap.xml | htmlq loc -t | rg -v '/search/$' | sort | tr '\n' ' ')"
# TODO: run lighthouse on every page in the sitemap.
# vi:ft=sh

12
scripts/populate-webrings.sh
View file

@ -85,21 +85,9 @@ endless_orbit() {
echo
}
netizens() {
printf 'Netizens,'
{
curl -sSL --compressed https://netizensring.link/onionring-variables.js \
| grep -C 1 https://seirdy.one/ | sd -s '];' "'https://netizensring.link/,'"
echo "'null',"
} | sd 'https://seirdy.one/,?' 'https://netizensring.link/,' \
| sd "\n|'" '' | trim_trailing_comma
echo
}
print_csv_values() {
george
endless_orbit
netizens
}
if [ "$dry_run" = '1' ]; then

2
scripts/xhtmlize-single-file.sh
View file

@ -29,7 +29,7 @@ trap cleanup EXIT
sed 7d "$html_file" | xmllint --format --encode UTF-8 --noent - | sd '^\t(?:\t)?' '' >"$tmp_file"
{
head -n7 "$tmp_file" | sd -s '/>' ' />'
cat "$OUTPUT_DIR/tmp.css"
cat tmp.css
# shellcheck disable=SC2016 # these are regex statements, not shell expressions
tail -n +8 "$tmp_file" \
| sd '<pre(?: tabindex="0")?>\n\t*<(code|samp)( |>)' '<pre tabindex="0"><$1$2' \

5
scripts/xhtmlize.sh
View file

@ -8,13 +8,12 @@ set -e -u
output_dir="$1"
script_dir="$(dirname "$0")"
printf '<style>%s</style>\n' "$(htmlq -t style <"$output_dir/index.html")" >"$output_dir/tmp.css"
printf '<style>%s</style>\n' "$(htmlq -t style <"$output_dir/index.html")" >tmp.css
cleanup() {
rm -f "$output_dir/tmp.css"
rm -f "tmp.css"
}
trap cleanup EXIT
export XMLLINT_INDENT=' '
export OUTPUT_DIR="$output_dir"
find "$output_dir" -type f -name '*.html' | xargs -n1 sh "$script_dir/xhtmlize-single-file.sh"
# done

5
static/robots.txt
View file

@ -8,6 +8,11 @@ User-Agent: Adsbot
Disallow: /
Allow: /ads.txt
# the UA should not be case-sensitive, but I gotta cover my bases.
User-Agent: AdsBot
Disallow: /
Allow: /ads.txt
# > This robot collects content from the Internet for the sole purpose of # helping educational institutions prevent plagiarism. [...] we compare student papers against the content we find on the Internet to see if we # can find similarities. (http://www.turnitin.com/robot/crawlerinfo.html)
# --> fuck off.
User-Agent: TurnitinBot