roast-my-design-system 3.5.1 → 3.7.0

package/README.md

@@ -24,11 +24,11 @@ Your AI agent (Claude, Cursor, Copilot) builds UI by imitating what's already in
 
 The full report for vercel/ai-chatbot, top to bottom:
 
-![The full diagnosis report for vercel/ai-chatbot in dark mode: health score, three-yardstick tiles, palette forensics, spacing receipts, typography, offenders, duplicates, and the where-to-start close](https://raw.githubusercontent.com/pencilrebel/roast-my-design-system/main/assets/report-full-dark.png?v=3.5.1)
+![The full diagnosis report for vercel/ai-chatbot in dark mode: health score, three-yardstick tiles, palette forensics, spacing receipts, typography, offenders, duplicates, and the where-to-start close](https://raw.githubusercontent.com/pencilrebel/roast-my-design-system/main/assets/report-full-dark.png?v=3.7.0)
 
 The same report in light mode (one file, built-in toggle):
 
-![The diagnosis report in light mode](https://raw.githubusercontent.com/pencilrebel/roast-my-design-system/main/assets/report-light-hero.png?v=3.5.1)
+![The diagnosis report in light mode](https://raw.githubusercontent.com/pencilrebel/roast-my-design-system/main/assets/report-light-hero.png?v=3.7.0)
 
 ## What makes the numbers trustworthy
 
@@ -120,6 +120,9 @@ Three real roasts of public repos, hosted as-is (the same self-contained HTML th
 | Duplicated components | 0 | 14 | 10 |
 | Inline style blocks | 0 | 42 | 12 |
 | Arbitrary Tailwind values | ~20 | 91 | 0 |
+| Near-identical colour pairs | 0 | 2 | 1 |
+| !important declarations | 0 | 5 | 3 |
+| Components never imported | 0 | 0 | 0 |
 
 Yes, the median repo is already a mess. That's the point.
 
@@ -127,4 +130,4 @@ Yes, the median repo is already a mess. That's the point.
 
 MIT
 
-Built and designed by <a href="https://gregkozakiewicz.com"><picture><source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/pencilrebel/roast-my-design-system/main/assets/gk-mark-dark.png?v=3.5.1"><img src="https://raw.githubusercontent.com/pencilrebel/roast-my-design-system/main/assets/gk-mark.png?v=3.5.1" height="15" alt="GK mark"></picture> Greg Kozakiewicz</a>.
+Built and designed by <a href="https://gregkozakiewicz.com"><picture><source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/pencilrebel/roast-my-design-system/main/assets/gk-mark-dark.png?v=3.7.0"><img src="https://raw.githubusercontent.com/pencilrebel/roast-my-design-system/main/assets/gk-mark.png?v=3.7.0" height="15" alt="GK mark"></picture> Greg Kozakiewicz</a>.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "roast-my-design-system",
-  "version": "3.5.1",
+  "version": "3.7.0",
   "description": "Roast your design system with real data. A deterministic, zero-dependency scanner that counts every colour, grey, spacing value, typeface, duplicated component, inline style and arbitrary Tailwind value in your repo, scores it 0-100 against Ideal Design System norms and a 30-repo benchmark, generates a shareable HTML diagnosis, and with --rules writes the agent rules file (CLAUDE.md, .cursor/rules) that stops the mess coming back.",
   "keywords": [
     "design-system",

package/skills/roast-my-design-system/scripts/benchmark/benchmark.json

@@ -1,5 +1,5 @@
 {
-  "builtAt": "2026-08-01T17:38:24.498Z",
+  "builtAt": "2026-08-03T16:33:32.652Z",
   "repoCount": 30,
   "ideal2026": {
     "colors": {
@@ -38,6 +38,18 @@
       "value": 0,
       "note": "styling belongs to the system"
     },
+    "nearPairs": {
+      "value": 0,
+      "note": "near-identical colours are copy-paste, not decisions"
+    },
+    "important": {
+      "value": 0,
+      "note": "!important is the cascade admitting defeat"
+    },
+    "neverImported": {
+      "value": 0,
+      "note": "a system component nobody imports is dead weight"
+    },
     "arbitrary": {
       "value": 20,
       "note": "bracket escape hatches; a handful of deliberate exceptions"
@@ -104,7 +116,7 @@
         174,
         206,
         246,
-        302,
+        303,
         385,
         403,
         1645
@@ -112,7 +124,7 @@
       "p25": 38,
       "median": 96,
       "p75": 170,
-      "p90": 310
+      "p90": 311
     },
     "greys": {
       "values": [
@@ -373,7 +385,7 @@
         95,
         103,
         115,
-        187
+        189
       ],
       "p25": 1,
       "median": 14,
@@ -397,7 +409,7 @@
         23,
         37,
         41,
-        42,
+        43,
         46,
         47,
         51,
@@ -411,7 +423,7 @@
         122,
         173,
         1178,
-        2914
+        2923
       ],
       "p25": 8,
       "median": 42,
@@ -443,7 +455,7 @@
         234,
         271,
         321,
-        374,
+        380,
         407,
         468,
         470,
@@ -456,6 +468,120 @@
       "p75": 309,
       "p90": 472
     },
+    "nearPairs": {
+      "values": [
+        0,
+        0,
+        0,
+        0,
+        0,
+        0,
+        0,
+        0,
+        0,
+        0,
+        0,
+        1,
+        1,
+        2,
+        2,
+        2,
+        9,
+        12,
+        13,
+        13,
+        15,
+        16,
+        23,
+        26,
+        30,
+        37,
+        47,
+        49,
+        70,
+        146
+      ],
+      "p25": 0,
+      "median": 2,
+      "p75": 21,
+      "p90": 47
+    },
+    "important": {
+      "values": [
+        0,
+        0,
+        0,
+        0,
+        0,
+        0,
+        0,
+        0,
+        0,
+        0,
+        0,
+        1,
+        1,
+        2,
+        4,
+        5,
+        5,
+        6,
+        9,
+        9,
+        11,
+        12,
+        20,
+        35,
+        42,
+        42,
+        74,
+        83,
+        88,
+        161
+      ],
+      "p25": 0,
+      "median": 5,
+      "p75": 18,
+      "p90": 75
+    },
+    "neverImported": {
+      "values": [
+        0,
+        0,
+        0,
+        0,
+        0,
+        0,
+        0,
+        0,
+        0,
+        0,
+        0,
+        0,
+        0,
+        0,
+        0,
+        0,
+        0,
+        0,
+        5,
+        7,
+        10,
+        13,
+        22,
+        22,
+        26,
+        36,
+        39,
+        45,
+        94,
+        100
+      ],
+      "p25": 0,
+      "median": 0,
+      "p75": 20,
+      "p90": 40
+    },
     "components": {
       "values": [
         9,
@@ -471,27 +597,27 @@
         342,
         350,
         417,
-        546,
-        629,
+        555,
+        637,
         777,
-        790,
-        834,
+        796,
+        836,
         936,
         940,
-        961,
+        962,
         970,
-        1043,
+        1052,
         1081,
         1216,
         1379,
         1414,
         1619,
-        2133,
-        2549
+        2134,
+        2566
       ],
       "p25": 233,
-      "median": 703,
-      "p75": 1025,
+      "median": 707,
+      "p75": 1032,
       "p90": 1435
     }
   },
@@ -511,6 +637,9 @@
         "exactDuplicates": 115,
         "inlineStyles": 79,
         "arbitrary": 321,
+        "nearPairs": 47,
+        "important": 161,
+        "neverImported": 39,
         "components": 1414
       }
     },
@@ -529,6 +658,9 @@
         "exactDuplicates": 3,
         "inlineStyles": 82,
         "arbitrary": 0,
+        "nearPairs": 49,
+        "important": 88,
+        "neverImported": 0,
         "components": 342
       }
     },
@@ -547,13 +679,16 @@
         "exactDuplicates": 4,
         "inlineStyles": 23,
         "arbitrary": 0,
+        "nearPairs": 37,
+        "important": 4,
+        "neverImported": 0,
         "components": 50
       }
     },
     {
       "repo": "outline/outline",
       "designSystem": "custom",
-      "codeFiles": 2100,
+      "codeFiles": 2122,
       "metrics": {
         "colors": 89,
         "greys": 15,
@@ -565,7 +700,10 @@
         "exactDuplicates": 23,
         "inlineStyles": 76,
         "arbitrary": 0,
-        "components": 629
+        "nearPairs": 1,
+        "important": 0,
+        "neverImported": 0,
+        "components": 637
       }
     },
     {
@@ -583,6 +721,9 @@
         "exactDuplicates": 2,
         "inlineStyles": 0,
         "arbitrary": 4,
+        "nearPairs": 0,
+        "important": 5,
+        "neverImported": 0,
         "components": 220
       }
     },
