Figma Developer Handoff, Sitecore Edition: From Design File to Working Component Library

A design agency finished a site refresh for a higher-education customer, handed over a set of polished Figma files, and moved on. Months later the internal web team was still stuck. The mockups looked finished, but nobody could turn them into pages. There was no component library in the content management system (CMS), no mapping from the design to anything an author could place, and one designer was quietly rebuilding screens by hand from a copied Figma file because that was faster than waiting for the parts that never came. If you have inherited a handoff like that, this is the rebuild process we run.

The core problem is a category error that shows up on almost every stalled Sitecore project we are asked to rescue. A Figma file is not a component library. It is a picture of one. The library of record is a set of templates, renderings, datasource contracts, and tests that live in source control, and the gap between the picture and the working system is exactly the work the previous team skipped. Closing it is not glamorous, but it is finite, and it follows a repeatable path.

First, agree on what the words mean

Before anyone builds a page, the design team and the Sitecore team have to be saying the same thing when they use the same word. This sounds obvious. It is the single most common place these projects go sideways, because "component" means one thing in Figma and something more specific in Sitecore, and nobody notices the mismatch until three sprints of rework have piled up.

We start by filling in one table together, in one meeting:

If the two teams cannot fill that table in a single meeting, that is the finding. Stop building pages and fix the vocabulary first. Every hour spent here saves a day of arguing about why a "button component" in the design has no clean home in the CMS.

Where the CMD CNTR process wraps around the work

The rebuild itself is a sequence of engineering steps, but we run those steps inside a delivery process that keeps a live site safe while its component library is reconstructed underneath it. Three environments, three gates.

Staging is where each rebuilt component lands first, serialized and reviewed as a pull request. Nothing reaches the content authors until it has passed component review: a keyboard pass, an accessibility check, and a look at the datasource contract to confirm authors cannot break it.

Review is a content-team gate, not an engineering one. The people who will actually place these components put them on two real page types and try to misuse them. Missing help text, confusing field order, and the temptation to nest a one-off all surface here, before the pattern is set in production.

Live is a controlled promotion, component by component, in the order the audit gave us. We never flip an entire rebuilt library at once. The site keeps working the whole way through because we replace parts in dependency order, chrome and navigation last.

That wrapper matters because the customer usually cannot take the site down. The rebuild has to happen on a running plane.

The seven-step rebuild

Here is the path we walk, condensed from the longer version but faithful to the order. Each step feeds the next, and skipping one is how you end up back where the previous agency left you.

Step 1: Inventory every component before you build anything

List every published component using the designer-facing names, then sort each into page chrome (header, footer, navigation), section content (hero, card grid, section navigation), or utility. Flag anything with multiple levels of navigation separately, because that is where the hard accessibility work lives. Capture the accessibility notes now too, because they become rendering requirements later, not a cleanup pass at the end.

We write each entry as a small record so the mapping is explicit:

name: SectionNav
design_source: Figma / Foundations / Navigation
sitecore_rendering: Foundation.Navigation.SectionNav
datasource_template: Foundation.Navigation.SectionNav
variants: Default, Sticky, Compact
a11y: aria-current, skip-to-section, 44px targets

Step 2: Fix the field mapping before the build sprints

For each component, decide once where every piece of content lives, and write it down. Title text becomes a single-line or rich text field with a real character limit. A call to action becomes a general link field, label and URL together. Theme becomes a rendering parameter or a droplink, never free text. Images get an image field with mandatory alt text. Nested blocks become placeholders, not one giant "mega-template" that authors have to fight.

The output is a fixed contract per component. When you skip this step, authors invent structure, and six months later you have forty variations of a card because nobody agreed on the one card.

Step 3: Build multi-level navigation as two components, not one

Navigation is where the copied-Figma-file rebuild usually broke, so it gets its own step. Do not build one reusable mega-menu. Build two components with two jobs.

Global navigation owns the primary destinations across the whole site and exposes the current section with aria-current="page". Its mobile pattern has to be operable by keyboard, and it must return focus to the trigger when it closes.

Section navigation manages orientation inside one section only. It reads the current page's context to highlight the active sibling or ancestor, and it must not duplicate the entire global tree into a side rail. A sticky version needs a skip control and must never trap the keyboard.

The rule that keeps this honest: navigation is an information architecture (IA) problem first and a styling problem second. If the structure is wrong, no amount of CSS fixes it.

Step 4: Layer the library so authors cannot reach the wrong parts

