🛡️ RTL Shield

Automated ESLint guardrails for robust RTL support in the GCC market.

⚠️ The Problem

In the Middle East and North Africa (MENA) region, Arabic and other RTL (Right-to-Left) languages represent a massive market opportunity. However, many engineering teams still build with physical CSS properties like left, right, marginLeft, and paddingRight—properties that fundamentally break bidirectional layouts.

Why This Matters

• Physical properties are direction-specific: left: 10px means "move 10px from the left edge"—in RTL, this is visually incorrect.
• Manual reviews are error-prone: CSS property mapping is tedious and easy to overlook in code reviews.
• Scale is impossible: As codebases grow, maintaining RTL consistency becomes exponentially harder without automation.
• Lost revenue: Poorly localized experiences drive users away from your platform.

RTL Shield solves this at the source—by enforcing logical CSS properties during development, ensuring your application is RTL-ready before it ships.

✨ Key Features

🎨 CSS-in-JS & Style Objects

Full support for React, Next.js, and JavaScript style objects (Emotion, Styled Components, inline styles, etc.)

• Automatically detects and fixes physical properties
• Works with object literals in JavaScript
• Smart autofix saves hundreds of manual hours

🌬️ Tailwind CSS Support

Seamlessly handles Tailwind utility classes in className and class attributes

• Converts ml-4 → ms-4, text-left → text-start
• Processes multiple classes in a single string
• Fully compatible with Next.js and modern React projects

🔄 Comprehensive Property Mapping

Covers the full spectrum of directional CSS:

• Margins & Padding: marginLeft → marginInlineStart
• Positioning: left → insetInlineStart, right → insetInlineEnd
• Borders: All variants—borderLeft, borderLeftWidth, borderLeftColor, etc.
• Border Radius: Complex radius properties like borderTopLeftRadius → borderStartStartRadius

⚡ Smart Autofix

One command to fix your entire codebase:

eslint --fix

No manual intervention required—just commit and deploy.

🎯 Zero Configuration

The recommended preset works out-of-the-box with sensible defaults.

📦 Installation

Step 1: Install the Plugin

npm install --save-dev eslint-plugin-rtl-shield
# or
yarn add --dev eslint-plugin-rtl-shield
# or
pnpm add --save-dev eslint-plugin-rtl-shield

Step 2: Configure ESLint

Add the plugin to your ESLint configuration file (.eslintrc.json, .eslintrc.js, or eslint.config.js):

Using the Recommended Config (Recommended ✅)

{
  "extends": ["plugin:rtl-shield/recommended"]
}

This automatically enables both rules with error-level severity:

• rtl-shield/prefer-logical-properties — for CSS-in-JS
• rtl-shield/prefer-logical-tailwindcss — for Tailwind CSS

Manual Configuration

If you prefer granular control:

{
  "plugins": ["rtl-shield"],
  "rules": {
    "rtl-shield/prefer-logical-properties": "error",
    "rtl-shield/prefer-logical-tailwindcss": "error"
  }
}

Step 3: Run ESLint

Lint your project:

eslint .

Auto-fix issues:

eslint --fix .

📊 Showcase: Physical vs. Logical

CSS-in-JS / Style Objects

| Physical (❌ Breaks RTL) | Logical (✅ RTL-Ready) | Use Case | | ------------------------- | ---------------------------- | --------------- | | marginLeft: 16 | marginInlineStart: 16 | Outer spacing | | paddingRight: 8 | paddingInlineEnd: 8 | Inner spacing | | left: 0 | insetInlineStart: 0 | Positioning | | right: 10 | insetInlineEnd: 10 | Positioning | | borderLeftWidth: 2 | borderInlineStartWidth: 2 | Border styling | | borderTopLeftRadius: 12 | borderStartStartRadius: 12 | Rounded corners |

Tailwind CSS

| Physical (❌ Breaks RTL) | Logical (✅ RTL-Ready) | Use Case | | ------------------------ | ---------------------- | ---------------------------- | | ml-4 | ms-4 | Margin start | | mr-8 | me-8 | Margin end | | pl-2 | ps-2 | Padding start | | pr-6 | pe-6 | Padding end | | text-left | text-start | Text alignment | | text-right | text-end | Text alignment | | rounded-tl-lg | rounded-ss-lg | Border radius (top-left) | | rounded-br-md | rounded-ee-md | Border radius (bottom-right) | | left-0 | start-0 | Positioning | | right-10 | end-10 | Positioning |

Before & After Example

Before (Physical Properties):

// ❌ Breaks in Arabic/RTL
const Card = () => (
  <div className="ml-4 p-4 rounded-tl-lg">
    <h1 style={{ paddingLeft: 16, textAlign: "left" }}>Title</h1>
  </div>
);

After (Logical Properties):

// ✅ Works perfectly in RTL
const Card = () => (
  <div className="ms-4 p-4 rounded-ss-lg">
    <h1 style={{ paddingInlineStart: 16, textAlign: "start" }}>Title</h1>
  </div>
);

🌍 Why for the GCC Market?

The GCC region (United Arab Emirates, Saudi Arabia, Qatar, Kuwait, Bahrain, and Oman) represents one of the fastest-growing digital markets:

• High-value market: GCC users have the highest digital spending in the MENA region
• Native RTL requirement: Arabic is a constitutional requirement in government and enterprise apps
• Business critical: Improper RTL support directly impacts user trust and platform adoption
• Regulatory compliance: Many GCC-based companies must meet localization standards
• Competitive advantage: Teams that ship proper RTL support get better retention and market share

RTL Shield enables your engineering team to:

• Ship RTL-ready code from day one
• Reduce localization QA cycles
• Avoid expensive refactoring late in the project lifecycle
• Build products that resonate with users across the MENA region

📋 Rules

prefer-logical-properties

Enforces logical CSS properties in JavaScript style objects, preventing physical properties that break bidirectional layouts.

Type: Suggestion Fixable: Yes ✅

Example:

// ❌ Error
const styles = { marginLeft: 10, borderRightColor: "red" };

// ✅ Correct
const styles = { marginInlineStart: 10, borderInlineEndColor: "red" };

prefer-logical-tailwindcss

Enforces logical Tailwind CSS utility classes in JSX className and class attributes.

Type: Suggestion Fixable: Yes ✅

Example:

// ❌ Error
<div className="ml-4 text-left rounded-tl-lg" />

// ✅ Correct
<div className="ms-4 text-start rounded-ss-lg" />

🚀 Quick Start

# 1. Install
npm install --save-dev eslint-plugin-rtl-shield

# 2. Add to .eslintrc.json
echo '{
  "extends": ["plugin:rtl-shield/recommended"]
}' > .eslintrc.json

# 3. Fix all files
npx eslint --fix .

# 4. Commit and deploy
git add .
git commit -m "chore: enforce RTL-safe logical properties"

📚 Resources

• MDN: CSS Logical Properties
• Tailwind CSS: Logical Properties
• W3C: Structural Markup and Right-to-Left Text in HTML

🤝 Contributing

We welcome contributions! Please feel free to open issues or submit pull requests on GitHub.

📄 License

MIT © 2025 Berkin Duz

💡 Support

Have questions or feedback? Open an issue on our GitHub repository.

Built with ❤️ for the GCC market and the broader MENA region.