Styling approaches for RTL and LTR writing directions

[jamieomaguire]

Terminology

1. Writing direction: Whether a language is read from left to right, or right to left.
2. RTL: Right to left
3. LTR: Left to right
4. Logical properties: These are CSS properties that handle layout logically, rather than directly referring to left, right, top and bottom.

Overview

When we style components, we want to ensure that they look correct for both RTL and LTR writing directions. This is usually a case of various elements being mirrored (which can mostly be handled by the browser when specifying a dir attribute on the html element).

There are some additional considerations, however. Browsers will not correct any directional styling applied by CSS. This means that if we use CSS such as float: left, padding-right: 24px or top: 1em, this can result in elements looking incorrect in an RTL context. Consider these visual examples below of a typical UI element—a media object.

Visual examples

In this first example, the text is flipped. However, the image is floated left and so it looks incorrect in RTL:

In this next example, the layout of the image correctly changes when the writing direction is RTL:

Images borrowed from rtlstyling.com

Another thing to factor in is keyboard navigation and general accessibility requirements. We should ensure that when a component supports RTL, the keyboard navigation and screenreader narration makes sense and follows an order that makes sense to the person interacting with the component.

Approaches

There are a number of ways in which RTL support can be achieved, each with its own pros and cons.

1. We could look into 3rd party libraries such as RTL CSS which automatically creates a new stylesheet for RTL languages.

2. We could write our CSS supporting LTR first, then manually apply RTL overrides where appropriate.

An example of this could be:

.media__image {
    float: left;
    margin-right: 16px;
    margin-left: 0px;
}

.media[dir="rtl] img {
    float: right;
    margin-right: 0;
    margin-left: 16px;
}

3. We could leverage newer CSS Logical properties, and write our styles in a way that 'just works' so long as the dir attribute is correctly set on the html tag.

An example of this could be:

.media__image {
    float: inline-start;
    margin-inline-start: 0;
    margin-inline-end: 16px;
}

4. In some cases, we could pass in an RTL flag to components if the writing direction would affect the markup or logic of a component

Proposal

Having spoken with some engineers at JET who have worked in this space previously, we believe that the most effective approach would be a hybrid of the following:

• We request that consumers of our components correctly set a dir attribute on their html element with a RTL or LTR value like so: dir="rtl"
• Leverage CSS Logical Properties to reduce the need for RTL-specific styling overrides
• Pass in an RTL flag to components that require some additional logic enhancements when the writing direction is changed (only where appropriate)
• Apply a very minimal dose of RTL style overrides for CSS which cannot be handled by Logical Properties, such as transform: translate()

We believe that a combination of the above will cater to most if not all of our needs when building and styling components that support RTL.

The benefits will be:

• Minimal CSS
• No overhead of integrating a 3rd party library or needing build processes/transforms
• Full control over our CSS
• Flexibility when more complex changes are required for RTL support

Actions to take if the proposal is accepted

• Investigate linting tools that could encourage engineers to utilise logical properties instead of dimensional CSS such as padding-left
• Investigate storybook RTL support and visual testing
• Create a page on our PIE Docs site that outlines our approach to RTL design and development

Summary

We would love to hear people's thoughts on the above proposal. We are still in the early stages and can adjust our proposal based on these discussions, so please leave us feedback!

Useful resources

• A great intro to CSS Logical Properties and RTL styling by Adrian Roselli
• A nice supplementary article from CSS tricks
• An overview of a number of ways to tackle RTL styling, including logical properties

[xander-marjoram]

Thanks for putting this together @jamieomaguire!

Fixed!
A small question: When we say writing mode, should we instead refer to writing direction? The existing CSS writing-mode doesn't differentiate between LTR and RTL, but rather between horizontal, vertical and the flow of text through the block rather than inline.

Overall I'm definitely in favour of learning to use CSS logical properties wherever possible for a number of reasons, on top of the ones you gave:

1. It's very easy to switch from the more common CSS properties.
2. Migrating to logical properties doesn't have to all be done at once, it can be done component-by-component, file-by-file, or even line-by-line.
3. It forces us LTR-natives to consciously consider how the styles will appear for RTL users.

We would need to make sure we have a way of making sure that direction-specific CSS properties like margin-left are caught in PRs or sooner. Fortunately it looks like there are linting packages available for this.

There is also the :dir() CSS pseudo-selector which could be quite useful, I think there is some distinction between that and using an attribute selector ([dir="rtl"]).

[jamieomaguire]

Thanks @xander-marjoram, yes that's a great point about writing mode. I will update the original post to swap out the terms.

Fully agree with your other points too. I think linting would be a great way to encourage a paradigm shift to this way of creating layouts.

I'm intrigued to know what that pseudo-selector offers, it sounds good. We could potentially use that instead of the attribute selector in the proposal above.

[ashleynolan]

Agree with the linting suggestions – I think catching this automatically during dev would be really useful.

Re the :dir() pseudo-selector – do we think this would potentially replace having to set dir="rtl"?

[jamieomaguire]

@ashleynolan my understanding is the attribute and pseudo selector are doing different things.

dir="rtl" on the HTML sets the direction for the entire document

dir(rtl) { } is applying styles only when the dir has been set to the value provided. In this case, I imagine it would replace any CSS like this: [dir="rtl"]. It's not actually setting anything.

[kevinrodrigues]

@jamieomaguire thanks a lot for putting this together.

I agree with the approaches here. Just a couple bits:

