Add namespace-spacing-utils rule #490

Copilot · 2026-01-23T09:02:39Z

Companion to Add namespaced styles to primers spacing css#2962, only release this after that is released
Towards https://github.com/github/primer/issues/6317

Summary: This PR adds a new ESLint rule namespace-spacing-utils that enforces namespacing of Primer CSS spacing utility classes (margin/padding) with the pr- prefix.

The rule:

Detects margin classes like m-4, mx-2, my-3, mt-1, etc.
Detects padding classes like p-4, px-2, py-3, pt-1, etc.
Handles negative spacing values like m-n4, mt-n2
Handles auto values like m-auto, mx-auto
Handles responsive variants like mx-sm-2, mx-md-4, p-lg-3 (Primer CSS format)
Provides autofix to add the pr- prefix automatically

Example transformations:

m-4 → pr-m-4
p-2 → pr-p-2
mx-md-4 → pr-mx-md-4

changeset-bot · 2026-01-23T09:02:43Z

⚠️ No Changeset found

Latest commit: aa07187

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

Co-authored-by: siddharthkp <1863771+siddharthkp@users.noreply.github.com>

siddharthkp · 2026-01-23T09:28:05Z

src/rules/__tests__/namespace-spacing-utils.test.js

+    '<div className={`pr-m-4 pr-p-2`} />',
+
+    // Responsive variants (already namespaced)
+    '<div className="md:pr-m-4" />',


@copilot This is the responsive format: .mx-sm-2 and .mx-md-4

Fixed in aa07187. Updated the regex pattern and tests to use the Primer CSS responsive format (mx-sm-2, mx-md-4, etc.) instead of the colon-separated format.

Co-authored-by: siddharthkp <1863771+siddharthkp@users.noreply.github.com>

Copilot

Pull request overview

This PR adds a new ESLint rule (namespace-spacing-utils) to enforce pr- namespacing for Primer CSS spacing utility classes (margin/padding), including responsive and negative/auto variants, with autofix support.

Changes:

Added the namespace-spacing-utils rule implementation for detecting un-namespaced spacing utility classes in className.
Added a comprehensive RuleTester suite for valid/invalid cases and autofix expectations.
Added rule documentation and exported the rule from the plugin entrypoint.

Reviewed changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated 6 comments.

File	Description
src/rules/namespace-spacing-utils.js	Implements detection + autofix for un-namespaced spacing utility classes.
src/rules/tests/namespace-spacing-utils.test.js	Adds test coverage for detection and fixes across many spacing patterns.
src/index.js	Registers the new rule in the plugin’s exported `rules` map.
docs/rules/namespace-spacing-utils.md	Documents the rule’s intent, patterns, and autofix behavior.

Copilot · 2026-01-23T13:03:38Z

docs/rules/namespace-spacing-utils.md

+
+## When to use autofix
+
+This rule includes an autofix that will automatically add the `pr-` prefix to unnamespaced spacing utility classes. The autofix is safe to use as it only modifies the class names that match the spacing utility patterns.


This section states the autofix is “safe to use”, but the current fixer implementation operates via substring replacement on the raw node text, which can rewrite non-spacing class names that contain m-*/p-* substrings, and may not fix multiple different spacing classes in one pass due to overlapping fixes. After adjusting the fixer to be boundary-aware and non-overlapping, update this wording (or qualify it) so the docs match the actual behavior.

Suggested change

This rule includes an autofix that will automatically add the `pr-` prefix to unnamespaced spacing utility classes. The autofix is safe to use as it only modifies the class names that match the spacing utility patterns.

This rule includes an autofix that will automatically add the `pr-` prefix to unnamespaced spacing utility classes. The autofix operates on individual class tokens and is designed to only modify class names that match the spacing utility patterns, but you should still review the changes before committing.

Copilot · 2026-01-23T13:03:39Z

src/rules/namespace-spacing-utils.js

