Design system modernization of a B2B SaaS platform

Our client runs a B2B SaaS platform focused on marketing data hygiene. Over time, the React-based front end had grown into a brownfield codebase. Visual rules were distributed across numerous CSS files and components, with no consistent or enforceable abstraction layer.

The client’s front-end architecture had grown organically, without a consistent abstraction layer for visual decisions. This became a critical issue when the company began planning a rebrand: updating the product’s visual identity would require every color, spacing, and typography decision across the application to be revisited and changed consistently—something the existing codebase had no reliable way to support.

Visual decisions, such as colors, spacing, typography, shadows, and border radii, existed only as raw implementation details, hardcoded directly into components and SCSS files. The same visual value might appear in multiple locations across the codebase, sometimes with slight variations introduced over time. As a result, even simple visual changes, such as updating a brand color, required developers to search through multiple files and manually update implementation details.

This fragmentation directly threatened the rebrand effort. Applying new brand styles consistently across the application would have required large-scale manual changes, with no reliable way to verify consistency once the work was complete. At the same time, MUI (Material UI) constructs and theme references had expanded beyond presentation layers into broader application code, increasing the coupling between UI implementation and business logic. Styling decisions were closely tied to framework-specific implementations, increasing the effort required to evolve the front end and raising the likelihood of regressions during major updates.

Over time, these constraints increased the cost of maintaining and evolving the platform. EffectiveSoft was brought in to introduce a structured design architecture that would support future design changes while reducing dependency on scattered styling implementations.

The team at EffectiveSoft avoided a front-end rewrite, because it would have introduced parallel maintenance, delayed delivery, and risked duplicating the same structural issues in a new codebase. Instead, EffectiveSoft established an incremental modernization strategy, introducing a structured design architecture into the existing codebase and progressively implementing it through automated refactoring.

To execute this strategy, we set up a controlled, agent-assisted refactoring workflow around Claude Code. This approach supported repository analysis and context-aware transformations across hundreds of files with mixed styling patterns, while preserving the existing application architecture.

Phase 1: Defining a design contract

The first step was to define what “correct” visual implementation meant in a system with no unified design layer.
EffectiveSoft led a full audit of the codebase, extracting all visual primitives—including colors, spacing, typography, shadows, and layout rules—that were scattered across SCSS and component files.

These values were consolidated into a unified design contract and implemented as a token system with 140+ design tokens.

The resulting contract defined semantic color roles, spacing scales, typography rules, elevation levels, border radii, and other UI primitives. It became the primary source of truth for UI decisions across the application, replacing hardcoded and duplicated implementation-level values.

Phase 2: Automated migration

Once the contract was defined, EffectiveSoft orchestrated the migration of the existing codebase to the new token-based structure.

Claude Code was used to execute context-aware transformations across the repository, replacing hardcoded styling values with references to design tokens.

This was not a mechanical replacement task. The transformation required an understanding of how styles were applied across inconsistent patterns, including mixed SCSS structures, legacy MUI theme usage, and conditional styling logic where identical values could be used in different UI contexts.

To manage this safely, EffectiveSoft structured the process as a controlled transformation pipeline. Each change was applied incrementally through diffs, allowing validation before merging.
As part of this work, styling logic was consolidated around the new token system and MUI usage was restricted to designated UI layers, reducing framework leakage into the broader application.

Phase 3: Architectural enforcement

To ensure the system remained stable after migration, EffectiveSoft introduced enforcement at the build level. CI rules restricted MUI usage outside designated UI layers, while linting prevented the reintroduction of raw styling values, such as hardcoded colors or spacing.

This shifted consistency from developer discipline to automated enforcement within the build process.

Phase 4: Visual regression validation

Because changes touched hundreds of files, EffectiveSoft introduced an automated visual regression layer to validate correctness.

UI states were captured before and after transformation and compared to detect unintended layout or styling changes. This allowed the team to safely execute large-scale automated refactoring while keeping functional and visual behavior intact.

The platform gained a governed design layer that replaced scattered styling conventions with centralized design tokens and architectural controls, enforced through CI and linting rules.

Key results:

• 140+ design tokens now define the entire UI system, replacing a codebase with no theme, no color scale, and no typography roles.
• 550+ files refactored in a single coordinated migration, without a manual, page-by-page rewrite.
• MUI leakage outside the design-system layer was reduced to 0 CI-detected violations, down from codebase-wide.
• 30+ SCSS files were migrated off legacy MUI palette variables, with duplicate legacy components consolidated into the canonical design library.
• 80+ remaining one-off values were classified, documented, and explicitly accepted with rationale, rather than left as technical debt.
• Automated visual regression testing caught layout shifts at every step, allowing the migration to ship without visual regressions reaching production.

The most immediate outcome was rebrand-readiness. Because visual decisions are no longer embedded directly in hundreds of files, the planned rebrand can now be executed through controlled token changes—by updating a handful of values in the design contract—rather than through a large-scale manual rewrite touching hundreds of components.

The initiative also reduced architectural risk. By restricting framework-specific styling to designated UI layers, EffectiveSoft created a clearer separation between presentation and application code. This makes future front-end modernization efforts more predictable and lowers the risk of visual regressions during major UI changes.

The cost of everyday UI changes dropped as well. Updates that previously required searching across multiple files and manually verifying every occurrence can now be made in a single place and propagated automatically through the token system. This also reduces the QA burden: because visual regression testing is built into the workflow, teams no longer need to manually inspect the entire application after each styling change—only the automatically flagged differences.

More broadly, design changes became a governed process rather than a file-by-file maintenance exercise. Visual changes can now be introduced through centralized updates, validated automatically, and enforced through build-time controls, reducing the long-term cost of maintaining and evolving the platform.