DEV Community: Denis Bratchikov

Design System: Governance and Adoption

Denis Bratchikov — Tue, 09 Dec 2025 12:02:38 +0000

1. Introduction

Building a design system is only half of the work.
Yes, it's challenging to evaluate multiple options, gather feedback from stakeholders, and implement everything in code - but this is still the part most engineers feel comfortable with. We know how to explore technologies, analyze requirements, write specifications, and eventually ship the technical foundation.

The real challenge, at least for me, was bringing this new solution into the daily life of other developers. Any new system introduces friction: it requires time, attention, and a willingness to go through the learning curve. And when teams are under roadmap pressure, people naturally gravitate toward the approaches they already know - even if those approaches caused the very problems we were trying to solve.

On top of that, some decisions that seem perfectly reasonable at the beginning may turn out to be inaccurate or incomplete - not only when they meet real-world usage across multiple teams, but also as that real world evolves faster than expected.

That's what I want to share in this final part of the series: how we handled governance, adoption, and the human side of making a design system truly work.

2. Why adoption is hard (even when the tech is good)

2.1. Common challenges familiar to any company

Adoption is rarely a technical problem - it's a human one.
Even when the new system is objectively better, teams face familiar obstacles:

People prefer familiar tools, especially under roadmap pressure.
New patterns require time, attention, and a mental shift.
Legacy code feels "safe", even if it's the cause of recurring issues.
Every team has slightly different habits, priorities, and constraints.
Benefits of a design system are long-term, while costs are immediate.

In other words: even good technology doesn't adopt itself.

2.2. What was hard in our case

Our situation wasn't radically different from the typical one, but a few challenges stood out.

First, since our single source of truth was Figma, some of the core complexities came from the design side. Understanding the correct meaning and usage of components - like when to use a Menu, a Select, or a Popover - isn't always obvious if you haven't worked deeply with accessibility-driven patterns. Things get even more complicated when a design blends attributes of multiple components, such as a popup that allows switching accounts and shows contextual actions at the same time.

Second, the learning curve was amplified by the number of new technologies introduced at once. The design system was built in parallel with a broader transformation of our frontend architecture: new monorepo structure, the first ui-kit package, migration from styled-components to PostCSS modules, introduction of Radix Primitives, design tokens, component architecture patterns, Storybook documentation, and Chromatic visual tests.

Each of these changes was reasonable on its own - but together they naturally made adoption more demanding than it would have been with fewer moving parts.

3. Migration strategy: slow, controlled, predictable

3.1. Main principles for gradual and consistent migration

The foundation of our migration strategy was simple: move forward without breaking what already works. A full "big bang" rewrite may look tempting from an engineering perspective, but it is rarely justified for the business unless the gains are dramatic - such as a major performance improvement or a critical SEO uplift. Neither was the case for us, so gradual adoption became the most reasonable and sustainable option.

Our main principles were:

All new features must use the new components This applied both to Figma (as the single source of truth) and to code. New work should build on the new system; legacy components should remain only where they already exist. This ensures natural growth of the new system without forcing teams into expensive rewrites.
"If you touch it - improve it" This company-wide rule proved extremely useful. Whenever someone modifies or refactors a piece of UI, it's a good opportunity to migrate that part to the new components as well. Since the PR must already be reviewed and visually tested, merging the migration into the same change often reduces the total cost compared to doing it later as a separate task.

Together, these principles created a predictable and manageable adoption flow: slow enough not to disrupt product work, but steady enough to avoid stagnation.

3.2. Design review as part of adoption

In most teams, new designs are reviewed by a Head of Design or CPO before they are marked as Ready for Dev.
However, neither of those roles initially owned the full context of the newly introduced design system - its components, constraints, patterns, or how they translated into code.

To bridge this gap, we introduced an additional review step for the first few months: Design System Review.

This review was handled by two people who fully understood the system's architecture and principles:

the Design System Lead from the design side, and
the Project Lead from engineering.

This additional checkpoint produced several important benefits:

Catching inconsistencies early Issues in component choice, naming, and patterns were flagged before any code was written.
Knowledge sharing Designers learned how to use the new system correctly - which components to pick, how semantic tokens worked, when to use specific patterns, etc.
Better predictability Designs handed to developers were more consistent, more realistic, and aligned with the actual capabilities of the system.

This short-lived review phase significantly accelerated adoption by ensuring that both design and engineering moved forward with the same mental model.

3.3 Developer Experience improvements

People naturally gravitate toward familiar behavior, we introduced several DX-focused guardrails to promote consistent usage of the design system and reduce friction:

Custom ESLint rules These rules enforced correct usage of components and tokens (as mentioned in Part II). They provided immediate feedback in the editor, long before a PR review.
Marking all legacy components as deprecated Even components not yet fully reimplemented in the new design system were flagged. This wasn't meant as pressure — just a clear visual signal that this is the old path.
Documentation (as a last resort) Proper docs were written and maintained, but realistically, documentation works best as a safety net, not as the primary adoption tool.
Automation scripts We built tools to export Figma variables into code, generate boilerplate for new components, and streamline contributions to the design system.
A dedicated Slack channel Centralised communication helped teams ask questions, share examples, and stay aligned. Most importantly, it created a sense of community rather than another rule to follow.

Together, these DX additions lowered the cognitive load of using the system and made the correct path the easiest one.

And most importantly, improving DX ensured that adoption didn't rely on discipline alone - the system itself guided developers toward the right patterns.

3.4 AI: migrating in 2025 and beyond

As LLMs have become more accurate and context-aware, a significant part of manual migration work can now be delegated to them.

To make adoption smoother, we embraced Cursor and GitHub Copilot as migration assistants:

