How a Frontend Team Rebuilt Its Design System

In early 2023, the Kakaostyle Zigzag FE team began rebuilding its design system to unify product card components that had been managed separately across the codebase. It wasn't just simple refactoring—it was work to rebuild the foundation for managing UI/UX in an integrated way.

Initially, a single package contained colors, icons, themes, and components all together, and as changes became more frequent, barrel file management and dependency conflicts emerged as problems. To solve this, the team modularized the system by dividing it into Core, Components, Icons, Themes, Tokens, and ZDS roles, prioritizing practical maintainability over excessive granularity in the early stages.

For styling, the team moved from Emotion, a runtime CSS-in-JS solution, to Vanilla Extract. The selection criteria were as follows.

• Can it support CSS variable-based token management?
• Can it handle theme switching flexibly?
• Does it provide type safety and prevent typos?
• Is the bundle size light and close to zero runtime?
• Is the learning curve manageable for the team?

After comparison, the team judged that Vanilla Extract was the best fit in terms of type safety, utilities, and RSC compatibility. In particular, by using createGlobalThemeContract and createGlobalTheme to separate token contracts from actual values, the final CSS retained meaningful variable names like --color-text-primary.

The previous approach relied on ThemeProvider and React state to inject themes, so only actual values remained in the CSS and the meaning of the tokens was lost. Also, FOUC could occur during prefers-color-scheme detection and state synchronization, but switching to a CSS variable-based approach reduced this issue by handling themes at the browser level.

Product card integration was solved with a compound component pattern and hierarchical design. Blocks such as Thumbnail, Metadata, and MetadataItem were placed under ProductCard, allowing flexible composition per page, while also separating UI logic, business logic, and page-specific logic to reduce duplication.

As a result, the team organized the product card structure, including vertical and horizontal layouts, and successfully integrated product cards across 11 pages through shared custom hooks and service components. With the design system rebuild and product card unification completed together, the team secured both maintainability and scalability.