corysanin/tubestation
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Bug 1825586 - Update RTL docs r=Gijs

Browse Source 
Differential Revision: https://phabricator.services.mozilla.com/D174136
This commit is contained in:
Itiel
2023-04-13 17:14:05 +00:00
parent 8626795607
commit 6da8219633
1 changed files with 123 additions and 51 deletions
Download Patch File Download Diff File Expand all files Collapse all files

174
docs/code-quality/coding-style/rtl_guidelines.rst
View File

@@ -24,40 +24,37 @@ When a UI is mirrored, these changes occur:
- Text is usually aligned to the right
In CSS, while it's possible to apply a rule for LTR and a separate one
specifically for RTL, it's usually better to use CSS Logical Properties
specifically for RTL, it's usually better to use CSS `Logical Properties <https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Logical_Properties>`_
which provide the ability to control layout through logical, rather than
physical mappings.
+----------------------------------+----------------------------------+
| Do | Don't do |
+==================================+==================================+
| ``margin-inline-start: 5px;`` | ``margin-left: 5px;`` |
+----------------------------------+----------------------------------+
| ``padding-inline-end: 5px;`` | ``padding-right: 5px;`` |
+----------------------------------+----------------------------------+
| ``float: inline-start;`` | ``float: left;`` |
+----------------------------------+----------------------------------+
| ``inset-inline-start: 5px;`` | ``left: 5px;`` |
+----------------------------------+----------------------------------+
| ``border-inline-end: 1px;`` | ``border-right: 1px;`` |
+----------------------------------+----------------------------------+
| ``border-{start | ``border-{top/bot |
| /end}-{start/end}-radius: 2px;`` | tom}-{left/right}-radius: 2px;`` |
+----------------------------------+----------------------------------+
| ``padding: 1px 2px;`` | ``padding: 1px 2px 1px 2px;`` |
+----------------------------------+----------------------------------+
| ``margin-block: 1px 3px;`` && | ``margin: 1px 2px 3px 4px;`` |
| ``margin-inline: 4px 2px;`` | |
+----------------------------------+----------------------------------+
| ``text-align: start;`` or | ``text-align: left;`` |
| ``text-align: match-parent;`` | |
| (depends on the context) | |
+----------------------------------+----------------------------------+
+---------------------------------------------------------+--------------------------------------------------+
| Do | Don't do |
+---------------------------------------------------------+--------------------------------------------------+
| ``margin-inline-start: 5px`` | ``margin-left: 5px`` |
+---------------------------------------------------------+--------------------------------------------------+
| ``padding-inline-end: 5px`` | ``padding-right: 5px`` |
+---------------------------------------------------------+--------------------------------------------------+
| ``float: inline-start`` | ``float: left`` |
+---------------------------------------------------------+--------------------------------------------------+
| ``inset-inline-start: 5px`` | ``left: 5px`` |
+---------------------------------------------------------+--------------------------------------------------+
| ``border-inline-end: 1px`` | ``border-right: 1px`` |
+---------------------------------------------------------+--------------------------------------------------+
| ``border-{start/end}-{start/end}-radius: 2px`` | ``border-{top/bottom}-{left/right}-radius: 2px`` |
+---------------------------------------------------------+--------------------------------------------------+
| ``padding: 1px 2px`` | ``padding: 1px 2px 1px 2px`` |
+---------------------------------------------------------+--------------------------------------------------+
| ``margin-block: 1px 3px`` && ``margin-inline: 4px 2px`` | ``margin: 1px 2px 3px 4px`` |
+---------------------------------------------------------+--------------------------------------------------+
| ``text-align: start`` or ``text-align: match-parent`` | ``text-align: left`` |
| (depends on the context) | |
+---------------------------------------------------------+--------------------------------------------------+
When there is no special RTL-aware property available, or when
left/right properties must be used specifically for RTL, use the pseudo
``:-moz-locale-dir(rtl)`` (for XUL files) or ``:dir(rtl)`` (for HTML
files).
``:-moz-locale-dir(rtl)`` (for XUL documents) or ``:dir(rtl)`` (for HTML
documents).
For example, this rule covers LTR to display searchicon.svg 7 pixels
from the left:
@@ -92,19 +89,22 @@ are displayed, particularly those depicting a sequence of events.
What to mirror
^^^^^^^^^^^^^^
- Icons that imply directionality like back/forward buttons
- Icons or animations that imply directionality or motion like
back/forward buttons or progress bars
- Icons that imply text direction, like
`readerMode.svg <https://searchfox.org/mozilla-central/rev/74cc0f4dce444fe0757e2a6b8307d19e4d0e0212/browser/themes/shared/reader/readerMode.svg>`__
`reader-mode.svg <https://searchfox.org/mozilla-central/rev/f9beb753a84aa297713d1565dcd0c5e3c66e4174/browser/themes/shared/icons/reader-mode.svg>`__
- Icons that imply location of UI elements in the screen, like
`sidebars-right.svg <https://searchfox.org/mozilla-central/rev/74cc0f4dce444fe0757e2a6b8307d19e4d0e0212/browser/themes/shared/icons/sidebars-right.svg>`__,
`open-in-new.svg <https://searchfox.org/mozilla-central/rev/74cc0f4dce444fe0757e2a6b8307d19e4d0e0212/browser/themes/shared/icons/open-in-new.svg>`__,
`default-theme.svg <https://searchfox.org/mozilla-central/rev/a78233c11a6baf2c308fbed17eb16c6e57b6a2ac/toolkit/mozapps/extensions/content/default-theme.svg>`__
`open-in-new.svg <https://searchfox.org/mozilla-central/rev/f9beb753a84aa297713d1565dcd0c5e3c66e4174/toolkit/themes/shared/icons/open-in-new.svg>`__,
`default theme's preview.svg <https://searchfox.org/mozilla-central/rev/f9beb753a84aa297713d1565dcd0c5e3c66e4174/toolkit/mozapps/extensions/default-theme/preview.svg>`__
or
`pane-collapse.svg <https://searchfox.org/mozilla-central/rev/74cc0f4dce444fe0757e2a6b8307d19e4d0e0212/devtools/client/debugger/images/pane-collapse.svg>`__
- Icons representing objects that are meant to be handheld should look
like they're being right-handed, like the `magnifying glass
icon <https://searchfox.org/mozilla-central/rev/e7c61f4a68b974d5fecd216dc7407b631a24eb8f/toolkit/themes/windows/global/icons/search-textbox.svg>`__
- Twisties in collapsed state (in RTL context only)
- Twisties in their collapsed state. Note that if the context in which
they appear is LTR (e.g. code in a devtools HTML view), they should
not be mirrored, even if the user might be using an RTL locale.
What NOT to mirror
^^^^^^^^^^^^^^^^^^
@@ -116,7 +116,7 @@ What NOT to mirror
buttons <https://searchfox.org/mozilla-central/rev/a78233c11a6baf2c308fbed17eb16c6e57b6a2ac/devtools/client/debugger/images/close.svg>`__
or the `bookmark
star <https://searchfox.org/mozilla-central/rev/a78233c11a6baf2c308fbed17eb16c6e57b6a2ac/browser/themes/shared/icons/bookmark-hollow.svg>`__
icon
icon, or any other symmetric icon
- Icons that should look the same as LTR, like icons related to code
(which is always LTR) like
`tool-webconsole.svg <https://searchfox.org/mozilla-central/rev/74cc0f4dce444fe0757e2a6b8307d19e4d0e0212/devtools/client/themes/images/tool-webconsole.svg>`__
@@ -131,16 +131,86 @@ What NOT to mirror
How
^^^
The most common way is by flipping the X axis:
The most common way to mirror images is by flipping the X axis:
.. code:: css
transform: scaleX(-1);
Or, if you're already using ``transform`` with a different value on the same
element, you can also use `scale`:
.. code:: css
scale: -1 1;
Note that mirroring images that way doesn't work when the image is a part of
an element with text using ``background-image``, because then the text would
be mirrored along with the image, and the image would be positioned incorrectly.
For such cases, try to use a different method for displaying the image,
like having it as an element all on its own.
If that's not possible, add a separate pre-mirrored image asset and specify
it in a separate ``:dir(rtl)`` rule:
.. code:: css
.element-with-icon {
background-image: url("path/to/image/image.svg");
}
.element-with-icon:dir(rtl) {
background-image: url("path/to/image/image-rtl.svg");
}
For animations like a progress bar, when using ``@keyframes`` to change
the ``transform: translateX()`` states, make sure to add a different
``@keyframes`` suited for RTL, and target that in a separate ``:dir()`` rule:
.. code:: css
#progressbar {
animation: progressbar-animation 1s linear infinite;
}
#progressbar:dir(rtl) {
animation-name: progressbar-animation-rtl;
}
@keyframes progressbar-animation {
0% {
transform: translateX(-100px);
}
100% {
transform: translateX(0);
}
}
@keyframes progressbar-animation-rtl {
0% {
transform: translateX(100px);
}
100% {
transform: translateX(0);
}
}
Likewise, if you're using ``transform-origin``, make sure to specify the
correct origin for RTL:
.. code:: css
#progressbar {
transform-origin: 0 0;
}
#progressbar:dir(rtl) {
transform-origin: 100% 0;
}
LTR text inside RTL contexts
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
By default, in RTL locales, some symbols like "/", "." will be moved
By default, in RTL locales, some symbols like ``/`` and ``.`` will be moved
around and won't be displayed in the order that they were typed in. This
may be problematic for URLs for instance, where you don't want dots to
change position.
@@ -148,7 +218,7 @@ change position.
Here's a non-exhaustive list of elements that should be displayed like
they would be in LTR locales:
- Paths (e.g., C:\Users\username\Desktop)
- Paths (e.g., C:\\Users\\username\\Desktop)
- Full URLs
- Code and code containers (like the DevTools' Inspector or the CSS
rules panel)
@@ -189,11 +259,12 @@ Here's a full code example:
direction: ltr; /* Force text direction to be LTR */
/* `start` (the default value) will correspond to `left`,
so we match the parent's direction in order to align the text to the right */
* so we match the parent's direction in order to align the text to the right */
text-align: match-parent;
}
/* :dir(ltr/rtl) isn't meaningful on .url, since it has direction: ltr, hence why it is matched on .container. */
/* :dir(ltr/rtl) isn't meaningful on .url, since it has direction: ltr, hence
* why it is matched on .container. */
.container:dir(ltr) .url {
padding-left: 1em;
}
@@ -225,21 +296,21 @@ Testing
~~~~~~~
To test for RTL layouts in Firefox, you can go to about:config and
set ``intl.l10n.pseudo`` to ``bidi`` or ``intl.uidirection`` to ``1``.
set ``intl.l10n.pseudo`` to ``bidi``, or select the ``Enable "bidi" locale``
option in the 3-dots menu in the :doc:`Browser Toolbox </devtools-user/browser_toolbox/index>`.
The Firefox UI should immediately flip, but a restart may be required
to take effect in some Firefox features and interactions.
.. note::
When testing with ``intl.uidirection`` set to ``1``, you may see some
When testing with ``intl.l10n.pseudo`` set to ``bidi``, you may see some
oddities regarding text ordering due to the nature of displaying LTR
text in RTL layout.
.. image:: about-protections-rtl.png
:alt: about:protections in RTL layout- English vs. Hebrew
This shouldn't be an issue when using an actual RTL locale or with
``intl.l10n.pseudo`` set to ``bidi`` .
This shouldn't be an issue when using an actual RTL build or language pack.
How to spot RTL-related issues
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -250,22 +321,23 @@ How to spot RTL-related issues
on the right side of the text, this probably means that the text
field is forced to be displayed as LTR.
- If icons/images/checkmarks do not appear on the opposite side of
text, when compared to LTR
text, when compared to LTR.
- If buttons (like the close button, "OK" and "Cancel" etc.) do not
appear on the opposite side of the UI and not in the opposite order,
when compared to LTR
when compared to LTR.
- If paddings/margins/borders are not the same from the opposite side,
when compared to LTR
- If on an Arabic or Persian build, digits are displayed as ``1 2 3``
and not ``١ ٢ ٣`` (note that Hebrew uses ``1 2 3``)
when compared to LTR.
- Although Hebrew uses ``1 2 3``, all the other RTL locales we support
should use ``١ ٢ ٣`` as digits. So if you see ``1 2 3`` on any such
locale, that likely indicates a bug.
- If navigating in the UI using the left/right arrow keys does not
select the correct element (i.e., pressing Left selects an item on
the right)
the right).
- If navigating in the UI using the Tab key does not focus elements
from right to left, in an RTL context
from right to left, in an RTL context.
- If code is displayed as RTL (e.g., ``;padding: 20px`` - the semicolon
should appear on the right side of the code). Code can still be
aligned to the right if it appears in an RTL context
aligned to the right if it appears in an RTL context.
See also
~~~~~~~~