+          fix(fixer) {
+            // Get the raw text of the value node
+            const rawText = sourceCode.getText(valueNode)
+
+            // Replace the unnamespaced class with the namespaced version
+            // Using replaceAll to handle multiple occurrences of the same class
+            const fixedText = rawText.replaceAll(original, replacement)
+            return fixer.replaceText(valueNode, fixedText)


Autofix currently does a plain rawText.replaceAll(original, replacement) on the entire Literal/TemplateElement text. This can incorrectly rewrite other class names that merely contain the substring (e.g. fixing m-4 would also change my-m-4), and it also makes every report replace the whole node so fixes overlap and ESLint will apply at most one of them. Consider generating a single fixed string using a boundary-aware regex (or tokenizing on whitespace) and returning the same full-node fix for every report (or reporting once per node) so --fix reliably namespaces all matching classes without touching unrelated substrings.

Copilot · 2026-01-23T13:03:39Z

src/rules/namespace-spacing-utils.js

+//          p-{size}, px-{size}, py-{size}, pt-{size}, pr-{size}, pb-{size}, pl-{size}
+// Sizes: 0-12, auto, n1-n12 (negative)
+// Responsive variants: mx-sm-2, mx-md-4, etc. (breakpoint embedded in class name)
+const spacingUtilPattern = /(?<!\S)([mp][xytblr]?-(?:sm-|md-|lg-|xl-)?(?:auto|n?[0-9]+))(?!\S)/g


spacingUtilPattern currently matches any numeric size (n?[0-9]+), but the rule/docs comment say the supported scale is 0-12 and n1-n12. As-is, this will flag/auto-fix non-Primer classes like m-99. Tighten the regex to the intended range (including negative) to avoid false positives.

Suggested change

const spacingUtilPattern = /(?<!\S)([mp][xytblr]?-(?:sm-|md-|lg-|xl-)?(?:auto|n?[0-9]+))(?!\S)/g

const spacingUtilPattern = /(?<!\S)([mp][xytblr]?-(?:sm-|md-|lg-|xl-)?(?:auto|[0-9]|1[0-2]|n(?:[1-9]|1[0-2])))(?!\S)/g

Copilot · 2026-01-23T13:03:39Z

src/rules/__tests__/namespace-spacing-utils.test.js

+    // Multiple unnamespaced classes - each is reported and fixed (first pass fixes first match only in test)
+    {
+      code: '<div className="m-4 p-2" />',
+      output: '<div className="pr-m-4 p-2" />',
+      errors: [
+        {messageId: 'namespaceRequired', data: {className: 'm-4', replacement: 'pr-m-4'}},
+        {messageId: 'namespaceRequired', data: {className: 'p-2', replacement: 'pr-p-2'}},
+      ],
+    },


This test case’s output only applies the first fix (m-4), even though the rule reports (and should be able to fix) both m-4 and p-2 in a single --fix run. Once the rule’s fixer is made non-overlapping (e.g. produce a single full replacement per node), update the expected output to include both prefixes, and consider adding a regression test that ensures fixing m-4 does not rewrite my-m-4 or other non-token substrings.

Copilot · 2026-01-23T13:03:39Z

src/index.js

    'enforce-button-for-link-with-no-href': require('./rules/enforce-button-for-link-with-no-href'),
    'enforce-css-module-default-import': require('./rules/enforce-css-module-default-import'),
    'enforce-css-module-identifier-casing': require('./rules/enforce-css-module-identifier-casing'),
+    'namespace-spacing-utils': require('./rules/namespace-spacing-utils'),


CI enforces the presence of a Changeset file (see .github/workflows/check-for-changeset.yml). Since this PR adds a new user-facing rule, it likely needs a changeset in .changeset/*.md (or the PR must be labeled skip changeset) so the workflow doesn’t fail.

Copilot · 2026-01-23T13:03:40Z

docs/rules/namespace-spacing-utils.md

+# Enforce namespacing of spacing utility classes (namespace-spacing-utils)
+
+Primer CSS spacing utility classes (margin and padding) should be namespaced with the `pr-` prefix to avoid conflicts with other CSS frameworks and ensure consistent styling.


The rule is documented here, but it isn’t currently listed in the top-level README.md “Rules” section (which enumerates all existing rules). Add namespace-spacing-utils to that list so users can discover the new rule and its docs.

Initial plan

542f49d

Copilot AI assigned Copilot and siddharthkp Jan 23, 2026

Copilot started work on behalf of siddharthkp January 23, 2026 09:03 View session

Copilot AI and others added 3 commits January 23, 2026 09:06

Add namespace-spacing-utils rule for Primer CSS spacing utilities

eb7a42d

Co-authored-by: siddharthkp <1863771+siddharthkp@users.noreply.github.com>

Address code review feedback: add sourceCode fallback and use replaceAll

c22acbc

Co-authored-by: siddharthkp <1863771+siddharthkp@users.noreply.github.com>

Update test comment for clarity

505646c

Co-authored-by: siddharthkp <1863771+siddharthkp@users.noreply.github.com>

Copilot AI changed the title ~~[WIP] Add namespace for primer-css margin and padding utilities~~ Add namespace-spacing-utils rule Jan 23, 2026

Copilot AI requested a review from siddharthkp January 23, 2026 09:11

Copilot finished work on behalf of siddharthkp January 23, 2026 09:11

siddharthkp reviewed Jan 23, 2026

View reviewed changes

Copilot started work on behalf of siddharthkp January 23, 2026 09:28 View session

Fix responsive format to use Primer CSS style (mx-sm-2, mx-md-4)

aa07187

Co-authored-by: siddharthkp <1863771+siddharthkp@users.noreply.github.com>

Copilot AI requested a review from siddharthkp January 23, 2026 09:31

Copilot finished work on behalf of siddharthkp January 23, 2026 09:31

siddharthkp marked this pull request as ready for review January 23, 2026 12:57

siddharthkp requested a review from a team as a code owner January 23, 2026 12:57

Copilot AI review requested due to automatic review settings January 23, 2026 12:57

Copilot started reviewing on behalf of siddharthkp January 23, 2026 12:58 View session

Copilot AI reviewed Jan 23, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add namespace-spacing-utils rule #490

Add namespace-spacing-utils rule #490

Uh oh!

Copilot AI commented Jan 23, 2026 •

edited by siddharthkp

Loading

Uh oh!

changeset-bot bot commented Jan 23, 2026 •

edited

Loading

Uh oh!

siddharthkp Jan 23, 2026

Uh oh!

Copilot AI Jan 23, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

Copilot AI Jan 23, 2026

Uh oh!

Copilot AI Jan 23, 2026

Uh oh!

Copilot AI Jan 23, 2026

Uh oh!

Copilot AI Jan 23, 2026

Uh oh!

Copilot AI Jan 23, 2026

Uh oh!

Copilot AI Jan 23, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants


		## When to use autofix

		This rule includes an autofix that will automatically add the `pr-` prefix to unnamespaced spacing utility classes. The autofix is safe to use as it only modifies the class names that match the spacing utility patterns.

	const spacingUtilPattern = /(?<!\S)([mp][xytblr]?-(?:sm-\|md-\|lg-\|xl-)?(?:auto\|n?[0-9]+))(?!\S)/g
	const spacingUtilPattern = /(?<!\S)([mp][xytblr]?-(?:sm-\|md-\|lg-\|xl-)?(?:auto\|[0-9]\|1[0-2]\|n(?:[1-9]\|1[0-2])))(?!\S)/g

		# Enforce namespacing of spacing utility classes (namespace-spacing-utils)

		Primer CSS spacing utility classes (margin and padding) should be namespaced with the `pr-` prefix to avoid conflicts with other CSS frameworks and ensure consistent styling.

Add namespace-spacing-utils rule #490

Are you sure you want to change the base?

Add namespace-spacing-utils rule #490

Uh oh!

Conversation

Copilot AI commented Jan 23, 2026 • edited by siddharthkp Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

changeset-bot bot commented Jan 23, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

⚠️ No Changeset found

Uh oh!

siddharthkp Jan 23, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jan 23, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Copilot AI Jan 23, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jan 23, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jan 23, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jan 23, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jan 23, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jan 23, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Copilot AI commented Jan 23, 2026 •

edited by siddharthkp

Loading

changeset-bot bot commented Jan 23, 2026 •

edited

Loading