From c3ea9c49e646c67788e901bfb17d8b1fcb7f604a Mon Sep 17 00:00:00 2001
From: Stephanie Hobson <stephaniehobson@users.noreply.github.com>
Date: Thu, 10 Sep 2026 14:08:34 -0700
Subject: [PATCH] Convert includes/ and base/ to CSS logical properties (#1084)

First pass of the logical-properties migration -- establishes the
conversion pattern the rest of the workstream follows, and removes
23 of the 127 remaining @include bidi() calls.

  includes/mixins/_utils.scss     (0 bidi, 2 physical: text-align kept
                                    physical -- see note below; inset:0
                                    shorthand for a symmetric all-sides
                                    absolute-position reset)
  includes/mixins/_details.scss   (2 bidi -> padding-inline-end,
                                    inset-inline-end)
  includes/forms/index.scss       (1 bidi -> inset-inline-start;
                                    this was the form-msg-pointer
                                    mixed-decls warning noted as
                                    deferred back in the mixed-decls
                                    PR -- confirmed fixed)
  base/elements/_lists.scss       (8 bidi -> margin-inline-start,
                                    all identical margin-left/right
                                    swap pattern; also collapsed two
                                    margin-left+margin-right !important
                                    pairs to margin-inline !important)
  base/elements/_forms.scss       (2 bidi -> padding-inline-end; the
                                    select rule's background-position
                                    kept physical with an explicit
                                    [dir='rtl'] override -- background-
                                    position has no standard logical
                                    keyword syntax safe for this
                                    matrix -- but its accompanying
                                    padding tuple did convert cleanly
                                    to padding-block + padding-inline)
  base/elements/_links.scss       (2 bidi -> margin-inline shorthand)
  base/elements/_tables.scss      (2 bidi -> text-align: start; also
                                    removed a redundant plain
                                    text-align: left that duplicated
                                    the LTR half of the old bidi call)
  base/elements/_quotes.scss      (1 bidi -> border-block-width +
                                    border-inline-*-width, since there's
                                    no single logical shorthand for all
                                    four border-width sides at once)
  base/elements/_details.scss     (1 bidi -> padding-inline, symmetric
                                    zero on both sides)
  base/utilities/_rich-text.scss  (4 bidi -> margin-inline-start, same
                                    swap pattern as _lists.scss)

Left _utils.scss's image-replaced mixin's text-align: left alone --
it also hardcodes direction: ltr, so it's intentionally fixed
regardless of page direction (an old image-replacement technique for
hiding text completely), not a case of missing RTL support. Using
text-align: start there would be misleading, implying adaptiveness
that was deliberately designed out.

Caught a real bug before it shipped: moving @include forms.form-input
to the end of the select rule would have fully silenced its last 2
mixed-decls warnings, but form-input() also sets a plain
padding: $field-padding shorthand -- moving it after my new
padding-inline/padding-block would let that shorthand win the cascade
and silently remove the space reserved for the dropdown caret icon.
Reverted to form-input's original early position; the 2 warnings stay
deferred (same conclusion the mixed-decls PR reached), but the actual
rendered padding is unaffected.

Found a second, related bug via a real visual regression report
(label.mzp-u-inline in _forms.scss): the original bidi() call used a
full 4-value padding shorthand (0 $spacing-sm 0 0), which explicitly
zeroed padding-bottom -- overriding the $label-v-spacing bottom
padding that forms.field-label() sets unconditionally on every
<label>. My first-pass conversion to padding-inline-end alone dropped
that override, so the label picked the mixin's padding-bottom back up.
Fixed by adding padding-block-end: 0 alongside padding-inline-end.
Systematically re-audited every other bare "padding"/"margin"-shorthand
bidi() conversion in this file for the same class of bug (a dropped
side silently falls back to some *other* rule's non-zero value rather
than the CSS-initial 0) -- the border-width conversion in _quotes.scss
already covered all four sides explicitly and wasn't affected.

Every conversion verified against a before/after sass compile diff of
both protocol.scss and protocol-components.scss -- confirmed each
logical property produces byte-identical LTR and RTL output to the
physical-plus-[dir=rtl]-override pair it replaced.

Stacked on v23/focus-visible-forms. Part of #1084.

Verified: npm run lint, npm test (47 specs, Firefox + Chrome),
npm run build-docs (523 items, no errors), npm run build-package, and
the before/after compile diff described above all pass.
---
 CHANGELOG.md                                  |  5 +++++
 .../sass/protocol/base/elements/_details.scss |  2 +-
 .../sass/protocol/base/elements/_forms.scss   | 14 +++++++-----
 .../sass/protocol/base/elements/_links.scss   |  4 ++--
 .../sass/protocol/base/elements/_lists.scss   | 22 +++++++++----------
 .../sass/protocol/base/elements/_quotes.scss  |  4 +++-
 .../protocol/base/utilities/_rich-text.scss   |  8 +++----
 .../sass/protocol/includes/forms/index.scss   |  2 +-
 .../protocol/includes/mixins/_details.scss    |  5 ++---
 .../sass/protocol/includes/mixins/_utils.scss |  5 +----
 10 files changed, 38 insertions(+), 33 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 1e9136f62..0955f0531 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -49,6 +49,11 @@ Introducing theme variables! CSS variables beginning with `--theme-` will adjust
   * Added status color variables (`--theme-color-success-*`, `--theme-color-error-*`, `--theme-color-warning-*`, `--theme-color-info-*`)
 * Removed Sass color variables from `_themes-sass.scss` (use CSS variables instead)
 
+### CSS Logical Properties
+
+* Started migrating physical directional properties (`margin-left`, `padding-right`, `text-align: left`, etc.) to their logical equivalents (`margin-inline-start`, `padding-inline-end`, `text-align: start`, etc.), which adapt to RTL languages automatically instead of needing a `[dir='rtl']` override or the internal `bidi()` Sass mixin. First pass covers `includes/mixins/_utils.scss`, `includes/mixins/_details.scss`, `includes/forms/index.scss`, and `base/elements/_forms.scss`, `_lists.scss`, `_links.scss`, `_tables.scss`, `_quotes.scss`, `_details.scss`, and `base/utilities/_rich-text.scss`. Components follow in subsequent PRs, ending with the removal of `bidi()` itself.
+* Where a property has no logical equivalent that's safe across the supported browser matrix (e.g. `background-position` for a decorative icon), kept the physical value with an explicit `[dir='rtl']` override rather than forcing an incomplete conversion.
+
 ## Component changes
 
 ### Feature Card
diff --git a/assets/sass/protocol/base/elements/_details.scss b/assets/sass/protocol/base/elements/_details.scss
index b63b158fb..64a9d1ec5 100644
--- a/assets/sass/protocol/base/elements/_details.scss
+++ b/assets/sass/protocol/base/elements/_details.scss
@@ -17,7 +17,7 @@ details .is-summary button,
 
 // Override styling the native element when the polyfill is applied (issue #658)
 summary.is-summary {
-    @include bidi(((padding-right, 0, padding-left, 0),));
+    padding-inline: 0;
 
     &::before {
         display: none;
diff --git a/assets/sass/protocol/base/elements/_forms.scss b/assets/sass/protocol/base/elements/_forms.scss
index 8f74a801a..0e4b22a15 100644
--- a/assets/sass/protocol/base/elements/_forms.scss
+++ b/assets/sass/protocol/base/elements/_forms.scss
@@ -114,7 +114,8 @@ label {
 
     &.mzp-u-inline {
         display: inline;
-        @include bidi(((padding, 0 $spacing-sm 0 0, 0 0 0 $spacing-sm),));
+        padding-block-end: 0;
+        padding-inline-end: $spacing-sm;
     }
 }
 
@@ -302,18 +303,21 @@ select {
     appearance: none;
     box-sizing: border-box;
     background-image: $url-image-caret-down-form, forms.$select-bg;
+    background-position: right 8px top 50%;
     background-repeat: no-repeat, repeat;
     background-size: 1em auto, 100%;
     display: block;
     font-weight: normal;
     max-width: 100%;
     min-width: forms.$field-min-width;
+    padding-block: forms.$field-padding;
+    padding-inline: forms.$field-padding forms.$symbol-spacing;
     text-overflow: ellipsis;
     @include forms.form-input;
-    @include bidi((
-        (background-position, right 8px top 50%, left 8px top 50%),
-        (padding, forms.$field-padding forms.$symbol-spacing forms.$field-padding forms.$field-padding, forms.$field-padding forms.$field-padding forms.$field-padding forms.$symbol-spacing),
-    ));
+
+    [dir='rtl'] & {
+        background-position: left 8px top 50%;
+    }
 
     // no down arrow on multi selects
     &[multiple] {
diff --git a/assets/sass/protocol/base/elements/_links.scss b/assets/sass/protocol/base/elements/_links.scss
index 295ec2e15..39aed65fe 100644
--- a/assets/sass/protocol/base/elements/_links.scss
+++ b/assets/sass/protocol/base/elements/_links.scss
@@ -84,11 +84,11 @@ a {
     }
 
     &-icon-start {
-        @include bidi(((margin-right, 0.5ch, 0), (margin-left, 0, 0.5ch),));
+        margin-inline: 0 0.5ch;
     }
 
     &-icon-end {
-        @include bidi(((margin-left, 0.5ch, 0), (margin-right, 0, 0.5ch),));
+        margin-inline: 0.5ch 0;
     }
 
 }
diff --git a/assets/sass/protocol/base/elements/_lists.scss b/assets/sass/protocol/base/elements/_lists.scss
index 6140dce2b..8977199e6 100644
--- a/assets/sass/protocol/base/elements/_lists.scss
+++ b/assets/sass/protocol/base/elements/_lists.scss
@@ -14,7 +14,7 @@ ol {
 
 ul.mzp-u-list-styled {
     list-style: disc;
-    @include bidi(((margin-left, $layout-sm, margin-right, 0),));
+    margin-inline-start: $layout-sm;
 
     li {
         margin-bottom: 0.25em;
@@ -23,19 +23,19 @@ ul.mzp-u-list-styled {
     ul {
         list-style: circle;
         margin-bottom: 0;
-        @include bidi(((margin-left, $layout-xs, margin-right, 0),));
+        margin-inline-start: $layout-xs;
     }
 
     ol {
         list-style: decimal;
         margin-bottom: 0;
-        @include bidi(((margin-left, $layout-xs, margin-right, 0),));
+        margin-inline-start: $layout-xs;
     }
 }
 
 ol.mzp-u-list-styled {
     list-style: decimal;
-    @include bidi(((margin-left, $layout-sm, margin-right, 0),));
+    margin-inline-start: $layout-sm;
 
     li {
         margin-bottom: 0.25em;
@@ -44,13 +44,13 @@ ol.mzp-u-list-styled {
     ol {
         list-style: lower-alpha;
         margin-bottom: 0;
-        @include bidi(((margin-left, $layout-xs, margin-right, 0),));
+        margin-inline-start: $layout-xs;
     }
 
     ul {
         list-style: disc;
         margin-bottom: 0;
-        @include bidi(((margin-left, $layout-xs, margin-right, 0),));
+        margin-inline-start: $layout-xs;
     }
 }
 
@@ -62,13 +62,13 @@ dl.mzp-u-list-styled {
 
     dd {
         margin-bottom: 0.25em;
-        @include bidi(((margin-left, $layout-xs, margin-right, 0),));
+        margin-inline-start: $layout-xs;
     }
 
     ul,
     ol {
         margin-bottom: 0;
-        @include bidi(((margin-left, $layout-xs, margin-right, 0),));
+        margin-inline-start: $layout-xs;
     }
 
     ul {
@@ -79,13 +79,11 @@ dl.mzp-u-list-styled {
 /* !important required to trump specificity and print stylesheet overrides */
 .mzp-u-list-unstyled {
     list-style: none !important; /* stylelint-disable-line declaration-no-important */
-    margin-left: 0 !important; /* stylelint-disable-line declaration-no-important */
-    margin-right: 0 !important; /* stylelint-disable-line declaration-no-important */
+    margin-inline: 0 !important; /* stylelint-disable-line declaration-no-important */
 
     ul,
     ol {
         list-style: none !important; /* stylelint-disable-line declaration-no-important */
-        margin-left: 0 !important; /* stylelint-disable-line declaration-no-important */
-        margin-right: 0 !important; /* stylelint-disable-line declaration-no-important */
+        margin-inline: 0 !important; /* stylelint-disable-line declaration-no-important */
     }
 }
diff --git a/assets/sass/protocol/base/elements/_quotes.scss b/assets/sass/protocol/base/elements/_quotes.scss
index fa3cc74ad..1d3d24ad2 100644
--- a/assets/sass/protocol/base/elements/_quotes.scss
+++ b/assets/sass/protocol/base/elements/_quotes.scss
@@ -6,13 +6,15 @@
 
 blockquote {
     @include text-heading-sm;
+    border-block-width: 0;
     border-color: $color-marketing-gray-20;
+    border-inline-end-width: 0;
+    border-inline-start-width: 5px;
     border-style: solid;
     color: var(--theme-heading-text-color);
     font-weight: bold;
     margin: $spacing-lg auto;
     padding: $spacing-sm $spacing-lg;
-    @include bidi(((border-width, 0 0 0 5px, 0 5px 0 0),));
 
     cite {
         @include text-heading-xs;
diff --git a/assets/sass/protocol/base/utilities/_rich-text.scss b/assets/sass/protocol/base/utilities/_rich-text.scss
index a95b5a2d1..0a8206527 100644
--- a/assets/sass/protocol/base/utilities/_rich-text.scss
+++ b/assets/sass/protocol/base/utilities/_rich-text.scss
@@ -55,7 +55,7 @@
 
     ul {
         list-style-type: disc;
-        @include bidi(((margin-left, $layout-sm, margin-right, 0),));
+        margin-inline-start: $layout-sm;
 
         ul {
             list-style-type: circle;
@@ -64,7 +64,7 @@
 
     ol {
         list-style-type: decimal;
-        @include bidi(((margin-left, $layout-sm, margin-right, 0),));
+        margin-inline-start: $layout-sm;
 
         ol {
             list-style-type: lower-roman;
@@ -75,7 +75,7 @@
         margin-bottom: 0.25em;
 
         ul, ol {
-            @include bidi(((margin-left, $layout-xs, margin-right, 0),));
+            margin-inline-start: $layout-xs;
         }
     }
 
@@ -86,7 +86,7 @@
 
     dd {
         margin-bottom: 0.25em;
-        @include bidi(((margin-left, $layout-xs, margin-right, 0),));
+        margin-inline-start: $layout-xs;
     }
 
     pre {
diff --git a/assets/sass/protocol/includes/forms/index.scss b/assets/sass/protocol/includes/forms/index.scss
index bee3eb207..7550f0c97 100644
--- a/assets/sass/protocol/includes/forms/index.scss
+++ b/assets/sass/protocol/includes/forms/index.scss
@@ -117,8 +117,8 @@ $line-height-shim: 0.15em; // two elements with text appear to have more space b
     bottom: 100%;
     content: '';
     height: 0;
+    inset-inline-start: 6px;
     position: absolute;
     width: 0;
     z-index: 1;
-    @include bidi(((left, 6px, right, auto),));
 }
diff --git a/assets/sass/protocol/includes/mixins/_details.scss b/assets/sass/protocol/includes/mixins/_details.scss
index d6f4d7e2a..75487728a 100644
--- a/assets/sass/protocol/includes/mixins/_details.scss
+++ b/assets/sass/protocol/includes/mixins/_details.scss
@@ -3,7 +3,6 @@
 // file, You can obtain one at http://mozilla.org/MPL/2.0/.
 
 @use '../tokens';
-@use 'bidi';
 @use 'images';
 
 @mixin details {
@@ -28,12 +27,13 @@
 }
 
 @mixin summary {
+    padding-inline-end: tokens.$layout-md;
     position: relative;
-    @include bidi.bidi(((padding-right, tokens.$layout-md, padding-left, 0),));
 
     &::before {
         background: images.$url-image-expand-black top left no-repeat;
         background-size: 20px, 20px;
+        inset-inline-end: 8px;
         transition: transform 100ms ease-in-out;
         content: '';
         height: 20px;
@@ -41,7 +41,6 @@
         position: absolute;
         top: 50%;
         width: 20px;
-        @include bidi.bidi(((right, 8px, left, auto),));
     }
 }
 
diff --git a/assets/sass/protocol/includes/mixins/_utils.scss b/assets/sass/protocol/includes/mixins/_utils.scss
index 40db95b87..c1ff44759 100644
--- a/assets/sass/protocol/includes/mixins/_utils.scss
+++ b/assets/sass/protocol/includes/mixins/_utils.scss
@@ -81,11 +81,8 @@
     iframe,
     object,
     embed {
-        bottom: 0;
-        left: 0;
+        inset: 0;
         position: absolute;
-        right: 0;
-        top: 0;
     }
 }