Automated migration guides With a simple Cursor prompt, we generated structured guides showing how legacy component configurations should be adjusted to match the new API. These guides could also be reused directly as transformation prompts, e.g.: "Migrate all legacy Button components to the new Button from ui-kit using docs/migration-guides/Button.mdx."
AI rules aligned with the design system Copilot/Cursor suggestions were adapted to prefer design-system components and patterns when generating new code. This gently nudged developers toward the correct implementation without enforcement.
Review automation AI-assisted review rules were added to detect code that could be replaced with design-system components and leave appropriate comments. This offloaded part of the cognitive burden from reviewers and helped teams identify migration opportunities early.

AI didn't replace the adoption process - but it became a surprisingly effective accelerator, reducing repetitive work and helping teams move toward the new system with less manual effort.

This allowed us to shift our focus from mechanical migration tasks to higher-level decisions about the future of the system.

4. What worked well

Here's a summary of the practices and approaches that proved especially effective during the development and adoption of our design system:

Unified and consistent design across new features Once components were standardized, new features automatically looked and behaved consistently across the product.
Higher-quality components with accessibility and keyboard support built in The new components had a clearer API, fewer edge-case bugs, and predictable behavior compared to their legacy equivalents.
A solid foundation for future technologies Introducing the first UI package in our monorepo, PostCSS instead of styled-components, Storybook as the central documentation hub, and design tokens created a long-lasting base for all upcoming UI work.
Snapshot stories increased trust in UI changes Visual regression testing made developers more confident that refactoring or migration wouldn't break existing UI.
DX tooling significantly reduced migration friction Boilerplate generators, token sync scripts, ESLint rules - all of these made the new path easier than the old one.
Design review improved alignment between design and engineering This step increased designers' awareness of component architecture and helped ensure that the designs handed to engineering were consistent and implementable.

5. What I would change (and what didn't work)

Looking back almost a year after we started the project, some decisions now seem much clearer - including those I would approach differently today.

5.1. Starting the project after the engineering team scaled

The design system effort began after a period of rapid growth. This created unnecessary technical debt and onboarding complexity.
In retrospect, investing in foundational quality before scaling the team would have saved time and reduced friction later.
Newcomers have to learn the system anyway - better to onboard them into a clean, consistent foundation.

5.2. Underestimating the impact of AI evolution (as of 2024)

We couldn't predict how dramatically AI-assisted development would improve.
Today, I would lean more toward mainstream, widely adopted technologies, simply because AI models are already deeply trained on them.
More mainstream tech => better suggestions => smoother onboarding => fewer custom rules.

For example, Tailwind might have been a more AI-friendly choice than vanilla CSS modules with utilities.

5.3. Documentation should live in the codebase, not Notion

This lesson became obvious in the age of AI agents:

Docs stored outside the repo are invisible to IDE assistants.
To make AI truly helpful, your documentation must be co-located with code - and ideally in a format consumable by Storybook, Docusaurus, or similar tools to publish it easily.

High-level architectural docs in Notion sound nice, but they become disconnected from where development actually happens.

6. Lessons learned (my biggest challenge)

When I first imagined this project, I assumed the hardest part would be designing the system and getting leadership approval to invest in it.

I was only half right.

The real challenge was convincing people - designers and engineers - to actually use the new design system.
This experience taught me several important lessons:

6.1. Know your client (KYC)

My clients were developers with a full roadmap, tight deadlines, and limited time to learn new systems.
A design system must feel familiar, even if that means compromising on theoretical best practices.
Practicality over purity.

6.2. People follow the easiest path

If the new system is not frictionless, adoption slows down dramatically.
Ease of use wins every time - even over code perfection.

6.3. Find allies

You need people who care - even a few of them.
Looking back, a great idea would have been to assign each team 1–2 components aligned with their roadmap.
This would distribute ownership, improve knowledge sharing, and turn contributors into advocates.

6.4. Celebrate contributions

I once created a simple script to count contributions to the design system (PRs, LOC, etc.) and shared the results quarterly.
Recognising people publicly boosted engagement and encouraged others to join.

7. Conclusion

A design system is not just a UI library - it's processes, people, habits, and trust.
Technology creates the foundation, but governance and culture create the actual value.

This project wasn't an easy walk in the park - it was a real organisational and technical challenge.
But it was a successful one: we built a scalable, predictable, trustworthy system that helped us deliver features faster and with more confidence.

Feel free to connect with me on LinkedIn

🚀 More content coming soon - stay tuned!

Design System: Building the Foundations

Denis Bratchikov — Tue, 11 Nov 2025 09:00:00 +0000

In the previous article, I talked about how our team moved from chaos to consistency.

This time, let's go deeper - into the engineering side of our design system: how we chose the right tools, why we made some trade-offs, and how these decisions shaped the foundation for everything that came later.

1. High-level architecture overview

Before diving into the details, it's worth mentioning that the actual technology stack or tool isn't what truly matters - it's why you pick one over another.
Tools come and go, but the reasoning behind your choices defines how maintainable and scalable your system will be in the long run.

Below, I'll walk through each technology we used and the reasoning behind those choices. Sometimes, the logic was the result of long discussions; other times, it was simply obvious (and that's perfectly fine - not every decision has to be over-engineered 😄).

To give a quick overview, here's our tech-stack snapshot:

Area	Tool / Approach
Packaging	Monorepo (Turborepo)
Styles	PostCSS Modules + Design Tokens
UI Components	Radix Primitives + Custom components
Documentation	Storybook
Testing	Chromatic visual diffs + Unit tests
Developer Experience	Scaffolding CLI, ESLint rules

2. Consistency by Design: Mirroring Figma

We have a strong design team in the company, and Figma is our single place for creating and maintaining visual consistency - from colors and typography to component states and prototypes.
Designers use variables for colors, font styles, spacing, and shared components like Button, Input, or Dropdown to ensure reusability and alignment across all product teams.

When it comes to implementation, developers receive the final designs for a feature and translate them into code.
That translation, however, can easily become a bottleneck if both sides speak different "languages".
So before we even started building the design system, we defined one guiding principle:

No translation layer between Figma and code.

