From Figma to Production Without Design Debt
Most UI debt isn’t a pretty Figma file—it’s missing tokens, forgotten states, and one-off decisions in code. A delivery path that shrinks the design–frontend gap.
Ali Mortazavi
Founder, Paradise Code
Where design debt is born
When every page invents its own color and spacing, buttons have three heights in three places, and error states exist in only one frame, design debt enters the codebase. The bill shows up later as brand inconsistency and slow features.
A tidy Figma is not automatically a tidy product. If the file is for pitching rather than building, engineers guess—and guessing is debt.
Tokens before hero pages
Turn color, type, space, radius, and shadow into named tokens and mirror those names in Tailwind/CSS variables. A design `blue-600` that becomes `#2F6FED` in code is chronic drift.
Before polishing the hero, align button, input, table, and modal names in both worlds. A hero without stable primitives is a shiny storefront on a fragile frame.
States demos forget
For every key flow, demand empty, loading, error, success, permission denied, and long-content frames (30-word labels, 100-row tables). Without them, frontend improvises in production.
Don’t treat RTL as a skin at the end—build it into components from the start. Directional icons, forms, and pricing tables are the usual break points.
Handoff that is actually handoff
A Figma link plus exported images is not enough. Specify responsive behavior, interaction, keyboard access, and which parts are static illustration versus API data.
For repeated components, keep a simple props table shared by design and code. When design adds a variant, it should map to a prop—not spawn another visual fork.
Stopping “close enough” QA
Review visually against criteria: spacing on the token grid, contrast, focus states. Route taste debates (“a bit bigger”) back to token decisions so the system grows instead of exceptions.
Screenshot diffs in PRs for money pages pay off. If every PR merges without visual criteria, debt accumulates invisibly.
Tools and speed without lock-in
Design tokens, Storybook (or equivalent), and a UI kit (e.g. HeroUI) shrink the gap—if brand customization rides on tokens rather than endless component forks.
Avoid rebuilding an entire design system mid-client-project unless debt is blocking delivery. Stabilize the product-critical path first.
A suggested team contract
Design: tokens + states + responsive. Frontend: implement with the same names + test states. Product: prioritize UI debt in the backlog like bugs, not “polish later.”
Paradise Code treats handoff as part of Done: if error states and tokens are missing, design is not ready for engineering—even if the hero dazzled in the pitch.
Frequently asked questions
Do we need a full design system on day one?
No. Start with primitives and two or three patterns. Expand when page repetition rises.
Is Figma Dev Mode enough?
It helps, but it doesn’t replace token and state contracts. Unnamed sizes drift again.
How do we pay down existing debt?
Pick one money path, extract tokens, unify that path, then spread the pattern to the next pages.
We’re a designer-developer hybrid—what then?
Still separate layers: token/pattern decisions versus page implementation. A mixed role is not an excuse for chaos.
Insights
Need these ideas implemented in your product?
Paradise Code supports you from consult to full delivery.