@@ -601,6 +742,9 @@
         "exactDuplicates": 0,
         "inlineStyles": 0,
         "arbitrary": 0,
+        "nearPairs": 0,
+        "important": 0,
+        "neverImported": 0,
         "components": 25
       }
     },
@@ -619,6 +763,9 @@
         "exactDuplicates": 0,
         "inlineStyles": 0,
         "arbitrary": 60,
+        "nearPairs": 0,
+        "important": 1,
+        "neverImported": 94,
         "components": 182
       }
     },
@@ -637,6 +784,9 @@
         "exactDuplicates": 0,
         "inlineStyles": 0,
         "arbitrary": 0,
+        "nearPairs": 0,
+        "important": 0,
+        "neverImported": 0,
         "components": 9
       }
     },
@@ -655,6 +805,9 @@
         "exactDuplicates": 1,
         "inlineStyles": 2,
         "arbitrary": 16,
+        "nearPairs": 0,
+        "important": 2,
+        "neverImported": 0,
         "components": 60
       }
     },
@@ -673,6 +826,9 @@
         "exactDuplicates": 1,
         "inlineStyles": 7,
         "arbitrary": 103,
+        "nearPairs": 0,
+        "important": 9,
+        "neverImported": 0,
         "components": 315
       }
     },
@@ -691,13 +847,16 @@
         "exactDuplicates": 1,
         "inlineStyles": 11,
         "arbitrary": 148,
