A practical framework to preserve design, prove parity, and integrate prototypes into production with Next.js and…
In-depth Next.js guides covering App Router, RSC, ISR, and deployment. Get code examples, optimization checklists, and prompts to accelerate development.
No spam. Unsubscribe anytime.
Have you ever had to integrate two codebases built by different developers working in parallel?
On a recent project, I was setting up the Payload CMS backend architecture and content models, while another developer was separately building out the Next.js frontend in an isolated repository. When the time came to merge the two sides together, the frontend was already substantial: custom components, design tokens, mock layouts, and a massive stylesheet were fully in place.
My initial developer instinct was predictable: maybe we should clean this up and rebuild it from scratch directly against our CMS schema.
Following that instinct would have thrown away weeks of design exploration, duplicated existing work, and delayed the production timeline. The real challenge wasn't proving what I would have done differently; it was figuring out how to preserve the valuable design and UI work that already existed, integrate it cleanly with Payload, and establish a maintainable production architecture without burning the schedule on unnecessary rewrites.
That reframing changed our entire approach. Here is the 4-step framework we used to take over an existing frontend safely.
When you inherit an existing frontend, there are usually three obvious options.
Replace the styling architecture.
Introduce your preferred component library.
Standardize everything.
This gives you the cleanest theoretical starting point, and it carries the most risk of the three.
You are rebuilding working visual behaviour, introducing regressions, consuming implementation budget and potentially invalidating months of design iteration.
You may end up with a cleaner codebase that doesn't guarantee you made the right business decision.
The opposite approach is to treat the existing frontend as finished.
Connect the CMS, replace mock data with real data and ship it.
This minimizes initial effort, and it means the production application ends up sitting directly on any hidden component dependencies, duplicated interaction logic, or fragile styling relationships already in place.
Once the CMS, business logic and additional features start depending on those components, fixing them becomes considerably harder.
This often feels like the responsible compromise.
Keep the design, and clean the architecture before connecting anything to the real system.
The problem is that you are refactoring without production pressure telling you which abstractions actually matter.
You may spend days improving components that barely appear in the final application while the real implementation is still waiting to begin.
That led me to a fourth approach.
This became the guiding rule:
Preserve first. Prove parity. Integrate vertically. Harden on touch.
Two instincts are common here: treat the frontend as disposable prototype code, or treat it as an untouchable finished product. Both skip a step. What matters first is understanding the useful parts of the existing system.
The sequence matters.
My initial impression came from one very visible number: roughly 20,000 lines of CSS in a global stylesheet.
That number sounds alarming on its own, and line count alone rarely tells you whether a frontend is architecturally broken.
A deeper audit showed considerably more structure:
There was real engineering structure there, and it came with one important weakness.
Some features were reaching into shared components and styling their internal elements from outside.
Something conceptually like this:
.hero .product-card__title {
color: white;
}
.recipe-feature .product-card__media {
height: 140px;
}
That is more significant than the size of the stylesheet.
Why?
Because another part of the application needs knowledge of how ProductCard is implemented internally.
The requirement exists without being visible in the component API.
The CSS is effectively telling us:
ProductCard actually has an inverse version.
and:
ProductCard actually has a compact version.
Those are hidden component requirements.
The better API might be:
<ProductCard
tone="inverse"
density="compact"
/>
Now the component owns what those concepts mean.
That was an important shift in the diagnosis: some component contracts stayed implicit when they should have been explicit.
This is particularly important when the frontend was produced by a designer or design-focused developer.
A prototype can do its job extremely well without being structured exactly like the production application should be.
Those are different optimization targets.
During design exploration, speed of iteration matters.
You may need to try multiple card treatments, hero layouts or responsive behaviours quickly.
Production has different requirements:
The original work simply reflects an earlier phase of the implementation.
As the person taking over the system, the job is to preserve the design intent while establishing the boundaries production needs.
This was probably the most important implementation decision.
Before restructuring the frontend, bring it into the actual production repository and make it work.
Copy the components.
Copy the assets.
Copy the design tokens.
Copy the styling required to reproduce the approved design.
Resolve framework differences and dependencies.
Resist the temptation to improve everything during the move.
The first milestone should be boring:
Can the production repository reproduce the existing frontend?
This gives you a known-good baseline.
You want:
Existing prototype
≈
Production repository using static/mock data
before you start changing its architecture.
Why?
Because otherwise you may simultaneously be:
When something breaks visually, you no longer know why.
A faithful baseline turns future refactoring into controlled change: there is always a clear before-and-after to check any regression against.
Once the frontend exists correctly in the production application, the real work can begin.
In this project, that means connecting it to Payload CMS.
Payload concerns should not spread throughout the presentation components.
The preferred architecture is:
Payload
↓
query / resolver / view model
↓
presentation component
For example:
Payload Hero configuration
↓
Hero resolver
↓
<Hero />
The existing design component keeps functioning purely as the presentation component, regardless of which CMS sits behind it.
Payload owns content and configuration.
The mapping layer translates that content into the stable props the component expects.
This matters because it keeps two responsibilities separate:
CMS structure
and
visual presentation
The same principle applies regardless of whether the CMS is Payload, Contentful, Sanity or something else.
There is another trap here.
You could establish visual parity, connect every page to the CMS and postpone all architectural cleanup until the end.
I would not do that either.
By then, the entire production application depends on the old contracts.
Work in vertical slices.
Take one real part of the application.
For example:
Payload content model
↓
query + mapping
↓
Blog template
↓
existing cards/components
↓
visual validation
↓
targeted component hardening
Then repeat for the next area.
Every time a component enters a real production path, inspect it.
That is what I mean by:
Harden on touch.
Do not pause the whole project for a massive cleanup, and do not continue building new dependencies on weaknesses you already understand.
In this particular frontend, we eventually made three separate architectural decisions.
If a component genuinely has multiple visual modes, expose them deliberately.
For example:
<HeroProductCard
tone="dark"
density="compact"
/>
This keeps the variation inside the component's own API and prevents several unrelated parents from reaching in to override its internal selectors.
Some differences work better as section-level context than as individual props. When an entire section creates a visual context, semantic CSS variables can carry it:
.dark-section {
--foreground: white;
--surface: #123;
}
A parent should be allowed to determine where a card sits in a grid, without needing to know how that card's internal title selector is named.
CSS Modules made sense once a component had a clear public API: its internal styling could then belong entirely to that component.
Something like:
ProductCard.tsx
ProductCard.module.css
with:
.root {}
.title {}
.media {}
.actions {}
The important detail is when to make that change.
Do not take a heavily coupled component, put all of its classes inside a CSS Module and celebrate that the CSS is now scoped.
You may simply have broken every external dependency.
First understand why those dependencies exist.
Turn legitimate differences into variants, context or parent layout.
Then scope the internals.
CSS Modules work best as one of the tools that enforce a component boundary once that boundary has been properly defined and its dependencies understood.
The frontend also had custom components for things like dialogs, drawers, autocomplete and tabs.
Some of them were already fairly sophisticated.
The real question was which interaction logic we actually wanted to own for the next several years:
Consider everything involved in a good dialog:
Or a combobox:
Implementing all of that is possible, and every piece of custom interaction behaviour then becomes something the team needs to test and maintain going forward.
So the decision was to keep the existing component layer and visual design while using Base UI underneath selected interaction-heavy components.
Conceptually:
Feature
↓
Existing Modal
↓
Base UI Dialog behaviour
↓
Existing styling and animation
The application still consumes:
<Modal />
That boundary matters.
Base UI becomes an implementation detail.
And we do not force it onto everything.
A normal button can remain a button.
A text input can remain an input.
Existing Floating UI functionality can remain where it already solves the problem well.
The goal is reducing the amount of difficult interaction machinery the team needs to own.
There is a broader lesson here for service businesses.
Technical implementation means balancing multiple factors alongside architectural cleanliness:
A full rewrite may be cleaner and still be the wrong decision for the business.
Likewise, accepting all existing implementation choices because "the design already works" can save money today and quietly create a much larger maintenance problem later.
The value of an implementation partner is partly in navigating that middle ground.
You need to be able to say:
This part is good and should stay.
This part looks unusual, and it is not actually a problem.
This part creates production risk and should change.
This part should change, just not yet.
Those are very different conclusions.
When I inherit an existing frontend now, I would evaluate it in this order.
Is there a coherent token system?
Are visual patterns consistent?
Are components actually reused?
Do components own their variations?
Or do other parts of the application reach into their internals?
Can you tell which component owns which styles?
Are overrides intentional or merely accumulated?
Which custom components own difficult keyboard, focus and accessibility behaviour?
Is that behaviour adequately tested?
Are presentation components tied directly to mock data, APIs or CMS document shapes?
Can a mapping layer isolate those concerns?
Which components are actually needed by the real site?
Which abstractions exist mainly because of prototype experimentation?
Can you create a working baseline before changing architecture?
If not, every refactor becomes harder to validate.
For this project, the direction eventually became:
Existing design system
tokens / visual language / animations
↓
Existing branded components
↓
Explicit component APIs
↓
CSS Modules for locally owned styles
+
Base UI for selected complex interaction behaviour
+
Native HTML / Floating UI where appropriate
↓
Payload through a separate data-mapping layer
The specific technologies matter less here than the decision process behind them — another project could easily reach a different technical answer.
These were the questions that actually drove the decisions, ahead of any individual tool preference:
What already works?
Where are the actual dependencies?
Which risks become more expensive once production starts depending on them?
What is the least disruptive way to create stronger boundaries?
Starting from questions like these is what produces much better implementation decisions.
The simplest version is still the one I would use to guide the work:
Preserve first. Prove parity. Integrate vertically. Harden on touch.
There is a middle ground between blindly preserving someone else's frontend and rewriting it into your preferred stack, and it is usually the more useful path.
Understand the system.
Preserve the value.
Make the hidden contracts explicit.
Replace difficult machinery where mature solutions are genuinely better.
And let real production requirements tell you which parts deserve your attention first.
That is usually a better use of both engineering effort and the client's budget.