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.

1. 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).

2. 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

3. 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.

4. 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.