Skip to content

Add new failure technique for non-semantic ruby annotation #4829

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
adampage wants to merge 8 commits into
base: main
Choose a base branch
from
Open

Add new failure technique for non-semantic ruby annotation #4829

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
8 commits
Select commit Hold shift + click to select a range
0a8c927
first draft of new failure and supporting working examples
adampage Dec 27, 2025
130a20a
cross-reference new failure to 1.3.1
adampage Dec 27, 2025
f71bb0c
cross-reference 1.3.1 to existing ruby html technique
adampage Dec 27, 2025
7f3e5f5
fix typo
adampage Jan 9, 2026
50b644c
Merge remote-tracking branch 'upstream/main' into ruby-new-failure
adampage Jan 9, 2026
52b9870
add 1.3.2 reference and explanations
adampage Jan 9, 2026
42382c3
role model ruby usage
adampage Jan 11, 2026
0850358
add cspell overrides for “tou” and “shi”
adampage Jan 11, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions cspell.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -55,6 +55,8 @@ overrides:
words: [voyture] # Pronunciation example
- filename: understanding/*/text-spacing.html
words: [drawi, whe] # Examples of text clipping
- filename: techniques/failures/F999.html
words: [tou, shi]
languageSettings:
- languageId: html
ignoreRegExpList:
Expand Down
248 changes: 248 additions & 0 deletions techniques/failures/F999.html
View file
Open in desktop

Large diffs are not rendered by default.

5 changes: 3 additions & 2 deletions understanding/understanding.11tydata.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -272,6 +272,7 @@ export default function (data) {
"PDF17",
"PDF21",
"H97",
"H62",
],
usingQuantity: "",
},
Expand All @@ -292,7 +293,7 @@ export default function (data) {
},
],
advisory: ["C22", "G162", "ARIA1", "ARIA2", "G141"],
failure: ["F2", "F33", "F34", "F42", "F43", "F46", "F48", "F90", "F91", "F92", "F111"],
failure: ["F2", "F33", "F34", "F42", "F43", "F46", "F48", "F90", "F91", "F92", "F111", "F999"],
},

"meaningful-sequence": {
Expand All @@ -313,7 +314,7 @@ export default function (data) {
"C27",
"PDF3",
],
failure: ["F34", "F33", "F32", "F49", "F1"],
failure: ["F34", "F33", "F32", "F49", "F1", "F999"],
},

"sensory-characteristics": {
Expand Down
73 changes: 73 additions & 0 deletions working-examples/ruby-annotation/misuse-abbr-title/index.html
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,73 @@
<!DOCTYPE html>
<html lang="en">
<head>
<title>Misuse of &lt;abbr title&gt; to convey ruby annotations</title>
<meta name="viewport" content="width=device-width, initial-scale=1">
<style>
html {
font-family: system-ui, sans-serif;
font-size: 62.5%;
}

body {
font-size: 2.0rem;
}

p {
max-inline-size: 80ch;
line-height: 1.5;
}

.specimen {
display: inline-block;
font-size: 6.0rem;
padding-block-start: 1.6rem;
}

abbr {
position: relative;
text-decoration: none;

&::before {
content: attr(title);
position: absolute;
inset-block-start: -1.1em;
inset-inline-start: 50%;
translate: -50%;
font-size: 0.5em;
white-space: nowrap;
}
}
</style>
</head>
<body>
<main>
<h1>Misuse of <code>&lt;abbr title&gt;</code> to convey ruby annotations</h1>
<p>
“<a href="https://www.w3.org/TR/ruby/">Ruby</a>” are short runs of text
alongside the base text, typically used in East Asian documents to
indicate pronunciation or to provide a short annotation.
</p>
<p>
In the following Japanese text, <span lang="ja">み, か, だお</span> are
ruby annotations that indicate to the reader how the kanji characters
<span lang="ja">見, 掛, 倒</span>, respectively, should be pronounced.
</p>
<div class="specimen">
<p lang="ja"
><abbr title="み">見</abbr
><abbr title="か">掛</abbr
>け<abbr title="だお">倒</abbr
>し
</p>
</div>
<p>
In this example, a well-meaning author has used
<code>&lt;abbr&gt;</code> (i.e., abbreviation) elements and custom CSS
to visually convey ruby annotations. This is a failure because assistive
technologies cannot programmatically determine the structured
ruby annotations that are visually presented.
</p>
</main>
</body>
</html>
71 changes: 71 additions & 0 deletions working-examples/ruby-annotation/misuse-span/index.html
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,71 @@
<!DOCTYPE html>
<html lang="en">
<head>
<title>Misuse of &lt;span&gt; to convey ruby annotations</title>
<meta name="viewport" content="width=device-width, initial-scale=1">
<style>
html {
font-family: system-ui, sans-serif;
font-size: 62.5%;
}

body {
font-size: 2.0rem;
}

p {
max-inline-size: 80ch;
line-height: 1.5;
}

.specimen {
display: inline-block;
font-size: 6.0rem;
padding-block-start: 1.6rem;
}

.annotated {
position: relative;
text-decoration: none;

& > span {
position: absolute;
inset-block-start: -1.1em;
inset-inline-start: 50%;
translate: -50%;
font-size: 0.5em;
white-space: nowrap;
}
}
</style>
</head>
<body>
<main>
<h1>Misuse of <code>&lt;span&gt;</code> to convey ruby annotations</h1>
<p>
“<a href="https://www.w3.org/TR/ruby/">Ruby</a>” are short runs of text
alongside the base text, typically used in East Asian documents to
indicate pronunciation or to provide a short annotation.
</p>
<p>
In the following Japanese text, <span lang="ja">み, か, だお</span> are
ruby annotations that indicate to the reader how the kanji characters
<span lang="ja">見, 掛, 倒</span>, respectively, should be pronounced.
</p>
<div class="specimen">
<p lang="ja"
><span class="annotated">見<span>み</span></span
><span class="annotated">掛<span>か</span></span
>け<span class="annotated">倒<span>だお</span></span
>し
</p>
</div>
<p>
In this example, an author has used <code>&lt;span&gt;</code> elements
and custom CSS to visually convey ruby annotations. This is a failure
because assistive technologies cannot programmatically determine the
structured ruby annotations that are visually presented.
</p>
</main>
</body>
</html>
72 changes: 72 additions & 0 deletions working-examples/ruby-annotation/misuse-sup/index.html
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,72 @@
<!DOCTYPE html>
<html lang="en">
<head>
<title>Misuse of &lt;sup&gt; to convey ruby annotations</title>
<meta name="viewport" content="width=device-width, initial-scale=1">
<style>
html {
font-family: system-ui, sans-serif;
font-size: 62.5%;
}

body {
font-size: 2.0rem;
}

p {
max-inline-size: 80ch;
line-height: 1.5;
}

.specimen {
display: inline-block;
font-size: 6.0rem;
padding-block-start: 1.6rem;
}

.annotated {
position: relative;
text-decoration: none;

& > sup {
position: absolute;
inset-block-start: -1.1em;
inset-inline-start: 50%;
translate: -50%;
font-size: 0.5em;
white-space: nowrap;
}
}
</style>
</head>
<body>
<main>
<h1>Misuse of <code>&lt;sup&gt;</code> to convey ruby annotations</h1>
<p>
“<a href="https://www.w3.org/TR/ruby/">Ruby</a>” are short runs of text
alongside the base text, typically used in East Asian documents to
indicate pronunciation or to provide a short annotation.
</p>
<p>
In the following Japanese text, <span lang="ja">み, か, だお</span> are
ruby annotations that indicate to the reader how the kanji characters
<span lang="ja">見, 掛, 倒</span>, respectively, should be pronounced.
</p>
<div class="specimen">
<p lang="ja"
><span class="annotated">見<sup>み</sup></span
><span class="annotated">掛<sup>か</sup></span
>け<span class="annotated">倒<sup>だお</sup></span
>し
</p>
</div>
<p>
In this example, a well-meaning author has used
<code>&lt;sup&gt;</code> (i.e., superscript) elements and custom CSS to
visually convey ruby annotations. This is a failure because assistive
technologies cannot programmatically determine the structured
ruby annotations that are visually presented.
</p>
</main>
</body>
</html>