fix: add defensive styles to prevent global CSS pollution (#214)

Author: mattrothenberg

.changeset/defensive-styles.md

@@ -0,0 +1,48 @@
+---
+"@cloudflare/kumo": patch
+---
+
+fix: add defensive styles to prevent global CSS pollution
+
+## Problem
+
+When Kumo components are used in applications with aggressive global styles (e.g., Stratus's `cfBaseStyles` layer), certain elements get polluted:
+
+- `label { margin-bottom: 1rem }` adds unwanted margins to all labels
+- `button { background: gray }` affects unstyled button wrappers (e.g., tooltip triggers)
+- `a { color: var(--text-color-primary) }` can override link colors if the consuming app defines `--text-color-primary` differently
+
+## Solution
+
+Add defensive Tailwind utility classes directly to components. These:
+
+1. Reset commonly-polluted properties to safe defaults
+2. Use `cn()` (tailwind-merge) so consumer styles via `className` still override them
+3. Are no-ops in clean CSS environments (no visual change in Kumo docs)
+
+## Changes
+
+### Label margins (`m-0`)
+
+- **Label**: `labelVariants()` now includes `m-0`
+- **Field**: `FieldBase.Label` gets `m-0`
+- **Checkbox**: label wrapper gets `m-0`
+- **Radio**: label wrapper gets `m-0`
+- **Switch**: label wrapper gets `m-0`
+
+### Button trigger resets
+
+- **Tooltip trigger** (when `!asChild`): `bg-transparent border-none shadow-none p-0 m-0 h-auto min-h-0 leading-[0] inline-flex items-center`
+- **Collapsible trigger**: `bg-transparent border-none shadow-none p-0 m-0`
+
+### Link color namespace fix
+
+- **Link**: Changed from `text-primary` to `text-kumo-link` to avoid collision with consuming apps that define `--text-color-primary` differently
+
+### Label tooltip composition
+
+- **Label**: Tooltip trigger now uses `<Button variant="ghost" size="xs" shape="square">` with `asChild`, leveraging composition instead of relying on defensive resets
+
+## Docs
+
+Added "Custom Trigger" section to Tooltip docs demonstrating that `className` can fully override defensive styles when not using `asChild`.

packages/kumo-docs-astro/src/components/demos/TooltipDemo.tsx

@@ -1,5 +1,5 @@
 import { Tooltip, TooltipProvider, Button } from "@cloudflare/kumo";
-import { PlusIcon, TranslateIcon } from "@phosphor-icons/react";
+import { Info, PlusIcon, TranslateIcon } from "@phosphor-icons/react";
 
 export function TooltipHeroDemo() {
   return (
@@ -39,3 +39,22 @@ export function TooltipMultipleDemo() {
     </TooltipProvider>
   );
 }
+
+/**
+ * Without `asChild`, Tooltip wraps children in an internal button element.
+ * Defensive styles are applied by default, but you can fully customize
+ * the trigger by passing className - your styles override the defaults.
+ */
+export function TooltipCustomTriggerDemo() {
+  return (
+    <TooltipProvider>
+      <Tooltip
+        content="Click to learn more"
+        className="inline-flex items-center gap-1.5 rounded-full bg-kumo-brand px-3 py-1.5 text-sm font-medium text-white shadow-md transition-transform hover:scale-105 active:scale-95"
+      >
+        <Info className="size-4" />
+        <span>Help</span>
+      </Tooltip>
+    </TooltipProvider>
+  );
+}

packages/kumo-docs-astro/src/pages/components/tooltip.astro

@@ -5,7 +5,7 @@ import ComponentSection from "../../components/docs/ComponentSection.astro";
 import ComponentExample from "../../components/docs/ComponentExample.astro";
 import CodeBlock from "../../components/docs/CodeBlock.astro";
 import PropsTable from "../../components/docs/PropsTable.astro";
-import { TooltipHeroDemo, TooltipBasicDemo, TooltipMultipleDemo } from "../../components/demos/TooltipDemo";
+import { TooltipHeroDemo, TooltipBasicDemo, TooltipMultipleDemo, TooltipCustomTriggerDemo } from "../../components/demos/TooltipDemo";
 ---
 
 <DocLayout
@@ -80,6 +80,24 @@ export default function Example() {
     </div>
   </ComponentSection>
 
+  <ComponentSection>
+    <Heading level={2} class="mb-6">Custom Trigger</Heading>
+    <p class="mb-4 text-sm text-kumo-subtle">
+      We recommend using <code>asChild</code> with a Kumo Button (as shown above). However, when <code>asChild</code> is omitted, 
+      Tooltip wraps children in an internal button element. Defensive styles are applied to protect this element from 
+      global CSS pollution. You can override these defaults via <code>className</code>.
+    </p>
+    <ComponentExample code={`<Tooltip
+  content="Click to learn more"
+  className="inline-flex items-center gap-1.5 rounded-full bg-kumo-brand px-3 py-1.5 text-sm font-medium text-white shadow-md transition-transform hover:scale-105 active:scale-95"
+>
+  <Info className="size-4" />
+  <span>Help</span>
+</Tooltip>`}>
+      <TooltipCustomTriggerDemo client:load />
+    </ComponentExample>
+  </ComponentSection>
+
   <ComponentSection>
     <Heading level={2}>API Reference</Heading>
     <PropsTable component="Tooltip" />