That meant - if a developer sees variant="secondary" on a Button in Figma, they should expect the exact same variant="secondary" prop in the UI kit component.

This approach brought two key benefits:

A single source of truth - Figma. The design system in code is not a copy of Figma; it's an extension of it. We don't reinvent naming conventions or variants - we mirror them.
Reduced cognitive overhead. Developers no longer need to mentally translate "what does Primary / Neutral / Subtle mean in code?" Instead, the codebase becomes a 1:1 reflection of the design decisions.

Of course, this approach wasn't free of trade-offs:

Designers now need to be careful when renaming or restructuring Figma components, since the code directly relies on those definitions.
Complex components (like comboboxes or date pickers) sometimes don't map cleanly to Figma due to differences in interaction logic or platform constraints.

Still, the result was worth it - this alignment made handoffs almost frictionless, and helped both designers and developers think in terms of system design, not just pixels or props.

3. Technology choices & rationale

3.1. ⚙️ Base Components

This choice was one of the most critical ones - because once we picked the approach, it would define the foundation for years. Changing the architecture later would require enormous effort, so we took this decision seriously.

For the first iteration, I created an ADR (Architecture Decision Record) describing all possible options, along with their pros and cons:

Use an existing third-party design system.
Build a fully custom system from scratch.
Follow a hybrid approach - adopt a base library and build our own components on top of it.

After gathering feedback from fellow developers, we quickly ruled out the first option. Given the nature of our product, we wanted much more control over component behavior and appearance - our designers often push beyond standard UI patterns, and a pre-built system would become a limitation rather than a shortcut.

That left us with two viable options:

building our own design system from scratch, or
adopting Radix Primitives, a well-known component library among our developers.

For context: Radix Primitives provides fully unstyled, accessible components that offer full control over visual implementation, while still handling all logic and accessibility behind the scenes.

To make the comparison more objective, I used a simple "traffic light" approach: I defined several critical criteria - such as time-to-market, team expertise, scalability & future-proofing, maintainability & long-term viability, etc. - and evaluated both options accordingly.

In the end, both options proved to be viable - the evaluation showed that neither clearly outperformed the other. However, we decided to go with Radix Primitives, as the time-to-market (and therefore budget) criteria were the most critical for us as a fast-moving product company. We needed to move fast, ship reliably, and avoid reinventing every accessibility behavior.

However, we established a few important internal rules to keep our implementation consistent and maintain control:

We never expose Radix components directly. All components are wrapped and exported only through our internal ui-kit package.
Each component exposes only a minimal set of props. This enforces consistency and prevents uncontrolled API sprawl across teams.
Custom components follow the same composition pattern as Radix. This keeps the implementation predictable and cohesive throughout the system.

3.2. 🧩 CSS Architecture

Before starting the design system, we were using a CSS-in-JS approach. It worked well at the beginning, but by 2024 it had already started showing several limitations:

styled-components rely on React Context, which makes server-side rendering inefficient - and even incompatible with React Server Components. We wanted to take full advantage of both Next.js SSR and React Server Components, so this became a blocker.
Runtime styling overhead - no built-in CSS caching or minification, and a visible delay in style application. This could be improved with time investments, but it wasn't worth the complexity at that stage.

Since we were building the new design system from scratch, it was a great opportunity to rethink our CSS architecture and choose a more scalable, modern, and compatible solution.

To make the decision structured, we again used the traffic light approach, comparing four main options:

CSS Modules - simple, widely supported, with preprocessors like SASS, PostCSS, or LESS.
StyleX (Meta) - a compile-time CSS-in-JS approach with the benefits of static extraction, but also with migration complexity.
Tailwind CSS - utility-first, scalable, and mature ecosystem.
Our current CSS-in-JS - used as a baseline for comparison.

As a result, we had two promising candidates: CSS Modules and Tailwind CSS.
StyleX, while technically appealing, would have added unnecessary infrastructure overhead - especially if we had to support two CSS-in-JS systems simultaneously during migration. It also came with a learning curve, since it isn't a one-to-one replacement for styled-components.

While Tailwind is scalable, well-known, and future-proof, it came with a significant drawback for our setup. We wanted to keep Figma as the single source of truth and ensure a smooth handoff between design and code. The utility-first nature of Tailwind, however, introduced an additional translation layer: developers had to interpret design specs into utility classes, which added friction and made it harder to maintain a direct connection between the design system in Figma and its implementation in code.

That was the main reason why we decided to go with CSS Modules - they allowed us to keep naming conventions and structure aligned with Figma, making the implementation process more natural for both designers and developers.

When selecting a preprocessor, we picked PostCSS, because:

It works on top of .module.css as a lightweight transpiler - no custom syntax or runtime overhead.
It's highly extensible, with a huge ecosystem of plugins, yet doesn't introduce unnecessary abstraction.
It's fully aligned with the official CSS spec, including modern features like CSS Nesting, giving it long-term stability.
By 2024, SASS and LESS were already considered legacy, while PostCSS continued evolving with modern tooling and browser support.

Ultimately, we went with a combination of CSS Modules + PostCSS - a simple, fast, and standards-based approach that gave us flexibility without sacrificing performance or future compatibility.

3.3. 🎨 Design Tokens as the Source of Truth

As you may have already noticed, the design system project became a pivot point for us - an opportunity to introduce modern technologies, workflows, and best practices, while gradually updating our existing codebase to align with them.

Before that (as I mentioned in the first article of the series), we were using abstract design tokens implemented as CSS variables to style UI components.
While this approach served us reasonably well, it revealed clear limitations once we started aiming for a more scalable and maintainable design system.

First, the same token was often serving multiple purposes.
For example, inkMain might be used both as a text color in one case and as a background color in another.
This made updates risky: whenever we changed a token's value, we had to search for all its usages and verify that the new color didn't cause contrast ratio or readability issues.

Second, it was hard to establish a consistent color scale - for example, from light gray to dark gray - because tokens were used inconsistently, and there was no clear hierarchy between base (primitive) and contextual (semantic) values.

