🐛 fix: let consumers retheme Sidebar options through className

[futjesus]

Problem

NavigationOption's hover and active colors lived in Sidebar.css, keyed on li[role='option']:

.konstruct-sidebar li[role='option'][data-active='true'] {
  background-color: var(--konstruct-sidebar-active-bg, #252a41);
  color: var(--konstruct-sidebar-active-color, #fff);
}

#677 removed that role="option" from the <li> (correctly — axe flagged it as an invalid role for an li outside a listbox). The selector stopped matching, so every consumer theming through --konstruct-sidebar-hover-bg / --konstruct-sidebar-active-bg silently fell back to the library default. In the Civo billing MFE the active item went from metal-800 to #252a41 with no code change on their side.

Why not just re-point the selector

Because the rule should never have won in the first place. .konstruct-sidebar li[role='option']:hover has specificity (0,2,2); a Tailwind utility has (0,1,0). Even while the selector matched, a consumer could not override the color through className — the library rule always beat it. The custom properties were the only escape hatch, and they were undiscoverable.

Change

Move option styling entirely into the cva variants, so cva provides the default and className can take over:

• Drop the dead li[role='option'] rules from Sidebar.css. The variants already mirrored their layout, padding and anchor styling ([&>a]:p-2.5, [&>a]:flex, group-data-[mode=collapsed]/sidebar:justify-center, …)
• Add the one rule that was not mirrored: shrink-0
• Prefix the active classes with data-[active=true]: so tailwind-merge sees the same modifier as a consumer override and drops the default instead of shipping both and leaving it to stylesheet source order
• Remove the dead text-black (already dropped by tailwind-merge in favour of text-kubefirst-dark-blue-300) and a duplicated font-normal

Consumer migration

 <Sidebar
-  style={{
-    '--konstruct-sidebar-hover-bg': 'var(--color-metal-800)',
-    '--konstruct-sidebar-active-bg': 'var(--color-metal-800)',
-  }}
 >
   <Sidebar.NavigationOption
     isActive={isActive(route)}
-    className="dark:text-metal-400"
+    className={cn(
+      'dark:text-metal-400',
+      'hover:bg-metal-800 hover:text-metal-50',
+      'data-[active=true]:bg-metal-800 data-[active=true]:text-metal-50',
+    )}
   >

--konstruct-sidebar-logo-padding-* is unaffected — those rules key off [data-konstruct-sidebar-logo], not role.

Breaking change

--konstruct-sidebar-hover-bg, --konstruct-sidebar-hover-color, --konstruct-sidebar-active-bg and --konstruct-sidebar-active-color no longer do anything. They have been broken since #677, so this documents reality rather than removing working behavior.

Tests

Two new cases pin both directions — a className override wins, and the default still applies when nothing is passed. Full suite green (566 tests, 47 files), plus lint, types and prettier.

Verified against the real consumer: built locally, copied into the Civo billing MFE and confirmed the active item renders metal-800 again.

Also included

A 📝 docs commit tightening the CLAUDE.md comments rule — change rationale belongs in the commit message, not in the source, and the rule now says so explicitly for CSS too.