From 702c1d43ff3ab1b415d81d3455651dd7f95ad6f0 Mon Sep 17 00:00:00 2001 From: Edward Langley Date: Sun, 20 Sep 2026 14:16:17 -0700 Subject: [PATCH] docs: correct the alt-text argument, which was right for the wrong reason MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The commit that added `content: "\2630 " / ""` claimed Firefox ignores the alt-text form and falls back to reading the content, making the change "an improvement in two engines and a no-op in the third". The mechanism is wrong: Firefox shipped the syntax in 133, and all three engines parse it -- measured in Chrome 141, Firefox 142 and WebKit 26, each computing the declaration intact. The conclusion survives; the reason given for it does not, and the reason was the load-bearing half, because it was what made the change look like a one-way door. It is one because every engine shipped to supports the syntax, not because the unsupported path is harmless. The unsupported path is NOT harmless, and that is the risk neither the change nor its first review named: `/ alt` in an engine that does not know it is a parse error for the whole `content` declaration, so the glyph does not lose its alt text -- it VANISHES. A silent visual regression, the opposite of the assumed failure mode. The glyph is now verified painted in all three engines by pixel diff against `::before { content: none }`, text starting 20px further right in each. This is written to context/ rather than left in the commit message because design-principles.md §6 says an argument must not live only in a commit message -- a message is write-once, unauditable, and no check in this repo can read one. The rule landed in the same merge this corrects under, which is a reasonable first exercise of it. It also records this file's fourth wrong-property instance, and the sharpest, because it produced a confident FALSE POSITIVE: the first probe measured the label's width with and without ::before and reported the glyph missing in all three engines. The label is display:block, so its width comes from the container and cannot see inline content. Right question, wrong property -- and this time the wrong instrument accused working code rather than clearing broken code. Gates on the merged tree: 1379 rust, 26 node --test, 16 playwright (3 skipped, webkit OPFS), fmt clean, clippy -D warnings clean, all three check-comment-runs modes, 3473 site links / 0 broken, 0 nested anchors, 189 bead ids all resolving. improvise-djoo Co-Authored-By: Claude Opus 5 (1M context) Claude-Session: https://claude.ai/code/session_01FC2jVn8Au7E9JPkw6bwXXH --- context/code/doc-site.md | 28 ++++++++++++++++++++++++++++ 1 file changed, 28 insertions(+) diff --git a/context/code/doc-site.md b/context/code/doc-site.md index e2da5e61..61667fcb 100644 --- a/context/code/doc-site.md +++ b/context/code/doc-site.md @@ -273,3 +273,31 @@ not a measurement either, however precise it is.** `checkVisibility` fixed the visibility instrument; it does not turn a visibility count into an operability check. Ask what the defect would *do* to a user, then pick the instrument that observes that. + +**A correction, and the risk the original argument missed.** The commit that +added `content: "\2630 " / ""` said Firefox ignores the alt-text form and falls +back to reading the content, so the change was "an improvement in two engines +and a no-op in the third". **That mechanism is wrong** — Firefox shipped the +syntax in 133, and all three engines parse it (measured: Chrome 141, Firefox +142, WebKit 26 each compute the declaration intact). The conclusion held; the +reason given for it did not, and the reason was the load-bearing part, because +it was what made the change look like a one-way door. It is one because every +engine shipped to supports the syntax — not because the unsupported path is +harmless. That commit message is superseded by this paragraph (design-principles +§6: an argument must not live only in a commit message). + +**The unsupported path is not harmless, and that is the risk neither the change +nor its first review named.** `/ alt` in an engine that does not know it is a +*parse error for the whole `content` declaration*, so the glyph would not lose +its alt text — it would **vanish**. A silent visual regression, the opposite of +the assumed failure mode. The glyph is therefore verified painted in all three +engines by pixel diff against `::before { content: none }`, with the text +starting 20px further right in each. + +That check also produced this file's fourth instance of the wrong-property +trap, and the sharpest, because it produced a confident **false positive**: the +first probe measured the label's *width* with and without `::before` and +reported the glyph missing in all three engines. The label is `display: block`, +so its width comes from the container and cannot see inline content at all. +Right question, wrong property, and this time the wrong instrument accused +working code rather than clearing broken code.