To address this, we introduced a three-layer token model:
Primitive, Semantic, and Component-specific tokens.
This approach didn't require much debate - it was warmly welcomed by both designers and developers, since it created a shared vocabulary and made color updates safer and more predictable.

You can find similar models described in Figma Learn, Atlassian Design Tokens, or Adobe Spectrum.

Despite the obvious benefits, this structure also introduced a few new challenges:

Designers had to learn the new naming conventions and meanings of tokens. For example, both --color-background-panel and --color-background-interactive might reference the same primitive token --color-gray-95, but they serve different purposes: one for static surfaces (panels, containers), and the other for interactive elements (buttons, inputs, etc.).
Developers had to adapt as well - using only semantic tokens instead of falling back to primitive ones, even when the design itself seemed to suggest otherwise. This required some muscle memory and discipline, but it paid off in long-term maintainability and consistency.

3.4. 📘 Storybook + Chromatic

So, the foundation was ready: Design Tokens, CSS Modules with PostCSS, Radix Primitives for base components (and custom UI components where needed), and the existing infrastructure for the Design System package.
The bare minimum was in place - now it was time to make it both clear for its users (developers) and trustworthy in terms of quality and stability.

We were already using Storybook in our main applications to showcase user stories, and it had proven to be a great fit for our workflow.
So there was no debate - we simply adopted it for the design system as well.

Since the design system can also be valuable for non-developers (e.g., designers or PMs who want to check if a certain pattern or interaction already exists in code), we decided to publish our Storybook using Chromatic.
It made the stories easily accessible to anyone in the company, with versioned previews for every change.
I won't go deep into Storybook configuration or story implementation here - there are already plenty of excellent resources on that.

Design system components are visually rich but behaviorally simple - they mostly render UI with the correct appearance and delegate event handlers to underlying DOM elements.
Because of that, the reliability of our system depends heavily on visual accuracy rather than complex business logic.
To ensure quality, we adopted a three-layer testing strategy:

Static analysis, such as type checking and linting (enabled by default).
Unit tests, covering isolated logic - e.g., disabled states, keyboard interactions, or component hooks.
Visual regression tests, to catch unintended UI changes.

Let's skip static and unit tests - those are well-covered by industry practices - and focus on the visual regression part.

For that, we used Chromatic's visual snapshot testing, integrated directly with our Storybook setup (docs).
It's not worth creating visual snapshots for every single story - that would be costly and redundant.
Instead, we focused only on representative visual states for each component.

To keep this consistent, we disabled automatic snapshots by default and introduced a rule:

Each component must have a dedicated Snapshot story that renders all relevant visual variations for regression testing.

It's also worth mentioning that Chromatic provides other testing capabilities - visual, accessibility, and interaction tests.
However, in our case, those felt like overhead, as the same coverage could be achieved through unit tests - and, importantly, free of charge.

Finally, to ensure no UI change goes unnoticed, we added a Chromatic CI step (docs) into our CI/CD pipeline.
It highlights visual diffs for every pull request and requires a manual review before merging - giving us confidence that no visual regressions slip into production.

3.5. 🧠 Developer Experience

Any technological change or new initiative inevitably meets some friction - people need time to learn, adapt, and develop new habits.
To make this process smoother, more reliable, and to improve the overall maintainability of the system, we introduced several developer experience (DX) practices.

First, we created a simple scaffolding script to generate the boilerplate for new UI components - React file, styles file, tests, stories, and the barrel export.
This ensured a consistent folder structure and prevented developers from accidentally skipping any required files.

/Button
 ├── Button.tsx
 ├── Button.module.css
 ├── Button.test.tsx
 ├── Button.stories.tsx
 └── index.ts

Second, we built a flow to export design tokens from Figma and convert them into CSS variables.
There are plenty of Figma plugins for exporting variables (for example, Export/Import Variables) into a JSON file.
From there, a simple script can generate themed CSS files for both primitive and semantic tokens.

To boost IDE productivity, we used the CSS Var IntelliSense plugin for VS Code-based IDEs.
It improves autocomplete for CSS variables and allows defining a custom source file, preventing suggestions from unrelated local component tokens.

However, since Figma variables can be renamed, removed, or overwritten (by accident or intentionally), we wanted to make sure no invalid tokens could slip into the codebase.
To address that, we created a custom ESLint rule that allows only variables either declared locally or listed in the auto-generated source file. This provided a basic but effective safety layer.

Sometimes you may also need to use a CSS variable inside TypeScript code - for example, setting the gap property in a Grid component.
To ensure both type safety and token consistency, we extended the generation script to produce a tokens.ts file that exports an object of all available variables, e.g.:

export const tokens = {
  colorText: 'var(--color-text)',
  colorBackground: 'var(--color-background)',
};

Developers can then import these tokens directly into components, while the linter and TypeScript will catch any non-existent references during CI.

Finally, we prepared thorough documentation, explaining how to use the design system, how to contribute, and how to migrate from legacy components to the new ones.
Storybook's .mdx syntax worked perfectly for that, allowing us to deploy the docs via Chromatic - keeping everything in a single source of truth.

The migration guide itself was generated using Cursor, and we plan to use the same AI tool to automate the migration of old components to the new system.

4. Outcome and lessons learned

These decisions weren't just about tools - they defined how we work. We moved faster, shipped safer, and established a technical culture around clarity and ownership. More importantly, the process helped us align engineering and design thinking - something that shaped how we approach UI development as a team.

However, the adoption of the design system was not entirely frictionless - it raised many organizational and technical challenges, which I'll dive deeper into in the next article.

Next: In Part 3, I'll share how we rolled out the design system across multiple teams - how we handled adoption challenges, established governance, measured success, and made the system a natural part of our daily development workflow.

From Chaos to Clarity: How We Realized We Needed a Design System

Denis Bratchikov — Wed, 29 Oct 2025 09:00:00 +0000

