Why Your Reusable Components Keep Breaking (And How to Fix Your API Design)

Ever stared at a component library you built just three weeks ago, only to realize it's already suffocating under a mountain of boolean props like hasBadge, isCompact, and withIcon? I ran into this exact wall recently while refactoring a set of modular landing page cards for a mixed-media client project. What started as a clean, reusable UI module quickly devolved into a brittle spaghetti monster the moment a new layout requirement dropped. Every time a client needed a tiny structural tweak—like shifting an image from top to side, or adding a secondary action tag—I found myself cracking open the core component file and risking regressions across the entire layout. The underlying problem isn't just poor planning; it's treating components like rigid black boxes instead of flexible composition primitives. Here is what that trap looks like in code: // The Trap: A monolithic component buckling under conditional props function ProductCard({ title, price, badgeText, isLarge, hasImage, imageSrc, variant }) { return ( {hasImage && } {badgeText && {badgeText}} {title} {price} ); } To break out of this cycle, I had to shift away from monolithic prop drilling and lean into compound component patterns—handing structural control back to the consumer while keeping styles neatly encapsulated: // The Fix: Composable layout primitives function Card({ children, className }) { return {children}; } Card.Header = function CardHeader({ children }) { return {children}; }; Card.Body = function CardBody({ children }) { return {children}; }; // Usage: Clean, extensible, and untouched core logic export default function App() { return ( Featured Dynamic System Spec Structured layout tokens in motion. ); } My question: How do you usually handle this in your own codebases? Do you enforce strict, heavily-propped components to keep teams locked into a rigid design system, or have you shifted toward compound composition patterns to handle custom layout variations? How do you keep things maintainable?