Stable keys for text content? (And possibly any figma node and other things?)

[cixzhang]

Hey, I'm working on Meta's internal design system with @vjeux.

We have a large number of components to connect and our system is in continuous development so one concern we have is around the stability of our code connect definitions and how to keep figma and code in sync while preserving our ability to work efficiently in a large system.

At the moment, the way we connect code to figma involves:

• text describing the contents of a figma text node for figma.textContent
• text describing the "name" of a figma node/instance for figma.children and figma.instance
• a node id pointing to the component set which is unclear how stable that id would remain over time

The textContent worries me the most since this text content is visible in how the components present to our users in figma so it's a user-readable string and can change if we decide on better content to show later on. I don't know if there's a good way to assign some stable key to a textContent node that is not as likely to change.

For figma nodes and instances, they're by the "name" of the node which isn't part of how components present to our users so it's more likely these can remain stable, but if there's a clear way to retrieve nodes and textContent by stable key, it could be possible for us to codegen more of our code connections and have designers make updates in figma to assign stable keys to the right nodes.

What if we allow designs to annotate their nodes in figma with stable keys? If designers make updates later to restructure/improve our figma components, it would be less likely for our code connections to become unstable.

[tomduncalf-figma]

Hey @cixzhang,

Thanks for the clear report! This is something that has been on our minds too, we don't have anything to share right now but we are thinking about it.

In the meantime, I can provide a few thoughts/suggestions:

"text describing the contents of a figma text node for figma.textContent"

While the default "name" of a text layer automatically matches the text content, you can actually rename text layers in the layers panel, just like any other layer. After a text layer has been renamed, its name will remain stable regardless of the text content (unless you rename it again, of course). See below for an example:

So working with your designers to give "stable" names to any text layers you depend on should give you greater stability here.

text describing the "name" of a figma node/instance for figma.children and figma.instance

Yeah, this relies on designers to not change the name of any layers which Code Connect relies on. Right now, there's nothing warning a designer that renaming might break the Code Connect, so you'd only find out when you try to publish Code Connect (e.g. maybe a CI job). We realise this isn't ideal so we are thinking about ways we can improve this, being able to give a stable ID indepdendent of what is seen in the layers panel could be one approach.

a node id pointing to the component set which is unclear how stable that id would remain over time

You can rely on this ID to remain stable as long as that component set node exists!

We'll keep you updated with our thinking here, and if you have any other questions or concerns please let me know!

[cixzhang]

@tomduncalf-figma thanks for the tips! I'll pass them to our designers :)

[ernestt]

@tomduncalf-figma Thanks for these tips! Im a designer working with @cixzhang and just want to share our approach to library management that might suggest that component node ids are not super stable for us long term either.

Its my understanding that there are certain limitations to change preservations when it comes to pushing library updates. (ie. changing layer structure of a component will reset certain instance overrides). After a few breaking publishes, we started to practice depreciating the component and republishing a brand new one under the same name. This is so that teams can receive updates but migrate to the latest components at their own timeline. I would says this kind of updates happen maybe every 2 years? So not too frequent but something factors into the stability of code connect.

I know this is a hard problem but just wanted to share our situation. Thanks for listening :)