“Mode conflicts”: cause and solution (text styles / typography tokens)

There are many closed posts trying to understand why Mode conflicts happen. While the Figma team continues investigating, I believe I’ve found some clues about the root cause—and part of the solution—based on repeated testing.

Before you start

• Make sure your libraries are exported and up to date:

  • Accept all updates in the source libraries.

  • Re-publish if anything changed.

  • In the affected file, relink/accept updates to the latest library versions.

How to diagnose

1. Find the component that shows the ⓘ warning when you try to switch a mode.

2. Duplicate the component, then detach the copy.

   • Work on the detached copy so you don’t lose the original.

   • Check if the conflict persists on the detached version.

3. If it persists, inspect layer by layer (text layers, containers, etc.) until you isolate the problematic element.

   In my experience, the culprit is almost always text styles or typography tokens.

Two common cases & solutions

Case 1 — One text layer with two text styles applied

• Step 1: You have a single text layer mixing, e.g., Bold 1 for the title and Body 2 for the paragraph.

• Step 2: Select the entire text layer and apply a single text style temporarily. Check if the conflict persists.

• Step 3: If it’s gone, reapply the original styles (you can split into separate text layers or re-apply ranges, avoiding the initial conflict).

Case 2 — Text using direct typography tokens (no Text Style)

• Step 1: A text layer is bound directly to a typography token (family/weight/size) without a Text Style.

• Step 2: Temporarily switch that semantic token to a different one and check again.

• Step 3: If the conflict clears, switch back to the correct token.

  • This “reset” often clears the stale reference that triggers the conflict.

Note

My working hypothesis is there’s a cached reference issue tied to fonts/styles. “Normalizing” (unifying styles or forcing a temporary swap) tends to clear it.