it’s like Figma wants you to write
bad publication notes 😰
Not only does Figma’s component publication experience make it hard to write good publication notes, it’s so uninviting that it seems to discourage writing anything! I suspect this is a big part of what makes folks scared to accept updates in their local files: if they can’t expect good publication notes, they can’t know what changes they’re accepting, so it’s easier to just... not. Let’s first examine the writing experience 👇
click to expand ☝️
😦 A text field designed for ants.
And with no ability to expand it. If you’re drafting a lengthy publication note, you’re in for a bad time. Scrolling, squinting,
😞 No formatting tools.
There is no way to make longer publications easier to consume. Line breaks, all caps, and emojis are all you’ve got. And remember the first point ☝️ this space is not at all friendly for drafting.
😭 No structured data, no templates, no guidance.
A cold and empty text field that leaves you wondering “What should I write? What makes for a good publication note?”
Nothing about this experience encourages designers to produce well-crafted, thoughtful, contextually-rich publication notes for their teammates.
And even if Figma did offer a space that encourages thoughtful note writing... the experience for viewing past publication notes is equally bad. The only real utility that a library’s publication history offers is the ability to restore a past version. If you’re curious about the file’s actual history, you’re out of luck. All you’re given a piddly little timeline. And for each publication in the timeline, you only get the first few words of its notes (that is, if the author bothered to write any. And I wouldn’t blame them if they didn’t!)
click to expand ☝️
Looking for historical context about a library in Figma will leave you wanting. There’s tons of great questions you may have, such as:
How big (or small) are publications? Are designers publishing big batches of components, or lots of small ones? Why?
Are there any patterns in when people publish? Does it happen evenly throughout a quarter, or year? Maybe in concentrated bursts? Why? What external factors cause this?
What kinds of changes are being published? Smaller corrections and fixes, or big overhauls and large enhancements?
What do individuals’ contribution stats look like? Who publishes the most? The least? And why?
What does the history of component-X look like? When was it introduced to the library, and who authored it? Who has contributed the most to it? Has it changed drastically over time, or mostly stayed the same?
Well, in Figma, you can’t answer any of that 😔
... but with a doc like this one, you can ✨
Welcome to the UI Library buddy doc
Encourages contributionsby making contributing easy, and keeps a detailed record of everyone’s individual contribution histories. Writing in Coda’s tables is a much more inviting experience than Figma’s publication note text field. This doc takes the guesswork out of writing by asking guiding questions to help designers write the best note possible for the type of material they’re publishing.
Enriches your library’s historical timelineby leveraging
. This allows you to capture the “size” or “risk level” of each publication, in addition to the “who” and “when.” No more nodes on a timeline; you can actually tell a library’s life-story. You will see this story take shape on the bubble chart found on
Captures context about design decisions at the component-level. Understanding the history of a library is one thing, but imagine getting that rich timeline view at the component level. Pick any component, and view every change its experienced, who made that change, when, why, and what other components were affected alongside it.
Get a copy of this doc
Who uses this doc?
UX Designers tend to be the primary audience and users of this doc. They are creating mockups and prototypes using components from
, in Figma, they should also come here to record that act of publishing. And since it’s here that we can offer them templates and guidance on writing good publication notes, this behavior should be easy to encourage and adopt.
A buddy doc also provides designers with a menu of tangible changes they might make in Figma. These each map to a publication type (listed above), and denote how risky any change may be in terms of override loss (⚠️ vs ⚠️⚠️)
⚙️ Defect fix
Correcting text or color style usage
Correcting auto layout settings (resizing rules, alignment, space between, padding)
Correcting stroke, fills, or effects
Correcting variant or property names
Correcting corner radii
Updating a component’s description
Adding missing interactive states
Adding component properties
Correcting visual design
🌱 Small enhancement
⚠️ Changing names of layers
Adding a new variant to existing component property
Moving component to new page / frame (re-organizing it in the assets panel)
Adjusting or reordering a component’s properties and/or variants (either on the canvas or in the design panel)
Enhancing visual design
🌳 Large enhancement
⚠️⚠️ Changing layer structure (any of the following):
Adding nested layers/instances
⚠️⚠️ Moving component or style to new file
Adding a new property (and variant(s)) to an existing component