+        "nearPairs": 0,
+        "important": 0,
+        "neverImported": 100,
         "components": 272
       }
     },
     {
       "repo": "documenso/documenso",
       "designSystem": "custom",
-      "codeFiles": 1906,
+      "codeFiles": 1912,
       "metrics": {
         "colors": 36,
         "greys": 13,
@@ -709,13 +868,16 @@
         "exactDuplicates": 17,
         "inlineStyles": 69,
         "arbitrary": 234,
-        "components": 790
+        "nearPairs": 15,
+        "important": 0,
+        "neverImported": 45,
+        "components": 796
       }
     },
     {
       "repo": "dubinc/dub",
       "designSystem": "custom",
-      "codeFiles": 3523,
+      "codeFiles": 3526,
       "metrics": {
         "colors": 102,
         "greys": 14,
@@ -727,6 +889,9 @@
         "exactDuplicates": 17,
         "inlineStyles": 47,
         "arbitrary": 470,
+        "nearPairs": 13,
+        "important": 1,
+        "neverImported": 22,
         "components": 1379
       }
     },
@@ -745,6 +910,9 @@
         "exactDuplicates": 59,
         "inlineStyles": 18,
         "arbitrary": 164,
+        "nearPairs": 13,
+        "important": 83,
+        "neverImported": 0,
         "components": 940
       }
     },
@@ -763,13 +931,16 @@
         "exactDuplicates": 92,
         "inlineStyles": 119,
         "arbitrary": 164,
+        "nearPairs": 0,
+        "important": 0,
+        "neverImported": 5,
         "components": 1081
       }
     },
     {
       "repo": "lukevella/rallly",
       "designSystem": "custom",
-      "codeFiles": 689,
+      "codeFiles": 692,
       "metrics": {
         "colors": 26,
         "greys": 4,
@@ -781,7 +952,10 @@
         "exactDuplicates": 10,
         "inlineStyles": 23,
         "arbitrary": 27,
-        "components": 546
+        "nearPairs": 2,
+        "important": 0,
+        "neverImported": 22,
+        "components": 555
       }
     },
     {
@@ -799,13 +973,16 @@
         "exactDuplicates": 20,
         "inlineStyles": 46,
         "arbitrary": 407,
+        "nearPairs": 0,
+        "important": 42,
+        "neverImported": 13,
         "components": 777
       }
     },
     {
       "repo": "elie222/inbox-zero",
       "designSystem": "custom",
-      "codeFiles": 1808,
+      "codeFiles": 1821,
       "metrics": {
         "colors": 154,
         "greys": 24,
@@ -817,7 +994,10 @@
         "exactDuplicates": 21,
         "inlineStyles": 5,
         "arbitrary": 125,
-        "components": 834
+        "nearPairs": 26,
+        "important": 6,
+        "neverImported": 0,
+        "components": 836
       }
     },
     {
@@ -835,6 +1015,9 @@
         "exactDuplicates": 7,
         "inlineStyles": 41,
         "arbitrary": 78,
+        "nearPairs": 0,
+        "important": 0,
+        "neverImported": 0,
         "components": 190
       }
     },
@@ -853,13 +1036,16 @@
         "exactDuplicates": 0,
         "inlineStyles": 173,
         "arbitrary": 1,
+        "nearPairs": 2,
+        "important": 5,
+        "neverImported": 0,
         "components": 417
       }
     },
     {
       "repo": "twentyhq/twenty",
       "designSystem": "library",
-      "codeFiles": 15125,
+      "codeFiles": 15132,
       "metrics": {
         "colors": 1645,
         "greys": 100,
@@ -871,13 +1057,16 @@
         "exactDuplicates": 22,
         "inlineStyles": 122,
         "arbitrary": 0,
-        "components": 2133
+        "nearPairs": 146,
+        "important": 9,
+        "neverImported": 0,
+        "components": 2134
       }
     },
     {
       "repo": "langfuse/langfuse",
       "designSystem": "custom",
-      "codeFiles": 2758,
+      "codeFiles": 2774,
       "metrics": {
         "colors": 170,
         "greys": 4,
@@ -887,9 +1076,12 @@
         "radii": 10,
         "shadows": 0,
         "exactDuplicates": 7,
-        "inlineStyles": 42,
-        "arbitrary": 374,
-        "components": 1043
+        "inlineStyles": 43,
+        "arbitrary": 380,
+        "nearPairs": 2,
+        "important": 12,
+        "neverImported": 10,
+        "components": 1052
       }
     },
     {
@@ -907,6 +1099,9 @@
         "exactDuplicates": 45,
         "inlineStyles": 37,
         "arbitrary": 468,
+        "nearPairs": 70,
+        "important": 42,
+        "neverImported": 0,
         "components": 1216
       }
     },
@@ -925,6 +1120,9 @@
         "exactDuplicates": 95,
         "inlineStyles": 22,
         "arbitrary": 561,
+        "nearPairs": 16,
+        "important": 74,
+        "neverImported": 7,
         "components": 1619
       }
     },
@@ -943,31 +1141,37 @@
         "exactDuplicates": 19,
         "inlineStyles": 1178,
         "arbitrary": 0,
