Building FigJam widgets

Within the last year I've discovered that Figma plugins and widgets are perfect bite-sized coding projects for me. I'd always wanted to get into Figma's APIs, and widgets seemed like the simplest way to start. So far I've created two widgets—one for annotating designs according to common UI design heuristics, and another for creating lightweight user flows.

UI Principles and Pitfalls

The first widget I made is for annotating mockups according to heuristic analysis criteria. The inspiration came from the UI Tenets and Traps deck of cards. You drag the widget onto the canvas, select a tenet and trap, and then you can rank the severity of the problem or add a note that provides additional context. The widget can be minimized so that it takes up less space on the canvas.

UI Flow Shorthand

The tenets and traps widget had pretty simple functionality and wasn't too hard to implement, but this one was more challenging. This widget helps you quickly get user flows out of your head, following the shorthand notation outlined by Ryan Singer many years ago. You use the widget by writing what the user sees, and then adding actions that the user can take. You then add additional screens and actions that are automatically linked together with connectors to assemble a flow.

Managing FigJam connectors

• Calculating where each connector should attach based on the location of the action button
• Dynamically repositioning all of the existing connectors whenever an action in the list is deleted or reordered
• Cleaning up deleted connectors from the widget's state

Repositioning connectors

Whenever the user creates a new node, rearranges actions, or deletes an action, the widget needed to programmatically update the positions of all existing connectors. Since I'm still an amateur programmer, it took me a while to figure out how to how to make this work. I had to learn more about async functions, TypeScript, and Figma's Widget API in order to get it working.

Cleaning up connectors

I discovered another problem that was invisible to users but resulted in polluted state behind the scenes and degraded performance. If a user deleted an attached connector manually by selecting it in FigJam, the widget it was attached to wouldn't know that the connector had been deleted, and would continue storing a reference to the deleted connector in its state. I wrote a function that checks for "ghost connectors" and removes them.

Other snags

• Figuring out how to manage state with useSyncedMap
• Handling the positioning of cloned widgets when the source widget is in a section vs. directly on the canvas
• Allowing the user to reorder actions
• Detecting collisions with other nodes on the canvas so that no overlap occurs during the cloning operation

Conclusion

These things probably wouldn't give a more seasoned programmer much trouble, but it was a nice challenge for me and I learned some things I didn't know before. Most of the features that gave me trouble were optional, but I kept going because they made the user experience better and I was enjoying the learning process.

The end result is a lot of smart functionality and attention to detail packed into a widget that's simple on the surface, and I'm really happy with how it turned out.