wordpress-mobile / wordpress-mobile/GutenbergKit

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

Open
#564 1 comment 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

[Type] Build Tooling Good First Issue Gutenberg
Dominant language
JavaScript
Stars
29
Forks
6
Avg merge
1d 9h
Merged PRs (30d)
41

Description

What problem does this address?

GutenbergKit's own SCSS is never processed by rtlcss. Gutenberg's stylesheets ship pre-generated -rtl variants, and the editor now loads whichever matches the text direction, but our own styles under src/ have no such counterpart — a physical property written there stays physical in both directions.

That produced a real bug during RTL testing: .gutenberg-kit-editor-toolbar .components-toolbar-group used border-right-color, which put the toolbar group divider on the wrong side in right-to-left layouts. It was found by eye, and nothing prevents the next one.

There is currently no stylelint setup in the repo at all — no config, no dependency, no lint:css script, no Makefile target — so this class of bug has no automated guard.

What is your proposed solution?

Add stylelint with stylelint-plugin-logical-css, matching how upstream Gutenberg catches the same problem (tools/stylelint/config.js).

Setup

  • Dependencies: stylelint, stylelint-plugin-logical-css, @wordpress/stylelint-config, postcss-scss
  • .stylelintrc.mjs extending @wordpress/stylelint-config/scss, enabling plugin/use-logical-properties-and-values
  • Reuse upstream's ignore list, which exempts vertical and direction-neutral properties (margin-top, width, overflow-y, border-top, …)
  • lint:css / lint:css:fix scripts in package.json, plus lint-css / lint-css-fix Makefile targets matching the existing lint-js pattern
  • Run lint-css wherever CI runs lint-js

Existing violations

The asymmetric cases that actually misrendered have already been fixed. What remains across the 11 SCSS files under src/:

  • 15 physical-property declarations, all symmetric pairs (padding-left: 8px; padding-right: 8px, margin-left: auto; margin-right: auto, border-left: none; border-right: none) or text-align: center. None misrender in RTL, but the rule will flag them because it cannot tell a symmetric pair is direction-safe. Converting to the shorthand (padding-inline: 8px) is mechanical and arguably cleaner.
  • 10 left/right positioning declarations that are symmetric full-width pins (left: 0; right: 0, left: 16px; right: 16px). Same situation — safe today, flagged by the rule, trivially convertible to inset-inline.

Two further left/right declarations in the toolbar scroll indicators are not symmetric and need their own investigation — tracked separately.

Notes

Whether this is worth the setup cost depends on how much RTL work follows. If right-to-left is now a supported dimension people will keep touching, the linter is what keeps it from regressing; it would also catch other WordPress CSS conventions as a side benefit.

Related: the RTL support work in the branch that fixed the original border-right-color bug.

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start by comparing the proposed setup with upstream Gutenberg's tools/stylelint/config.js, then inspect package.json, the Makefile, CI's existing lint-js path, and the 11 SCSS files under src/. Define the stylelint configuration, scripts, targets, and CI invocation, then convert the listed symmetric violations. Done means lint:css and lint:css:fix work and CI runs lint:css without unresolved expected violations.

Written by the indexing model from the issue text.

Assessment

Tech stack
scss
Domain
ci-cd, frontend, internationalization, tooling
Issue type
Feature
Difficulty
4/5
Estimated time
3-5 days
Activity status
Active
Clarity
Mostly clear
Newbie friendliness
66/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.