+        "nearPairs": 23,
+        "important": 35,
+        "neverImported": 36,
         "components": 350
       }
     },
     {
       "repo": "lobehub/lobe-chat",
       "designSystem": "library",
-      "codeFiles": 8299,
+      "codeFiles": 8344,
       "metrics": {
-        "colors": 302,
+        "colors": 303,
         "greys": 37,
         "spacing": 61,
         "typefaces": 1,
         "fontSizes": 2,
         "radii": 1,
         "shadows": 0,
-        "exactDuplicates": 187,
-        "inlineStyles": 2914,
+        "exactDuplicates": 189,
+        "inlineStyles": 2923,
         "arbitrary": 0,
-        "components": 2549
+        "nearPairs": 9,
+        "important": 0,
+        "neverImported": 0,
+        "components": 2566
       }
     },
     {
       "repo": "danny-avila/LibreChat",
       "designSystem": "custom",
-      "codeFiles": 2424,
+      "codeFiles": 2430,
       "metrics": {
         "colors": 174,
         "greys": 30,
@@ -979,7 +1183,10 @@
         "exactDuplicates": 38,
         "inlineStyles": 71,
         "arbitrary": 492,
-        "components": 961
+        "nearPairs": 30,
+        "important": 20,
+        "neverImported": 0,
+        "components": 962
       }
     },
     {
@@ -997,13 +1204,16 @@
         "exactDuplicates": 103,
         "inlineStyles": 117,
         "arbitrary": 1751,
+        "nearPairs": 12,
+        "important": 0,
+        "neverImported": 26,
         "components": 970
       }
     },
     {
       "repo": "triggerdotdev/trigger.dev",
       "designSystem": "custom",
-      "codeFiles": 2354,
+      "codeFiles": 2366,
       "metrics": {
         "colors": 137,
         "greys": 18,
@@ -1015,6 +1225,9 @@
         "exactDuplicates": 8,
         "inlineStyles": 51,
         "arbitrary": 271,
+        "nearPairs": 1,
+        "important": 11,
+        "neverImported": 0,
         "components": 936
       }
     },
@@ -1033,12 +1246,15 @@
         "exactDuplicates": 0,
         "inlineStyles": 0,
         "arbitrary": 26,
+        "nearPairs": 0,
+        "important": 0,
+        "neverImported": 0,
         "components": 36
       }
     }
   ],
   "referenceSystems": {
-    "builtAt": "2026-08-01T17:38:26.401Z",
+    "builtAt": "2026-08-03T16:33:34.617Z",
     "count": 10,
     "note": "Curated scoped scans of reputable public design systems. Not comparable head-to-head with product repos: see per-system notes.",
     "stats": {
@@ -1192,6 +1408,51 @@
         ],
         "median": 0
       },
+      "nearPairs": {
+        "values": [
+          0,
+          0,
+          0,
+          0,
+          1,
+          1,
+          1,
+          5,
+          33,
+          50
+        ],
+        "median": 1
+      },
+      "important": {
+        "values": [
+          0,
+          0,
+          0,
+          1,
+          1,
+          4,
+          4,
+          30,
+          33,
+          61
+        ],
+        "median": 3
+      },
+      "neverImported": {
+        "values": [
+          0,
+          0,
+          0,
+          0,
+          0,
+          0,
+          0,
+          0,
+          0,
+          0
+        ],
+        "median": 0
+      },
       "components": {
         "values": [
           0,
@@ -1226,6 +1487,9 @@
           "exactDuplicates": 0,
           "inlineStyles": 1,
           "arbitrary": 35,
+          "nearPairs": 0,
+          "important": 0,
+          "neverImported": 0,
           "components": 331
         }
       },
@@ -1246,6 +1510,9 @@
           "exactDuplicates": 13,
           "inlineStyles": 14,
           "arbitrary": 0,
+          "nearPairs": 5,
+          "important": 33,
+          "neverImported": 0,
           "components": 228
         }
       },
@@ -1266,6 +1533,9 @@
           "exactDuplicates": 15,
           "inlineStyles": 10,
           "arbitrary": 0,
+          "nearPairs": 0,
+          "important": 30,
+          "neverImported": 0,
           "components": 243
         }
       },
@@ -1286,6 +1556,9 @@
           "exactDuplicates": 6,
           "inlineStyles": 17,
           "arbitrary": 0,
+          "nearPairs": 1,
+          "important": 4,
+          "neverImported": 0,
           "components": 314
         }
       },
@@ -1306,6 +1579,9 @@
           "exactDuplicates": 2,
           "inlineStyles": 10,
           "arbitrary": 0,
+          "nearPairs": 50,
+          "important": 0,
+          "neverImported": 0,
           "components": 170
         }
       },
@@ -1326,6 +1602,9 @@
           "exactDuplicates": 0,
           "inlineStyles": 1,
           "arbitrary": 0,
+          "nearPairs": 1,
+          "important": 0,
+          "neverImported": 0,
           "components": 711
         }
       },
@@ -1346,6 +1625,9 @@
           "exactDuplicates": 17,
           "inlineStyles": 24,
           "arbitrary": 0,
+          "nearPairs": 1,
+          "important": 1,
+          "neverImported": 0,
           "components": 246
         }
       },
@@ -1366,6 +1648,9 @@
           "exactDuplicates": 0,
           "inlineStyles": 0,
           "arbitrary": 0,
+          "nearPairs": 33,
+          "important": 61,
+          "neverImported": 0,
           "components": 0
         }
       },
@@ -1386,6 +1671,9 @@
           "exactDuplicates": 170,
           "inlineStyles": 14,
           "arbitrary": 0,
