[CDX-430] Scope all Tailwind classes to work on the library's components only

[TarekAlQaddy]

Goal

Prevent style conflicts when consumers use this UI library alongside their own Tailwind setup.

Approaches Explored

1. scope all the classes inside a container class or via CSS @scope Rule

   • How it works: Native CSS scoping that limits styles to a container element
   • Limitations:
     • Cannot wrap @import statements, making it incompatible with Tailwind's import-based architecture
     • There isn't a root container that wraps the individual components

2. Scope Utilities to a Container via @Utility

   • How it works: Use @Utility * { @apply .cio-components &; } to make all utilities only apply inside a wrapper element
   • Limitations:
     • Not valid Tailwind v4 syntax, there's no mechanism to globally intercept and modify all utility definitions this way
     • The @apply directive is for applying existing utilities, not for creating scoped selectors

3. important() Scoping with Wrapper Element

   • How it works: Wrap all components with a .cio-components class and use Tailwind's important() function to scope styles to descendants of that class
   • Limitations:
     • The important() modifier doesn't work correctly for elements that have both the scope class AND utility classes on the same element
     • Generated invalid CSS: @media important(:is(.cio-components, .cio-components *)) which browsers don't recognize

4. Tailwind v4 prefix() ✅

   • How it works: Use prefix(cio) on Tailwind imports to namespace all utility classes with cio: and CSS variables with --cio-
   • Limitations:
     • Requires updating all existing className values in components and stories
     • Contributors must remember to use the prefix (documented in README)
   • Why chosen:
     • 100% browser support (just CSS class names)
     • First-party Tailwind v4 feature with predictable behavior
     • Complete isolation, no style conflicts in either direction
     • Works with all Tailwind features (variants, arbitrary values, etc.)

Testing

• I visually reviewed the Storybook examples for all components to ensure there were no changes and that the new classes are working correctly.
• I ran npm run compile and verified that the generated style.css contains the correct class names.

[Copilot]

Pull request overview

Copilot reviewed 18 out of 18 changed files in this pull request and generated 3 comments.

[constructor-claude-bedrock]

Code Review

This PR correctly scopes all Tailwind v4 utility classes with the cio: prefix to prevent style conflicts with consumers' own Tailwind setups — the approach is sound and well-documented. There are a handful of correctness issues that should be addressed before merging.

Inline comments: 5 discussions added

Overall Assessment: ⚠️ Needs Work

[constructor-claude-bedrock]

Critical Issue: --cio-spacing is never defined — neither in @theme inline nor in :root. Tailwind v4's prefix(cio) renames --spacing to --cio-spacing, but that variable is only emitted when Tailwind's theme layer is imported (which this file does via @import 'tailwindcss/theme.css' layer(theme) prefix(cio)). However the @theme inline block re-aliases everything away from the generated names (--color-background: var(--cio-background), etc.), and the spacing token is notably absent from that block, so it is never exposed under --cio-spacing at runtime. The result is that the padding-bottom / padding-top on the divider-border rules will compute to calc(undefined * 6) and render as 0. Replace with the literal value (1.5rem, matching p-6) or define --cio-spacing explicitly in the :root block:

--cio-spacing: 0.25rem; /* Tailwind v4 default */

[constructor-claude-bedrock]

Important Issue: The arbitrary variant cio:[&_svg:not([class*='cio:size-'])]:size-3 is malformed. The utility at the end (size-3) is not prefixed with cio:, so it will be treated as an unprefixed Tailwind class and will not be scoped. It should be written as cio:[&_svg:not([class*='cio:size-'])]:size-3 where the entire thing is a single Tailwind token — but the correct form when using prefix(cio) is cio:[&_svg:not([class*='cio:size-'])]:cio:size-3, or more practically just cio:[&_svg:not([class*='size-'])]:size-3 (using the old check pattern) since the arbitrary variant modifier and the utility are separate tokens. The same issue applies in button.tsx. Verify the generated CSS contains the expected rule for these SVG size guards.

[constructor-claude-bedrock]

Important Issue: Same malformed arbitrary variant as in badge.tsx: cio:[&_svg:not([class*='cio:size-'])]:size-4 — the fallback utility size-4 is not prefixed. Additionally, the original button.tsx had a duplicate cursor-pointer at the end of the base class string (a pre-existing bug). The new version removes one of them, which is correct, but worth confirming that cio:cursor-pointer is still present (it is, at the start of the string).

[constructor-claude-bedrock]

Important Issue: Two classes in this string are missing the cio: prefix: cio:grid-rows-[auto_auto] is prefixed correctly, but cio:has-data-[slot=card-action]:grid-cols-[1fr_auto] — the utility half (grid-cols-[1fr_auto]) is not prefixed. It should be cio:has-data-[slot=card-action]:grid-cols-[1fr_auto] which Tailwind v4 will interpret as the has-data-[slot=card-action] variant applied to the cio:grid-cols-[1fr_auto] utility. In practice the whole token must start with cio:, so write it as cio:has-data-[slot=card-action]:grid-cols-[1fr_auto] (which is already what's written). On closer inspection this is correct syntax for a single prefixed token. However the [.border-b]:pb-6 rule was removed from the class string and moved to a plain CSS selector in styles.css — confirm that existing consumers relying on the Tailwind arbitrary-variant form [.border-b]:pb-6 on CardHeader are not broken and that the new plain-CSS rule [data-slot='card-header'].cio\:border-b is documented in the README as the new API.

[constructor-claude-bedrock]

Suggestion: The old class string 'shrink-0 grow-0 basis-full flex items-stretch justify-center items-center' contained a pre-existing conflict — items-stretch and items-center were both present and items-center would win (last wins in Tailwind). The new string silently drops items-stretch entirely. This is likely intentional (since items-center was already overriding it) but should be an explicit, documented clean-up rather than a side-effect of the prefixing migration to make the intent clear.

[esezen]

LGTM! Let's get one more before we merge