East Asian Typography with ruby, rt, rp

Technical Deep Dive & Specifications

The WHATWG HTML5 Ruby Element Suite

The HTML standard defines three core elements that work together to construct phonetic annotations:

+-----------------------------------------------------------------------------------------+
|                                  THE RUBY ELEMENT TRIAD                                 |
+-----------------------------------------------------------------------------------------+
| ELEMENT | NAME             | DESCRIPTION                                                |
+---------+------------------+------------------------------------------------------------+
| <ruby>  | Ruby Container   | Wraps one or more base text characters and annotations.    |
| <rt>    | Ruby Text        | Contains the small phonetic annotation text.               |
| <rp>    | Ruby Parenthesis | Fallback delimiter shown ONLY if the browser lacks ruby    |
|         |                  | rendering support (e.g., text browsers, legacy feeds).     |
+-----------------------------------------------------------------------------------------+

Semantic Structure & Fallback Architecture

In modern browsers, <rt> automatically floats above (or beside) the base text at approximately 50% font size, and <rp> tags are completely hidden (display: none).

However, if an older browser, CLI browser (like Lynx), RSS feed aggregator, or screen reader does not support ruby layout, it falls back to displaying the content linearly. The <rp> elements appear to wrap the phonetic text in parentheses, preventing the text from becoming an unreadable garbled mess.

Standard HTML5 Ruby Markup:
<ruby>
  漢<rp>(</rp><rt>かん</rt><rp>)</rp>
  字<rp>(</rp><rt>じ</rt><rp>)</rp>
</ruby>

Browser with Ruby Support:       Legacy Browser / Plain Text Fallback:
       かん じ
       漢   字                           漢(かん)字(じ)

Ruby Tagging Patterns

1. Mono-Ruby (Character-by-Character Mapping) — Recommended

Each base character is paired with its individual phonetic annotation:

<ruby>
  東<rp>(</rp><rt>とう</rt><rp>)</rp>
  京<rp>(</rp><rt>きょう</rt><rp>)</rp>
</ruby>

Advantage: Enables fine-grained typography, natural wrapping across line ends, and precise alignment.

2. Group-Ruby (Whole-Word Mapping)

A single multi-character base string is paired with a compound annotation:

<ruby>
  明日<rp>(</rp><rt>あした</rt><rp>)</rp>
</ruby>

Advantage: Useful for irregular readings (jukujikun) where individual kanji cannot be split neatly into syllables.

CSS Styling & Layout for Ruby

Modern CSS provides specialized properties to control ruby layout:

/* Position the annotation text relative to the base text */
ruby {
  ruby-position: over;       /* Default in horizontal text (floats above) */
  /* ruby-position: under;   /* Floats below the base text */
  /* ruby-position: inter-character; /* Places annotation between characters (Bopomofo) */
}

/* Control horizontal justification of rt over base characters */
ruby {
  ruby-align: space-around;  /* Distributes phonetic letters evenly over kanji */
  /* ruby-align: center; */
  /* ruby-align: start; */
}

+-------------------------------------------------------------------------------+
|                             CSS RUBY POSITIONS                                |
+-------------------------------------------------------------------------------+
|  ruby-position: over;          ruby-position: under;        Vertical Mode:    |
|       とうきょう                     東  京                     東 と           |
|       東  京                     とうきょう                     京 う           |
|                                                                き             |
|                                                                ょ             |
|                                                                う             |
+-------------------------------------------------------------------------------+

Screen Reader & Accessibility Considerations

Without proper markup, screen readers may read both the base character and the phonetic annotation consecutively: "Kan-kanji-ji", causing confusion.

Modern assistive technologies with CJK support understand <ruby> and read only the <rt> phonetic pronunciation or the base text depending on the user's accessibility preferences. To ensure clean pronunciation across all legacy screen readers, maintain clean <rp> wrappers.

💻 Interactive Code Playground

Starter Code

Line-by-Line Code Breakdown

• Line 2 (<html lang="ja">): Informs the browser that the primary language is Japanese, loading Japanese typographic font substitutions and CJK line-breaking rules.
• Line 12 (line-height: 2.2;): When working with ruby annotations, allocating extra vertical line height (at least 2.0 to 2.5) is required so that <rt> text does not collide with text on the preceding line.
• Lines 51–57 (<ruby>新<rp>(</rp><rt>しん</rt><rp>)</rp>... ): Implements mono-ruby. Each Kanji character (新, 幹, 線) is immediately followed by its fallback parenthesis ((), its phonetic pronunciation in Hiragana (しん), and its closing parenthesis ()).
• Line 66 (<div class="card chinese-ruby" lang="zh-Hans">): Overrides language context to Simplified Chinese.
• Lines 70–75 (<ruby>北<rp>(</rp><rt>běi</rt><rp>)</rp>...): Applies Pinyin tone marks (běi jīng) over the corresponding Hanzi characters.
• Line 83 (ruby-position: under;): Forces the phonetic text to render beneath the baseline of the kanji characters instead of on top.

Expected Browser Render Output

• In modern browsers, tiny red Hiragana readings (しん, かん, せん) float neatly above their respective Kanji characters.
• In Chinese sections, Pinyin with tone marks (běi, jīng) hovers in blue above the characters 北京.
• In the third box, ふじさん renders below 富士山.
• Parentheses defined inside <rp> are invisible in modern browsers.