Structure the library in layers, each with its own review bar. Tokens (colors, type scale, spacing, focus ring) sit at the bottom as CSS variables. Primitives (button, link, icon, text) carry no page logic. Composites (card, hero, accordion) have strict datasource contracts. Chrome (global navigation, section navigation, footer, skip link) gets the highest review bar because it appears on every page. Page types compose placeholders only: an author assembles a page, but cannot invent new chrome.

Serialize all of it with Sitecore Content Serialization (SCS) or an equivalent like Unicorn or TDS, so template and rendering changes arrive as reviewable pull requests instead of silent edits in a shared environment. If you run a Helix solution, this maps cleanly onto the layers: Foundation holds tokens, primitives, and navigation, Feature holds domain composites, and Project holds only site wiring and page types.

Step 5: Handle variants without exploding your templates

Every design has variants, and the wrong instinct is a new template for each one. Use the lightest tool that works:

The rule: if a designer called it a variant of the same component, prefer parameters. If the markup structure changes, a carousel versus a static grid, prefer a separate rendering.

Step 6: Treat the author experience as part of the component

A component is not done when it renders. It is done when an author cannot easily misuse it. Order the fields the way the Figma panel is ordered (content, then media, then behavior). Add help text that names the design source, for example "Maps to Figma: Section Nav / Compact." Enforce validation in the CMS: required alt text, maximum lengths, allowed link types. The Experience Editor should quietly discourage nested one-offs rather than invite them.

Step 7: Lock the field contract for headless and Layout Service

If you deliver through Layout Service or XM Cloud, the field names in Sitecore have to match what the front-end component map expects, exactly. A rename on either side breaks the contract silently. Write the contract down as the shape both sides agree to:

{
  "componentName": "SectionNav",
  "fields": {
    "heading": { "value": "About" },
    "items": [
      { "fields": { "link": { "value": { "href": "/about", "text": "About" } } } }
    ]
  },
  "params": { "variant": "sticky" }
}

Orientation rules the section nav has to follow

Because navigation is where these rebuilds most often fail an accessibility review, we hold the section navigation to a written set of orientation rules and keep them in the component's README so the next developer inherits the reasoning, not just the code:

• Show the user where they are. Deep trees disorient people fast. Use aria-current, a visible active state, and an optional breadcrumb.
• Scope the section nav to its section root. Resolve it from the page's ancestors so you are not dumping the whole site into a side rail.
• Match navigation labels to page titles. A label that disagrees with the page it leads to erodes trust.
• Keep keyboard order matched to visual order. No positive tabindex, and let the DOM order carry the sequence.
• Close the mobile drawer on Escape and restore focus to the trigger. Trap focus only while the drawer is open.

Resolving the section root is a few lines, and getting it right is what stops the side rail from listing every page on the site:

var page = Sitecore.Context.Item;
var sectionRoot = page.Axes.GetAncestors()
  .FirstOrDefault(a => a.TemplateID == SectionRootTemplateId) ?? page;
var links = sectionRoot.Children
  .Where(c => c.TemplateID == NavLinkTemplateId);

The governance that stops it from happening again

The reason the customer needed a rebuild in the first place is that the original library had no guardrails, so it forked until it was unusable. We install a short governance checklist and hold the line on it:

• No new rendering ships without a design component ID in its README.
• No hex colors in rich text. Tokens only.
• Navigation changes go through IA review, not visual QA alone.
• Every template or rendering change arrives as a serialization pull request.
• A quarterly audit hunts for unused renderings, duplicate heroes, and orphan placeholders.

None of these are heavy. Together they are the difference between a library that stays coherent for years and one that needs this same rescue again in eighteen months.

This discipline is not Sitecore-specific

We run the exact same process when we build our own component libraries in Nuxt from purchased or commissioned designs. The platform changes, the discipline does not: agree on vocabulary, map fields to a real contract, build navigation as an IA problem, layer the library, and govern it so it cannot fork. Sitecore has the richest tooling for enforcing these contracts at the CMS layer, which is why we lean on it hard for enterprise work, but the failure mode (a design file mistaken for a working library) is universal.

Further reading

This process is adapted, with permission, from Mohd Naeem's deeper walkthrough, From Zeplin and Figma to a Sitecore Component Library, which includes the full worked SectionNav example and more of the Helix detail. The blank version of the mapping table above is available as a free Figma-to-CMS component mapping template. If accessibility is where your handoff is failing review, the companion piece on WCAG 2.2 for Sitecore teams covers what authors break after launch and how the CMS can stop them. For the wider platform-and-partner picture, start with the enterprise CMS pillar.