Skip to content

build: add stylelint for RTL-unsafe logical CSS properties - #608

Open
akashfer wants to merge 1 commit into
wordpress-mobile:trunkfrom
akashfer:feat/stylelint-logical-css-rtl
Open

build: add stylelint for RTL-unsafe logical CSS properties#608
akashfer wants to merge 1 commit into
wordpress-mobile:trunkfrom
akashfer:feat/stylelint-logical-css-rtl

Conversation

@akashfer

Copy link
Copy Markdown

Fixes #564

What?

Adds a stylelint setup to GutenbergKit's SCSS, using stylelint-plugin-logical-css to flag physical (left/right/padding-left/etc.) properties that should be written as logical properties (inset-inline-start, padding-inline, etc.) for RTL correctness. Converts the ~29 existing violations the new rule flags to their logical equivalents.

Why?

GutenbergKit's own SCSS is never processed by rtlcss, and nothing currently guards against physical-property RTL bugs — one (border-right-color misplacing the toolbar divider) had to be found by eye during RTL testing. There was no stylelint setup at all: no config, no dependency, no lint:css script, no Makefile target.

How?

  • Added stylelint, stylelint-plugin-logical-css (pinned to ^1.2.3, matching the version upstream Gutenberg pins in tools/stylelint/config.js — v2 renamed the rule this issue asks for), @wordpress/stylelint-config, and postcss-scss as dev dependencies.
  • Added .stylelintrc.mjs extending @wordpress/stylelint-config/scss and enabling plugin/use-logical-properties-and-values, reusing upstream's ignore list for properties that don't affect RTL (margin-top, width, overflow-y, border-top, etc.).
  • The base @wordpress/stylelint-config/scss ruleset is otherwise stricter than this codebase's existing conventions (BEM-style double-underscore class names, blank-line formatting, specificity ordering). Relaxed the same rules upstream's own config relaxes for the same reason, to keep this PR scoped to the logical-properties rule rather than a repo-wide style rewrite.
  • Added lint:css / lint:css:fix npm scripts and matching lint-css / lint-css-fix Makefile targets, mirroring the existing lint-js pattern.
  • Wired lint-css into the Buildkite pipeline alongside lint-js, including the release-gate depends_on list.
  • Converted the ~29 flagged declarations (all symmetric left/right pairs, or single vertical properties like scroll-padding-bottom) to their logical equivalents.
  • Two declarations in the toolbar's scroll-indicator gradients (::before/::after) are not a symmetric pair — they're the left- and right-scroll affordances, and whether they should flip in RTL needs its own investigation. Left those physical with an inline stylelint-disable-next-line and a comment, rather than guessing at a fix.
  • Along the way, fixed a handful of small pre-existing issues the new linter surfaced independent of RTL (a dead duplicate position: absolute overridden by a later position: fixed !important, two duplicate selector blocks that can merge into one, three 0px0 unit cleanups, and a few non-shorthand/named colors).

Testing Instructions

  1. npm run lint:css (or make lint-css) — should pass with no errors.
  2. make lint-js / make test-js / make build — included here to confirm the change doesn't affect JS lint, unit tests (227 passing), or the Vite build.
  3. Spot-check the converted rules still render correctly, e.g. the fixed toolbar (src/components/editor-toolbar/style.scss) and the visual editor toolbar/error boundary (src/components/visual-editor/style.scss) in both LTR and RTL (?lang=ar or similar).

Accessibility Testing Instructions

No UI/behavior changes — this is a build-tooling and CSS-property-name change only; visual output is unchanged (logical properties resolve to the same physical box-model values in LTR, which is this project's current default and only tested direction).

GutenbergKit's SCSS was never linted for physical left/right
properties, so a direction-specific bug (border-right-color on the
toolbar) had to be found by eye. Add stylelint with
stylelint-plugin-logical-css, mirroring the setup and ignore list
upstream Gutenberg uses in tools/stylelint/config.js, and wire
lint:css / lint-css into npm scripts, the Makefile, and CI alongside
lint:js / lint-js.

Also converts the ~29 existing physical-property declarations the
new rule flags to their logical equivalents. Two declarations in the
toolbar's scroll-indicator gradients are not a symmetric pair and are
left physical with a stylelint-disable, pending separate investigation
into their RTL behavior.

The base @wordpress/stylelint-config/scss ruleset is otherwise
stricter than this codebase's existing conventions; the
selector-naming, blank-line, and specificity-ordering rules it would
also enable are relaxed the same way upstream's own config relaxes
them, to keep this change scoped to the logical-properties rule.
@akashfer
akashfer requested a review from a team as a code owner August 27, 2026 19:48
@github-actions github-actions Bot added the [Type] Build Tooling Issues or PRs related to build tooling label Aug 27, 2026
@AliSoftware
AliSoftware requested a review from dcalhoun August 28, 2026 09:37
@AliSoftware

AliSoftware commented Aug 28, 2026

Copy link
Copy Markdown
Contributor

In terms of infra/tooling (Makefile change & package.json changes) the changes looks ok to me.
But in terms of the CSS changes, I'm adding @dcalhoun as reviewer because he'll probably be more knowledgable in the changes this PR makes to the CSS properties in the GutenbergKit's code itself than our team would.

@dcalhoun

Copy link
Copy Markdown
Member

@akashfer thank you for exploring this. It may take me a little while to begin review of this, but hopefully I can next week. I'll follow up.

@akashfer

Copy link
Copy Markdown
Author

Okay thanks

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

[Type] Build Tooling Issues or PRs related to build tooling

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Add stylelint with logical-property rule to catch RTL styling bugs

3 participants