Some initiatives are easy to pitch.
Some take a few meetings and diagrams.
And some - even if they're clearly beneficial - feel like dragging a boulder uphill for months.

For me, that boulder was our design system.
It took almost a year to convince the company that we needed it.

What Was Wrong

Before we started the initiative, our frontend lived in a kind of organized chaos.
Here's what it looked like:

Design inconsistency - Designers re-created components for (almost) every new feature, using loosely defined color tokens. Developers were reusing almighty components - not as bad as react-select, but close enough.
Lack of reliability - Nobody wanted to touch core components. Every small fix risked breaking something elsewhere, and there were barely any tests to catch regressions.
No documentation - You had to know what components existed or spend time reverse-engineering them from the code.
No accessibility - Almost no keyboard support, no focus management, no a11y structure at all.

For a small company focused on delivering features as fast as possible, this was "fine".
Shipping speed mattered more than consistency or maintainability.
Until it didn't.

When Grows Hit

In 2024, our engineering team tripled.
New developers joined critical projects with tight deadlines, and naturally, they had no time to explore the existing UI foundation.

So they did what anyone under pressure would do - they just built things from scratch to match the designs.
Within a few months, we ended up with dozens of inconsistencies, duplicated code, and bugs that nobody wanted to own.

The lack of ownership became a real cost - every small feature was getting slower and riskier to release.

The Breaking Point: Rebranding

Then came the rebranding project - our "bingo moment".
We had to update almost all colors and fonts in the product… in two weeks.

On paper, that sounded simple. In reality, it was a nightmare.

We did have CSS tokens, but they were too abstract (inkMain, inkMedium, etc.). During rebrand, it turned out that the new inkMain could mean several different things depending on where it was used - background, text, or hover state, etc.

This rebrand became a stress test.
We patched components with feature-specific if statements, applied conditional CSS, and created more exceptions than rules.
CI started producing weird, unpredictable failures that haunted us for months.

What looked like a "simple UI refresh" turned into 100+ engineering tickets, exposing every bit of technical debt we had accumulated.

We had finally hit the ceiling of our "move fast and patch things" philosophy.
A design system was no longer a nice-to-have; it was the only way to bring order back to the product.

It was clear that without a unified design language and shared ownership, every future change - even a small one - would cost us exponentially more time and nerves.

And at that moment, something finally clicked.
One of our senior designers stepped up to become the design system ambassador - someone willing to take responsibility for the design side, ensure that the design team followed consistent Figma components, and work closely with engineering to build the bridge we'd been missing.

That was the moment when the idea stopped being "my thing" and became our initiative.

Finding the Right Starting Point

Once we finally got the green light, we needed a plan - roadmap, resources, milestones.

Right after the rebranding, we were scheduled to rebuild two major user experiences:

The logged-in dashboard and its related pages;
The core product UI.

That was the perfect timing: if we were already rebuilding large parts of the product, we might as well build them properly this time.

Defining The "Foundation"

We started with an architecture planning session to define what "foundation" actually meant for us.
Building a design system isn't a one-week task - so we had to define a minimal, realistic first iteration.

We used an impact–effort matrix to prioritize components:

most-used and visible components first,
those blocking new features next,
and finally, replacements for bug-prone legacy ones (if still have some time).

Every new UI task in ClickUp was linked to a component ticket in the new design-system project. That helped us track dependencies and ensure that the base components were built before any new feature ticket was started.

Some components were intentionally postponed for the post-release phase, and a few legacy ones we decided not to touch at all until there was a real need to update them.

Lessons Learned (So Far)

Looking back, the hardest part wasn’t the tech.
It was the waiting - nearly nine months before we could even start.

And while we finally made it happen, I still believe we could have saved enormous effort by starting earlier, before the aggressive hiring phase and the architectural sprawl that followed.

But that's a topic for the final part - where I'll look back at what worked, what didn't, and what I'd absolutely do differently if I were starting again.

Next: In Part 2, I'll share how we built the actual system - architecture, tooling, CI/CD, and the technical decisions behind it.

Monorepo in Practice (part 2): so was it worth it?

Denis Bratchikov — Tue, 22 Jul 2025 08:45:35 +0000

This post is part 2 of 2. In this one:

Where monorepo shines
Where it sucks
My honest take: when you should and shouldn't do it

Introduction

In part one, I covered why we decided to move to a monorepo — and what pains we were trying to solve.

So now, the big question: was it worth it?

Spoiler: mostly yes - but not without surprises.

1. What are the benefits?

1.1 Code awareness went through the roof

Now, when I search for a function or a component, chances are it already exists - inside a feature package. I can just move it to a shared package and reuse instead of reimplementing everything from scratch.

I don't think that kind of visibility happens often in a polyrepo world...

Also, with a unified structure and shared configs, developers are on the same page. Even if you're changing someone else's code — you know exactly how to test it and where to look.

1.2 Refactoring became a walk in the park

Refactoring used to be tedious. So we outsourced it to AI 🤖

Imagine:

You improve a component contract
You update all its usages
You double-check every edge case

Classic headache.

A while back, we shipped a feature behind a feature flag. It worked great - and when it was time to clean it up, we just asked Cursor:

"Hey, remove this flag and delete any leftover code."

It worked brilliantly.

Mostly because the AI had full visibility into the monorepo and could grep all flag usages, one file at a time. I just prompted, clicked continue a few times when it hit operation limits - and spent ~20 minutes reviewing.

That's it.

1.3 Developer experience is just better

Day-to-day work became much smoother.

Want to run just the ui package?

pnpm dev --filter=ui

Want to run everything? Go ahead.

You're no longer connecting the dots across 5 repos to debug a single change. You don't need to play "git archaeologist" to find where something came from.

And onboarding?

New devs can install and start coding in minutes:

pnpm install && pnpm dev

2. What are the pain points?

2.1 CI/CD pipelines

Yeah, that's a real one.