+          "nearPairs": 0,
+          "important": 1,
+          "neverImported": 0,
           "components": 819
         }
       },
@@ -1406,6 +1694,9 @@
           "exactDuplicates": 28,
           "inlineStyles": 22,
           "arbitrary": 0,
+          "nearPairs": 0,
+          "important": 4,
+          "neverImported": 0,
           "components": 508
         }
       }

package/skills/roast-my-design-system/scripts/diagnose/index.mjs

@@ -12,6 +12,8 @@ import { resolve, basename, join, dirname } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { distinctTypefaces } from '../lib/typefaces.mjs';
 import { rulesMarkdown } from '../rules/build.mjs';
+import { nearColorPairs } from '../lib/nearpairs.mjs';
+import { neverImportedComponents } from '../lib/neverimported.mjs';
 
 // The benchmark (Ideal-2026 norms + scanned-repo stats) ships next to the
 // code so the page works offline; degrade gracefully when absent.
@@ -34,7 +36,7 @@ const GK_MASK = 'data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAEAAAABACAYAAACqa
 const GK_MARK = 'data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAACAAAAAgCAIAAAD8GO2jAAAACXBIWXMAAAAAAAAAAQCEeRdzAAACPklEQVR4nOVWTYh5URR/PlJYEKV8LKwkZalsmI2dZmMnK8pKmaZ87JSanexEkayUhSxsZyfJNBQ7UYqVhSShfM+v/6mXmtU81+p/Frfze+/d3++ce88993Hcf2cikehZ1GazWafTPUVDLBZjLBQKnU6HMTVvcrl8Op3ebrdsNgsokUiYUVP4Pp/v9s96vd79cwZGK95sNkkgGAwC2u12lhrY3u12C/b1ei2TyV5eXjabjV6vZ6BBa51MJin8arUKWKlU4H99fSkUCo5JUQ2HQxJwuVzIYLVawcdIVSs8CQoNpMQ+Go0Aw+EwwXw+D+h2u4Vr0LRSqUSMqVQKsN1uE3Q4HEql8ng8BgIBTnDhqlSqxWIBuvP5bDAYLBbL5XIBHAwGeBuJRODvdjun0/nnPOjraDRK8TYaDcBMJkMwFosBfn9/E0wkEn9OgjYgnU6fTidQwAGcTCbw9/u9VqvFUYB/vV5RskajkRNcTiaTKR6PI9j5fE7xlstlPM/lcgTr9ToneJ/5oOB4PB70O8Tb7/f9fv9sNqPkXl9fhQsQ9f1ktVqNvUVCxA6ZRxsf5pMAxnsuVBSOwvv7+6Phk0PsBNn0OOLC9haLReqdvBL/wUNKNPnt7Q0LjeVutVqhUEij0TwU9W8BVA4JUEUul8tarcZGhpbIarWiSeA0HQ4Hkvn4+GB56VMvov6DA+z1eplR89btdsE+Ho9tNhv3jOv+8/MTFz06M3ypVMqMnTfcwPhn4djG/tue+Mf4RGom9gMt6lAx16huIwAAAABJRU5ErkJggg==';
 
 // Shown in the report footer; keep in step with plugin.json when releasing.
-const VERSION = '3.5.1';
+const VERSION = '3.7.0';
 
 // Two shipped skins, same layout: 'dark' (navy glass, mint accent) and
 // 'light' (lilac wash, white glass, violet accent). --theme picks one.
@@ -151,6 +153,13 @@ const greyStrays = greys.filter((c) => !c.isToken).length;
 const arbitrary = h.tokens.tailwind?.arbitrary ?? [];
 const arbitraryCount = arbitrary.reduce((sum, a) => sum + a.count, 0);
 
