feat: add no-important rule (#124)

* feat: add no-important rule

* review suggestions

* remove periods from list items

Author: thecalamiity

README.md

@@ -62,6 +62,7 @@ export default defineConfig([
 | :----------------------------------------------------------------------- | :------------------------------------ | :-------------: |
 | [`no-duplicate-imports`](./docs/rules/no-duplicate-imports.md)           | Disallow duplicate @import rules      |       yes       |
 | [`no-empty-blocks`](./docs/rules/no-empty-blocks.md)                     | Disallow empty blocks                 |       yes       |
+| [`no-important`](./docs/rules/no-important.md)                           | Disallow !important flags             |       yes       |
 | [`no-invalid-at-rules`](./docs/rules/no-invalid-at-rules.md)             | Disallow invalid at-rules             |       yes       |
 | [`no-invalid-properties`](./docs/rules/no-invalid-properties.md)         | Disallow invalid properties           |       yes       |
 | [`prefer-logical-properties`](./docs/rules/prefer-logical-properties.md) | Enforce the use of logical properties |       no        |

docs/rules/no-important.md

@@ -0,0 +1,45 @@
+# no-important
+
+Disallow `!important` flags.
+
+## Background
+
+The `!important` flag is a CSS declaration modifier that overrides normal cascade behavior, forcing a declaration to take precedence over competing rules—regardless of specificity or source order. While it can be necessary in rare cases (e.g., overriding third-party styles or enforcing accessibility fixes), it’s widely considered an anti-pattern because:
+
+- It breaks the natural cascade of CSS
+- It makes debugging more difficult
+- It can lead to specificity wars where developers keep adding more `!important` declarations to override each other
+- It makes the code harder to maintain
+
+## Rule Details
+
+This rule warns when it detects the `!important` flag in declarations.
+
+Examples of incorrect code:
+
+```css
+.foo {
+	color: red !important;
+}
+```
+
+Examples of correct code:
+
+```css
+.foo {
+	color: red;
+}
+```
+
+## When Not to Use It
+
+You may disable this rule if you are using `!important` in these specific cases:
+
+- Overriding third-party styles where you lack control over the source CSS
+- Fixing accessibility issues (e.g., enforcing focus states or color contrast)
+- Working with legacy code where refactoring isn’t feasible
+
+## Prior Art
+
+- [`important`](https://github.com/CSSLint/csslint/wiki/Disallow-%21important)
+- [`declaration-no-important`](https://stylelint.io/user-guide/rules/declaration-no-important/)

src/index.js

@@ -11,6 +11,7 @@ import { CSSLanguage } from "./languages/css-language.js";
 import { CSSSourceCode } from "./languages/css-source-code.js";
 import noEmptyBlocks from "./rules/no-empty-blocks.js";
 import noDuplicateImports from "./rules/no-duplicate-imports.js";
+import noImportant from "./rules/no-important.js";
 import noInvalidProperties from "./rules/no-invalid-properties.js";
 import noInvalidAtRules from "./rules/no-invalid-at-rules.js";
 import preferLogicalProperties from "./rules/prefer-logical-properties.js";
@@ -32,6 +33,7 @@ const plugin = {
 	rules: {
 		"no-empty-blocks": noEmptyBlocks,
 		"no-duplicate-imports": noDuplicateImports,
+		"no-important": noImportant,
 		"no-invalid-at-rules": noInvalidAtRules,
 		"no-invalid-properties": noInvalidProperties,
 		"prefer-logical-properties": preferLogicalProperties,
@@ -44,6 +46,7 @@ const plugin = {
 			rules: /** @type {const} */ ({
 				"css/no-empty-blocks": "error",
 				"css/no-duplicate-imports": "error",
+				"css/no-important": "error",
 				"css/no-invalid-at-rules": "error",
 				"css/no-invalid-properties": "error",
 				"css/use-baseline": "warn",

src/rules/no-important.js

@@ -0,0 +1,94 @@
+/**
+ * @fileoverview Rule to disallow `!important` flags.
+ * @author thecalamiity
+ * @author Yann Bertrand
+ */
+
+//-----------------------------------------------------------------------------
+// Imports
+//-----------------------------------------------------------------------------
+
+import { findOffsets } from "../util.js";
+
+//-----------------------------------------------------------------------------
+// Type Definitions
+//-----------------------------------------------------------------------------
+
+/**
+ * @import { CSSRuleDefinition } from "../types.js"
+ * @typedef {"unexpectedImportant"} NoImportantMessageIds
+ * @typedef {CSSRuleDefinition<{ RuleOptions: [], MessageIds: NoImportantMessageIds }>} NoImportantRuleDefinition
+ */
+
+//-----------------------------------------------------------------------------
+// Rule Definition
+//-----------------------------------------------------------------------------
+
+/** @type {NoImportantRuleDefinition} */
+export default {
+	meta: {
+		type: "problem",
+
+		docs: {
+			description: "Disallow !important flags",
+			recommended: true,
+			url: "https://github.com/eslint/css/blob/main/docs/rules/no-important.md",
+		},
+
+		messages: {
+			unexpectedImportant: "Unexpected !important flag found.",
+		},
+	},
+
+	create(context) {
+		const importantPattern = /!(\s|\/\*.*?\*\/)*important/iu;
+
+		return {
+			Declaration(node) {
+				if (node.important) {
+					const declarationText = context.sourceCode.getText(node);
+					const importantMatch =
+						importantPattern.exec(declarationText);
+
+					const {
+						lineOffset: startLineOffset,
+						columnOffset: startColumnOffset,
+					} = findOffsets(declarationText, importantMatch.index);
+
+					const {
+						lineOffset: endLineOffset,
+						columnOffset: endColumnOffset,
+					} = findOffsets(
+						declarationText,
+						importantMatch.index + importantMatch[0].length,
+					);
+
+					const nodeStartLine = node.loc.start.line;
+					const nodeStartColumn = node.loc.start.column;
+					const startLine = nodeStartLine + startLineOffset;
+					const endLine = nodeStartLine + endLineOffset;
+					const startColumn =
+						(startLine === nodeStartLine ? nodeStartColumn : 1) +
+						startColumnOffset;
+					const endColumn =
+						(endLine === nodeStartLine ? nodeStartColumn : 1) +
+						endColumnOffset;
+
+					context.report({
+						loc: {
+							start: {
+								line: startLine,
+								column: startColumn,
+							},
+							end: {
+								line: endLine,
+								column: endColumn,
+							},
+						},
+						messageId: "unexpectedImportant",
+					});
+				}
+			},
+		};
+	},
+};

src/util.js

@@ -23,3 +23,28 @@
 export function isSyntaxMatchError(error) {
 	return typeof error.syntax === "string";
 }
+
+/**
+ * Finds the line and column offsets for a given offset in a string.
+ * @param {string} text The text to search.
+ * @param {number} offset The offset to find.
+ * @returns {{lineOffset:number,columnOffset:number}} The location of the offset.
+ */
+export function findOffsets(text, offset) {
+	let lineOffset = 0;
+	let columnOffset = 0;
+
+	for (let i = 0; i < offset; i++) {
+		if (text[i] === "\n") {
+			lineOffset++;
+			columnOffset = 0;
+		} else {
+			columnOffset++;
+		}
+	}
+
+	return {
+		lineOffset,
+		columnOffset,
+	};
+}