Implementing Right-to-Left (RTL) Support in UI

This document outlines a systematic strategy for implementing Right-to-Left (RTL) support across the user interface. It explains how to replace physical (direction-based) CSS properties and Tailwind utility classes with logical (flow-relative) equivalents, ensuring that layouts automatically mirror when the document direction is set to RTL.

RTL support is essential for languages like Arabic, Hebrew, and Persian, and using logical properties ensures consistent layout mirroring without maintaining separate CSS.

Core Principle: Logical vs. Physical Styling

The foundational change is shifting from fixed spatial directions (left, right) to directions relative to the content flow (start, end).

• Physical Properties: Refer to fixed screen directions (e.g., margin-left). They do not flip in RTL.

• Logical Properties: Refer to the start/end of the content's flow (e.g., margin-inline-start). They map to left in LTR and right in RTL (and vice-versa).

CSS Logical Properties Conversion

All instances of physical directional CSS properties must be replaced with their logical counterparts.

Special Case: Border Radius

Physical border radius properties are converted to logical corner properties:

• border-top-left-radius -->border-start-start-radius

• border-top-right-radius --> border-start-end-radius

• border-bottom-left-radius --> border-end-start-radius

• border-bottom-right-radius --> border-end-end-radius

Tailwind Utility Class Conversion

Tailwind utility classes based on physical directions (l=left, r=right) must be converted to their logical counterparts (s=start, e=end).

Note: Utility classes such as space-x-*, space-y-*, gap-x-*, and gap-y-* are already logical and should be kept as-is.

Handling CSS Shorthand and Variables

Conversions must extend to complex and indirect style definitions:

1. CSS Shorthand: For 2-value, 3-value, or 4-value margin and padding shorthands, conversion is mandatory if the left and right values are asymmetric (different).

   • Example: If you have padding: 10px 20px 30px 5px; (Top Right Bottom Left), you must rewrite it using logical properties: padding-block: 10px 30px; padding-inline-start: 5px; padding-inline-end: 20px;

2. Code Styling: Audit and convert physical properties found in:

   • Inline styles (in templates like JSX, ERB, Liquid).

   • CSS-in-JS/Style Objects (e.g., { marginLeft: '10px' } must become { marginInlineStart: '10px' }).

3. Animations/Transitions: Replace left or right within animation keyframes or transition properties with their inset-inline-* equivalents.

4. CSS Variables: Review and update CSS variables that are defined with or reference physical directional properties.

Icon and Directional Asset Mirroring

While logical CSS properties automatically handle layout flipping, certain directional UI elements — such as navigation arrows, chevrons, or progress indicators — must be mirrored manually in RTL layouts.

For example, a Back button should point left in LTR mode and right in RTL mode.

Implementation Example (React with i18next):

import { useTranslation } from "react-i18next";
import { LeftArrow, RightArrow } from "@/icons";

const { t, i18n } = useTranslation();

const BackButtonIcon = i18n.dir() === "ltr" ? LeftArrow : RightArrow;

<Button
  icon={BackButtonIcon}
  label={t("back")}
  onClick={handleBack}
/>;

Notes:

• Use the i18n.dir() method (from libraries like i18next) or check the document.dir value to determine layout direction dynamically.

• Apply this rule to any directional icons such as:

  • Navigation arrows (Next/Back)

  • Play/Forward controls

  • Expand/Collapse indicators

  • Breadcrumb separators