Atomic Design to Figma: Importing Your Component Hierarchy

Atomic Design in Code vs. Figma: The Gap

Brad Frost's atomic design methodology is widely adopted in frontend codebases. Component libraries organized as atoms (Button, Input, Badge, Icon), molecules (SearchBar, FormGroup, CardHeader), organisms (ProductCard, NavigationBar, CheckoutForm), templates, and pages are standard in React, Vue, and Angular projects.

But Figma libraries often don't match. Designers build Figma components from their own mental model — which may not align with the code structure at all. The result is predictable friction: developers get handoffs that reference "Figma components" that don't exist in code, and designers propose changes to components without understanding the code dependency tree.

The fix is to bootstrap your Figma library from the actual codebase — importing each component level by level so the Figma hierarchy mirrors the code hierarchy from day one.

Mapping Atomic Levels to Figma Pages

Why Import Bottom-Up (Atoms First)

Import atoms before molecules before organisms. This mirrors how atomic design works in code — organisms are compositions of molecules which are compositions of atoms. If you import an organism first and try to extract the atoms from it, you're decomposing a complex structure after the fact. It's harder and error-prone.

Importing bottom-up also gives you reusable Figma Components at each level before you need them in higher-level compositions. When you import a molecule and convert it to a Figma Component, you can then reference that Component inside organism frames — creating a true nested component hierarchy that matches the code.

The Import Workflow: Level by Level

1. Import atoms from Storybook or a component playground

Storybook is the ideal source for atomic imports because it renders components in pure isolation — no page navigation, header, or footer wrapping your Button or Input. For each atom:

1. Open Storybook at http://localhost:6006 (or your staging Storybook URL).
2. Navigate to the component story (e.g., Button → Primary).
3. In the Storybook canvas, right-click the rendered component → Inspect Element.
4. In DevTools, right-click the component's root element → Copy → Copy outerHTML.
5. In Figma, run html2design, paste, and convert. You get the atom as a native Figma frame.
6. Rename the frame, right-click → Create Component. Name it "Atoms / Button / Primary."

Repeat for every atom variant. A "Button" atom typically has 4–8 variants: Primary, Secondary, Danger, Ghost, Disabled state, Loading state, Icon-only, Icon+Label.

2. Register atom tokens as Figma Variables

Before moving to molecules, register the design tokens you discovered in the atom imports:

• Colors — Every unique hex value from fills becomes a Figma Variable: Colors / Primary / 600, Colors / Neutral / 100, etc.
• Typography — Every unique font/size/weight combination becomes a Figma Text Style: Type / Body / Regular, Type / Label / Bold.
• Spacing — If your design system uses a spacing scale (4px grid, 8px grid), register the values as Figma Number Variables: Spacing / 4, Spacing / 8, Spacing / 16.

Re-attach the imported atom Components to use these Variables instead of raw values. This step is the foundation of your design system — without it, molecules and organisms will contain inconsistent raw values that drift from the token spec.

3. Import molecules

Molecules compose atoms. When you import a molecule — say a SearchBar (Input + Button) — the rendered outerHTML includes the HTML for both the input and the button. html2design creates a nested Figma frame structure that mirrors the DOM hierarchy.

After importing a molecule frame, convert it to a Figma Component ("Molecules / SearchBar"). If the molecule contains atoms you've already created Components for, you can optionally swap the imported atom layers for their Component instances — this creates true component nesting in Figma that matches the code.

4. Import organisms

Organisms are the most visually complete components and often the most useful for design work — they look like real product UI. For a ProductCard organism, navigate to the relevant Storybook story or render the component in your component playground, copy the outerHTML, and import.

Organism imports typically produce the most complex Figma frame trees — many nested frames reflecting the DOM hierarchy. Focus on getting the visual output right; the layer cleanup (removing empty wrapper divs, flattening unnecessary nesting) can happen after the initial import.

5. Build templates and pages

Templates and pages are best imported from the running application rather than Storybook, since they represent full page layouts. For a page import:

1. Navigate to the page in your browser (production or staging).
2. Set the DevTools viewport to your standard desktop width (typically 1440px).
3. Copy the <main> element's outerHTML (or the full body).
4. Import with html2design. This is your "Pages" level frame.
5. Don't convert pages to Components — they are reference frames, not reusable components.

Maintaining the Hierarchy After Import

The hierarchy you've built is only valuable if it stays current. When the codebase adds a new component variant or changes an atom's styles, the Figma library needs to reflect it. The maintenance workflow:

• New components — Import the new component from Storybook, create the Figma Component at the correct level, publish the library update.
• Changed atoms — Re-import the affected atom from Storybook, compare with the existing Component, update fills/fonts/spacing, push the change through the Component so molecules and organisms using it update automatically.
• Token changes — Update the Figma Variable, not individual components. If your colors use Variables, every component that uses the variable updates automatically when the variable value changes.

For a deeper treatment of token sync, see Design Tokens: Bridging Code and Figma.

Naming and Library Organization Best Practices

The naming convention is the most important structural decision. Use the slash-separated format that Figma uses to create component groups:

• Atoms / Button / Primary
• Atoms / Button / Secondary
• Atoms / Input / Default
• Atoms / Input / Error
• Molecules / SearchBar / With Button
• Organisms / ProductCard / Default
• Organisms / ProductCard / Featured

This naming creates a navigable component tree in Figma's asset panel that directly mirrors your codebase's directory structure — /components/atoms/Button/index.tsx maps to Atoms / Button in Figma.

Frequently Asked Questions

How do I import an atomic design system into Figma?

Import bottom-up: atoms first (from Storybook), then molecules, then organisms. Convert each import to a Figma Component with atomic naming ("Atoms / Button / Primary"). Register design tokens as Figma Variables before building higher-level components. The result is a Figma library whose hierarchy mirrors your code.

What is atomic design in Figma?

Organizing a Figma component library using Brad Frost's methodology — atoms, molecules, organisms, templates, pages — with slash-separated naming that creates a hierarchy in the Figma assets panel. Each level corresponds to a component complexity level in code.

Does html2design preserve component nesting?

html2design imports the rendered DOM tree as nested Figma frames — so nesting is preserved visually. Component identity (which layer is a "Button" vs a "Container") is determined by you when you create Figma Components from the imported layers.

Should I import from Storybook or from the live application?

Atoms and molecules: Storybook (isolated context). Organisms and templates: Storybook or the live app (organisms with full surrounding context). Pages: the live application (full page context). Storybook is ideal for atoms because it eliminates surrounding page context and lets you target each variant directly.