Component Specifications
What to include, where it goes, and why it matters more now
During the emerging years of design systems (2015–2018), designers and developers form teams to crank out components. Tight collaborative connections favored conversation over artifacts to align, decide, and move forward. As a component design stabilized, designers might have erratically sprinkle callouts, tidied up the variant grid, or redlined a variant. After that, it was ready to handoff to a developer.
Things have changed. Components are more complicated. Designers are delivering to many different developers. Accessibility has risen to the fore. For design systems that scale, teams are finding it necessary to write down all the details again.
Over the past three to four years, I’ve worked across many design systems to formalize a design specifications format that’s proven repeatable and robust. Parts of it are repeatable enough that we’ve published a Specs Figma plugin that’s described in a companion article and supported by a Figma community file with templates and components. This article expands on why component specs are important, where teams consolidate them, and what kinds of details and artwork they include.
Why specs matter
I’m still amazed when designers schlep together a few pictures, publish a configurable Figma component, point their developer counterparts at the main component and say “Use Figma’s inspect tool.”
First, Figma’s Inspect tool isn’t bad, but it’s limited. Inspection in general requires considerable scrutiny and persistence to find every decision you’ve made. Understanding design intent shouldn’t be a treasure hunt. Don’t give a developer a shovel, point into the distance and say “Dig over here, try that area too, but bother digging in those corners?” If you know where the treasure is, just dig it up and given it to them.
Understanding design intent shouldn’t be a treasure hunt
Second, Figma components don’t reveal everything you need to know to built a well-designed component. There’s more to it than that: behaviors, code only properties, accessibility to name a few. Therefore, it’s like dishonestly setting a teammate out with a shovel to dig up treasure when you know half the treasure isn’t even buried there anyway.
Nevertheless, for a few years, design system teams were small and strong enough to talk often and synchrously enough to agree on those things.
Now, the game has changed.
Multi-platform builds → Collaborative connections are weaker
A single code library has given way to building across platforms. A three platform setup (iOS, Android, and web) is common, and some systems like IBM Carbon spread across many more. As a result, one design serves many independent development teams. While handoffs across teams remain, developers lack tight relationships with designer(s) to understand requirements. Specs fill that void.
Props, motion, accessibility, … → Components are complicated
It’s not just styling. Components increasingly encapsulate many features. From detailed accessibility notes to analytics integration to content to tokens, there’s so much more to describe and decide. Specs provide a model to fill in all those blanks.
Quality and craft → Naming needs a decisive focal point
We’re now years into crafting API together. Those conversations can fluidly span from planning a component before you start to polishing and pivoting during coding. Yet, the spec handoff is the routine moment to discuss and decide the structure (element and layer names), configuration (mostly, properties and option names), and default content.
Theming → Tokens must be mapped
The component’s API has extended to include how semantic tokens flow into each component, and how themes may need to target specific attributes of specific elements to vary characteristics. Specs document those mappings.
Flexibility → Components have intricate parts and dependencies
The trend towards greater flexibility has design systems thinking in slots and subcomponents and offering smaller parts. This disperses configuration across more components of greater nested depth. Specs help us expose, decide, and evolve where we target each feature.
Enterprise scale → Change across generations must be described
Systems last longer with impacts that span rebrands, refactors, and replatforms. Designs evolve, often more and more slowly, and different code implementations may upgrade design at different, staggered times. Specs offer a place to record, illustrate, and track that change.
Where specs go
Teams that I work with are authoring specs in a consistent format in a single Core Specifications Figma file. This file is:
- Visible to everyone in the organization
- Branched with only a few editors of the main branch (such as the design system’s design lead and 1–2 senior design team members)
- Begun with Cover, Component status and About this file pages
- One foundation (e.g., color) or component (e.g., text input) per page
- Ordered alphabetically within Foundation and Components sections
What specs include
Specifications include a range of content, some automated and others manual, including:
- Anatomy
- Properties
- Layout and spacing
- Behavior
- Accessibility
- Motion
- Component tokens
- Version history
Anatomy
An anatomy breaks down a component into parts, itemizes and names each one, and can describe visual attributes (like text color) and configured properties (of nested component dependencies).
Properties
A properties section can illustrate each property, contrast a default with alternative options, and describe detailed differences of visual attributes and nested component properties.
Property specifications can also highlight non-visual props relevant to code, accessibility and content, often in a tabular format.
Layout and spacing
Specs help us highlight the very intentional spacing choices that separate, inset, and align each element we arrange. A Spacing section illustrates padding, margin (in Figma, item spacing), direction and other mechanics.
Text wrapping, also labeled as Overflow, illustrates what to expect visually with excessive content, such as long text strings and/or large images. These specs can reveal unexpected intents of counter alignment (such as middled aligned text columns) or truncation (such as a text input’s hiding characters that exceed it’s width).
Additional subsections can illustrate aspects Responsiveness, Sizing, and Touch Targets.
Behavior and animation
Behavior specifications often document events (such as click, mousedown, and drag) and textually describe or visual depict the change in state triggered by that event.
Animation specifications can be conflated with behavior, since event triggers and shifts of state are central to the motion that occurs between those moments.
Accessibility
Designers can add considerable detail across broad considerations to ensure a component design is implemented accessibly. Stephanie Walter gave a great talk at the Clarity Conference in 2022 about A Designer’s Guide to Documenting Accessibility & User Interactions.
While I’m not an accessibility expert, I’ve worked with many designers who know more than I do to describe the auditable expectations of how a compoennt is built. For example, Felix Kuo and I worked to refine a detailed section on Screen reading. Artwork is paired with element-by-element annotations of the reading format, an example in practice (matching the artwork), and the role of the element described.
Among the many potential other component accessibility spec formats, I’ve most often encountered treatments on Focus order, Announced order, and Alternative text.
Component tokens
As design tooling evolves quickly, many teams use plugins like Tokens Studio for Figma and homegrown theme plugins to enable designers to apply and swap themes. Nevertheless, component specs can still be valuable to communicate component token-level models and overrides and extensions per component.
Using the format depicted below, teams inventory will component-level tokens (mostly color, but there could be typography, space and other attributes needed for theming. Relevant token details could include a description, alias (usually to a semantic token), Figma style names (when relevant) and default values.
Version history
Component specs usually aren’t handed off once. Instead, specs are managed over time during a redesign cycle, as it evolves, as it’s adjusted when built for multiple code platforms like React, Angular, iOS and Android, and after it’s released.
A version history can be useful for spec readers to understand what’s changed since they referenced the specification in their own work. Versions are typically added each time a branch is merged that changes the specs.
Specs ≠ Design guidelines
Specs are largely concerned with how to make a component, not how to use a component in practice. Therefore, I advise teams that design specs and design guidelines overlap yet have different audiences and intents. The overlapping content can take differing forms such as a spec’s Anatomy including far more detail than a similar, simpler Anatomy of design guidelines.
Takeaway: Don’t get stuck delaying or complicating specs with guidelines; save design guideline production for later closer to release.
In closing, component specifications can include a wide range of in-depth details. While some facets can be automated, others require deliberate consideration and manual work to get the details right. As you consider the potential specs you could create, keep your reader in mind: usually, first and foremost, the people building what you’ve designed and also others who must understand how it’s built to use it in their work.