You go from having a few focused pipelines… to one giant spaghetti-pipeline that tries to handle everything at once.

For example, we run Playwright tests for application X via currents.dev - but we absolutely don't want them triggered when someone changes application Y.

Unfortunately, Turborepo doesn't give you that out of the box. Its caching model assumes that you run all affected commands and skip what's not changed - but coordinating that with external CI jobs like Currents is tricky.

Same goes for other per-app jobs.

To solve it, we had to build a custom GitHub Action that reads Turbo's output and determines which jobs should run - or be skipped - depending on which apps were actually touched.

Is it cool? - Yeah.
Is it plug-and-play? - Not even close.

2.2 Dependency management

pnpm is blazing fast and works great for monorepos - no doubt. But it comes with gotchas.

Since pnpm installs each dependency once at the top level and uses symlinks everywhere, transitive dependencies can cause headaches.

Let’s say:

Your app depends on A@2.3.0
It also depends on B@2.0.0, and B depends on A@1.4.0

pnpm will only install one version of A, and it might pick the wrong one for your use case.

That can break:

types
runtime behavior
or both

You'll especially feel the pain when:

One app uses a modern stack (e.g. latest React)
Another app is stuck with legacy versions

...and they both depend on shared packages.

You either:

start version pinning everything manually, or
accept the chaos and debug weird mismatches

So yeah - fast install times come at a price.

3. When `don't` and when `do`?

We actually tried moving our API services into the same monorepo - aiming to have literally all code in one place.

Sounds neat.
But in practice? A total headache.

Even though our backend is built with Node + Express (so technically compatible with our frontend stack), the divergence in config, dependencies, CI jobs, and workflows made the whole thing a mess.

It wasn’t an outright failure - but it forced us to step back and ask:

Do we really need the API in the same repo?
Or is it enough to keep just the frontend there?

We haven't fully answered that yet. For now, we've paused the migration and kept our backend separate - and honestly, that feels okay. We'll probably revisit it when (or if) the benefits start outweighing the overhead.

When I would recommend monorepo:

✅ When your code shares the same stack (e.g., TS + React + tooling)
✅ For medium to large-scale apps (but not mega-enterprise)
✅ When you're trying to kill off submodules and avoid version juggling

When I wouldn't:

🚫 When teams work independently on fully untangled apps
🚫 For tiny projects — it's overkill
🚫 At massive scale (think 2k+ devs) - trying to keep everyone aligned gets absurd fast

There's no one-size-fits-all, just like the classic articles said.
But for our stack, our scale, and our team - monorepo turned out to be the right move.

Will that still be true in five years? No idea.

But for now, it's a powerful tool - and we're glad we took the leap.

"(Choo|U)se wisely"!

Feel free to connect with me on LinkedIn

🚀 More content coming soon - stay tuned!

Monorepo in Practice (part 1): Between “Please Don’t” and “Please Do”

Denis Bratchikov — Tue, 15 Jul 2025 07:53:03 +0000

This post is part 1 of 2. In this one:

Why we ditched submodules and went monorepo
How our structure looks now
What to consider before migrating (team buy-in, effort, risk)

Introduction

Not long ago, I stumbled upon two classic articles: Monorepos: please don’t! and Monorepo: please do!. It's been six years since those posts were written, but the topic is still very much alive.

That got me thinking: how much has really changed since then? In this post, I’ll share our journey moving to a monorepo for our frontend, what worked, what didn’t, and what surprised us along the way.

For context: Our codebase is ~8,700 files, 700k lines of code, and around 1.2GB (including test screenshots). We’re a team of 25–30 frontend devs working full time on it.

1. WHY?

Why on earth did we decide to switch to a monorepo?

To answer that, let’s take a look at the setup we had right before the migration:

A few shared packages (like ui, configs) in separate repos, published to GitHub registry
app X — React (CRA 🫠) app, deployed daily on Vercel with Playwright integration tests
app Y — Next.js app (dashboard + landing pages), also deployed daily on Vercel, but uses the main application via GitHub submodules (yep, legacy from when we had only 2 apps)
Each app had its own GitHub CI pipeline
The engineering team was growing — we no longer fit in one room, and management started dividing us into smaller teams with distinct business areas... but the code was still shared

This setup caused us a lot of problems.

First — GitHub submodules.

Surprisingly, not many people have worked with them before, so ~70–80% of new hires struggled with them. But that wasn’t even the worst part.

Imagine you’re mostly working on app X. You update a component, tweak its behavior and contract, update all its usages, run tests — CI passes — great! You merge it.
All good. Everything works.
Then, someone updates the submodule SHA in app Y — just one line changed — and boom, CI breaks. Why? Because you forgot to update app Y when you changed the contract.

Congrats, your 5-minute fix just turned into a 1-day headache.

Second — delivering fixes to core packages.

Let’s say you fix a bug in the UI components. You’re fast — 15 minutes and it works perfectly in Storybook. But now comes the “real” flow:

create PR → wait for review → wait for QA → merge and publish the package →
create PR to update app X → review → QA → merge →
create PR to update app Y → review → QA → merge →
scratch your eyes out and consider a career in goat herding.

Now imagine doing that at scale... or with late feedback.

Third — ownership and code boundaries.

We were already moving toward smaller, purpose-driven packages with clear ownership. This could work in both mono- and polyrepo setups. We didn’t need true microservices (felt like overengineering), but we did need structure.

And on top of the submodule mess, polyrepo gave us even more headaches:

Every repo needed its own GitHub config: roles, branch rules, required CI jobs...
Developer experience was rough: > run package A → symlink it to B → symlink B to C → symlink C to app X → finally start debugging
Knowledge sharing was a joke — unless you proactively hunted through GitHub, you’d have no idea new packages even existed

Having all this in mind, we decided to migrate to a monorepo (Turborepo) setup.

2. What's the current status?

It’s been almost a year since we migrated to a monorepo. After polishing things up and iterating a bit, we’ve landed on the following setup.