+// !important declarations: the cascade admitting defeat.
+const important = h.tokens.important ?? { count: 0, files: [] };
+
+const nearPairs = nearColorPairs(colors);
+
+const neverImported = neverImportedComponents(h.components, h.profile?.uiDir);
+
 // Benchmark helpers: for a metric value, where does this repo sit among the
 // scanned fleet? ("more colours than 90% of scanned repos")
 function percentile(metric, value) {
@@ -204,6 +213,8 @@ if (effGreys > 13 * 1.25) candidates.push({ ratio: effGreys / 13, text: tokenLed
   ? `${greyStrays} hardcoded greys outside the token set`
   : `${greys.length} shades of grey doing the job of 13` });
 if (spacingTotal > 15) candidates.push({ ratio: spacingTotal / 12, text: `${spacingTotal} off-scale spacing values where a dozen would do` });
+if (nearPairs.length >= 3) candidates.push({ ratio: 1 + nearPairs.length / 6, text: `${nearPairs.length} colour pairs are nearly identical (${nearPairs[0].a.value} next to ${nearPairs[0].b.value}), copy-paste, not decisions` });
+if (important.count >= 10) candidates.push({ ratio: 1 + important.count / 30, text: `${n(important.count)} !important declarations, the cascade admitting defeat` });
 if (iconCollisions.length >= 5) candidates.push({ ratio: 1 + iconCollisions.length / 8, text: `two icon sets collide on ${iconCollisions.length} names` });
 if (hardDupes.length > 0) candidates.push({ ratio: 1 + hardDupes.length / 5, text: `${hardDupes.length} component${hardDupes.length > 1 ? 's' : ''} implemented more than once` });
 if (inline.count > 20) candidates.push({ ratio: inline.count / 20, text: `${n(inline.count)} inline style blocks bypassing every system` });
@@ -235,8 +246,8 @@ if (bench && findings.length) {
 // Where the median is missing or sits at/below ideal, warn caps at 1.5x ideal.
 // Zero-ideal metrics (duplicates, inline styles): 0 is good; a small tolerance
 // is warn; beyond that bad.
-const ZERO_IDEAL = new Set(['exactDuplicates', 'inlineStyles']);
-const WARN_TOLERANCE = { exactDuplicates: 2, inlineStyles: 10 };
+const ZERO_IDEAL = new Set(['exactDuplicates', 'inlineStyles', 'nearPairs', 'important', 'neverImported']);
+const WARN_TOLERANCE = { exactDuplicates: 2, inlineStyles: 10, nearPairs: 2, important: 5, neverImported: 2 };
 // Absence rule also skipped for arbitrary values: zero brackets is discipline
 // (nine of ten reputable systems sit at 0, including Tailwind-native shadcn/ui).
 const NO_ABSENCE_RULE = new Set(['colors', 'greys', 'arbitrary']);
@@ -289,6 +300,9 @@ const bigStats = [
   tile(spacingTotal, 'off-scale spacing values', 'spacing', 'a dozen deliberate exceptions'),
   tile(hardDupes.length, 'duplicated components', 'exactDuplicates', 'should be 0'),
   tile(inline.count, 'inline style blocks', 'inlineStyles', 'invisible to any system'),
+  tile(nearPairs.length, 'near-identical colour pairs', 'nearPairs', 'copy-paste, not decisions'),
+  tile(important.count, '!important declarations', 'important', 'the cascade admitting defeat'),
+  tile(neverImported.length, 'components never imported', 'neverImported', 'the system nobody found'),
   tile(arbitraryCount, 'arbitrary bracket values', 'arbitrary', 'a handful of deliberate exceptions'),
 ];
 
@@ -361,6 +375,9 @@ function paletteSection() {
     </div>
     <div class="usage-bar">${cells}${restCell}</div>
     ${ramp}
+    ${nearPairs.length ? `
+    <div class="receipts">${eyebrow(`${nearPairs.length} nearly identical pair${nearPairs.length === 1 ? '' : 's'} · copy-paste, not decisions`)}
+    <div class="chips-row">${nearPairs.slice(0, 8).map((pr) => `<span class="vchip" title="every channel within ${pr.d} of its twin"><i class="ndot" style="background:${esc(pr.a.value)}"></i>${esc(pr.a.value)} ×${pr.a.count} <b class="nsim">≈</b> <i class="ndot" style="background:${esc(pr.b.value)}"></i>${esc(pr.b.value)} ×${pr.b.count}</span>`).join('')}${nearPairs.length > 8 ? `<span class="vchip dim">+${nearPairs.length - 8} more</span>` : ''}</div></div>` : ''}
   </div>
 </section>`;
 }
@@ -457,20 +474,24 @@ function offendersSection() {
 }
 
 function inlineSection() {
-  if (inline.count < 5) return '';
+  if (inline.count < 5 && important.count < 5) return '';
   const max = Math.max(...inline.files.slice(0, 6).map((f) => f.count), 1);
-  return `<div class="glass pad half">
-    ${sectionHead(`${n(inline.count)} inline style blocks`, 'styling no system can see')}
-    <div class="fam-rows">${inline.files.slice(0, 6).map((f) => `
+  const importantRow = important.count ? `
+    <div class="receipts">${eyebrow(`${n(important.count)} !important declaration${important.count === 1 ? '' : 's'} · the cascade admitting defeat`)}
+    <div class="chips-row">${important.files.map((f) => `<span class="vchip bad" title="${esc(f.file)}">${esc(basename(f.file))} ×${f.count}</span>`).join('')}</div></div>` : '';
+  const blocks = inline.count >= 5 ? `<div class="fam-rows">${inline.files.slice(0, 6).map((f) => `
       <div class="mini-card col">
         <div class="mc-row">${fileLink(f.file)}<span class="mc-count">×${f.count}</span></div>
         <div class="mc-track"><div class="mc-bar" style="width:${Math.round((f.count / max) * 100)}%"></div></div>
-      </div>`).join('')}</div></div>`;
+      </div>`).join('')}</div>` : '';
+  return `<div class="glass pad half">
+    ${sectionHead(inline.count >= 5 ? `${n(inline.count)} inline style blocks` : `${n(important.count)} !important declarations`, 'styling no system can see')}
+    ${blocks}${importantRow}</div>`;
 }
 
 function componentsSection() {
   const top = reusable.filter((c) => c.usageCount > 0).slice(0, 10);
-  if (!top.length) return '';
+  if (!top.length && neverImported.length < 2) return '';
   const rows = top.map((c) => `
     <tr><td class="mono strong">&lt;${esc(c.name)}&gt;</td>
     <td><span class="pill pill-mint">${c.usageCount}×</span></td>
@@ -478,7 +499,11 @@ function componentsSection() {
     <td>${c.propsHint?.named?.length ? c.propsHint.named.slice(0, 5).map((p) => `<span class="chip chip-xs">${esc(p)}</span>`).join(' ') : '<span class="dim">none</span>'}</td></tr>`).join('');
   return `<section class="glass pad">
     ${sectionHead('What you actually use', `${n(reusable.length)} components defined · top by adoption · the real system, buried in here`)}
-    <div class="tbl-wrap"><table><thead><tr><th>component</th><th>used</th><th>defined in</th><th>props</th></tr></thead><tbody>${rows}</tbody></table></div></section>`;
+    ${top.length ? `<div class="tbl-wrap"><table><thead><tr><th>component</th><th>used</th><th>defined in</th><th>props</th></tr></thead><tbody>${rows}</tbody></table></div>` : ''}
+    ${neverImported.length >= 2 ? `
+    <div class="receipts">${eyebrow(`${n(neverImported.length)} components defined but never imported · candidates for deletion, or the system nobody found`)}
+    <div class="chips-row">${neverImported.slice(0, 8).map((c) => `<span class="vchip" title="${esc(c.file)}">&lt;${esc(c.name)}&gt;</span>`).join('')}${neverImported.length > 8 ? `<span class="vchip dim">+${neverImported.length - 8} more</span>` : ''}</div>
+    <p class="sub" style="margin-top:8px">Routers, dynamic imports and barrel files can hide real usage, so treat this as a shortlist to check, not a demolition order.</p>` : ''}</section>`;
 }
 
 // "Where to start" — at most three moves, every one derived from this repo's
@@ -830,6 +855,8 @@ const html = `<!doctype html>
   footer .brand { color:var(--accent); font-weight:700; text-decoration:none; }
   footer .brand:hover { text-decoration:underline; }
   footer .creds { display:flex; gap:16px; font:700 9.5px/1.6 var(--sans); letter-spacing:.16em; text-transform:uppercase; color:var(--dim2); }
+  .ndot { display:inline-block; width:9px; height:9px; border-radius:3px; margin-right:4px; vertical-align:-1px; box-shadow:inset 0 0 0 1px var(--cell-ring); }
+  .nsim { color:var(--dim2); font-weight:400; padding:0 2px; }
   .gift-sec { margin-top:16px; }
   .gift-stage { position:relative; display:grid; place-items:center; min-height:120px; }
   .gift-stage.open { min-height:0; }

package/skills/roast-my-design-system/scripts/harvest/tokens.mjs

@@ -129,6 +129,8 @@ export function harvestTokens(root, styleFiles, codeFiles) {
   const twArbitrary = new Tally();
   let inlineStyleCount = 0;
   const inlineStyleFiles = new Map();
+  // !important is the cascade admitting defeat; counted per style file.
+  const importantFiles = new Map();
 
   // Colours that appear in a CSS custom-property DEFINITION (--grey-100: #f5f5f5)
   // are deliberate tokens; everything else is a hardcoded stray. The diagnosis
@@ -137,6 +139,8 @@ export function harvestTokens(root, styleFiles, codeFiles) {
   const tokenDefsPerFile = new Map();
 
   const scanCssText = (text, file) => {
+    const imp = (text.match(/!\s*important/gi) ?? []).length;
+    if (imp) importantFiles.set(file, (importantFiles.get(file) ?? 0) + imp);
     for (const m of text.matchAll(/--[\w-]+\s*:\s*([^;{}]+)[;}]/g)) {
       tokenDefsPerFile.set(file, (tokenDefsPerFile.get(file) ?? 0) + 1);
       for (const c of m[1].matchAll(HEX_RE)) tokenDefined.add(normalizeHex(c[0]));
@@ -303,6 +307,11 @@ export function harvestTokens(root, styleFiles, codeFiles) {
       textSizes: twTextSizes.toJSON(),
       arbitrary: twArbitrary.toJSON(),
     },
+    important: {
+      count: [...importantFiles.values()].reduce((a, b) => a + b, 0),
+      files: [...importantFiles.entries()].sort((a, b) => b[1] - a[1]).slice(0, 6)
+        .map(([file, count]) => ({ file, count })),
+    },
     inlineStyles: {
       count: inlineStyleCount,
       files: [...inlineStyleFiles.entries()].sort((a, b) => b[1] - a[1]).slice(0, 10)

package/skills/roast-my-design-system/scripts/lib/nearpairs.mjs

@@ -0,0 +1,31 @@
+/**
+ * Near-identical colour pairs (#f5f5f5 next to #f6f6f6): copy-paste, not
+ * decisions. Hex-parseable colours only; a pair is "near" when every channel
+ * sits within 8 of its twin and alpha matches. Two TOKENS sitting close are a
+ * designed ramp (every good grey scale has near neighbours) and are skipped;
+ * drift needs at least one hardcoded stray. Shared by diagnose and rules.
+ */
+export function hexRgb(v) {
+  const m = /^#([0-9a-f]{3,8})$/i.exec(v);
+  if (!m) return null;
+  let x = m[1];
+  if (x.length === 3 || x.length === 4) x = [...x].map((c) => c + c).join('');
+  if (x.length !== 6 && x.length !== 8) return null;
+  return { r: parseInt(x.slice(0, 2), 16), g: parseInt(x.slice(2, 4), 16), b: parseInt(x.slice(4, 6), 16),
+    a: x.length === 8 ? x.slice(6, 8) : 'ff' };
+}
+
+export function nearColorPairs(colorList) {
+  const hexes = colorList.map((c) => ({ ...c, rgb: hexRgb(c.value) })).filter((c) => c.rgb);
+  const pairs = [];
+  for (let i = 0; i < hexes.length; i++) {
+    for (let j = i + 1; j < hexes.length; j++) {
+      const a = hexes[i].rgb, b = hexes[j].rgb;
+      if (a.a !== b.a) continue;
+      if (hexes[i].isToken && hexes[j].isToken) continue;
+      const d = Math.max(Math.abs(a.r - b.r), Math.abs(a.g - b.g), Math.abs(a.b - b.b));
+      if (d > 0 && d <= 8) pairs.push({ a: hexes[i], b: hexes[j], d });
+    }
+  }
+  return pairs.sort((x, y) => (y.a.count + y.b.count) - (x.a.count + x.b.count));
+}

package/skills/roast-my-design-system/scripts/lib/neverimported.mjs

@@ -0,0 +1,17 @@
+/**
+ * Design-system components defined but never imported — scoped so the claim
+ * is honest. File-local subcomponents elsewhere legitimately never get
+ * imported by name; icon sets are deliberately complete; sub-exports of an
+ * adopted file are API surface, not dead code. Shared by diagnose, rules and
+ * the benchmark builder.
+ */
+export function neverImportedComponents(components, uiDir) {
+  const reusable = (components ?? []).filter((c) => !c.isPage);
+  const dsDirRe = uiDir
+    ? new RegExp(`^${uiDir.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}/`)
+    : /(^|\/)(packages\/ui|design-system|ui-kit)\//;
+  const usedFiles = new Set(reusable.filter((c) => c.usageCount > 0).map((c) => c.file));
+  return reusable.filter((c) => !c.usageCount && dsDirRe.test(c.file)
+    && !/(^|\/)icons?\//.test(c.file)
+    && !usedFiles.has(c.file));
+}

package/skills/roast-my-design-system/scripts/rules/build.mjs

@@ -5,6 +5,8 @@
  * with a receipt from the scanned repo.
  */
 import { distinctTypefaces } from '../lib/typefaces.mjs';
+import { nearColorPairs } from './../lib/nearpairs.mjs';
+import { neverImportedComponents } from '../lib/neverimported.mjs';
 
 export function rulesMarkdown(h) {
 const repoName = h.profile?.name ?? 'this repo';
@@ -36,6 +38,8 @@ const repoName = h.profile?.name ?? 'this repo';
     } else if ((t.colors ?? []).length) {
       rule(`There is no token file yet. Until one exists, reuse the colours already in the codebase instead of introducing new ones (${t.colors.length} distinct colours are already in play).`);
     }
+    const near = nearColorPairs(t.colors ?? []);
+    if (near.length) rule(`Never eyeball a colour from memory: the scan found ${near.length} nearly identical pair${near.length === 1 ? '' : 's'} (like ${near[0].a.value} next to ${near[0].b.value}). Look the exact value up, or better, use its token.`);
     const ds = h.profile?.designSystem;
     if (ds?.kind && !['none', 'custom'].includes(ds.kind) && ds.confidence !== 'low') {
       rule(`This repo uses ${ds.name ?? ds.kind}${h.profile.uiDir ? `; its components live in \`${h.profile.uiDir}\`` : ''}. Prefer extending it over building parallel pieces.`);
@@ -84,7 +88,14 @@ const repoName = h.profile?.name ?? 'this repo';
     if (icons.length) rule(`Two icon sets collide on ${icons.length} name${icons.length === 1 ? '' : 's'}. Before adding any icon, check which set the surrounding file already imports and stay with it.`);
   }
   
-  // ---------- spacing ----------
+  // ---------- never-imported components ----------
+const neverImported = neverImportedComponents(h.components, h.profile?.uiDir);
+if (neverImported.length >= 3) {
+  section('Components nobody imports');
+  rule(`${neverImported.length} components are defined but never imported (${neverImported.slice(0, 3).map((c) => `\`<${c.name}>\``).join(', ')}…). Before writing any new component, check this list first; adopt one or flag it for deletion instead of adding another.`);
+}
+
+// ---------- spacing ----------
   const arbitrary = t.tailwind?.arbitrary ?? [];
   const arbCount = arbitrary.reduce((s, a) => s + a.count, 0);
   const offScale = (t.spacing ?? []).length;
@@ -106,6 +117,7 @@ const repoName = h.profile?.name ?? 'this repo';
   section('Styling discipline');
   rule(`Never write ${reusable.length ? '`style={{ ... }}`' : 'inline `style="..."` attributes'} for static values; styling belongs to classes and tokens where the system can see it.`);
   if ((t.inlineStyles?.count ?? 0) > 0) lines.push(`  (${t.inlineStyles.count} static inline block${t.inlineStyles.count === 1 ? '' : 's'} already exist; do not add to them.)`);
+  if ((t.important?.count ?? 0) >= 3) rule(`Never write !important; the scan found ${t.important.count} declaration${t.important.count === 1 ? '' : 's'} already. When a style does not apply, fix the selector or the source of the conflict instead of shouting over it.`);
   rule('Before styling anything new, look at a neighbouring component and match how it does it. Consistency with the repo beats personal preference.');
   
   lines.push('');