From e6233c7428f061498e71827ccefe9d0c72084ad5 Mon Sep 17 00:00:00 2001
From: Tony Ruscoe <tonyruscoe@gmail.com>
Date: Thu, 13 Jan 2022 14:29:39 +0000
Subject: [PATCH] Add recommendation to avoid using !important

This recommendation was adopted internally to align with our infrastructure conformance checks and best practices.

While !important is a legitimate feature of CSS, its use increased complexity and maintenance costs when styles were reused and shared across multiple projects.
---
 htmlcssguide.html | 25 +++++++++++++++++++++++--
 1 file changed, 23 insertions(+), 2 deletions(-)

diff --git a/htmlcssguide.html b/htmlcssguide.html
index 8bab67a6e..ba283fea2 100644
--- a/htmlcssguide.html
+++ b/htmlcssguide.html
@@ -693,6 +693,27 @@ <h4 id="Hexadecimal_Notation" class="numbered">Hexadecimal Notation</h4>
 color: #ebc;
 </code></pre>
 
+<h4 id="Important_Declarations" class="numbered">Important Declarations</h4>
+
+<p>Avoid using <code>!important</code> declarations.</p>
+
+<p>These declarations break the natural cascade of CSS and make it difficult to
+reason about and compose styles. Use
+<a href="https://developer.mozilla.org/en-US/docs/Web/CSS/Specificity">selector specificity</a>
+to override properties instead.</p>
+
+<pre><code class="language-css bad">/* Not recommended */
+.example {
+  font-weight: bold !important;
+}
+</code></pre>
+
+<pre><code class="language-css good">/* Recommended */
+.example {
+  font-weight: bold;
+}
+</code></pre>
+
 <h4 id="Hacks" class="numbered">Hacks</h4>
 
 <p>Avoid user agent detection as well as CSS “hacks”—try a different approach
@@ -713,8 +734,8 @@ <h4 id="Declaration_Order" class="numbered">Declaration Order</h4>
 
 <p>Alphabetize declarations.</p>
 
-<p>Put declarations in alphabetical order in order to achieve consistent code in a
-way that is easy to remember and maintain.</p>
+<p>Put declarations in alphabetical order in order to
+achieve consistent code in a way that is easy to remember and maintain.</p>
 
 <p>Ignore vendor-specific prefixes for sorting purposes. However, multiple
 vendor-specific prefixes for a certain CSS property should be kept sorted (e.g.