CSS ruby-position Property

The ruby-position property specifies how ruby annotations (short runs of text typically used for pronunciation or annotation in East Asian typography) are positioned in relation to their base text. It determines whether the annotation text appears visually above, below, inside, or attached to the base content, and thus controls the basic placement strategy for small inline annotations that accompany base glyphs. Because ruby annotations occupy their own visual plane near the base text, ruby-position affects how a line of text is composed and how readers perceive the relationship between annotation and content.

Placement chosen by ruby-position interacts with line composition and spacing: depending on where annotations are placed, lines may need extra height or different vertical alignment to avoid collisions or clipping. That interaction makes properties that influence line box metrics important to consider - for example, control of the line box can be adjusted with line-height, and document flow or orthogonal text layout can change how ruby is displayed when using different writing directions, which is governed by writing-mode. When annotations are placed outside the normal ascent/descent of the base text, their layout can push or overlap neighboring lines unless overall line metrics account for them.

ruby-position also works together with other ruby-specific properties that refine alignment and merging behavior. For instance, visual alignment of the annotation relative to the base run is influenced by ruby-align, while how multiple adjacent ruby annotations combine is affected by ruby-merge and how annotation spans are treated relates to ruby-span. Designers often use these properties in combination to achieve compact, readable ruby presentation - for example, choosing a position that minimizes line-height escalation and then tuning alignment and merging rules to prevent visual crowding.

From an authoring and accessibility perspective, choosing an appropriate ruby-position value should balance typographic conventions, legibility, and reading order. In scripts where ruby normally appears above or to the inline-start side of text, selecting a position consistent with reader expectations helps comprehension; in rotated or vertical layouts, ensure positioning takes the orientation into account so annotations remain clearly associated with their base text. For broader alignment within a line or container, authors may also coordinate ruby choices with horizontal alignment rules such as text-align to maintain consistent visual rhythm in blocks that include annotated text.