feat: introduce stylelint plugin (nodejs#7644)

canerakdas · avivkeller · web-flow · commit 65ae2f19861f · 2025-04-13T14:11:59.000Z
* feat: introduce stylelint plugin

* Update packages/ui-components/stylelint.plugin.mjs

Co-authored-by: Aviv Keller &lt;me@aviv.sh&gt;
Signed-off-by: Caner Akdas &lt;canerakdas@gmail.com&gt;

* refactor: review suggestions

* chore(docs): align Tailwind usage with official documentation in docs and Stylelint config

---------

Signed-off-by: Caner Akdas &lt;canerakdas@gmail.com&gt;
Co-authored-by: Aviv Keller &lt;me@aviv.sh&gt;
diff --git a/COLLABORATOR_GUIDE.md b/COLLABORATOR_GUIDE.md
@@ -187,14 +187,14 @@ Finally, if you're unfamiliar with how to use Tailwind or how to use Tailwind wi
 #### Guidelines when writing CSS
 
 - We use camelCase for defining CSS classes
-- We use Tailwind's `@apply` selector to apply Tailwind Tokens
+- We use Tailwind's `@apply` selector to apply Tailwind utility classes
   - We discourage the usage of any plain CSS styles and tokens, when in doubt ask for help
-  - We require that you define one Tailwind Token per line, just as shown on the example above, since this improves readability
+  - We require that you define one Tailwind utility class per line, just as shown on the example above, since this improves readability
 - Only write CSS within CSS Modules, avoid writing CSS within JavaScript files
 
 > \[!NOTE]\
 > Tailwind is already configured for this repository. You don't need to import any Tailwind module within your CSS module.\
-> You can apply Tailwind Tokens with Tailwind's `@apply` CSS rule. [Read more about applying Tailwind classes with `@apply`](https://tailwindcss.com/docs/functions-and-directives#apply).
+> You can apply Tailwind utility classes with Tailwind's `@apply` CSS rule. [Read more about applying Tailwind utility classes with `@apply`](https://tailwindcss.com/docs/functions-and-directives#apply).
 
 > \[!IMPORTANT]\
 > When using IDEs such as Visual Studio Code, we recommend installing the official [Stylelint](https://marketplace.visualstudio.com/items?itemName=stylelint.vscode-stylelint)
diff --git a/apps/site/.stylelintrc.mjs b/apps/site/.stylelintrc.mjs
@@ -23,7 +23,11 @@ const ONLY_ALLOW_CAMEL_CASE_SELECTORS = [
 
 export default {
   extends: ['stylelint-config-standard'],
-  plugins: ['stylelint-order', 'stylelint-selector-bem-pattern'],
+  plugins: [
+    'stylelint-order',
+    'stylelint-selector-bem-pattern',
+    '@node-core/ui-components/stylelint/one-utility-class-per-line.mjs',
+  ],
   rules: {
     // Enforces Element Class Names to be camelCase
     'selector-class-pattern': ONLY_ALLOW_CAMEL_CASE_SELECTORS,
@@ -45,5 +49,6 @@ export default {
     'import-notation': 'string',
     // Allow the `@apply` at rule as its part of Tailwind
     'at-rule-no-deprecated': [true, { ignoreAtRules: CUSTOM_AT_RULES }],
+    'nodejs/one-utility-class-per-line': true,
   },
 };
diff --git a/apps/site/layouts/layouts.module.css b/apps/site/layouts/layouts.module.css
@@ -137,14 +137,14 @@
 
     &:nth-of-type(2) {
       @apply flex
-          min-w-0
-          max-w-full
-          flex-[1_1]
-          flex-col
-          items-center
-          gap-4
-          md:max-w-2xl
-          lg:max-w-3xl;
+        min-w-0
+        max-w-full
+        flex-[1_1]
+        flex-col
+        items-center
+        gap-4
+        md:max-w-2xl
+        lg:max-w-3xl;
 
       > div {
         @apply w-full
@@ -154,9 +154,9 @@
 
       > p {
         @apply text-center
-            text-sm
-            text-neutral-800
-            dark:text-neutral-200;
+          text-sm
+          text-neutral-800
+          dark:text-neutral-200;
       }
     }
   }
diff --git a/apps/site/styles/effects.css b/apps/site/styles/effects.css
@@ -21,7 +21,7 @@
 
   & img {
     @apply h-auto
-    w-24
-    md:w-48;
+      w-24
+      md:w-48;
   }
 }
diff --git a/packages/ui-components/.stylelintrc.mjs b/packages/ui-components/.stylelintrc.mjs
@@ -23,7 +23,11 @@ const ONLY_ALLOW_CAMEL_CASE_SELECTORS = [
 
 export default {
   extends: ['stylelint-config-standard'],
-  plugins: ['stylelint-order', 'stylelint-selector-bem-pattern'],
+  plugins: [
+    'stylelint-order',
+    'stylelint-selector-bem-pattern',
+    './stylelint/one-utility-class-per-line.mjs',
+  ],
   rules: {
     // Enforces Element Class Names to be camelCase
     'selector-class-pattern': ONLY_ALLOW_CAMEL_CASE_SELECTORS,
@@ -45,6 +49,7 @@ export default {
     'import-notation': 'string',
     // Allow the `@apply` at rule as its part of Tailwind
     'at-rule-no-deprecated': [true, { ignoreAtRules: CUSTOM_AT_RULES }],
+    'nodejs/one-utility-class-per-line': true,
     // We need complex `:not()` for headings with anchor
     'selector-not-notation': null,
   },
diff --git a/packages/ui-components/Common/Blockquote/index.module.css b/packages/ui-components/Common/Blockquote/index.module.css
@@ -1,10 +1,26 @@
 @reference "../../styles/index.css";
 
 .wrapper {
-  @apply flex max-w-2xl flex-col items-start gap-4 self-stretch border-l-2 border-green-600 py-2 pl-5 text-lg font-semibold text-neutral-900 dark:border-green-400 dark:text-white;
+  @apply flex
+    max-w-2xl
+    flex-col
+    items-start
+    gap-4
+    self-stretch
+    border-l-2
+    border-green-600
+    py-2
+    pl-5
+    text-lg
+    font-semibold
+    text-neutral-900
+    dark:border-green-400
+    dark:text-white;
 
   & cite {
-    @apply font-regular text-base not-italic;
+    @apply font-regular
+      text-base
+      not-italic;
 
     &::before {
       @apply content-['—_'];
diff --git a/packages/ui-components/Common/Breadcrumbs/BreadcrumbItem/index.module.css b/packages/ui-components/Common/Breadcrumbs/BreadcrumbItem/index.module.css
@@ -1,27 +1,41 @@
 @reference "../../../styles/index.css";
 
 .item {
-  @apply flex max-w-fit items-center gap-5 truncate text-sm font-medium;
+  @apply flex
+    max-w-fit
+    items-center
+    gap-5
+    truncate
+    text-sm
+    font-medium;
 
   &:last-child {
     @apply w-full;
   }
 
   a {
-    @apply shrink grow;
+    @apply shrink
+      grow;
   }
 
   &,
   > a,
   > a:hover {
-    @apply text-neutral-800 motion-safe:transition-colors dark:text-neutral-200;
+    @apply text-neutral-800
+      motion-safe:transition-colors
+      dark:text-neutral-200;
   }
 
   &.visuallyHidden {
     @apply hidden;
   }
 
   .separator {
-    @apply size-4 max-w-fit shrink-0 grow text-neutral-600 dark:text-neutral-400;
+    @apply size-4
+      max-w-fit
+      shrink-0
+      grow
+      text-neutral-600
+      dark:text-neutral-400;
   }
 }
diff --git a/packages/ui-components/Common/Breadcrumbs/BreadcrumbLink/index.module.css b/packages/ui-components/Common/Breadcrumbs/BreadcrumbLink/index.module.css
@@ -1,13 +1,22 @@
 @reference "../../../styles/index.css";
 
 .link {
-  @apply max-w-fit truncate;
+  @apply max-w-fit
+    truncate;
 
   &.active {
-    @apply rounded bg-green-600 px-2 py-1 font-semibold text-white motion-safe:transition-colors dark:text-white;
+    @apply rounded
+      bg-green-600
+      px-2
+      py-1
+      font-semibold
+      text-white
+      motion-safe:transition-colors
+      dark:text-white;
 
     &:hover {
-      @apply bg-green-700 text-white;
+      @apply bg-green-700
+        text-white;
     }
   }
 }
diff --git a/packages/ui-components/Common/Breadcrumbs/BreadcrumbRoot/index.module.css b/packages/ui-components/Common/Breadcrumbs/BreadcrumbRoot/index.module.css
@@ -1,5 +1,9 @@
 @reference "../../../styles/index.css";
 
 .list {
-  @apply xs:w-full flex w-screen gap-5 px-6;
+  @apply xs:w-full
+    flex
+    w-screen
+    gap-5
+    px-6;
 }
diff --git a/packages/ui-components/Common/LanguageDropDown/index.module.css b/packages/ui-components/Common/LanguageDropDown/index.module.css
@@ -29,7 +29,8 @@
 
   > div {
     @apply max-h-80
-      w-48 overflow-y-auto;
+      w-48
+      overflow-y-auto;
   }
 }
 
@@ -47,5 +48,6 @@
 }
 
 .currentDropDown {
-  @apply bg-green-600 text-white;
+  @apply bg-green-600
+    text-white;
 }
diff --git a/packages/ui-components/Common/Tabs/index.module.css b/packages/ui-components/Common/Tabs/index.module.css
@@ -35,7 +35,7 @@
 
         .tabSecondaryLabel {
           @apply text-green-800
-          dark:text-green-600;
+            dark:text-green-600;
         }
       }
     }
diff --git a/packages/ui-components/stylelint/__tests__/index.test.mjs b/packages/ui-components/stylelint/__tests__/index.test.mjs
@@ -0,0 +1,75 @@
+import {
+  indentClassNames,
+  cleanClassNames,
+  applyIndentation,
+} from '../utils.mjs';
+
+describe('cleanClassNames', () => {
+  it('removes newlines and extra spaces', () => {
+    const input = '  text-xl   \r   font-bold \n\n   text-center  ';
+    const expected = 'text-xl font-bold text-center';
+
+    expect(cleanClassNames(input)).toBe(expected);
+  });
+
+  it('trims leading and trailing spaces', () => {
+    const input = '   mt-4   ';
+    const expected = 'mt-4';
+
+    expect(cleanClassNames(input)).toBe(expected);
+  });
+
+  it('returns empty string when input is empty', () => {
+    expect(cleanClassNames('')).toBe('');
+  });
+});
+
+describe('applyIndentation', () => {
+  it('adds indentation to each class name', () => {
+    const input = 'text-xl font-bold text-center';
+    const indent = '    ';
+    const expected = ['text-xl', '    font-bold', '    text-center'].join('\n');
+
+    expect(applyIndentation(input, indent)).toBe(expected);
+  });
+});
+
+describe('indentClassNames', () => {
+  it('returns null if rule is missing required properties', () => {
+    expect(indentClassNames(null)).toBeNull();
+    expect(indentClassNames({})).toBeNull();
+    expect(indentClassNames({ params: 'foo' })).toBeNull();
+    expect(indentClassNames({ params: 'foo', raws: {} })).toBeNull();
+  });
+
+  it('cleans and indents class names correctly', () => {
+    const rule = {
+      params: '  text-xl \n font-bold  \n text-center ',
+      raws: {
+        before: '  ',
+      },
+    };
+
+    const result = indentClassNames({ ...rule });
+    const expectedParams = ['text-xl', '   font-bold', '   text-center'].join(
+      '\n'
+    );
+
+    expect(result).toEqual({
+      ...rule,
+      params: expectedParams,
+    });
+  });
+
+  it('returns the same rule object with modified params', () => {
+    const rule = {
+      params: 'p-4 mb-2',
+      raws: { before: '  \n' },
+    };
+
+    const result = indentClassNames(rule);
+
+    expect(result).toBe(rule);
+    expect(result.params).toBe('p-4\n    mb-2');
+  });
+});
diff --git a/packages/ui-components/stylelint/one-utility-class-per-line.mjs b/packages/ui-components/stylelint/one-utility-class-per-line.mjs
@@ -0,0 +1,64 @@
+import stylelint from 'stylelint';
+
+import { indentClassNames } from './utils.mjs';
+
+const {
+  createPlugin,
+  utils: { report, ruleMessages },
+} = stylelint;
+
+const name = 'nodejs/one-utility-class-per-line';
+
+const messages = ruleMessages(name, {
+  className: classNames =>
+    `Each line should contain only one Tailwind utility class; "${classNames}"`,
+  spacing: classNames =>
+    `Each utility class used with @apply should be indented by 2 spaces on a new line; ${classNames}`,
+});
+
+const meta = {
+  url: 'https://github.com/nodejs/nodejs.org/blob/main/COLLABORATOR_GUIDE.md#styling-a-component',
+  fixable: true,
+};
+
+/** @type {import('stylelint').Rule} */
+const rule = () => (root, result) => {
+  root.walkAtRules('apply', rule => {
+    if (!rule.params.includes(' ')) {
+      // If there are no spaces in the params, we don't need to check anything
+      return;
+    }
+
+    // Since we use 2 spaces for indentation, each line in the apply rule
+    // should be indented with two extra whitespaces.
+    const classes = rule.params.split(`${rule.raws.before}  `);
+    const classNames = classes.join('');
+
+    // Check if the params contain any spaces
+    if (classNames.includes(' ')) {
+      if (classNames.includes('\n')) {
+        return report({
+          ruleName: name,
+          result: result,
+          message: messages.spacing(JSON.stringify(rule.params)),
+          node: rule,
+          fix: indentClassNames(rule),
+        });
+      }
+
+      return report({
+        ruleName: name,
+        result,
+        message: messages.className(rule.params),
+        node: rule,
+        fix: indentClassNames(rule),
+      });
+    }
+  });
+};
+
+rule.ruleName = name;
+rule.messages = messages;
+rule.meta = meta;
+
+export default createPlugin(name, rule);
diff --git a/packages/ui-components/stylelint/utils.mjs b/packages/ui-components/stylelint/utils.mjs

Original file line number	Diff line number	Diff line change
`@@ -21,7 +21,7 @@`
`21`	`21`
`22`	`22`	`& img {`
`23`	`23`	`@apply h-auto`
`24`		`- w-24`
`25`		`- md:w-48;`
	`24`	`+ w-24`
	`25`	`+ md:w-48;`
`26`	`26`	`}`
`27`	`27`	`}`
Original file line number	Diff line number	Diff line change
`@@ -29,7 +29,8 @@`
`29`	`29`
`30`	`30`	`> div {`
`31`	`31`	`@apply max-h-80`
`32`		`- w-48 overflow-y-auto;`
	`32`	`+ w-48`
	`33`	`+ overflow-y-auto;`
`33`	`34`	`}`
`34`	`35`	`}`
`35`	`36`
`@@ -47,5 +48,6 @@`
`47`	`48`	`}`
`48`	`49`
`49`	`50`	`.currentDropDown {`
`50`		`- @apply bg-green-600 text-white;`
	`51`	`+ @apply bg-green-600`
	`52`	`+ text-white;`
`51`	`53`	`}`