@latte-macchiat-io/latte-vanilla-components 0.0.339 → 0.0.341

package/README.md

@@ -295,6 +295,76 @@ const customButton = style({
 });
 ```
 
+### Overriding Component Styles
+
+All components accept a `className` prop for customization. However, due to CSS cascade order in bundled applications (Next.js, Webpack, etc.), you need to use proper specificity to ensure your styles override library defaults.
+
+#### Recommended: Use `styleOverride` Utility
+
+```tsx
+import { Button, styleOverride } from '@latte-macchiat-io/latte-vanilla-components';
+
+const customButton = styleOverride({
+  textTransform: 'uppercase',
+  letterSpacing: '0.1em',
+  backgroundColor: '#FF0000',
+  padding: '20px 40px',
+});
+
+<Button variant="primary" className={customButton}>
+  Custom Styled Button
+</Button>
+```
+
+**Why use `styleOverride`?** In production builds, CSS files are split into multiple chunks (`layout.css`, `page.css`, etc.). This can cause library styles to override your customizations even when your className appears last in the HTML. The `styleOverride` utility uses CSS attribute selectors to increase specificity from `(0,1,0)` to `(0,2,0)`, ensuring your styles always win.
+
+#### Manual Override (Advanced)
+
+If you prefer manual control:
+
+```tsx
+import { style } from '@vanilla-extract/css';
+
+const customButton = style({
+  selectors: {
+    '&[class]': {
+      // Your styles here - guaranteed to override library styles
+      backgroundColor: '#FF0000',
+      border: '2px solid #000',
+    },
+  },
+});
+```
+
+#### Combining Class Names
+
+Use the exported `cn` utility for conditional class names:
+
+```tsx
+import { cn, styleOverride } from '@latte-macchiat-io/latte-vanilla-components';
+
+const baseButton = styleOverride({ padding: '20px' });
+const activeButton = styleOverride({ backgroundColor: 'red' });
+
+<Button className={cn(baseButton, isActive && activeButton)}>
+  Conditional Styles
+</Button>
+```
+
+#### Troubleshooting Style Overrides
+
+**Problem:** Custom styles aren't applying
+
+**Solutions:**
+1. Use `styleOverride` utility instead of plain `style()`
+2. Check browser DevTools to see which CSS rule is winning
+3. Verify your className appears in the rendered HTML
+4. Clear build cache: `rm -rf .next && npm run dev`
+
+**Problem:** Styles work in dev but not production
+
+**Solution:** This is a CSS chunking issue. Using `styleOverride` ensures proper specificity regardless of load order.
+
 ## 🎯 Performance
 
 - **Zero Runtime CSS-in-JS** - All styles compiled at build time

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@latte-macchiat-io/latte-vanilla-components",
-  "version": "0.0.339",
+  "version": "0.0.341",
   "description": "Beautiful components for amazing projects, with a touch of Vanilla 🥤",
   "type": "module",
   "main": "./src/index.ts",
@@ -9,6 +9,7 @@
   "exports": {
     ".": "./src/index.ts",
     "./*.css.ts": "./src/*.css.ts",
+    "./utils/*": "./src/utils/*.ts",
     "./src/*": "./src/*"
   },
   "files": [
@@ -44,7 +45,6 @@
     "@vanilla-extract/recipes": "^0.5.7",
     "@vanilla-extract/sprinkles": "^1.6.5",
     "@vanilla-extract/vite-plugin": "^5.1.1",
-    "clsx": "^2.1.1",
     "eslint": "^9.15.0",
     "eslint-config-prettier": "^10.0.1",
     "eslint-import-resolver-typescript": "^4.4.4",

package/src/components/Actions/index.tsx

@@ -1,6 +1,6 @@
-import { clsx } from 'clsx';
-
 import { actionsRecipe, type ActionsVariants } from './styles.css';
+import { cn } from '../../utils/styleOverride';
+
 
 export type ActionsProps = React.HTMLAttributes<HTMLDivElement> &
   ActionsVariants & {
@@ -8,5 +8,5 @@ export type ActionsProps = React.HTMLAttributes<HTMLDivElement> &
   };
 
 export const Actions = ({ align, direction, className, children }: ActionsProps) => (
-  <div className={clsx(actionsRecipe({ align, direction }), className)}>{children}</div>
+  <div className={cn(actionsRecipe({ align, direction }), className)}>{children}</div>
 );

package/src/components/Button/index.tsx

@@ -1,7 +1,7 @@
-import { clsx } from 'clsx';
 
 import { buttonRecipe, type ButtonVariants } from './styles.css';
 import { AllowedButton } from './types';
+import { cn } from '../../utils/styleOverride';
 
 export type ButtonProps = React.HTMLAttributes<HTMLButtonElement | HTMLAnchorElement> &
   ButtonVariants & {
@@ -30,14 +30,14 @@ export const Button = ({
 }: ButtonProps) => {
   if (as === 'a') {
     return (
-      <a href={href} className={clsx(buttonRecipe({ variant, style, size, fullWidth }), className)}>
+      <a href={href} className={cn(buttonRecipe({ variant, style, size, fullWidth }), className)}>
         {children}
       </a>
     );
   }
 
   return (
-    <button onClick={onClick} disabled={isDisabled || isPending} className={clsx(buttonRecipe({ variant, style, size, fullWidth }), className)}>
+    <button onClick={onClick} disabled={isDisabled || isPending} className={cn(buttonRecipe({ variant, style, size, fullWidth }), className)}>
       {isPending ? translation.isPendingLabel : children}
     </button>
   );

package/src/components/Carousel/index.tsx

@@ -1,6 +1,5 @@
 'use client';
 
-import { clsx } from 'clsx';
 import { ReactNode, useEffect, useRef, useState } from 'react';
 
 import {
@@ -20,6 +19,7 @@ import {
 
 import { breakpoints } from '../../styles/mediaqueries';
 import { getResponsiveValue, parseResponsiveNumber } from '../../utils/getResponsiveValue';
+import { cn } from '../../utils/styleOverride';
 import { useWindowSize } from '../../utils/useWindowSize';
 
 import { Icon } from '../Icon';
@@ -172,7 +172,7 @@ export const Carousel = ({
   const maxIndex = Math.max(0, data.length - visibleItems);
 
   return (
-    <div className={clsx(carouselRecipe({ isFullWidth }), className)}>
+    <div className={cn(carouselRecipe({ isFullWidth }), className)}>
       <div ref={carouselRef} className={carouselContent({ overflow })}>
         <div
           ref={slideRef}
@@ -208,7 +208,7 @@ export const Carousel = ({
               type="button"
               aria-label={`Go to slide ${index + 1}`}
               onClick={() => handleBulletClick(index)}
-              className={clsx(carouselBullet, index === currentIndex && carouselBulletActive)}
+              className={cn(carouselBullet, index === currentIndex && carouselBulletActive)}
             />
           ))}
         </div>

package/src/components/Columns/index.tsx

@@ -1,6 +1,6 @@
-import { clsx } from 'clsx';
-
 import { columnsRecipe, ColumnsVariants } from './styles.css';
+import { cn } from '../../utils/styleOverride';
+
 
 export type ColumnsProps = React.HTMLAttributes<HTMLDivElement> &
   ColumnsVariants & {
@@ -12,7 +12,7 @@ export const Columns = ({ align, vAlign, columns, children, className }: Columns
   const columnsValue = columns.map((c) => `${c}fr`).join(' ');
 
   return (
-    <div className={clsx(columnsRecipe({ align, vAlign }), className)} style={{ ['--columns' as never]: columnsValue }}>
+    <div className={cn(columnsRecipe({ align, vAlign }), className)} style={{ ['--columns' as never]: columnsValue }}>
       {children}
     </div>
   );

package/src/components/ConsentCookie/index.tsx

@@ -1,10 +1,10 @@
 'use client';
 
-import { clsx } from 'clsx';
 import { useEffect, useState } from 'react';
 
 import { getCookie, setCookie } from './cookie';
 import { consentActions, consentContent, type ConsentCookieVariants, consentRecipe } from './styles.css';
+import { cn } from '../../utils/styleOverride';
 
 import { Button } from '../Button';
 
@@ -89,7 +89,7 @@ export const ConsentCookie = ({
   if (!showConsent) return null;
 
   return (
-    <div className={clsx(consentRecipe({ variant }), className)} role="dialog" aria-modal="true" aria-labelledby="consent-title">
+    <div className={cn(consentRecipe({ variant }), className)} role="dialog" aria-modal="true" aria-labelledby="consent-title">
       <div className={consentContent}>
         {children}
         <div className={consentActions}>

package/src/components/Footer/index.tsx

@@ -1,9 +1,9 @@
-import { clsx } from 'clsx';
-
 import { footerRecipe } from './styles.css';
+import { cn } from '../../utils/styleOverride';
+
 
 export type FooterProps = React.HTMLAttributes<HTMLDivElement> & {
   children: React.ReactNode;
 };
 
-export const Footer = ({ children, className }: FooterProps) => <footer className={clsx(footerRecipe, className)}>{children}</footer>;
+export const Footer = ({ children, className }: FooterProps) => <footer className={cn(footerRecipe, className)}>{children}</footer>;

package/src/components/Form/Row/index.tsx

@@ -1,13 +1,13 @@
-import { clsx } from 'clsx';
 import { forwardRef } from 'react';
 
 import { rowRecipe, type RowVariants } from './styles.css';
+import { cn } from '../../utils/styleOverride';
 
 export type RowProps = React.HTMLAttributes<HTMLDivElement> & RowVariants;
 
 export const Row = forwardRef<HTMLDivElement, RowProps>(({ children, align, className }, ref) => {
   return (
-    <div ref={ref} className={clsx(rowRecipe({ align }), className)}>
+    <div ref={ref} className={cn(rowRecipe({ align }), className)}>
       {children}
     </div>
   );

package/src/components/Form/TextField/Input/index.tsx

@@ -1,12 +1,12 @@
-import { clsx } from 'clsx';
 import { inputRecipe } from './styles.css';
 
 import { InputType } from './types';
+import { cn } from '../../../utils/styleOverride';
 
 export type InputProps = React.InputHTMLAttributes<HTMLInputElement> & {
   type?: InputType;
 };
 
 export const Input = ({ name, type = 'text', value, required, placeholder, className }: InputProps) => (
-  <input id={name} name={name} type={type} value={value} required={required} placeholder={placeholder} className={clsx(inputRecipe(), className)} />
+  <input id={name} name={name} type={type} value={value} required={required} placeholder={placeholder} className={cn(inputRecipe(), className)} />
 );

package/src/components/Form/TextField/Label/index.tsx

@@ -1,6 +1,6 @@
-import { clsx } from 'clsx';
-
 import { labelRecipe, type LabelVariants } from './styles.css';
+import { cn } from '../../../utils/styleOverride';
+
 
 export type LabelProps = React.LabelHTMLAttributes<HTMLLabelElement> &
   LabelVariants & {
@@ -10,7 +10,7 @@ export type LabelProps = React.LabelHTMLAttributes<HTMLLabelElement> &
   };
 
 export const Label = ({ label, name, required, className }: LabelProps) => (
-  <label htmlFor={name} className={clsx(labelRecipe(), className)}>
+  <label htmlFor={name} className={cn(labelRecipe(), className)}>
     {label} {required && '*'}
   </label>
 );

package/src/components/Form/TextField/Textarea/index.tsx

@@ -1,11 +1,11 @@
-import { clsx } from 'clsx';
-
 import { textareaRecipe } from './styles.css';
+import { cn } from '../../../utils/styleOverride';
+
 
 export type TextareaProps = React.TextareaHTMLAttributes<HTMLTextAreaElement> & {
   name: string;
 };
 
 export const Textarea = ({ name, rows, className }: TextareaProps) => (
-  <textarea id={name} rows={rows} name={name} className={clsx(textareaRecipe(), className)} />
+  <textarea id={name} rows={rows} name={name} className={cn(textareaRecipe(), className)} />
 );

package/src/components/Form/TextField/index.tsx

@@ -1,6 +1,5 @@
 'use client';
 
-import { clsx } from 'clsx';
 import { useMemo } from 'react';
 
 import { Input } from './Input';
@@ -8,6 +7,7 @@ import { InputType } from './Input/types';
 
 import { errorMessage, messageContainer, textFieldRecipe } from './styles.css';
 import { Textarea } from './Textarea';
+import { cn } from '../../utils/styleOverride';
 
 type CommonProps = {
   name: string;
@@ -31,7 +31,7 @@ export const TextField = (props: TextFieldProps) => {
   const isTextarea = type === 'textarea';
 
   return (
-    <div className={clsx(textFieldRecipe(), className)}>
+    <div className={cn(textFieldRecipe(), className)}>
       {label && <label htmlFor={name}>{label}</label>}
 
       {isTextarea ? (

package/src/components/Form/index.tsx

@@ -1,5 +1,5 @@
-import { clsx } from 'clsx';
 import { formRecipe } from './styles.css';
+import { cn } from '../../utils/styleOverride';
 
 export type FormProps = React.HTMLAttributes<HTMLDivElement> & {
   as?: 'form' | 'div';
@@ -8,5 +8,5 @@ export type FormProps = React.HTMLAttributes<HTMLDivElement> & {
 
 export const Form = ({ as = 'form', children, className }: FormProps) => {
   const Component = as;
-  return <Component className={clsx(formRecipe(), className)}>{children}</Component>;
+  return <Component className={cn(formRecipe(), className)}>{children}</Component>;
 };

package/src/components/Header/HeaderToggleNav/index.tsx

@@ -1,7 +1,7 @@
-import { clsx } from 'clsx';
 
 import { ReactNode } from 'react';
 import { bar, toggleNavButton, toggleNavButtonMenu } from './styles.css';
+import { cn } from '../../../utils/styleOverride';
 
 export type HeaderToggleNavProps = React.HTMLAttributes<HTMLDivElement> & {
   isOpen?: boolean;
@@ -11,12 +11,12 @@ export type HeaderToggleNavProps = React.HTMLAttributes<HTMLDivElement> & {
 
 export const HeaderToggleNav = ({ isOpen, onClick, children, className }: HeaderToggleNavProps) => {
   return (
-    <button onClick={onClick} aria-label="Toggle navigation" className={clsx(toggleNavButton(), className)}>
+    <button onClick={onClick} aria-label="Toggle navigation" className={cn(toggleNavButton(), className)}>
       {children || (
         <span className={toggleNavButtonMenu()}>
-          <span className={clsx(bar, isOpen && 'open')} />
-          <span className={clsx(bar, isOpen && 'open')} />
-          <span className={clsx(bar, isOpen && 'open')} />
+          <span className={cn(bar, isOpen && 'open')} />
+          <span className={cn(bar, isOpen && 'open')} />
+          <span className={cn(bar, isOpen && 'open')} />
         </span>
       )}
     </button>

package/src/components/Header/index.tsx

@@ -1,10 +1,10 @@
 'use client';
 
-import clsx from 'clsx';
 import { useState } from 'react';
 
 import { HeaderToggleNav } from './HeaderToggleNav';
 import { headerOverlayRecipe, headerPlaceholder, headerRecipe, headerToggleNav, HeaderToggleNavVariants } from './styles.css';
+import { cn } from '../../utils/styleOverride';
 
 export type HeaderProps = React.HTMLAttributes<HTMLDivElement> &
   HeaderToggleNavVariants & {
@@ -30,7 +30,7 @@ export const Header = ({ children, childrenOverlay, childrenToggleNav, isFixed =
 
   return (
     <>
-      <header className={clsx(headerRecipe({ isFixed }), className)}>
+      <header className={cn(headerRecipe({ isFixed }), className)}>
         {childrenOverlay && <div className={headerOverlayRecipe({ isOpen: isNavOpen })}>{childrenOverlay}</div>}
 
         {children}

package/src/components/Heading/index.tsx

@@ -1,8 +1,8 @@
-import { clsx } from 'clsx';
 import parse from 'html-react-parser';
 
 import { headingRecipe, HeadingVariants } from './styles.css';
 import { AllowedHeading } from './types';
+import { cn } from '../../utils/styleOverride';
 
 export type HeadingProps = React.HTMLAttributes<HTMLHeadingElement> &
   HeadingVariants & {
@@ -24,7 +24,7 @@ export const Heading = ({ as, size, className, children }: HeadingProps) => {
   const resolvedSize = size ?? levelToSize[as];
 
   return (
-    <Component className={clsx(headingRecipe({ size: resolvedSize, as }), className)}>
+    <Component className={cn(headingRecipe({ size: resolvedSize, as }), className)}>
       {parse(typeof children === 'string' ? children : '')}
     </Component>
   );

package/src/components/Icon/index.tsx

@@ -1,9 +1,9 @@
-import clsx from 'clsx';
 
 import path from './path';
 
 import { iconRecipe } from './style.css';
 import { themeContract } from '../../theme/contract.css';
+import { cn } from '../../utils/styleOverride';
 
 export type IconProps = React.HTMLAttributes<HTMLDivElement> & {
   icon?: string;
@@ -17,7 +17,7 @@ export const Icon = ({ icon = '', className, size = 24, iconPath = '', viewBox =
   const d = iconPath || path[icon as keyof typeof path];
 
   return (
-    <svg className={clsx(iconRecipe, className)} viewBox={viewBox} width={`${size}px`} height={`${size}px`}>
+    <svg className={cn(iconRecipe, className)} viewBox={viewBox} width={`${size}px`} height={`${size}px`}>
       <path className={iconPath} d={d} fill={color} />
     </svg>
   );

package/src/components/KeyNumber/index.tsx

@@ -1,12 +1,12 @@
 'use client';
 
-import { clsx } from 'clsx';
 import { forwardRef } from 'react';
 import CountUp from 'react-countup';
 
 import { useInView } from 'react-intersection-observer';
 
 import { keyNumberRecipe, keyNumberValueRecipe, KeyNumberValueVariants, type KeyNumberVariants } from './styles.css';
+import { cn } from '../../utils/styleOverride';
 
 export type KeyNumberProps = React.HTMLAttributes<HTMLDivElement> &
   KeyNumberVariants &
@@ -39,7 +39,7 @@ export const KeyNumber = forwardRef<HTMLDivElement, KeyNumberProps>(
             }
           }
         }}
-        className={clsx(keyNumberRecipe({ align, vAlign }), className)}>
+        className={cn(keyNumberRecipe({ align, vAlign }), className)}>
         {prefix}&nbsp;
         <CountUp end={inView ? value : 0} duration={duration} separator={separator} decimals={decimals} className={keyNumberValueRecipe({ size })} />
         &nbsp;{suffix}

package/src/components/LanguageSwitcher/index.tsx

@@ -1,5 +1,5 @@
-import { clsx } from 'clsx';
 import { languageSwitcherIcon, languageSwitcherRecipe, languageSwitcherSelect, type LanguageSwitcherVariants } from './styles.css';
+import { cn } from '../../utils/styleOverride';
 
 import { Icon } from '../Icon';
 
@@ -31,7 +31,7 @@ export const LanguageSwitcher = ({
   const handleSelectChange = (event: React.ChangeEvent<HTMLSelectElement>) => onChange(event.target.value);
 
   return (
-    <div className={clsx(languageSwitcherRecipe({ variant, size }), className)}>
+    <div className={cn(languageSwitcherRecipe({ variant, size }), className)}>
       <select className={languageSwitcherSelect} value={currentLocale} onChange={handleSelectChange} disabled={disabled} aria-label="Switch language">
         {placeholder && (
           <option value="" disabled>

package/src/components/Logo/index.tsx

@@ -1,10 +1,10 @@
-import { clsx } from 'clsx';
 import { ReactNode } from 'react';
 
 import { logo } from './styles.css';
+import { cn } from '../../utils/styleOverride';
 
 export type LogoProps = React.HTMLAttributes<HTMLDivElement> & {
   children?: ReactNode;
 };
 
-export const Logo = ({ children, className }: LogoProps) => <div className={clsx(logo, className)}>{children}</div>;
+export const Logo = ({ children, className }: LogoProps) => <div className={cn(logo, className)}>{children}</div>;

package/src/components/Main/index.tsx

@@ -1,9 +1,9 @@
-import { clsx } from 'clsx';
-
 import { main } from './styles.css';
+import { cn } from '../../utils/styleOverride';
+
 
 export type MainProps = React.HTMLAttributes<HTMLDivElement> & {
   children: React.ReactNode;
 };
 
-export const Main = ({ className, children }: MainProps) => <main className={clsx(main, className)}>{children}</main>;
+export const Main = ({ className, children }: MainProps) => <main className={cn(main, className)}>{children}</main>;

package/src/components/Modal/index.tsx

@@ -1,11 +1,11 @@
 'use client';
 
-import { clsx } from 'clsx';
 import { ReactNode, useState } from 'react';
 
 import { modal, modalContentCloseButton, modalContentRecipe, type ModalVariants } from './styles.css';
 
 import { themeContract } from '../../theme/contract.css';
+import { cn } from '../../utils/styleOverride';
 import { Actions } from '../Actions';
 import { Button } from '../Button';
 import { Icon } from '../Icon';
@@ -39,7 +39,7 @@ export const Modal = ({ triggerLabel, className, children, align, withCloseButto
 
       {isOpen && (
         <div className={modal} role="dialog" aria-modal="true">
-          <div className={clsx(modalContentRecipe({ align }), className)}>
+          <div className={cn(modalContentRecipe({ align }), className)}>
             {withCloseButton && (
               <button type="button" className={modalContentCloseButton} onClick={closeModal} aria-label="Close modal">
                 <Icon icon="close" color={themeContract.modal.closeButtonColor} />

package/src/components/Nav/index.tsx

@@ -1,10 +1,10 @@
-import { clsx } from 'clsx';
-
 import { navRecipe, NavVariants } from './styles.css';
+import { cn } from '../../utils/styleOverride';
+
 
 export type NavProps = React.HTMLAttributes<HTMLDivElement> &
   NavVariants & {
     children: React.ReactNode;
   };
 
-export const Nav = ({ children, className, direction }: NavProps) => <div className={clsx(navRecipe({ direction }), className)}>{children}</div>;
+export const Nav = ({ children, className, direction }: NavProps) => <div className={cn(navRecipe({ direction }), className)}>{children}</div>;

package/src/components/NavLegal/index.tsx

@@ -1,9 +1,9 @@
-import { clsx } from 'clsx';
-
 import { navLegalRecipe } from './styles.css';
+import { cn } from '../../utils/styleOverride';
+
 
 export type NavLegalProps = React.HTMLAttributes<HTMLDivElement> & {
   children: React.ReactNode;
 };
 
-export const NavLegal = ({ className, children }: NavLegalProps) => <div className={clsx(navLegalRecipe(), className)}>{children}</div>;
+export const NavLegal = ({ className, children }: NavLegalProps) => <div className={cn(navLegalRecipe(), className)}>{children}</div>;

package/src/components/NavSocial/index.tsx

@@ -1,7 +1,7 @@
-import { clsx } from 'clsx';
 
 import { navSocialLink, navSocialRecipe } from './styles.css';
 import { Social } from './types';
+import { cn } from '../../utils/styleOverride';
 import { Icon } from '../Icon';
 import icons from '../Icon/path';
 
@@ -11,7 +11,7 @@ export type NavSocialProps = React.HTMLAttributes<HTMLDivElement> & {
 };
 
 export const NavSocial = ({ size = 24, navSocial, className }: NavSocialProps) => (
-  <div className={clsx(navSocialRecipe(), className)}>
+  <div className={cn(navSocialRecipe(), className)}>
     {navSocial?.map(({ name, link }, index) => {
       const capitalized = name[0].toUpperCase() + name.slice(1);
 

package/src/components/Paragraph/index.tsx

@@ -1,7 +1,7 @@
-import { clsx } from 'clsx';
 import parse from 'html-react-parser';
 
 import { paragraphRecipe, type ParagraphVariants } from './styles.css';
+import { cn } from '../../utils/styleOverride';
 
 export type ParagraphProps = React.HTMLAttributes<HTMLDivElement> &
   ParagraphVariants & {
@@ -9,5 +9,5 @@ export type ParagraphProps = React.HTMLAttributes<HTMLDivElement> &
   };
 
 export const Paragraph = ({ align, className, children }: ParagraphProps) => (
-  <p className={clsx(paragraphRecipe({ align }), className)}>{parse(typeof children === 'string' ? children : '')}</p>
+  <p className={cn(paragraphRecipe({ align }), className)}>{parse(typeof children === 'string' ? children : '')}</p>
 );

package/src/components/Section/index.tsx

@@ -1,6 +1,6 @@
-import { clsx } from 'clsx';
-
 import { sectionContent, sectionRecipe, type SectionVariants } from './styles.css';
+import { cn } from '../../utils/styleOverride';
+
 
 export type SectionProps = React.HTMLAttributes<HTMLDivElement> &
   SectionVariants & {
@@ -21,7 +21,7 @@ export const Section = ({
 }: SectionProps) => (
   <section
     style={style}
-    className={clsx(sectionRecipe({ align, isDark, variant, isFullHeight, withPaddingTop, withPaddingBottom, isHeaderFixed }), className)}>
+    className={cn(sectionRecipe({ align, isDark, variant, isFullHeight, withPaddingTop, withPaddingBottom, isHeaderFixed }), className)}>
     <div className={sectionContent}>{children}</div>
   </section>
 );

package/src/components/Video/index.tsx

@@ -1,6 +1,5 @@
 'use client';
 
-import { clsx } from 'clsx';
 import { useEffect, useRef, useState } from 'react';
 
 import {
@@ -15,6 +14,7 @@ import {
   type VideoVariants,
 } from './styles.css';
 import { themeContract } from '../../theme/contract.css';
+import { cn } from '../../utils/styleOverride';
 import { Icon } from '../Icon';
 
 export type VideoProps = React.HTMLAttributes<HTMLDivElement> &
@@ -82,7 +82,7 @@ export const Video = ({
   }, [isMuted]);
 
   return (
-    <div className={clsx(videoRecipe({ size }), className)}>
+    <div className={cn(videoRecipe({ size }), className)}>
       <video ref={videoRef} className={videoElement} playsInline muted={isMuted} autoPlay={isAutoPlay} onEnded={handleVideoEnded}>
         <source src={video} type="video/mp4" />
       </video>

package/src/index.ts

@@ -6,6 +6,7 @@ export { createLightTheme, createDarkTheme, type ThemeOverrides } from './theme/
 // Styles utilities (sprinkles, media queries, etc.)
 export { sprinkles, type Sprinkles } from './styles/sprinkles.css';
 export { breakpoints, queries } from './styles/mediaqueries';
+export { styleOverride, cn } from './utils/styleOverride';
 
 // Components
 

package/src/utils/styleOverride.ts

@@ -0,0 +1,43 @@
+import { style, StyleRule } from '@vanilla-extract/css';
+
+/**
+ * Creates a style override with higher specificity to ensure consumer styles
+ * always win over library component styles, regardless of CSS load order.
+ *
+ * Uses the [class] attribute selector to increase specificity from (0,1,0) to (0,2,0).
+ *
+ * @example
+ * ```tsx
+ * import { styleOverride } from '@latte-macchiat-io/latte-vanilla-components/utils/styleOverride';
+ *
+ * const customButton = styleOverride({
+ *   textTransform: 'uppercase',
+ *   letterSpacing: '0.1em',
+ *   backgroundColor: 'red',
+ * });
+ *
+ * <Button className={customButton}>My Button</Button>
+ * ```
+ */
+export function styleOverride(styleRule: StyleRule) {
+  return style({
+    selectors: {
+      '&[class]': styleRule,
+    },
+  });
+}
+
+/**
+ * Alternative utility that merges class names properly.
+ * This is a lightweight replacement for clsx with better type safety.
+ *
+ * @example
+ * ```tsx
+ * import { cn } from '@latte-macchiat-io/latte-vanilla-components/utils/styleOverride';
+ *
+ * <Button className={cn(baseStyle, customStyle)} />
+ * ```
+ */
+export function cn(...classes: (string | undefined | null | false)[]) {
+  return classes.filter(Boolean).join(' ');
+}