1. Overview
During the project, I experienced the issue of increasingly complex management of color and style variables while operating a SCSS-based style system. Initially, simple variable declarations were sufficient, but as the scale of the service grew and various UI components were added, the roles of the variables became unclear and duplicate definitions increased.
In particular, in structures where common UI is used across multiple services, there have been cases of using the same color with different names, which led to decreased maintainability and collaboration efficiency. From the perspective of design systems, the “value-centric” structure also had limitations, and the need to reconstruct it into a meaning-based token system has increased.
Accordingly, the existing SCSS variable structure has been refactored into a design token-based structure, and the system has been redesigned in the direction of improving maintainability and scalability.
Additionally, the existing style definitions were mixed within the components, making common style management difficult. As the requirements for each service increased, there were more style variations even within the same component, leading to low code readability. To resolve this issue, we considered managing common design standards on a token basis.
2. Issues with the existing structure
The existing variable structure was managed with names close to actual color values, such as --gray200 and --primary600. This method allowed for fast initial development, but various problems arose as the size of the project increased.
The first limitation was conveying meaning. It was difficult to determine whether a given color was for text, background, or border based solely on the variable name. As a result, interpretations could vary among developers, leading to increased communication costs during collaboration.
The second issue was the problem of duplicate definitions. When developing new UI, it has become common to redefine similar colors rather than reusing existing colors. As a result, the consistency of the design system has gradually weakened.
The third issue was the increase in maintenance costs. It became difficult to identify the scope affected by changes to specific colors, leading to unexpected UI changes. In particular, the process of tracking the impact of variables used in common components was inefficient.
As the customization of styles at the component level increased, the possibility of style conflicts also rose. As the project scale grew, it became difficult to manage reliably with just a variable system, and a more systematic structural design was necessary.
3. Improvement Direction
To solve the above problem, we have introduced a meaning-centered design token system that goes beyond a simple value-based structure. The tokens are designed in a three-tier hierarchy of Primitive, Alias, and Semantic.
3.1 Primitive Token
Primitive Token defines the actual color values. For example, it manages the actual HEX values of gray scale, primary scale, etc.
3.2 Alias Token
Alias Token defines the role of colors. For example, it has been grouped and managed into meaningful units such as text, border, background, etc.
3.3 Semantic Token
Semantic tokens are the stage that applies to actual UI elements. It defines tokens used at the actual component level, such as button background colors, card borders, and status messages.
Through this structure, it has become possible to manage styles based on meaning rather than just simple values, allowing for more systematic management of common UI and service-specific UI.
We have also laid the foundation for flexible responses to dark mode or service-specific theme extensions by hierarchizing the token structure. Previously, changing colors required modifications throughout the entire code, but with the current structure, you can reflect changes consistently across the entire UI by only modifying specific layers.
4. Application Process
In the process of introducing the token structure, the entire style structure was overhauled not just by changing simple variable names, but based on actual usage purposes.
First, we conducted a comprehensive survey of existing SCSS variables to analyze where they are used in screens and components. Based on this, we proceeded to reclassify them by meaning units.
We also utilized SCSS's @use and @forward to build a modular system. Each token layer was separated by file, and the import structure was unified through _index.scss. This clarified dependencies and allowed for explicit use of only the necessary tokens.
Considering that replacing the entire code at once poses a significant risk, we implemented a gradual application strategy. We prioritized applying it to new pages and areas that needed revision, transitioning steadily while operating alongside the existing code.
We also collaborated with the design team to整理the token naming conventions and document common standards. This process greatly helped in organizing not only code improvement but also collaboration processes.
During the actual implementation process, we repeatedly conducted design QA to validate the application scope of the tokens. In particular, styles applied to common components are used simultaneously across various services, so even small changes can impact the entire UI, requiring careful review.
5. Improvement Effects
The most significant improvements after applying the design token structure were in readability and collaboration efficiency. Through Semantic Tokens, the roles can be intuitively understood just by the variable names, leading to clearer communication between designers and developers.
It was effective in terms of maintenance as well. When modifying the color of a specific UI, changing only the related Semantic Token reflected consistently across the entire style. I was able to quickly grasp the scope of modifications compared to before, and unexpected side effects were also reduced.
Scalability has also greatly improved. When adding new components, it was possible to develop in a consistent manner based on the existing token structure, making it easier to maintain design consistency across services.
Additionally, we were able to secure the possibility of expanding dark mode or service-specific themes. Previously, color values were scattered throughout the code, making it difficult to change themes, but with the current structure, we can respond flexibly by simply adjusting the Alias and Semantic stages.
Above all, the common design standards allowed new team members to quickly understand the structure when joining the project. This has brought positive effects not only on collaboration efficiency but also on project stability.
6. Conclusion and Reflection
This refactoring was not just a simple variable organization task, but an experience of redesigning the structure from the perspective of a design system. In particular, I realized that managing styles based on 'meaning' rather than 'value' is essential to ensure both maintainability and scalability.
I was also able to reaffirm the importance of collaboration standards and naming conventions in the process of designing the token structure. I felt that the design system is not just a collection of styles, but a common language used by the entire team.
In the future, we plan to apply the same token structure not only to colors but also to various design elements such as spacing, typography, radius, and shadow. Through this, we aim to build a more systematic and scalable design system environment.
Through this work, I was able to experience the importance of structural design that takes long-term maintainability and scalability into account, rather than just focusing on simple implementation. Moving forward, I aim to view projects from a common system perspective and build a more stable UI environment.
nature