1. For the part under "Actions to take if the proposal is accepted" I think we need an area somewhere to document how to approach RTL maybe? So developers have an area to read up on our guidelines. I think we mentioned the pie doc site?

2. The default html direction is usually LTR so maybe we just need RTL supported tenants/teams to set that only. Also worth considering auto.

3. For the props (JS) passed to components where we need to be able to handle cases which can't be controlled by css, it would be good to try and come up with a universal prop name to keep it consistent across components (something to consider later tho).

4. The linter point around logical properties is a good one. Only concern is we might need to refactor the repo as linting may fail once added, unless we limit on a component basis. Or we can set it to warn, something to consider.

5. For RTL styles within components we should try and separate out the style somehow, having a separate file or directory that's injected for RTL will help keep the css limited within the component.

[jamieomaguire]

Thanks @kevinrodrigues, great point I completely forgot about! I've added an action to create a Docs site page.

I think only specifying dir as rtl could potentially be simpler, for sure. It would be interesting to see how auto would affect the CSS. We'd need to test that.

Fully agree with point 3.

Yeah, I expect we could set the linter to warn and incrementally update parts of the monorepo. Big refactors around this stuff could indeed be risky and there isn't much to gain from rushing it.

I'm intrigued about point 5. We actually have a talk with the team next week in which we're going to discuss some of our ideas around organising styles for web components. Perhaps this point could feed into that discussion?

[xander-marjoram]

Setting the linting to warn initially, then to error once everything is fixed sounds like a good approach.

[fernandofranca]

Awesome! Thanks for sharing.

[LTurns]

@jamieomaguire thanks for this ❤️

Looks good to me and I'm keen to learn more about CSS logical properties!

My main thoughts were it's interesting that JET doesn't have a process for this already! But you covered this by talking to other engineers in that space 😄

My second thought is I suppose we need to be extra clear with making sure people add the dir="rtl" in the consuming apps. Unlike a required prop, there won't be anything preventing them from forgetting to add it - so just making sure the docs are super clear about that

[jamieomaguire]

Thanks @LTurns, fully agree. We'd need some clear documentation. I'd be keen for us to have a dedicated page on the PIE docs site, as well as in the component readmes

[jamieomaguire]

Another thought I've had:

• We should update our Typography page on the docs site to include a code example of how we can set up/fall back to an appropriate RTL font-family.

An example of this can be seen here

[ashleynolan]

Just to add to this – the current JET Sans Digital fontset should be RTL ready, as long as people are using the extended-subset (which includes characters for hebrew and other RTL languages).

[JoshuaNg2332]

Thanks @jamieomaguire! This looks awesome!
Lots of points that I had have been covered in the comments like documenting our approach and also how we can make sure that consuming teams do actually follow this convention moving forward and not forgetting to add the dir="rtl".

I think from a visual testing perspective, it shouldn't be difficult to cover.

Couple of points that may be me looking a little more down the road and maybe not a discussion for here.
Do we feel/know if this RTL work will extend to more than just our writing direction?
I know its early days but do we feel that this is a good time to take into consideration future components. Not necessarily about implementation but thinking about how we want to take into consideration all the different aspects of RTL web design.
Just did a little reading into this this morning and found this and thought it was quite insightful about how many more things go into RTL specific designs on web.

[jamieomaguire]

Thanks @JoshuaNg2332!

Yeah, absolutely. I'm working together with Naz who is researching this on the design side. Looking at the article you linked, I am confident we'll have covered all of those example cases and a few more.

Just for fun, here is an example of how you could (quite catastrophically) remind people to add dir attributes to their HTML. Simply create some CSS and ask people to install it as a dependency (as part of a CSS library, perhaps).

Disclaimer - we wouldn't actually do this, but it's a fun demo of how we can use CSS to highlight issues in markup.

[dandel10n]

Great proposal Jamie!

I agree with using CSS Logical Properties with minimal overrides when building new components but for snacks and fozzie components it will mean a lot of manual updates. Do we have a deadline for this? Maybe we can use some tools like https://rtlcss.com/ to automatically mirror directional CSS properties and generate a separate stylesheet for RTL?

[jamieomaguire]

Thanks @dandel10n!

Yes funnily enough the engineers we spoke to had used RTLCSS when they were doing this too. I expect if we need to retro-fit this support for Snacks and Fozzie, this might be the way.

I am unsure if there is going to be a requirement for Fozzie but certainly for Snacks. I am unaware of any deadline at the moment 😃

RTLCSS seemed quite good for handling styling at the application level but we were unconvinced about it for a component-level implementation. We'd need some extensive testing in place if we're going to let the library write the CSS for us too.

[sebastienrocks]

Looks like a very good approach to handling RTL. Great work!

One thing I would see us doing going forward is paying close attention to our CSS Logical Properties. Hopefully a linting tool will solve this, but rather than encourage, I'd propose we enforce it, so we can be sure all of our future web components have RTL support.

We should also consider documenting this, once signed off, in any styleguides we may have, to ensure the information is available to all new-joiners, as it will be a different way of styling for most.

We may also want to backlog a spike to test out RTLCSS on snacks or fozzie, to understand any limitations if we need to go down that route

[jamieomaguire]

Thanks @sebastienrocks, I think linting to enforce could eventually be ideal!

Regarding the RTLCSS spike, that's definitely going to be the next step for Snacks. We don't have the same requirement for Fozzie so it's less of a concern for that repo 👍