2.1 Folder structure

apps/* — all applications (both production and dev)
packages/features/* — functional, domain-specific feature packages
packages/* — common/shared utilities and modules
configs/* — all configuration code (ESLint, TS configs, custom plugins, etc.)
scripts/* — various dev scripts and automation tools

2.2 Tech stack

🛠 [Turborepo(https://turborepo.com/) as the build orchestrator
📦 pnpm as the package manager

2.3 Compilation strategy

Turborepo supports three main compilation strategies:

Just-in-Time Packages
Compiled Packages
Publishable Packages (not relevant for us — we don't publish internal packages)

We initially went with compiled packages — mostly because it was the easiest to implement given our (legacy) tech stack and tight timeline. It worked, kind of. But now we’re investing time into switching to just-in-time strategy instead. Why?

It requires far less configuration (and less risk of misconfiguring things).
You don’t need to rebuild packages every time you build the app.
It enables better code sharing. For instance, we use postcss custom media defined in the ui package - but it doesn’t get propagated to other packages because postcss is stripped out during compilation.

So yeah — compiled got us up and running fast. But just-in-time is what’s going to scale.

3. Our Migration Story: Time, People, and Pain

- "Where’s the money, Devowski?"
- "It's uh... it's in monorepo somewhere, let me take another look."

So - how long does it take to migrate? And what should you think about before even starting?

Well, first: define your scope - how many apps and packages you’re migrating, your time budget, and what you’re hoping to gain. That will shape everything else.

In our case, we had a company initiative called Dev Week — one week where developers aren’t obligated to work on business features and can instead invest in tech debt or internal tools. We figured: perfect timing. Let’s migrate the whole codebase to a monorepo in one shot.

Here’s how we organized it:

A 6-person team
2 devs focused on the CRA-based app (legacy-heavy)
2 devs handled the Next.js app (that depends on the CRA one via submodules)
2 devs worked on infrastructure, migration scripts (for open PRs), and CI pipelines
We wanted to preserve git history, so we used git filter-repo to merge the old repo histories into their respective folders

By the end of the week, we had... a solution that just about worked.

The CI pipelines were mostly green, preview links were up, and we could ship from the monorepo - so we did.

Of course, we hadn’t caught everything - Sentry config, Storybook setup, some edge cases - so we spent the following week fixing and polishing.

But migrating code is only half the story.

You also need to prepare your team for that shift.

From this point on, your devs aren’t in isolated repos anymore — they’re part of a bigger, interconnected system. There's no more "my code" vs "their code" - now it’s "our code I know" and "our code I don’t know yet".

Moving to monorepo isn’t just a git decision — it’s a team, process, and trust decision.
Make sure you're not only moving code, but moving minds too.

This is the end of part 1. In Part 2, I’ll cover:

Where monorepo shines
Where it sucks
My honest take: when you should and shouldn't do it

Feel free to connect with me on LinkedIn

🚀 More content coming soon - stay tuned!

AI-Powered Code Refactoring: A Case Study Using Cursor with GPT-4o and Claude 3.7 Sonnet

Denis Bratchikov — Tue, 04 Mar 2025 09:12:04 +0000

Introduction

Hey there! Code refactoring is one of those necessary parts of keeping software clean and maintainable. But let’s be honest—it can get pretty tedious, especially when dealing with repetitive tasks across a ton of files. In this case study, I’ll walk you through how I used Cursor IDE, powered by GPT-4o and Claude 3.7 Sonnet, to automate a refactoring task across 64 Playwright test specification files.

The goal? Remove deprecated arguments from function calls with minimal manual intervention. Let’s dive in!

Preconditions

Before we dive into the technical details, it's worth mentioning that Cursor was modified with specific rules from this github. These rules helped ensure that the AI would divide tasks into smaller ones and perform one-by-one.

Problem Statement

During a recent redesign, several test helper functions had been temporarily modified to include additional parameters. Specifically, our Playwright test suite contained:

Project initialization functions using:

page.goto(path, config)
page.createProject(config)
page.loadProject(project_name, config)

IConfig {
  featureFlags: {
    'feature-1': true,
    'feature-2': true,
    'new-ui-design': true // <= our first target
  },
  ...some_other_params
}

Snapshot verification using:

page.toHaveSnapshot(optional_name, params);

IParams {
  shouldClip: true, // <= our second target
  ...some_other_props
}

After the redesign, the default behavior of page.toHaveSnapshot() was restored, meaning shouldClip: true property was no longer needed. Similarly, new-ui-design: true was no longer relevant and needed to be removed from all test files.

Approach: AI-Assisted Batch Refactoring

To automate the changes, I used Cursor IDE with the Composer (Agent) mode, leveraging both GPT-4o and Claude 3.7 Sonnet for code modifications.

Initial Prompt (Single-Step Approach)

My first attempt was a single prompt to process all .spec.ts files at once:

In `application\e2e`, find all `.spec.ts` files and do the following:
1. Remove object with `shouldClip: true`
2. Remove the empty string before the removed object (if any)
3. Remove `'new-ui-design': true,` from the corresponding object
4. If the corresponding object (e.g., `featureFlags`) becomes empty, remove it
5. If the parent object of the corresponding object becomes empty, remove it

While the AI handled a lot of cases correctly, I ran into some hiccups:

TSometimes the model added unintended modifications, like changing snapshot names or adding more checks.
It only partially applied changes across different files (fixing one method but skipping another in the same file).
The results were not deterministic, varying on different runs.

Refining the Approach: Two-Step Refactoring

To make things smoother, I decided to split the refactoring into two separate tasks.

Prompt 1 (Snapshot Cleanup)

For each file `application\e2e\**\*.spec.ts`, do the following:
1. Remove object with `shouldClip: true`
2. If the corresponding object becomes empty, remove it
3. Remove the empty string before the removed object (if any)

Prompt 2 (Feature Flags Cleanup)

For each file `application\e2e\**\*.spec.ts`, do the following:
1. Remove `'new-ui-design': true,` from the corresponding object
2. If the corresponding object (e.g., `configureCustomFeatureFlags`) becomes empty, remove it
3. If the parent of the corresponding object becomes empty, remove it

Why This Worked Better:

Avoided unintended side effects from overlapping edits.
Ensured consistency across all files.
Reduced hallucinations, since each task was clearer and more focused.

Code update examples

Refactoring Example 1, Before:

page.createProject({
  featureFlags: {
    'new-ui-design': true
  }
})

page.loadProject('my-project', {
  featureFlags: {
    'new-ui-design': true,
    'some-feature': true,
  }
})

page.goto('/', {
  featureFlags: {
    'new-ui-design': true
  },
  foo: {
    bar: 'baz'
  }
})

Refactoring Example 1, After:

page.createProject()

page.loadProject('my-project', {
  featureFlags: {
    'some-feature': true,
  }
})

page.goto('/', {
  foo: {
    bar: 'baz'
  }
})

Refactoring Example 2, Before::

const snapshotParams = {
  threshold: 0.6,
  shouldClip: true
};

page.toHaveSnapshot('', snapshotParams);

page.toHaveSnapshot('my-snapshot', { shouldClip: true });

page.toHaveSnapshot(undefined, { shouldClip: true });

Refactoring Example 2, After:

const snapshotParams = {
  threshold: 0.6
};

page.toHaveSnapshot('', snapshotParams);

page.toHaveSnapshot('my-snapshot');

page.toHaveSnapshot();

Model Comparison: GPT-4o vs. Claude 3.7 Sonnet

When using both GPT-4o and Claude 3.7 Sonnet for this task, I found that there was no significant difference in their performance or accuracy for these specific refactoring tasks. Both models struggled with the one-step approach and were able to process the files, making the changes I needed without introducing major differences in output quality with the two-step approach.

Challenges and AI Limitations

Using AI for this task was pretty great overall, but it wasn’t without its quirks:

Task Execution Limit - Cursor’s Composer has a default task limit of 25, after which manual confirmation (proceed / continue) is required.
AI Deviations & Over-Eagerness - in some runs, the model attempted to generate a Python script to automate the task despite explicit instructions to modify the files directly.

Key Takeaways

💡 AI is already a powerful tool for large-scale code modifications, allowing for efficient batch refactoring with minimal manual oversight.

✅ What worked well:

Using Cursor IDE’s Composer mode with well-defined prompts.
Splitting complex refactoring into smaller, focused tasks.
Leveraging both GPT-4o and Claude 3.7 Sonnet to compare performance.

❌ Challenges:

AI still struggles with perfect consistency across multiple files.
AI still struggles with following all instructions

👨‍💻 Would I use AI for similar tasks again? Absolutely. While AI isn't perfect, it's already a valuable assistant for handling tedious, repetitive refactoring tasks—giving developers more time to focus on higher-level problem-solving.

Final Thoughts

This was my first adventure with AI-assisted batch refactoring, and I’d love to hear what you think! Have you ever used AI for similar tasks? Let’s chat about it in the comments. 👇

Feel free to connect with me on LinkedIn

🚀 More content coming soon - stay tuned!

P.S. This is my first article on development, so I’d really appreciate any feedback or suggestions! Thanks for reading! 😊

DEV Community: Denis Bratchikov

Design System: Governance and Adoption

1. Introduction

2. Why adoption is hard (even when the tech is good)

2.1. Common challenges familiar to any company

2.2. What was hard in our case

3. Migration strategy: slow, controlled, predictable

3.1. Main principles for gradual and consistent migration

3.2. Design review as part of adoption

3.3 Developer Experience improvements

3.4 AI: migrating in 2025 and beyond

4. What worked well

5. What I would change (and what didn't work)

5.1. Starting the project after the engineering team scaled

5.2. Underestimating the impact of AI evolution (as of 2024)

5.3. Documentation should live in the codebase, not Notion

6. Lessons learned (my biggest challenge)

6.1. Know your client (KYC)

6.2. People follow the easiest path

6.3. Find allies

6.4. Celebrate contributions

7. Conclusion

Design System: Building the Foundations

1. High-level architecture overview

2. Consistency by Design: Mirroring Figma

3. Technology choices & rationale

3.1. ⚙️ Base Components

3.2. 🧩 CSS Architecture

3.3. 🎨 Design Tokens as the Source of Truth

3.4. 📘 Storybook + Chromatic

3.5. 🧠 Developer Experience

4. Outcome and lessons learned

From Chaos to Clarity: How We Realized We Needed a Design System

What Was Wrong

When Grows Hit

The Breaking Point: Rebranding

Finding the Right Starting Point

Defining The "Foundation"

Lessons Learned (So Far)

Monorepo in Practice (part 2): so was it worth it?

Introduction

1. What are the benefits?

1.1 Code awareness went through the roof

1.2 Refactoring became a walk in the park

1.3 Developer experience is just better

2. What are the pain points?

2.1 CI/CD pipelines

2.2 Dependency management

3. When don't and when do?

When I would recommend monorepo:

When I wouldn't:

Monorepo in Practice (part 1): Between “Please Don’t” and “Please Do”

Introduction

1. WHY?

2. What's the current status?

2.1 Folder structure

2.2 Tech stack

2.3 Compilation strategy

3. Our Migration Story: Time, People, and Pain

AI-Powered Code Refactoring: A Case Study Using Cursor with GPT-4o and Claude 3.7 Sonnet

Introduction

Preconditions

Problem Statement

Approach: AI-Assisted Batch Refactoring

Initial Prompt (Single-Step Approach)

Refining the Approach: Two-Step Refactoring

Code update examples

Model Comparison: GPT-4o vs. Claude 3.7 Sonnet

Challenges and AI Limitations

Key Takeaways

Final Thoughts

3. When `don't` and when `do`?