The EightShapes Specs Figma Plugin
How it works, and how to make it work for you
Creating component design specifications (“specs”) is grueling. Designers can spend hours manually itemizing elements, outlining props and options, and mapping tokens to elements across states and configurations. Oh, and all the redlines. For many, it’s time consuming and tedious.
However, while specs can at times be subtle, considerable design intent can be logically derived from how it’s built in Figma. Given the power of Figma’s developer API, it’s about time that tasks that took two hours are automated to take two seconds instead. So, I built and published a Figma plugin that automates Anatomy, Props and Layout and spacing.
This post describes how the plugin works, what it outputs, how teams adjust and style based on their preferences, and a bit of the background of how I got here. As you read, keep in mind: the plugin is great for specs but also proved unexpectedly useful for designers to audit in-progress Figma work for quality and completeness and critique their component with teammates. I hope this component brings you speed, inspiration, and even ideas you submit to make it better. Enjoy!
How it works
The EightShapes Specs plugin is run as a command on one or more currently selected instance or frame nodes.
The command takes a one or two seconds to run on a single, simple component and usually up to at most ten seconds for a very complicated case. After processing is complete, a design specification of multiple frames — Title, Anatomy, Props (if an instance) and Layout and spacing (if Autolayout is used) — appears on the canvas to the right.
Some components take longer. For example, Github Primer’s Comment box’s processes in around eight seconds. This delay is often due to comparing many sibling nodes in a layer like this component’s toolbar.
The plugin produces and organizes output as Figma frames organized into sections (like Props) and subsections (like a prop) as needed. Rows called “exhibits” pair content on the left with annotated artwork on the right.
About Anatomy
To produce the anatomy, the plugin traverses the node’s layers to itemize and mark text, instances, and other shapes as elements.
Each itemized component is enumerated in the content, with instances highlighting dependency name and relevant prop values and other nodes reflecting visual attributes and styles. In the artwork, markers are placed on the periphery, prioritizing the left edge and finding a location on any edge that hasn’t already been used.
The plugin stops traversing into a the hierarchy of a component (like Card) when it runs into a nested component (like CardText). Spec authors are encouraged to run the plugin again on each relevant nested component. Refer my writing on Subcomponents for learn more.
The results work for most practical component displays, even if it’s not perfect. In extreme cases, components with many sibling elements “cross the streams” (nod to Ghostbusters) of each marker’s tail and many components left unmarked. In these cases, spec authors can prune and tailor what markers work best.
About Properties
For component instances, the plugin iterates through each property to highlight differences per option.
Variant props
For variant props, the plugin compares a default with each alternative option by traversing layers and comparing relevant attributes of each layer to find and display differences.
Compound props
In some cases, property combinations (such as type and color mode) are required to fully document how styles changes. While not automated, spec authors can run the plugin against different instance configurations to quickly if manually assemble a “compound property” display.
Boolean props
Boolean props are simplified displays to highlight the property type, default value, and impacted layers marked with a blue highlight. While nearly all boolean props are associated with a single layer in practice, the list of associated layers scales to potentially list two or more.
About Layout and spacing
The plugin traverses the item to find any layer configured with Figma autolayout to create an exhibit for that layer.
While teams I’ve been working with stabilized how to document anatomy and props long ago, the work on Layout and spacing was new and by far the most exciting. Notable design decisions included:
- Breaking down space layer by nested layer — as code works! — instead of layering all redlines into one artwork frame.
- Dimming component portions irrelevant to the nested layer’s story.
- Mapping redline colors (orange as margin, green as padding, blue as element) to the color language of Chrome’s Inspector.
We’re hopeful of adding more here, such as text wrapping demos, markers for resizing types (fixed vs hug vs fill), and better highlighting absolutely positioned elements.
With Autolayout (in Figma) and layout (in general) skills underdeveloped in many designers, I’m hopeful that these improved and easy-to-produce displays help people grow.
Adjusting and expanding specs manually
Teams consistently adjust outputs manually, cope with maintaining specs over time, and tailor layouts to their own preferences. Examples include:
- Darkening artwork frame backgrounds for dark mode exhibits
- Re-running the plugin because the design or Figma build was adjusted
- Reorienting frames to display horizontally rather than vertically
Combining automated and manual specs
Of course, specifications aren’t limited to what’s automated here. Specifications also usually include more, such as text wrapping and responsiveness in Layout and spacing as well as broader topics of Accessibility, Behavior, Motion/Animation, and more. I expect designers to continue to manually assemble these pieces, and we’re at work creating a Figma Community file with those templates.
Styling outputs
In the initial release, the plugin added Figma color and text styles so that authors can customize spec appearance. Most often, teams use these styles to apply their own branded font and adjust the artwork background and marker colors to distinguish specs from the artwork they annotate.
Some plugin users objected to embedding spec styles in library files. Therefore, the plugin was revised to hard code such attributes unless the local styles already exist that the plugin could apply. Future plugin releases may enable plugin users to configure this option.
About the development experience
Over the past three to four years, I’ve consulted with many teams to improve how to record design specs. I’m indebted to the countless hours and shared ideas with people like James Melzer, Kevin Powell, Talia Fisher, Jules Forrest, Sean Glenn, Di Apostol, other others with whom I’ve shared a specification journey or two.
Notably, this plugin is not in my near term self interest. My EightShapes teammates and I have spent considerable consulting time generating specs, and we get paid by the hour. But if not me, now it’s gonna be someone else, soon. And I’d rather work on architecting good components rather than laboring to detail the architecture.
Plus, what an interesting diversion back into code! This project reinvigorated dormant development skills, enabled me to learn Typescript, and resulted in a tangible demo of my knowledge of the Figma API and skills of developing plugins. I’m game for more of that work. It’s quite fun.
