Spock stood still on the transporter pad, waiting. And then … ENERGIZE! He transforms into glittery streams of light, disappears, and is away somewhere doing good. Some time later, he reappears through that same swirling energy. His shirt’s still blue, his ears pointy, his hair still a stark, bowled edge. Spock’s back, right? Mission complete!

No systems expert would rate that sufficient evidence of a successful transport. Glancing at shirt color, ears shape and hair style isn’t “good enough.” You want Spock: half-human, half-Vulcan, hyper-calculating, mindmeld-capable and yet humanly empathetic. We love Spock for all his complicated powers and nuance.

What I see today is designers shipping kind-of-Vulcans and expecting agents and engineering teammates to make that more “Spock-like.” Contracts carry color, fold in shape, and itemize styles. They add prop tables and variant axes. Cue amazed reactions from consumers of your markdown and json? At least designers aren’t shipping red shirts, right?

Contracts should carry design intent as exhaustively as needed. One way to test is a looping “round trip:” beam away, beam back, and evaluate the difference. This will expose whether a contract carries a kind-of-Vulcan or actually Spock.

I experienced a nearly-but-not-Spock humbling by accident. Round-trip testing a new feature revealed that my specs transformation and model was incomplete and lossy. Looping revealed defects, model gaps, and a lack of clarity around what the contract can’t, doesn’t, and doesn’t yet carry. This blog post describes the journey through a contract’s loss and depth and how round trips exposed how to make it better.

Loss

In a spec-driven UI component workflow, we strive for lossless transformation: converting data from one structure into another without losing, altering or inventing a single bit of information. Loss accumulates in the conversion from Figma asset to spec data, and then compounds as agents and engineers make interpretations and inferences on an incomplete picture .

When translating from Figma to spec, loss can take many forms:

• Emitting a hex code when a color token is bound.

• Missing a layer’s maxWidth applied to only the last of many options.

• Omitting a change in backgroundColor or layer presence when properties interact, such as selected:true and state:hover simultaneously occur.

Loss can occur when intent gets more complicated:

• Representing an Alert’s decorative icon as customizable when it shouldn’t be in an error variant or not customizable when it should be in a neutral variant.

• Missing how a Pill's horizontal padding varies across sizes depending on if content is composable in a slot or includes just a built-in label.

• Errantly consolidating a Figma BOOLEAN and SLOT prop into a single nullable slot property when the layer is only bound as a SLOT in some but not all variants.

These complicated examples are like Spock’s capabilities for logic, Vulcan pinch and mindmeld. These losses are worse: dropping or inventing complicated, powerful intent and easiest to miss when reviewing an asset visually. Nobody noticed because the contract had no place for it.

Depth

Contracts can carry a little or contracts can carry a lot. It’s simple to devise a format (in markdown and/or json) and an agentic skill to extract colors, spacing, corner radius, width and height across a tree of named layers. Another iteration, and a contract may also emit detected changes across each variant axis and generate a props table. A simple contract is easy to evaluate and unlikely to lose much. But it’s not carrying much, either.

Shallow contracts don’t work when UI components are intricate.

Design system teams express far more intent, authored at far finer grain in Figma assets. Variants subtly shift styling across interdependent props. Cases vary tokens and prop bindings, rules and intents.

The focus on contract depth is evident in the very first setting I implemented in the latest Specs generation: variant depth. Many publicized contract tools evaluate a Figma component set’s variant axes, comparing how design changes across enumerated options. That’s variantDepth:1. The Specs Classic (first generation) tool offered a “Two way” feature that evaluated difference of every combination of two properties, such as selected:true|false and state:rest|hover|pressed. That’s variantDepth:2.

Most tools and demos I see go no more than two levels deep. Why stop there? Designers express intent in any variant, and contracts promise exhaustiveness, right? I run Specs on variantDepth:9999 every time: no variant, layer, styling, or binding is ever missed.

Plus, depth isn’t just about variants. Subcomponents, nested instances, slots, content and props all interact in fantastic ways. Implicit naming is used to express explicit concepts. Layouts makes layers shift, appear and disappear, show and hide. Phew, I’m out of breath, and that’s not all of it! Design intent can gets deep and complicated across these concerns.

The reward for expressing more intent is that you have more to lose. A shallow contract round-trips perfectly: carry eight properties, render eight, empty diff. That’s flawless yet entirely misleading losslessness, because so much wasn’t carried in the first place. The trap is thinking shallow contracts are good. What matters for a strong contract is both how much the contract carries and how much survives the trip.

The round trip

So how would you rate depth and losslessness? Reading a schema tells you what it meant to model. It doesn’t tell what the contract actually carried. The best way to find out what a contract holds is to make it give the component back.

Starting in reverse

I recently built a render command in my Specs ecosystem, which takes a spec and renders it as a component asset in Figma via a script. It takes a few seconds per component. Why? Design system intent is originating outside of Figma. If a design system is supports building and expressing designs in both Figma and prototype, then the system must be able to move the expression between them cleanly. Therefore, the render command bring a spec’ed expression back into a Figma library.

The challenge is that the schema model underlying specs is incredibly rich: components, anatomy, props, styling, bindings, variants, slots and recursive nested composition, code only props and more. Generating a Figma asset could be agentically done, but it’d likely be lossy and error prone. Writing a deterministic render script instead was possible if bloody complicated.

The loop

As render development progressed and most features were implemented, I found inspiration in Addy Osmani’s writings like Loop Engineering. As a result, I began to loop between generated specs and rendered Figma assets to refine and polish the render's implemented features. The goal is to remove as much loss at depth as possible, proving that render has reached parity with generate in the opposite direction.

An agent would run each round, using an orchestrating script to set the harness for one component or entire catalog. The harness uses a bridge to connect Figma through a plugin to the LLM chat and cached library data (variables, icons, assets). The loop takes these steps:

1. generate a baseline spec from an existing Figma component

2. render a test Figma component from a baseline spec

3. generate a test spec from the test Figma component

4. diff the baseline and test specs

5. Create a report of what’s change (once for an entire library)

6. delete the test Figma component

Anything the pipeline loses, mangles, or invents shows up concretely rather than a hunch. The report skill validates diff counts and variant shapes and separates signals of unimplemented features from defects and regressions. Data in hand, the skill then groups symptoms into themes with root causes and create prioritized Github issues that I smash immediately or save for later. Let the loop-by-loop-burn-down commence!

The first loop against an entire library was loud: many big themes, each requiring an investment to parse, plan and smooth the render engine. Over many loops, differences diminished to residue that I could precisely inspect, refine the code, and loop more narrowly. As themes and defects quieted down, I gained confidence as less and less data was being lost. Eventually, the render command converged on feature parity with generate command.

Whether or not you build a render script, the broader takeaway is to use round trips and loops to test your contract. Agents and skills can beam back and compare to what agents beamed out. Even if it’s not deterministic, you can still find ways to distinguish carried intent from loss and lacking depth.

Yet, the loop yielded something more valuable than getting render done.

The Reckoning

I began my render work more than confident that the Figma-to-Specs generate transform and underlying schema was complete and stable. Yet, each loop exposed pipeline weaknesses. generate was dropping details silently. The schema lacked shape to express details. The contract wasn’t capturing intent I didn’t realize I valued. Mind you, my confidence in generate + schema's viability wasn’t shaken. But the tools were neither perfect nor reaching their potential.

Turns out, a round trip is a brutal test of a contract. Anything a transform and schema can’t capture gets dropped beaming out, and anything a spec captures too loosely risks loss and differences beaming back.

So, converging a round trip’s baseline and test differences to zero wasn’t actually the right goal. The diff doesn’t converge to nothing. Instead, it converges on sets I can name: reaffirmed assumptions, defects to fix, and what the contract can’t, won’t, or doesn’t yet carry that I can clearly communicate.

Expose assumptions

As I’ve built Specs, there are choices about data that I knew and others I sensed. Making the round trip made them explicit and visible, such as:

• Alphabetical order is not neutral; instead, it destroys authored order.

• Booleans must be booleans everywhere, if that’s how you want to treat them. Even VARIANT prop options that are true or True, false or False.

• Visibility is not existence; instead, hidden layers must be respected exhaustively.

If not recognized and handled correctly, transformations break. Speaking of which…

Fix the transformation

Lots of small defect emerged over time, implemented feature by implemented feature:

• Broken styling: clipsContent – very rarely used and lacking unit tests and text fixtures – sneakily never worked defined as clipContent. Not just a transformer fix, but an ADR because it changed the model’s mistake. Sigh. Details.

• Warnings where there had been silence: unresolved slot constraint keys, an ignored binding, an unbindable property. Knowing when and how much processing trips up enables smoothing more rough edges.

• Examples lacked top-level rules: content in slots wasn’t evaluating the relationship with the slot layer parent. As a result, data suggested content with a fixed width, when instead it was filling horizontally.

Such small defects go unnoticed to those reviewing visual test cases. Even visual regression snapshot tests would have missed the last Examples issue. Yet round trip transformations and differencing of data caught so much more.

Other defects rest in the backlog, with an unclear priority awaiting when they’ll actually negatively impact transmission. Authors in Figma shouldn’t be naming a code-only prop as the same name as a native prop. Detecting that should be some other tool’s job even if a Specs warning might be nice.

Expand the schema

The model does a great job carrying intent, but surprisingly tripped over basic identities. Naming is hard.

Converting Figma labels to camelCase or snake_case (a long supported, high-demand feature) is lossy, dropping characters and capitalization on round trips. Therefore, it became essential to add a safe key grammar to carry names losslessly and preserve Figma names when needed. Establishing a figmaKey:NONE|SENTENCE|TITLE convention to declare how designers are naming in Figma came along for the ride.

What can’t be supported

Unfortunately, the round trip also made clear intent that Specs can’t support, like:

• Customized prop order in Figma’s Props panel. You can derive VARIANT prop order from component layer names. However, Figma’s plugin API doesn’t carry the order of remaining BOOLEAN, INSTANCE_SWAP, TEXT, and SLOT props.

• Locking aspect ratio means that bound variables for both width and height can’t both be carried even if both remain bound “under the covers” of Figma’s UI.

Designers won’t care about the bound variable-dropping of locked aspect ratio. But I’ve witnessed more than enough designers fiddling with Figma Props panel property order to know there’s intent there. Through order, there’s priority and proximity. Through proximity, there’s groups and relationships. Those mean something, even if implicit.

What isn’t yet supported

Doing the work on the opposite render direction reaffirmed the boundary of how much Figma expression is carried through Specs. I don’t prematurely optimize to cover all cases, and demand suggests how the model and transformations grow.

As a result, I continue to not yet support Figma features like Grid autolayout, esoteric line end point styles, and stacks of stroke and fill colors. Designers aren’t yet using them in work I support (although Liquid Glass seems to have something to say about that; stay tuned!).

What won’t be supported

This exercise also reinforced the higher cost that outweighs any current benefit of building around Figma’s new motion capabilities. Figma’s motion data model is necessarily very complicated: pages and pages of docs and many nested levels of data depth, making typography and effects look elementary.

Motion is a whole separate language, few in our field know it well, nobody I know is yet expressing it in Figma, and it’d be enormously expensive for me to build a whole ecosystem around it. Maybe that day will come. But I’m not planning on it, and I’m overt about it to curious customers.

So, if you beamed your component back, what wouldn’t it return? Most don’t know, having focused on only the good and obvious stuff they’d beamed out. So take a round trip. Or two. Or some series of loops until you settle where you need to. Look for what you are missing, and how much you value it. Your diffs probably won’t converge on empty either. But you’ll be able to name the gaps and provide the polish elsewhere to ensure the components you make are the best they can be.

People encounter my specs tooling often first through the Specs Figma plugin that’s been around for years. They see it as a designer-to-engineer handoff helper. That’s understandable, since the plugin’s origin was “Select a component, automate production of a specifications document on Figma’s canvas.”

As AI emerged over 2024 and 2025, it became clear that agents and tools value the underlying data emitted in a structured, predictable schema. So I evolved the specs tooling to generate specs both via the Plugin API and Rest API interfaces, per component at for an entire library.

Yet, these narrower tools don’t necessarily convey how specs fits into a larger UI component production environment.

My work in 2026 builds further towards a single place where a design system records, evolves, projects, and synchronizes expressions of design intent. Specs serve as a hub for expressions across all the surfaces – Figma, prototypes, code libraries, docs – each a source of intent and a surface on which to render intent. To many, that probably sounds like THE source-of-truth. Well, kinda. It’s a place that normalizes, synchronizes, and versions the intent expressed across the many origins-of-truth.

Designers continue with design tools (mostly, Figma and “prototyping kits”) and engineers are expanding code factories to produce React, iOS and Android libraries. My current work provides a home for specs and translations across surfaces, building models and tools that contain design intent of components, tokens, icons and more. I make parts of a broader puzzle: tools (a Figma plugin, a command-line interface, agent skills), models (schemas, ADRs), and also still features (components and tokens) that help me grow as an architect.

I’ll sometimes blog, post or comment about a part in isolation. What’s missing is the broader picture, threading these parts with a designer’s expression in Figma or an engineer’s code factory. No one person or team owns everything. And we must agree on the edges that connect our parts. And the edges are where it gets hard.

This post maps the current specs architecture into which many emerging tools fit. I’ll start with specs: what they contain, how they are authored, and the sophistication we’ve grown into gradually. I’ll then expand on how specs connects into multiple design “origins-of-truth” (Figma and prototypes) and consuming code factories, with a break to ground the reader in the underlying architecture gluing those edges together.

About Specs

Spec serve as the hub of design intent as content to completely describe a component as best as we can. Our specs come in two flavors: generated through deterministic transformation versus authored by humans, agents or both. We favor generated over authored, and build tools that arc specs towards more generated outputs over time.

Generated specs

My specs focus is on component concerns, each extracted from Figma.

1. API declares component names, props and elements, serving as the exposed surface to configure and override it.

2. Variants declare layered rules (much like CSS) that declare the styles, tokens, prop bindings, slots, composition, layout, structure, and more. This data is complicated, rich, and best authored today solely in Figma.

3. Examples carries composed relationships via nested slots, content, and images leveraged for docs, test cases, and reusable scaffolds.

To learn more, try the Specs 2 Figma plugin and emit “Data” or visit the Specs site and follow the simple steps to generate specs for your library.

Authored specs

Figma can’t express every intent you have for a component. Therefore, it’s inevitable that generated outputs are paired with authored content to describe what’s left. Designers I work with don’t use Figma to express behaviors or accessibility. Additionally, Figma can’t express advanced layout and configurations like discriminated unions and other prop relationships.

Therefore, teams augment generated specs with authored supplemental requirements also stored in the specifications repo. Supplemental requirements can be general to all components (such as the precedence of disabled over read-only) as well as platform- and component-specific, stored in files like configurations.md or card.accessibility.android.md. Downstream agents and scripts find and filter requirements as needed.

Designers use agents and skills to research, analyze generated specs, author requirements, and post pull requests for teammates to review, comment and approve. Requirements are consistently formatted (often with MUST, SHOULD, COULD, …) and skills keep descriptions tight and consistent.

Notwithstanding the considerable Figma motion tools released at Config 2026, designers continue to express motion requirements via a combination of prototypes and supplemental requirements for now.

Foundations

Undoubtedly, design system specs are more than just components. Critically, components are served by foundations that include tokens, fonts, icons, images, and other product marks and assets.

Enterprise design systems build tools to store, publish, and manage these assets. Formats per type per enterprise vary. Sometimes it’s a repository consolidating all of them. Other times, it’s databases built with custom UI front ends to manage icons and theming tokens across countless brands.

While I’m involved in architecting relationships and taxonomies, they are highly variable across clients and worthy of a separate post.

Handling specs from multiple origins

Designers should express intent in whatever tool fits best and specs tools blend and normalize those expressions. These days, I encounter designers expressing intent in both Figma and web-based prototypes.

Imagine designing a date picker first in Figma and product card first in a prototyping kit. If intent starts in different places, the system must support porting that intent from one place to another quickly and precisely. It’s not just about generating specs based on an expression of design intent, but rendering that intent elsewhere too.

As a result, my work is expanding from one edge to four: from Figma to specs (existing), specs to Figma, specs to prototype code, and prototype code to specs.

From Figma to specs

Specs from Figma can be generated now in three ways:

1. Via plugin as designers build and review assets, producing an on-canvas report.

2. Via commands leveraging Figma’s Rest API via command line, Github action or LLM chat. Commands fetch files, scan for components marked READY_FOR_DEV and generate a library’s worth of specs in less than a minute.

3. Via bridge into the Figma file via the plugin UI generating specs based on a current selection.

Great care has been put into how multiple paths produce “byte-equivalent” (identical) specs whether from the Figma Plugin API or Rest API. These APIs are not the same, and thus require development (skills, fixtures, loops and harnesses) to sustain equivalent emission across both.

From specs to Figma

A specs render command leverages a bridge and a cache of system data to build a Figma asset from specs in complete detail: >50 style properties, props, tokens, Figma styles, prop bindings across variants, layout, and slots including default content.

Sure, agents could do this. Yet, inference comes with costs and risks. Specs data is layered and complicated, and imprecision and loss through inference is inevitable. The solitary render script is deterministic, demonstrated through “round trips” (specs to Figma to specs) that prove specs remain byte-identical: no variant, style, element or layout choice is dropped or degraded along the way.

From specs to prototypes

The specs transform command scripts CSS, a TypeScript contract, React component scaffold, and Storybook stories. These leverage Figma authoring conventions for states and component and element-specific roles to generate behaviors beyond what Figma enables designers to author out of the box.

The code isn’t intended for production, although teams could use it as a fast-forwarded starting point to coding work. Nevertheless, the files are evolving to a point suitable as a starting point for an prototyping kit that need not wait for hardened testing or engineering capacity.

From prototypes to specs

A blend of agents and scripts will likely extract data from prototypes into specs.

Early concepts rely on well-scaffolded and organized code that separates “spec worthy” decisions from the platform-specific code specs can’t represent. For example, imagine separate generated.css, extensions.css and overrides.css to relate spec-generated choices to prototype-specific expressions. It’s early days, not everything is simple (particularly the layout tree itself), but results are promising.

These transformations must be lossless, cheap, and fast to scale, regardless of direction or expression surface. Until they are in place and reliable, we can’t pursue the bigger objective: reconciliation and synchronization across surfaces.

Architecting specs

Versions

Specs versions express the evolution of design intent over time. Each version is accompanied by change logs, change sets, and skill-derived release notes. These serve both to validate impact and intent (“Are these the changes we want?”) and communicate to consumers (“What’s different?”).

When specs can be validated against an explicit schema, you remove all doubt about what changes are major/breaking, minor or patch fixes.

• Change or remove <component name>.props.<prop name>? Breaking!

• Add a <component name>.anatomy.<element name>? Minor.

• Bind a different token value to an element in a particular variant? Patch.

I am excited about a future where discussions of “Is this breaking or not?” shift from long, tedious debates relying on subjective taste to immediate, inarguable facts.

Schema

Specs content is delivered within an established schema. This enables us to describe the structure and relationships of all the different intent a system collects. Combining a schema with the content we put in it forms a contract by which any consumer of the specs can build predictably and absorb changes gradually.

For more, read Component Contracts and Schema and browse my Specs’ schema.

Architecture Decision Records (ADRs)

Schema, tools and models are evolved using architectural decision records, or ADRs. These documents record decisions in a format with structured sections:

• metadata

• context

• problem

• alternatives

• decision

• consequences

• other concerns.

Authors use straightforward skills to create, implement, and update ADRs. Once initiated, authors work with LLMs using an ADR as the baseline to evolve. They’ll explore divergent ideas, express examples, challenge assumptions, and quickly converge on a recommendation. From there, teammates can predictably review, comment on and approve the familiar format.

While we started using ADRs to ground the schema first, the approach has expanded to cover wider architecture (design and code conventions and transformations, library and asset relationships, and more). Additionally, authors now commit to visions that organize many ADRs helping teams understand the scope and impact of work often spanning many system parts.

For juicy ADR examples, read layout positioning and sides and corners.

Analysis and monitoring

Specs rich with structured data offers ample opportunity to analyze and monitor how design intent is evolving. Every release, the specs analyze command autogenerates reports that itemize the library’s tokens and styling usage, props models, dependencies and “keys” (naming is hard for props and layers/elements). Each report pivots spec data to many perspectives, answering questions like:

• Where is the text-tertiary token used across components and elements?

• How do options available for state vary across components?

• If I change the API of the icon component, what components are impacted?

No agent needs to call a library via MCP, extract and pivot the data themselves. Most questions are directly answered by the data on offer. Adding and generating more reports is extremely cheap, and 5-10 more are already on the docket.

Consuming specs

Once specs is populated with well-structured content, our downstream engineering partners consume it with ease.

From specs to code

Specs are consumed to build component code across platforms like React, iOS and Android. My engineer teammates are architecting and building subsystems:

• Cross-platform factories that transform specs data and compare to existing code for things like CSS, contracts, and React TSX

• Per-platform skills and workflows where humans and agents polish the components to completion together, grounded in specs data

• Cross-platform learning capabilities to identify gaps, weaknesses and areas of improvement, including specs

• Testing capabilities automate spec data like variants, content and examples to ease designer review and quicken validation passes

From code to specs and design

Engineers express design intent, too. As they work, they’ll evolve and extend API, identify and resolve accessibility issues, and fill behavior gaps designers hadn’t considered. That’s design work, just not done by a designer. Some choices already filter upstream into requirements that designers see and approve.

That work pushes how specs schema models sophisticated prop patterns, composition, behaviors and accessibility. My hope is that engineers “downstream” engage more and originate intent upstream, not just via requirements but also during planning and design.

Additionally, requests flow upstream from factories, workflows and learnings. These require changes across the ecosystem: schema, transformers, supplemental requirements and how components are built in Figma. I enjoy serving as trafficer, routing tickets to teammates and rapidly resolving them myself. The trafficer roles helps me see the system’s stability and where we can improve. Some parts hum along, others bend but stick together, and a few leak in ways smaller by the day.

From specs to docs? Some, but not much

Undoubtedly, specs inform docs but not so much so far . Specs are a record of names and change. Yet, prop tables and “how to use” React, iOS and Android originate more appropriately from coded implementations. Exhibit artwork remains generated from Figma assets.

Specs are far more about how to make the components well. The other content – how to use components – is really a separate enterprise driven by a partner team.

Where do we go from here?

Teams commit to supporting surfaces like Figma and prototypes for design, React, Android and iOS from development. These choices guide our focus and priority in optimizing how specs threads through each.

Yet, open questions remain:

• Is there a future where designers express intent in prototypes but not Figma?

• Will we reach a point where design intent can be transpiled across code implementations such that “designer” surfaces cease being valuable?

• Can one code implementation serve as the predominant reference implementation other platforms derive from, or will all implementations remain peers to synchronize? Most but not all teams I work with would likely name their “most important” web-based implementation as their reference design.

• Will AI just do it? 🤷🏻‍♂️

On that last point, maybe in a way I can’t visualize today. I believe our tools and systems must make our design intent visible, manageable, and verifiable. We need to make decisions, see their impact, and evolve our systems with intent.

Models to define components as data are spawning across our industry. Markdown formats are proliferating. Schema models like my Specs plugin and command’s schema and PJ Onori’s Design System Doc spec are emerging. TJ Pitre, Christine Vallaure, and Christian Morales Achiardi are diving into contracts. Perspectives abound, solving distinct and sometimes overlapping problems in similar ways.

These artifacts record UI component decisions that humans and machines read to build a component. Builders interrogate a detail and decide “What should this implementation do about it?” System designers change specs and communicate to builders to revise what’s made. In my role as a system architect, I’m responsible for “shaping specs,” evolving the model of how specs express design intent.

A library of 25 components used to change once or twice a year. Now systems span hundreds of components across libraries and platforms. Any given change lands on a spec’s shape, content, tooling or the many implementations that depend on it — sometimes all at once. The impact is wide, and widens daily. I’ve spent the past 18 months building schema and tools that describe component design as contracts, largely because we couldn’t handle change any other way.

This post describes conveying the design intent of a UI component as a contract and how that contract can be modeled as a schema. It then follows with facets of good contracts – well-typed, normalized, independent, verifiable, deterministic, efficient and evolvable – I’ve embraced as principles to guide work.

The Contract

A UI component contract is an artifact that centralizes design intent in one place so that it can be implemented, verified and evolved across implementations. For example, an intent for button size resolves into a contract of “The button can be one of three sizes (medium by default, or small or large), with styles varying as…”.

Teams are leveraging AI to increase the formality with which they store, change, and communicate component specs as contracts. A published component spec serving as a contract declares intent formally in a way implementers can rely on. Literally, as data to consume, build upon, and verify against. There’s often a specifications repository with component contracts, published with the changelogs and release notes to derive and build what’s changed.

As a contract, a component spec isn’t just about recording truth. Instead, a contract arbitrates interpreting truth across each implementing party. In a multi-platform design system, React, iOS, Android, Web Components and – yes – even Figma are all parties to that contract. As a multi-party agreement, no platform owns it and each platform is meant to sign and abide by it through its implementation.

Without a contract and infrastructure around it, the system’s promise of consistency, quality and pace rests on human vigilance. Humans on teams I work with have no time for that anymore, as expectations have changed.

So, contracts have replaced meetings with automated and verifiable communication and checks. Before, delivering a component would require a handoff meeting per platform team. Now we’re mass-delivering an entire library’s spec from Figma with a single, repeatable command. Designers simply mark a component READY_FOR_DEV, conduct an agentic pass to compose the behaviors and accessibility Figma can’t, and field occasional Slack threads to clarify requirements as needed.

The Schema, Shaping the Contract

Less formal component specs may represent decisions in a file with templated sections, such as a markdown file with tables for Layout, Props and Anatomy. Markdown components specs have spread for a reason: anyone can author it, PR tools can review it, agents can read and write it, and no tooling is needed to adopt it. Yet, markdown is loosely structured and not structurally validated, leaving it weak to arbitration and verification. Contracts should be formal and strict, and developing a schema for a contract is a way to do so.

A schema is the model a contract is written in. It defines what and how to define a component while deliberately saying nothing about any component in particular. The schema is the structure: a model of types, hierarchies, and relationships that express the system’s elements and relationships explicitly.

I’ve spent the last 18 months modeling a component contract into Specs schema. In the button example above, the schema models decisions in a grammar. A Component has Props, including an EnumProp with a name (like size) and enum options, each a string (like large and small), one of which is the default (like medium). A UI component schema is a meta system one level deeper: an abstraction of component decisions shaped into a model.

The spec’s content (there’s a Button with a size prop) is versioned, and the schema model (a Component has Props such as an EnumProp) is versioned too, separately. Implementing a component’s contract depends on both. It’s this model that makes a component contract being “wrong” both computable and inarguable.

The more rigorous the contract and schema, the more deterministic transformation (to CSS, stories, TypeScript contracts, scaffolds, etc) can become boring infrastructure, too. With a strong contract, component production is supported by scripts that generate 80-90% of the code you need before agents get to work. This leaves agentic inference for last strides, not foundation-up construction, and also isolates what you’ve generated when things change.

What makes a good contract and schema?

1. Favor well-typed over loosely formed

A type declares what kind of value is legal in a given position: a number, a true/false, or one choice from a fixed list — an enum. A well-typed contract makes it impossible to write malformed things.

props:
  size:
    type: string
    enum:
      - small
      - medium
      - large
    default: medium

A size enum reduces any possible size to three legal choices. In a loosely formed document, every value is just text, and text accepts anything, such as size:med or size: kind of large.

An Element is included in a Variant and is bound to Styles like backgroundColor and itemSpacing (if a container) or textColor (as a themed token) and typography.fontSize (if text). All of these types and relationships are explicitly structured. No text element should have a backgroundColor, and no container should ever have a glyph name.

Additionally, contracts are too loosely formed when signals are left to implicit naming conventions. For example, a markdown file might encode states implicitly in token or variant names like button-primary, button-primary-hover, and button-primary-active. An agentic pass usually figures it out, but the contract can’t verify and hold every implementation accountable.

2. Favor normalized over redundant

Good contracts state each decision once. My favorite example remains the button’s disabled state. A contract need only state this as a configuration variant, specifying an opacity of the root element once.

button:
  variants:
    - configurations:
        disabled: true
      elements:
        root:
          opacity: 0.36

Yet a Figma button with 96 variants requires 96 more variants, each carrying the varied opacity property. This exposes Figma’s verbose data model as an imperfect contract. That’s massive redundancy – maybe 500ish layers – for one simple intent.

Contracts are bad when you state the same decision twice, in different positions or contexts. A self-contradicting artifact cannot arbitrate anything. For example, a markdown file describing colors like text-primary (#21272A) in a prose description and text-primary: “#1A1C1E” in a YAML inventory is redundant. This de-normalization isn’t an accident; it’s an intentional, documented format that risks drift intrinsically.

Be wary of contracts positioned as a “single source of truth” that then encode decisions in multiple locations. I think to myself, “Is this declaration here the source, or is that declaration there the source?” Nobody knows.

The moment a decision lives in two places, the contract risks disagreeing with itself. A spec architect could write rules into skills to prevent drift. Yet guarding against conflicts of intentional redundancies is wrong; avoid the redundancy in the first place.

3. Favor independent over platform biased

A good contract minimizes the bias of its shape away from any predominant platform, whether Figma, CSS, iOS, Android. A definition extracted untransformed from one party’s point-of-view (like a Figma file) is testimony, not a contract.

It’s challenging to model schema when you spend as much time as I do extracting intent from Figma. Figma’s biased point-of-view is evident in ways glaring (like prop types of INSTANCE_SWAP) or subtle (like absolute positioning anchored in constraints rather than edges). Grounding contracts in Figma-only types is wrong, since Figma’s model is an approximation relative to web, iOS and Android code.

As I’ve been modeling Specs schema, I’ve spent considerable effort bringing spec data to be more platform neutral. Example cases include:

• The “Sides” of padding, strokeWeight and absolutely positioned elements as start and end rather than the familiar left and right (Sides ADR) and constraints (Positioning ADR). In each case, Figma’s model is weaker as a contract.

• Mass-transforming Figma TEXT props from string to number when default values match specific numeric formats (Numbers ADR). Here, Figma’s model is incomplete, requiring us to concede the risk of misclassification to correctly re-type props en-masse based on a heuristic.

Avoiding bias is hard. My Specs’ layout echoes Figma’s layer hierarchy. Admittedly, all code platforms diverge and achieving a deterministically transformable hierarchy across platforms is a fool’s errand (or, at least for now, not a priority). So, I’ll cull unintentional leaks over time. Other times, we’ll simply override Figma generated outputs with authored versions, such as declaring more sophisticated component props because Figma’s limited prop types lack the needed expressiveness.

Critics could also point to Specs’ Variants structure and cry foul. The bias is right there in the name – Variants! – encoded as a type (Variants, Variant) and the variants.yaml file output by the generator. Yet, reading further exposes schema’s layered, compact data model, which is far closer to web’s CSS. So bias may remain by name (towards Figma) and model (towards web). Yet the concept has proven very suitable across all implementations. We’re sticking with it.

4. Favor verifiable over readable

Verifiable contracts can be evaluated and decided as right or wrong by a machine, without human intervention. Two questions, two levels: is this a validly structured spec, and is it precisely implemented? A verifiable contract can reject a definition that references a dependency that doesn’t exist, sets a property the schema doesn’t support, or names an icon glyph the library doesn’t ship. Reading a markdown file answers none of that.

Markdown readers are built to tolerate ambiguity. Unknown token name? Accept it. Unknown component property describing this variant? Maybe fire a warning. A format where nothing is invalid is a format where nothing is verifiable. A linter can still check WCAG contrast or a broken link. However, when malformed isn’t defined, a reader is left to guess or hunt.

I am uncomfortable with spec prose describing types of decisions that frequently recur when they can be more strictly modeled. When prose like “Depth is achieved through tonal layers rather than heavy shadows” is load bearing, I’m lost. What makes a shadow heavy? What makes a layer tonal? What are the tones? When I can’t verify something, I want to delete it. And if deleting that sentence changes the contract, that sentence was bearing too much load. That’s not the contract I want.

A validated extract isn’t strict if downstream recipients consume a markdown file that an LLM already smoothed and elaborated. The verification data got stuck at the boundary and every consumer downstream is inferring from inference.

5. Favor determinism over inference

Determinism means the same input produces the same output, every time. Generate the spec twice with nothing changed, and your diff should be empty – no reordered keys, no noise. I change a textTruncation property buried deep in a text layer in a variant combining three props, regenerate, and that admittedly esoteric intent appears as a single additive change.

In 2026, solely markdown formats serving as “THE System” – foundational context to guide agents making decisions – makes me nervous. Even when a workflow extracts data deterministically to start, agents layering intent through skills and rules inject uncertainty early and invisibly. Errors are introduced upstream before becoming spec, propagate wider and harden right when we thought we were recording truth.

Transformations are necessary, such as overlaying subcomponents, icon glyphs, and states onto Figma’s model using naming conventions. Reading them back out takes real logic, but it’s achievable, maintainable and based on conventions set by system architects. That’s my line: inference I configure, not inference I hope for. We know what comes out based on what goes in, it’s mechanical, and it takes seconds.

6. Favor efficiency over expense to keep true

Efficiency means the cost of bringing the contract current is close to zero – in time, in tokens, and in human attention. Not the cost of building it, the cost of keeping it true. Once built, we used to change a component infrequently. Now we want to adjust and evolve constantly – a minor tweak, new element, added configuration, fixed defect – because we can. Every tweak comes with a bill, and nobody likes to be kept waiting.

The more deterministic the infrastructure, the more the marginal cost of regeneration converges on zero. That matters, because a contract too costly to maintain will rot. A rotted contract is worse than no contract at all, because people trust contracts. If you’ve got 25 simple components on one platform, this doesn’t matter and you shouldn’t spend on it. But if your vision is updating 100+ components across 4 implementations changing weekly? Economics decides the architecture for you.

Using Specs’ command line tools to (re)fetch and (re)generate has made this possible for clients. Want to update backgroundColor for an active, selected, tertiary variant? Go ahead. Regenerating specs will pick up the change, whether we run it next sprint, tomorrow, or the moment a watcher notices the Figma library file’s main branch moved.

7. Favor evolvable over simply flexible

Strict doesn’t mean static. A contract that can’t change dies, and a contract that changes without governance was never actually a contract. Is there a record of why the contract is shaped the way it is, and how that shape changed over time?

I recently integrated a new contract feature: images. The feature impacted many components and spread across the schema’s surface: a component’s API (a new image prop type), styles bindings (via a backgroundImage property), examples and even storage.

I could have just winged it, adding notes to markdown files of impacted components. Yet, that’s evolving the contract privately, in a manner undetectable downstream without reading the entire contract from scratch every time. This is “flexibility” masquerading as evolvability, which is like branding drift with a more favorable descriptor.

Architectural decision records (ADRs) are the machinery to evolve component specs. The images ADR sprawled, but the breadth fostered iteration and alignment with teammates. Decisions in ADRs drive new schema versions, keep specs valid, and communicate downstream to consumers who see exactly what’s changed and opt in when ready.

My downstream partners pushed back on the images update, if only because their tools include deterministic scripts that weren’t ready. Delaying the next generating pass for a week is a welcome outcome. It reinforced that conversations had shifted from complicated interpretations to simple coordination. For everybody, the change felt more like business-as-usual than a threat to stability.

Settling on the correct form(s) of component contracts will take time. JSON schema took two decades. The W3C design tokens community group needed a full decade after tokens hit the scene. Formats will continue to spawn and refine. They’ll also solve different problems for different systems.

Heck, my own work has come so far that I look back unamused with how much less effective my schema was this time last year. Sometimes Figma bias still leaks through and other gaps reveal themselves. So I push on, one ADR and tooling update after another.

Can you point implementing teams at a contract, change its content and its model over time, and regenerate it so they consume it cost-effectively as needed? If you are delivering specs manually or via a contract with less structure, skeptically critique your setup to identify where and how you can do better. For some, markdown may be all you need. For others, the journey continues somewhere more structured.

The empty card. Drop it on a canvas and it stares back: unopinionated, empty, waiting for instruction.

In composable component catalogs, it’s common for assets like a Card to either offer a default scaffold of simplistic content or – when there’s no predominant default – nothing at all. The starting point leaves an author tremendous flexibility, but uncertainty too. What am I to do with this? What am I permitted to do with this? What’s possible with this?

Crafting the best UI component isn’t just authoring configurable props and varying visual style and layout. System designers should also express a component’s composable potential and intended use. Those downstream depend on examples: designers see range and start fast, system engineers get pre-validated, on-foundation starting points, and AI gets a corpus encoding patterns, rules and guidance.

Which components actually need examples? It’s definitely not all of them, but it’s more than you think. Sure, the Card, Modal and Sheets of your system intend to provide a composable body and even customizable headers and footers within. These shells benefit greatly from examples. Other components like Rows in feeds and e-commerce tightly orchestrate visuals, content and actions. Even configurable atomics like Pill and Button – used at high volume and customized very infrequently – may require a composition from time to time.

This post describes what examples are, where they fit, why they matter, how they demonstrate a range of composable possibilities, legible to both humans and AI alike.

About Examples

Ready-made examples build upon the configurable component asset that all catalogs start with. They are additive, built beside the configurable asset to represent the component’s potential distinct from what otherwise could become a sprawling matrix of brittle variants. Composing examples redirects teams to spend time to demonstrate possibility rather than engineering yet another multitude of variants to achieve a single requirement. It answers what can I make with this as an improved well crafted starting point that people can duplicate and take from there.

Design systems have been crafting ready-made examples for years, as demonstrated by Atlassian’s Figma library published on the Figma community. Examples are often positioned to the right of the component set and parts as one of often many other authored outputs (such as specs and change history). While historically also possibly in a sticker sheet on another page or even in another file, most teams today position these directly adjacent to the component asset itself.

The craft that makes a component quality clear to a designer is the same that makes it legible to a machine. Props aren’t enough. Ready-made examples are not variants that show up as a configurable surface. Those props represented as a Figma variant grid or Storybook stories represent what’s built into the component. Composition goes wider, and examples take us there.

Component test cases pressure test a component, but lack nuance and intent. As configured alternatives, they’ll miss the real thing: composed arrangements, real content, custom binding and styles that bring a component to life. Examples bring humans and machines out of the narrow, configurable essence towards how components fit together to solve problems.

Slot Default Content is an Example, Too

Now that Figma has enabled slots, examples take on an extended importance. Component assets can now include example slot content as a customizable scaffold directly in the asset itself. Make no mistake: this content is NOT part of the component’s configurable contract. Nevertheless, a slot’s default content expands how system designers convey intent and provide a starting point to be extended and overridden.

Default slot content also challenges system designers to assess the component’s configurable boundary. What elements should only be configured? What elements are suitably composed in a slot? When the latter, to achieve what kinds of result? Formalizing examples – including the content scaffolded within an asset’s slot – enables system practitioners to illustrate both configurations and compositions beside and within assets.

Examples Illustrate Common Customization

“Simple, atomic” components like button may warrant only one or two examples, such as with a counter or loading spinner. Having a composed example sends a signal: it’s OK to customize when the time is right. From there, ready made examples provide the place to demonstrate a range of component concerns across many axes.

The Alert component demonstrates a widening array of shifts. Variants capture changes in icon and color per configuration and examples broaden the story

When using this Alert, it’s ok to…

• insert elements like badge, dismiss button, o drawer

• customize style of elements like text to increase a font size or a frame to create additional emphasis or space

• rearrange layout, like vertical or horizontal direction of elements and areas

• exhibit what elements are essential elements, like a title or description or both

So look at a component with a different lens: how might its elements, styles, and layout shift in ways that configurable props don’t – and shouldn’t – control?

Examples Data Consumed Downstream

Example data fidelity matters: screenshots may be good, code may be better, but well modeled component data is best. As examples proliferate, we’re building mechanics to capture these examples and project them through the rest of the pipeline. Generating examples as data from Figma can be useful for generating many outputs. The same Card example renders the React doc page, seeds a Storybook story, and answers a Cursor prompt for a pricing card.

As such, I’ve integrated `examples` into my Specs plugin and Specs CLI framework as a first class component output alongside `api` (props and elements) and styling rich `variants` (default and variant-based shifts in styling, layout and bindings). This positions examples in the same flow as handing off design: author examples (today, in Figma), generate the data, use for downstream applications over and over.

Two new data shapes are emitted:

• instanceExamples, corresponding to the ready-made instances of the component assets matching particular naming patterns and/or parents in the Figma page (like a frame or section named “Examples”)

• slotContentExamples for each slot composition of content referenced in an instanceExample or embedded as default slot content in the component assets

For now, we’re limited to using the instance layer name to connote a basic description and we’ll experiment with how to layer in guidance (do/don’t, must/should/could/avoid/never, etc.) as relevant.

Example Intent and Guidance

In the case of a Row component, the subtle shifts of structure and styling are evident across this gallery of seemingly similar variants. When you look closely, it’s clear that capturing all of these shifts as configurations is a fool’s errand.

All three areas – visuals, text, and actions – are wildly divergent.

• Visuals may be square or round, image or avatar, and include or exclude a highlighting border.

• Text may include two or three lines, strategically included links and actions, formatted and highly structured data, and even a child highlight box (and that, with an image too!).

• Actions may include buttons or icon buttons, horizontal versus vertical displays, menus, one or many. Even the right corner can include plain text too!

So as you craft examples, you’ll focus on expressing:

• Structure of elements and layout that composition extends and bends

• Style, favoring formal, semantic tokens over hardcoded hexes and cheap, one-off spacer frames

• Content expressed as real data or structured labels like {Title} and {Description} that carry sufficient intent within clear boundaries that’s easy to swap. You’ll be the judge to leverage just enough specificity – such as {Vacation package title} – in examples to carry the intent needed to make evident your context, flexibility and intent.

There’s just too much to control in any of those spaces. Examples, not component properties or component set variants, can be a place to record variation and guidance.

Where Examples Can Break Down

A place to author examples carries a certain gravity. Yet, System practitioners should remain cautious. You don’t want to slide towards challenges of composition ownership and maintenance.

Once people perceive the system as the place to store some compositions, they may perceive that it’s the place to store and govern all compositions. That is the wrong signal. Instead, you’re demonstrating potential, not an exhaustive catalogue. You also aren’t demonstrating limits, constraints, or final decisions around how to compose in a certain space. Just because you see rows depicted in this way in this location doesn’t mean that a new idea about a new row format isn’t suitable or can’t be done.

Additionally, more examples means a widened surface area of assets for the system to maintain. Examples help us compose customized style and rearrange elements in interesting ways. But those decisions can grow stale. As tokens and nested components change, so too must the examples that leverage them. As with all system assets, balance is needed.

Yet, tooling like Specs CLI addresses the hard part. Examples are real instances that inherit token and component changes. Rerunning generators, linters and other tools as your versions change catch and often enable quick, direct resolution to limit the challenge altogether.

Examples help us move past thinking of components as independent and narrow, configurable objects. Instead, they move us towards a language of space and structure and composition that can be machine readable. The composer’s freedom and potential is supported with a map with new types of reference points: drawn in Figma, carried as data, read by everyone and sustained as a growing corpus over time.

When I watch an AI agent spend four minutes crawling a Figma file to answer a question I already knew the answer to, I get impatient. I get frustrated. Not because I’d memorized it — because the answer is computable. The agent was reading 45 variants, one by one, not even trying to infer which properties change across states. C’mon isn’t even an inference problem! It should be a diff!

To date we’ve worked like this: an engineer is assigned a component, opens a connection to a Figma file, pokes around, learns structure, infers decisions, and writes code. MCP is genuinely useful and fits this workflow well. It’s human-paced exploration now with an AI turboboost.

Yet, design system teams face two kinds of decisions. The hard kind — which components belong in the library, how to structure variant hierarchies, polishing up design intent, when to compose versus configure — require judgment, context, and experience. Our workflows necessarily involve inspection and reflection, inference and decision making. MCP tools help with that. Crafting code from Figma’s (partial) rendering of our intent can be similarly nuanced, and there are moments MCP can help there too.

But that moment in between – what we’ve called “handoff” that extracts a Button’s anatomy from 45 variants, diffs states, resolves token references — has no ambiguity at all. It’s mechanical, known, deterministic. The answers are in the data. And today’s agents seem happy to dawdle and lollygag around all that data over and over over, tokens be damned.

I see teams shaping a different model for tomorrow. Coding agents take a spec and generate types, structure, styling, behaviors, and accessibility in parallel, governed by rules and skills. Humans review this at gates rather than doing discovery themselves. As components change, the work is knowing what’s different and changing just that. That pipeline needs a pre-computed, durable, and comparable artifact.

I built a tool to generate specs mechanically, and design systems of enterprise scale are using this as a primary Figma-to-code input to agentically generate code. Sure, making decisions downstream remains the hard part. But extracting complete and compact specs from Figma should be a blazingly fast, repeatable activity. This post describes the problems I see, how to think mechanically about specs, the command line tool I built that my teams use, and examples of why it matters.

The Problem:
Raw Figma Data Is the Wrong Starting Point

However you get it — MCP, REST API, plugin — raw Figma data has limitations when thrown to AI to generate components at scale.

Figma data is expensive and ephemeral

MCP fetches and processes vast payloads every time, throwing countless tokens to take it through its paces. Nothing persists. The work is disposable. The chat ends, the data dies, the memory largely flushed as attention diverts elsewhere.

Figma data is a noisy dumping ground

Data isn’t incomplete, it’s overloaded. 26,901 properties when you need ~350. Signal-to-noise ratio is abysmal. Plus, you get 45 full variant copies when what matters is 15 subtle differences between them, organized by simple rules that trigger each.

Figma data isn’t clean

Even library files have inconsistent naming, orphaned variants, dead variables, and experimental components mixed in. It’s messy in there. But that’s the job of the systems designer to clean that up, and MCP tools help to clean that up. It’s just that handoff isn’t the time to expose that. Just because we are using AI doesn’t mean letting our guard down.

Figma data is unprocessed

The raw data speaks Figma’s language: opaque IDs (5641:6912), float RGBA wrapped in solids, gradients and effects when a style already mapped to your design token will do. Hash-suffixed property names (Label#3813:0) when a prop binding reference can be set cleanly.

Figma favors Figma

Figma’s data model is Figma’s, not your platform’s. Figma says paddingLeft — but iOS needs .padding(.leading) and CSS needs padding-inline-start. Figma treats an icon glyph as a nested component instance, while code typically references SVG assets you color. Figma lacks a native model for ARIA roles and screen reader labels, but your components ship with each. A cross-platform spec needs to be neutral ground, not one tool’s more limited view. Your pipeline speaks token references using your formats, clean prop names, semantic anatomy.

Something somewhere has to translate. AI should be reading, not writing, these specs from Figma. As it turns out, all this requires is a scriptable algorithm.

The Right Tool for the Job:
Mechanical Transformation

Figma’s data model is stable, incomplete and evolving slowly. Surely you’ll have “unstructured” and “less structured” specs to describe behaviors, motion, accessibility and more. But what it does cover, it covers cleanly.

Therefore, you can build tools to derive rules-based decisions from variant data using a dependable and durable algorithm. I want my design intent in an artifact that’s:

• complete, such that every property of every layer of every variant is examined meticulously and every decision that matters is recorded

• compact, compressing data from MB to KB to remove 99% of the noise

• precise, with differences across variants reduced to simple, layered rules

• translated into a more platform-neutral language and using token, data, and file formats that work for you

• versioned so that as you evolve, it detects what’s changed since last time

• human-readable, that designers can scan and see intent, details and mistakes

Specs must yield the same output given the same input, every time deterministically. This class of problem demands speed, not inference and improvisation. Never rely on a predictive model when you can count something directly. At this step in the process, you can count everything. If you can transform what is known faster, completely, precisely and far more compactly, then computation should win. Every time.

specs-cli:
Commands To Generate Your Specs For You

The specs-cli available at https://github.com/DirectedEdges/specs requires four terminal commands. The two main commands – fetch and generate run cleanly and quickly in ~30 seconds per library each time you need specs. The other two are one-time setup tasks that take a few minutes and are covered in getting started docs — or you can paste a single line into Claude Code and let Claude walk you through it.

## Install from npm
npm install -g @directededges/specs-cli

## Initialize and configure an environment (~1-2 min, one time)
specs init

## Fetch the Figma library file (5-15 seconds)
specs fetch

## Find and select components to generate (~1-2 min, one time)
specs scan

## Generates specs for an entire library file (10-30 seconds)
specs generate

In a few minutes, you have an entire, well-organized, compact specification of all the relevant design decisions you’ve put into an entire library. Need to refresh library data? Run fetch then generate again in less than a minute. Need to compare it against the last run? Ask AI, use Git to discern your changelog, or wait for tools I intend to build soon. Want to run it every week, day or hour using a Github action? Sure, however often you want.

Could AI do all this for you? Sure, but it’d take so so much longer, require so many tokens, and probably hallucinate in ways you can’t detect. Why do that?

Examples: A Disabled Button and Action List with Subcomponents

The proof? Imagine a button with 45 variations, 9 of which are disabled. The raw Figma data is 1.38MB large, 42,000+ lines of JSON comprising 280 nodes and their 26,000+ properties.

Process this with the specs-cli, and in about 1 second, and you are left with 10 KB, 442 lines, 4 anatomy elements and 15 configurations that yield rules with design decisions. It’s 99.25% less data, 134:1 compression into a well-organized schema.

That spec is semantic anatomy, clean prop names, token references, diff-based variants, invalid variant analysis, structured metadata, and platform-neutral directions. Along the way, it discards bounding boxes, transforms, geometry paths, opaque IDs, duplicate variant copies, paint object wrappers, useless and exceedingly redundant information.

AI doesn’t need 80 nodes with 30+ properties each when your design intent is “When the button is disabled, make the root layer 0.36 opacity.” A simple rule will suffice. And humans can read it too. Not that designers want to spend their time reading YAML. Yet, acclimating to the structure and scanning it quickly can yield small corrections to unexpected misses that polish the delivery.

Do you think the Button example flatters this approach, but remain unconvinced? More complicated components with a bevy of subcomponents result in **even more** compression. The Action List, with its subcomponents for items, headers, groups and group headers, resulted in a 2.6MB → 14KB (188:1 compression, 99.47% reduction), and yet included even more that Figma doesn’t like conditional visibility, code only props and invalid combination mappings.

Where was AI this time? At most, running your commands, although you can do this without AI and use zero tokens. AI belongs in this pipeline: *downstream*, not necessarily to generate specs. A mechanical engine can produces a durable, precise artifact; AI agents can consume it to generate code, answer questions, build components.

Extending and Moving Beyond Components

There are clear places where the specs tools will need to grow in the short term. Capturing slot content and instance examples is imminent. VPs are demanding refined motion and behaviors, yet nobody uses Figma for that. From there, questions about how to capture and relate deeper behavior (usually reserved for code) and accessibility persist.

At the same time, the tools are already in use at clients, and more than one see git versioning as insufficient. I would anticipate building in versioning capabilities that include automated changesets, changelogs and classification of major, minor and patch changes.

Leadership, however, has already moved their attention to other things. Components seem like well understood territory, but AI’s pattern recognition and speed of automation has them clearly desiring to go up the chain to layout patterns, scaffolds, and full page compositions. Not just what they are but also when to use and relate and compose each one. I cannot imagine how fast these things will change or look in months let alone years.

Figma’s native slots promise a more flexible and easily composable future for design libraries. System owners are eager to transform their components, often with the expectation of a simple, one-to-one swap of existing slot utility instances for the new slot layers.

“I can’t wait. Our components will be delightfully easier to use.” True

“Figma’s native slot layers are simple to set up.” Also true.

“Just swap slot utilities for slot layers!” Hold up a minute. That’s not quite right.

A transition to native slots should reach further than replacing your slot utility asset. Migrating to Figma’s slots should force system architects to critically look at how components are composed and customized.

This post describes the journey of implementing native slots in a Figma library, from discovery with exploration through deciding your patterns and implementing them across the catalog.

Discovery

Don’t expect to just open a Figma library branch, rapidly change a bunch of components and hit publish. Migrating a library to slots with deliberate care can be informed by discovery activities like a library audit, research, and synthesis to identify patterns.

Audit

Start by auditing your existing Figma assets. Begin with already-composable components that may include slot utility instances, but don’t stop there. My audit included any component or subcomponent asset, and I catalogued each component with:

• Name, like Button or Pill / Start Visual.

• Role in the composition, such as Root / the “Main Component” versus its Header, Body, Footer, Actions, Start Element, End Element, or Other purpose

• Slot utility?, indicating if it has a slot utility bound to an instance swap prop.

• Slot utility as variant option?, if the slot utility is available in some variants but not others. For example, a Content prop with options for Icon, Mark, Avatar, and Slot option (that shows a slot utility).

• Composable nested instances?, if any nested instance had a slot utility in it. For example, a Button that has an End Visual with a slot utility option.

• Props (all types) to determine which variant, text, and boolean configurations will be kept, changed or removed.

I found myself sorting component props that I expected to keep versus those to consider more deeply or expect to remove (at least some instance swap props, obviously!).

In hindsight, I would structure the data I collected (and the decisions to come) in the format of this Slots Audit Google Sheet. It boils down what can feel like myriad different cases and examples into the kinds of patterns and decisions to plan around.

Comparative research

The migration’s intended to balance incorporating legacy code patterns with adopting a modern, composable shape. While working through Figma assets, I also researched both:

• Compare against and align with existing code implementations, across platforms as needed and ideally via LLM prompts and agents

• Gain inspiration from public libraries with strong compositional qualities, like Github Primer and MUI React.

Exploration

Before making decisions, I dug in and experimented with many approaches within and across components. I varied many aspected of the architecture like where props were exposed, where elements were included, how content was available by default, and how to name each slot. This led to an array of working examples to workshop with the team.

I prepared a Figma file with sections per pattern, establishing dedicated zones for:

• Examples established the pattern’s relevance. For example, the Group and repeating items pattern included Checkbox Group, Tabs, Radio Buttons, Breadcrumbs, Action List and Avatar Group. I annotated each likely slot area in magenta.

• Alternatives distinguished choices around component hierarchy, layer structure, props, slot layer depth, and slot default content.

In the periphery, I tracked:

• Open questions in the form of voting dots and rationale.

• Architecture decisions addressing conventions of slots, props and layout. If I felt strongly, I recommended a decision as a starting point.

This enabled me to learn by building and thinking through how to communicate distinctions per slot model. As we worked through options and examples, we riffed and made decisions.

Decisions

It may feel like you are just working through components (Checkbox Group, Card, Button), but the reality is that you are defining rules and standards to apply across your entire catalog as core patterns.

The spreadsheet started with the audit serves as a structured way to record and plan implementation of your slot approach, props, and layout as you refactor each and align them with code.

Slot approach

As decisions gave way to patterns, we ultimately decided on an approach. Each component or subcomponent was either EOL’ed (deleted) or kept with a slot architecture of:

• Slot, empty default

• Slot, with default content

• Configuration-first (props bound to layers, but no slot), “Custom” escape hatch (a slot with layers not bound to props)

• Named slot, always visible

• Named slot with visibility prop

• Items slot

• Subcomponent, no slot

• Subcomponent with slot

• No slot

Slot properties

Slot property conventions are straightforward yet require agreement:

• Name of both “default” slots (like children or items) and other named slots if needed

• Default content, whether none, uniform, or varying across variants

• Permissiveness, whether closed (to a strict set of anyOf children) or open (to set preferred values) as well as minItems and maxItems as relevant.

Slot layout

I recommend avoiding setting visual styles of slots like color, corners, and strokes. However, it’s practical to set layout properties like direction, resizing and item spacing and work out with development how those do or don’t impact code implementation.

Prohibit padding on the slot layer. A component should not control the inset of its slot. If internal padding is required, nest the slot within a containing frame and apply padding there.

Empty slot sizing. In cases like Card and Modal, slots could be empty by default. Empty slots will retain a customized fixed height and width if needed. Discuss if and how to set the slot’s default height or width, likely to a typical expected size.

Refactored props and subcomponents

The transition to composable native slots forces a look at every component, both for its own internals as well as its relationships with other components. This leads to refactoring, and I expect slots to result in a configuration collapse described in a recent, separate post. Composition, not configuration, becomes the preferred approach to solve many problems.

Relating design assets and code architecture

In addition, consider a method to distinguish props that are “Figma helpers” that may not belong on a composable component’s code API.

For example, a Custom (false|true) prop that activates the slot for composability, and the bound label, description and visibility props presented to designers by default as the more common configurable case. This separates the bound label, description, and visibility props—presented for the common configurable case—from the asset’s Custom appearances, which define its true, composable API.

In the spreadsheet, I distinguish these using the *. In our tooling, that’s transformed when converting Figma assets to specification data.

Implementation

Equipped with implementation patterns and confident decisions, it’s time to plan and convert a library, from low- to high-order components, one at a time.

Notable characteristics of my implementation plan included:

• One branch per component.

• Convert components of the same pattern (such as groups with repeating items) simultaneously as a batch. That way, you can implement, review, and adjust across branches as decisions evolve.

• Leave more deeply nested component structures for later, like Alert (with its e, Text and Actions) and Action List (with its Item, Start Visual, Text, and End Visual). This offers space to sit with the more complicated architecture for a bit as people adapt to the easier stuff.

• Test slots using ready-made examples built beside the component assets. Early on, they are more test cases than published examples, even if they should represent acceptable cases by the time you publish.

• Pilot and get feedback on many things before publishing all the things.

Equipped with a plan, the conversion is a structured, component-by-component process of applying new conventions to a library that’s robust, tested, and ready for adoption.

Glance at the Props panel of a mature Figma component, and you risk encountering a scrollbar of shame. Countless props fine tuning element visibility (like showIcon) and layout (horizontal or vertical direction). Each solves for a real yet specific case, added with the best of intentions.

Yet together, those “helpful” and enabling props sprawl into a paradox of configurable choice. When component variant counts explode or a simple change breaks an inherited style, it’s not because the design system is flawed—it’s because it’s using the wrong tool. The system further burdens itself to document, test, and maintain more features, locking it in a box of its own making.

A single, rigid component need not solve all things for all people.

Figma’s native slots are coming for your configurable props, and will tear many of them down. System power should come from not switches and variants, but by allowing for creative, unconstrained composition. This will demand a bold act: a configuration collapse to drop props that make components fragile.

This article explores this shift by moving our prop-first mindset to purer composability, with examples of the Pill, Alert and Card.

A Leaner Component Core

Shifting towards composability must leave the component’s identity untouched, retaining only behavioral and foundational visual props—such as state, appearance, and size—as the component’s essential, top-level API.

Yet many other props types and subcomponents are at risk, like:

• Layout props for padding, direction, and resizing are removed.

• Visibility props (Figma BOOLEAN props like showIcon, hideDescription, actionsVisible) declined severely in favor of controlling element presence and visibility via slot composition.

• Visual hack props declined, particularly those impacting single visual choices (e.g., color, corner radius, or border) of a nested layer.

• Subcomponents for varying layout and element structure were eliminated entirely (see the Alert > Body > Text example below).

• Configuration shifts removed complex props (actionsVisible, actionsCount) in favor of a dedicated, simpler subcomponent that’s slotted into the main component with potential constraints.

Decoupled visual styling of composed children (e.g., the text color of a Button Label or a Card Title) is an undesirable but necessary trade-off. These relationships have efficient, effective controls in code, but become the composer’s responsibility in Figma. Use strong, variant-specific defaults and rich examples to mitigate this challenge.

The immediate effect is leaner component APIs. In the long-term, teams and systems across the enterprise can better extend, build around, and build within core components without conflict and delay.

Why Now? AI-Ready Components

Design systems have been built for composability for some time. Systems have been putting the right props at the right levels of the right components. Putting things together feels right… in code. But not in design tools. And certainly not in design tools increasingly manipulated by AI.

Because Figma can compose in components now
So the easy answer is: because designers couldn’t do this before with Figma. Native slots – or more abstractly, composition within a component asset – was too difficult and clunky to replicate, so Figma’s architecture was different.

I think Figma prioritizing building slots in 2025 is neither because slot utility instance swapping sucks (it has for years) nor that slots just happened to be next on the roadmap. I speculate that slots are a priority because machines now compose interfaces and Figma needs customer’s assets ready for the challenge.

Component composition is grammar
In a prop-heavy system, element relationships are implicit and bound to prop combinations that are arbitrary and often quite uncommon. With composition, relationships become explicit: a Pill is composed of an Icon and text Label inside it, each with important yet contextual configurations of their own. This creates structure that AI can read, understand, and generate.

Favor predictable patterns over hyper-configuration
Also, a reduced configurable shape improves predictability. Figma boolean and layout variant props feel arbitrary and don’t cover all possible needs anyway. Instead, systems should supply AI with training data that records relationships in other ways, such as ready-made examples augmented with guidance. Models could perform better with fewer yet higher-confidence patterns rather than spinning on copious, hyper-specific configuration states.

Layer semantics over flexible building blocks
Figma’s slot composition also opens up opportunities to build purpose-driven components (like a ProductCard with opinionated structure and layouts) by wrapping a composable Card container starting point. This more effectively separates concerns, affords extensibility, and improves autonomy.

The takeaway shouldn’t be to “Drop all the props.” Instead, it’s about finding the right balance. It’s still essential to offer the right configurable choices at the right level without necessarily rigidly controlling what’s inside.

Moreso, it’s about tearing away the structural noise from our configurable surface. Now’s the time to put compositional choices in the hands of the composer, scaffolded with starting points and guided by rich examples and context

Examples

Start and End Visuals

Many more atomic components like Pill, Badge, Chip, Tab, Link, and Button have Start and/or End visuals on either side of a label. In the past, to control for a set of expected visual types (like an Icon, Mark, Image or Avatar), we’d use a component or subcomponent variant prop.

With native slots, favor flexibility and ease over control. Nesting text and paired visuals (either hidden or visible by default) in a children slot.

This resulted in a near complete collapse of some component’s props, including:

• All visibility props (Start Visual Visible, End Visual Visible)

• Type variant props

• Padding variants that controlled spacing between a label and visual, omitted in favor of a composer implementing that choice.

Icon is a predominant default visual. Certainly, adding it as a slot “Preferred Value” is a start. However, inserting it results in a likely Icon configuration mismatch. Alternatively, it could be included by slot, whether shown or hidden by default. That way, the Icon can be configured to match the parent state, such as Pill selected‘s impact on Icon‘s appearance.

The need to control was rare but did arise, such as Button / Start Visual. This strongly typed subcomponent reinforced expected use, even if it could be omitted and a different element included just in case.

Body, Text and Actions Layout

As component structure becomes more complicated, varying layouts and included elements become more common. For example, an Alert component may include a Title or Description or both as well as arrange those horizontally or vertically as well as their combination horizontally or vertically with Actions. Sometimes, the entire Alert’s Body may need to be customized.

This can be achieved with subcomponents, each with variants controlling layout directions (at multiple levels) and element visibility. “Most” layouts become configurable. Yet the overwhelmingly most common layout is all elements vertical, and three-level deep subcomponents always felt quite brittle.

Alternatively the elements – both text elements like Title and Description as well as frame containers – could be included in a slot. This scaffolds a starting point with everything you need, enables rapid layout refactoring using the frames equipped with autolayout, removes the need for Body and Text subcomponents altogether. Anchoring on the predominant layout felt liberating.

As a result, subcomponents and their layout, text and visibility props vanished. Instead, the component asset was coupled with a few ready made examples of the alternative layouts. Designers have everything they need to achieve the outcome they want as quickly as before, yet with far more flexibility.

Card

Early Card experimentation focused on common structures – Visual, content layouts, Actions. Depending on the design system, that could result in useful, composable subcomponents that recombine in a few predictable ways.

Not this particular system. The system served divergent experiences spanning 50 brands. There simply was no predominant default, or even common limited collection. Instead, the system would likely require a deep collection of diverse ready-made examples. As a result, for the core library at least, it made sense to hollow out the Card to an unopinionated container.

With a hollowed out container component, that meant the core library deliberately offered no configurable subparts. There’s justification for a composable Card / Visual , but the core team might rather focus on offering an Image component that you can overlay custom content instead. The Card / Actions subcomponent would echo the pattern established by Alert, but actions too were too diverse to normalize. Why bother? Just compose what you need.

The core Card’s unopinionated container is a strategic choice. Less is more. It acts as a maximally flexible foundation without imposing constraints, enabling other teams to build purpose-driven extensions.

A separate team has already begun. They’ve initiated a separate library, signaling a rich array of even more hyper-specific card content subcomponents and zones, layouts and visual expression. The design system will then weave those inspirations in among the broader collection of ready-made examples to guide everyone.

There’s no one shape that’s perfect for everyone. I’m making different judgments for different design systems as I go to get to the goodness-of-fit that works for each case. Onward!

As I talk with design system teams about Figma’s native slots rolling out for early evaluations, conversations invariably start with how a migration will replace Slot utility instances with native slots. I’m pretty quick to point out that “You may not even be using a slot utility for you most common kind of native slot. Have you thought about repeating items?”

This post illustrates many examples of repeating items within a core component library and why it’s been difficult to date to compose them effectively. The solution is Figma’s new native slots, with a more careful architecture of naming, default content, and more granular specs.

Background

Many, many UI components serve as a container for repeating items. This is most common when a component’s purpose is as group containing items, like:

• checkbox in checkboxGroup

• radioButton in radioButtonGroup

• avatar in avatarGroup

• button in buttonGroup

Many components are groups implicitly even if not named that way:

• tab in tabs

• breadcrumb in breadcrumbs

• actionListItem in actionList

• listItems in a list

Repeating items also exist in a component area like actions in an alert, toolbar or dialog. Suffice it to say, a repeating item pattern is pervasive across a component library of any scale. As systems migrate Figma assets to native slots, don’t be surprised when you find that repeating items are the most common composable pattern in a library.

Anti-Patterns

Unfortunately, that’s never been easy to enable in Figma component assets. This led to workarounds like instance swapping, hidden layers, and “count” props.

Instance Swapping: Some systems implement repeating items as an instance swap, even creating a row-based convention of instance swaps-within-instance swaps within which repeating items were placed. No thanks.

• Users find instance swapping ergonomically annoying

• Users had to create a separate component asset to swap in an instance

Hidden Nested Instances: Systems also use hidden layers for extra items, with quantities based on implicit conventions (such as showing ‘x’ layers and hiding ‘y’ layers). Negative outcomes include:

• Users drill deep into component layers to find and manipulate items

• Overridden instance layer visibility and other nested configurations, an antipattern

• Items cannot be reordered

• Additional items cannot be added

• Degraded file performance due many hidden and often complicated layer hierarchies per instance

Quantity Props: Systems add props like Count to control item quantity. For example, systems may implement an enum Count prop to display 1, 2 or 3 actions in an Alert.

This is composition, not configuration. Avoid it given negative outcomes of:

• Variant explosion in component sets

• Handoff friction in handoff to ignore props not a part of the “official API”

• Item configuration conflation into props of a higher-order asset

All of these approaches are hacks to make up for Figma’s historical lack of component asset composability.

Solution

Use Figma native slots to compose repeating items within a component asset and populate the slot’s default content with a reasonable and consistent number of items.

For example, include an items slot in a checkboxGroup with three checkbox instances by default. It’s easy for the user to add, remove, reorder and even quick drag to create a longer list of items.

Pros

• Improved Composability: Slots solve the primary problem: a clean container-child relationship to easily add, remove, and reorder items.

• Low Asset Complexity: This eliminates the need for workarounds like “hidden layers” and “count props,” which improves file performance and reduces implicit conventions.

• Clear API: An items slot is an explicit, native way to define the types and constraints of customizable children.

Cons

• Open, Uncontrolled Children: Figma slots are inherently open. They’ll take anything, no matter what you designate as “preferred.” Therefore, systems must trust users and implement methods to verify design and code.

• Risk of Empty Slots: The user can remove all default items, causing the slot to appear empty.

• More Complicated Definition: Systems must define a more granular slot architecture including naming, constraints and guidance.

You could also assert it requires a learning curve. I wouldn’t agree. All the previous methods were both error prone and harder to use. The simplicity of starting with a composable area with items you need drastically saves time and is directly the interaction users prefer.

Architecture

When adding native slots to library components for repeating patterns, be mindful of details like naming the prop and layer, default content, minimum and maximum quantity, and permitted values.

Naming

In Figma, slots are both a property type (SLOT) and layer type (SlotNode). The names of each are revealed in the Props and Layers panels, respectively. Choosing a conventional name for both improves user understanding and expectations when composing repeating items across a library.

Favor items (purposeful) over children generic). During our refactor to native slots, we narrowed down to considering items versus children, where children had already been chosen generic component slots with no default content. We chose items to carry a narrower purpose that expects specific types of children.

Distinguish items and children. In addition, components with items often have additional elements not included in the slot, such as an avatarGroup’s end count or a checkboxGroup’s header and error message. This, too, distinguishes the repeating items case from corresponding to “all of a component’s children.”

components:
  checkboxGroup:
    elements:
      items:
      header:
      description:
      validation:
    default:
      layout:
        - root
          - headerArea
            - header
            - description
          - items
          - error
            - errorIcon
            - errorMessage

Default items

Generally, three items seems the reasonable convention for most item sets, since three:

• Affords that it’s an indeterminate list more strongly than two or one

• Enables distinguishing a selected item (often the first item) separately from other items in components like tabs and radioButtonGroup.

However, there are cases where two (such as actions in an alert) or other counts make more sense. We’ll document when to diverge from the convention.

Additionally, it’s important to not confuse default slot data with ready-made examples. Sure, a checkboxGroup can have many, many items, and you can depict that in your system’s set of examples. However, that’d prove a very hostile default relative to the far more frequent cases of a few items.

Minimum and maximum item quantity

Unlike generic slots which can be empty, slots for repeating items generally require one or more items. As a result, we’ll define such slots as minItems:1.

Occasionally, an items slot may govern a maximum number of items. For example, an Avatar group may include up to four Avatar components, after which a count to the right of the last item.

If a system chose to include this hard constraint, the avatarGroup would define an items slot as:

components:
  avatarGroup:
    props:
      items:
        type: slot
        anyOf: avatar
        minItems: 1
        maxItems: 4

Permitted vs preferred values

Figma’s slot preferred values match the experience for instance swapping. Undoubtedly, slot properties should associate the single item type (like checkbox within checkboxGroup) as preferred values.

Nevertheless, Figma’s slots are open to accept any child and cannot be formally governed. This relationship is stricter. In specification data, this is represented by a list anyOf items, like:

components:
  checkboxGroup:
    props:
      items:
        type: slot
        anyOf: checkbox
        minItems: 1

We’ll use code only props to identify what items are permitted, minimums and maximums so as to handoff the intent via component data downstream to collaborators and machines.

Figma’s native slots are the new primitive that shifts the burden of complexity from the designer's canvas back to the system’s architecture. By providing an explicit, consistent API for repeating items, systems can move post brittle hacks and offer a cleaner canvas, a simpler property panel, and a more flexible library for everyone.

I’m among those that steward cohesive component API. In designing systems, it’s our job to define and communicate accessibility, behavior and non-visual logic just as much as style and layout.

As we define components, we’ll face intricate questions that shape how components work. Figma hasn’t yet been the place to express all those answers. Yet, what if… we started shaping more of that via props to Figma assets?

This post details a technique for adding “code only props” to Figma components. It covers how these props better connect system designers with their users and system developer counterparts, how to build them into Figma, and ends with examples from simple to controversial to gloriously yet dizzyingly complicated.

Challenges

My work often focuses on a core component library that is built into Figma assets, transformed into spec data and is implemented across iOS, Android, and the web.

Each component’s property shape can be complicated. Figma provides for many prop types: text (primarily for text characters), variant, boolean (for visibility), instance swap and soon slot too. Yet, Figma prop types are nowhere near comprehensive and bias heavily towards visual outcomes rather than broader concerns.

This challenges system designers, who want to:

1. Specify non-visual accessibility and other configurations as a part of defining a system component

2. Maximize API they can shape and deliver into deterministic, automated processes

3. Expose non-visual props that product designers can use to express an intent

4. Clarify relationships of visual and non-visual props

5. Improve how Figma synchronizes with code libraries and other assets

Solution

We began to add Figma TEXT and props and VARIANT props of nested instances that correspond to additional props, housed in a practically hidden “Code only props” layer.

Step 1. Code-only props layer

Add a Code only props layer as a child of the component’s root layer, positioned at (0,0) with width and height of 0.01 and clipping contents.

This virtually hidden layer contains semantically-relevant layers bound to component props that are nonetheless hidden from the visual experience.

Step 2: Nest a layer per prop

Add text and nested instance layers corresponding to each prop.

For example, interactive components like button, link, checkbox and breadcrumbs can include an Accessibility label prop. This property often maps to an internal label like aria-label or an associated <label> tag.

A system designer could bind an Accessibility label property to an Accessibility label text layer within the code only props frame.

A product designer will then see the prop in the Props panel.

In general, the text layer is left visible or hidden (thus suppressing the field from view) depending on whether it’s relevant to a product designer.

Step 3: Integrate into handoff and automations

Handoffs and tools (like generating specification data from assets via tools like my Anova plugin) pick up the prop, adding accessibilityLabel to the versioned contract centrally leveraged to implement and maintain a component across platforms.

components:
  {component name}:
    props:
      ...
      accessibilityLabel:
        type: string

As Figma data is transformed, tools can:

• Infer types based on default values, such as a string (Label), number (0) or enumerated list (such as h1|h2|h3|h4|…), although be careful with that

• Omit the Figma structure irrelevant to generated code, since the code only props layer and its children are metadata, not formal component layout

• Add and bind these layers when generating Figma assets from spec data

Tradeoffs

Sure, props like accessibilityLabel, headingRole, and maxRows are less important to designers exploring design concepts. Tradeoffs include:

• ✅ Improves visibility of component props to product designers

• ✅ Enables system designers to shape more of the component API

• ❌ Complicates Figma assets

• ❌ Adds friction when defining component due to unclear boundaries on which props to include and how to name them (in my opinion, this is productive friction)

Additional Examples

Image src and altText

If building for one platform or even a content management system, it may or may not be valuable for a product designer to specify an altText or src but it could still be relevant for a system designer to convey one or both expected props to a system developer or a pipeline.

To accomplish this, a system designer add both text layers, bind each to a component prop, and hide those irrelevant to product designer activities by hiding the text layer(s).

The product designer would then only see the props they need to, such as only the altText prop.

Spec data would predictably encode both props:

components:
  image:
    props:
      ...
      src:
        type: string
      altText:
        type: string

Now, there are reasons we’d avoid these props in many systems, such as (1) not needing to because they are default HTML attributes or (2) it’s platform specific, running counter to the broader goal of orchestration across platforms. Nevertheless, the example reflects the flexibility of exposing and hiding props.

Heading Semantic Tag and Level

For a prop used to set which HTML tag is rendered in the DOM, the Heading component Figma asset could include a nested instance of an as component with variants for h1|h2|h3|… and so on. While it feels odd to create such utility assets in Figma, it’s actually simple and quick.

The instance with one variant prop then gets transformed into spec data alongside related props like level:

components:
  heading:
    props:
      ...
      as:
        type: string
        enum:
          - h1
          - h2
          - h3
          - h4
        default: h1
        nullable: false
      level:
        enum:
          - 1
          - 2
          - 3
          - 4
          - 5
        default: 1
        nullable: false

In code, this would be used as:

<Heading as=”h3” level=”2”>My Title</Heading>

For teams working across platforms, they’d need to decide whether or not specification data captures platform-specific props like these and whether or not those sync with Figma assets. That said, decades of experience suggests that conversations of separating concerns of as (structure) and level (presentation) aren’t dead yet..

Slot Properties

As we migrate to native slots in Figma, we’re adding additional props to describe slot configurations like anyOf (permitted children), minItems and maxItems.

For the Checkbox Group, we’d expect at least one child and they’d only ever be a Checkbox. Therefore, we build our asset to include:

• The items slot prop

• The items anyOf that includes a comma separated list of component names (in this case, set to simply Checkbox)

• The items minItems prop, here set to 1

Both props are hidden from view for the product designer.

This corresponds to spec data of the shape:

components:
  checkboxGroup:
    props:
      ...
      items:
        type: array
        anyOf: 
          - checkbox
        minItems: 1

We considered other options in Figma. The emerging slot prop type may include a description field. However, a description is a rich text, less stable and unstructured target for automated tools. If we were to leverage it, we’d use it for guidance, not specs. The already supported .preferredValues field is much closer in intent, but we chose to not overload it with what’s permitted values. More on that another time.

Text Area

In more complicated components, a system designer must consider what may become a dizzying array of logical relationships.

Textarea could include configurations like minimum value length, maximum value length, showing or hiding a max character count and whether that includes current character count. Not all these props reveal themselves visibly to the user.

For example, a minLength property could be enforced through a component behavior but not within a Figma asset. minLength could also be related to – but doesn’t trigger – a validation represented by Figma variant with an error message. As a result, minLength is a viable code only prop.

Textarea height might be bound by a minRows count (such as 2 by default) and a maxRows count (possibly undefined by default). In Figma, product designers simulate that by resizing and fixing asset height to fit their use case. Yet, system designers could imbue this intent via code only props.

These logical relationships result many text and boolean. All are built into the asset, enable logical relationships to show and hide relevant layers, and convey to spec data. Yeah, this one’s a doozy. Yet by the end of this modeling exercise, we’d learned much more about the component’s intricate behaviors.

Using “Code-Only Props” in Figma—it’s a bit of a technical trick using hidden layers to sneak data through—lets Figma be an origin of truth defining a component. It’s behind-the-scenes stuff, for sure. System designers should handle complicated requirements without making the product designer’s prop panel a mess.

No system solves every problem we’ll ever face. Nor should we want it to. Instead, a well-architected system balances what’s fixed and what’s open, where you are constrained by guardrails and where you can – and should – innovate.

Insert slots.

Slots define the areas in a component to vary content and structure, adapt layout, and improvise new ideas. Adding flexible, customizable areas to components move systems away from rigid, frustrating boundaries designers and developers struggle with today. Emerging native support of slots in Figma should usher in a next generation of component libraries, enabling more customization we crave without sacrificing control and consistency systems promise.

This post introduces the concept of slots in UI components. First, we’ll define slots and demonstrate the many forms slots take across common, familiar components. From there, we’ll dive into considerations of slot types, properties, subcomponent parts, and ready-made examples we’ll curate. Ultimately, slots present an array of new architectural challenges we’ll face and resolve in the year(s) ahead.

Getting Started

A slot is a designated place inside a component where custom content can be inserted—an intentional opening in a component’s hierarchy to allow custom variation.

In Figma, a slot are presented as a layer bordered in pink that acts a frame inside a component instance. Inside that boundary, you compose whatever you want.

In code, slots present as mechanisms like children (what’s included within the component’s tags) and tags and props like footer in the example below. Different platforms (like iOS and Android) and frameworks (like React, Web Components and Vue) use different syntax to accomplish the same goals.

<Card footer={<Button variant="primary">Buy now</Button>}>
  <h2>Product name</h2>
  <p>Product description</p>
</Card>

Slots make components composable and adaptable, providing a predictable way to customize content while preserving control of the component’s surrounding layout, styling, and behavior. Common needs can remain configurable, yet uncommon challenges can then be solved through composition.

Yet, slots blur component boundaries. Without slots, what’s inside a component is encapsulated, unyielding beyond what you configure using props. With slots, what’s inside can include a customized design. Teams become empowered to shape what they need, and systems continue to constrain what stays consistent.

Slots also improve alignment of design structure to how code works. Component hierarchies in React, Web Components, and native libraries are likely already quite composable. Adding component slots in design tools isn’t just a boon for creativity, it improves clarity and alignment during handoff and implementation, too.

Usage

Slots can impact more components across an ecosystem than one might expect. Sure, slots apply to moderately sized components that need customization. However, they can also apply to smaller “core” components as well as layout up through layers of composition including the page.

General slots

Slots are most recognizable and expected in components like Modal and Card for which users already expect to compose content and structure inside. These are examples of general slots for the component’s main body, and typically corresponds the component code’s children.

Named slots

Components name slots for multiple composable areas. For example, subtle shifts in content, styling, interactivity and layout abound in each area of a Row component seen stacked in feeds. Supporting each unique display as a configuration isn’t just impractical, it’s avoidable brittleness.

Instead, the Row warrants named slots. This three-part layout could enable customizing independent areas: the leading visual on the left, the text in the middle (possibly as the general slot), and the trailing actions on the right.

Slots for groups of repeating items

Slots also improve our ability to encode nested yet flexible relationships. These are evident in group/item components like Checkbox Group, Tabs, Breadcrumbs and even Buttons. In each case, slots provide the space for an indeterminate quantity of a single, predictable type of children.

Nested slots

Nested slot relationships can span more than two levels. An Action List group could nest specific Headers and Items, and even Group those items each with a Group Header too. Each item could warrant slots for their leading and trailing visuals. Slots are everywhere, serving levels of nested composition.

Slots for higher-order layout

Slots can apply conceptually upward through layers of reusable components to compose an entire page. You could nest a Checkbox Group in an Accordion slot. You could stack Accordions in the left column slot of a reusable Page row layout component. You could assemble multiple Page Rows in a reusable Product Category layout pattern.

That layout hat pattern, or layout component, or increasingly smaller and customized layouts and components could be included in the Body slot of a Page component. Components with slots from the Page down afford an opportunity to position layout rules, structure, and visual styling at many reusable, independently managed levels.

Time to say goodbye to countless designers detaching instances and putting in tremendous solo efforts to scaffold, build and maintain higher-order layout.

Architecture

Properties

Architecting slots in a UI component includes specifying properties like:

• Name, for both general “default” slots flowing children as well as specific, named slots in areas like header, footer, actions or leading visuals

• Description, whether guidance displayed to component users and/or spec data formalizing other properties

• Default value that can be a single nested instance or a deep, complicated composition to serve as a starting point and possible fallback

• Preferred or permitted children by both type and quantity, such as only Checkbox Items in a Checkbox Group’s slot but any quantity you need

• Layout, such as how slot contents arrange themselves in direction, item spacing and padding relative to the containing component

Subcomponent Parts

An increase in component slots and custom compositions within them could lead to a decrease in the need for configurable properties and a rise of more modular yet simpler subcomponents.

Breaking down larger components into subcomponent parts is challenging. What level(s) are better as smaller modules? At which level does each remaining configuration belong? What happens when bigger things still need to control the smaller things inside?

A Card may have reusable Title Lockup and card-specific Reviews module. It’ll be up the component user to arrange these flexible, smaller parts instead of configuring so many properties that resulted in the brittle supercomponents pursued in the past.

For a Product Card, this could mean any array of typical nested instances used in particular ways (like how to communicate discounts using a Badge) as well as primitives with conventional visual styling (like an original price, struck through).

Ready-Made Examples

Equally challenging is how to equip designers and developers to put pieces together faster. With greater composition comes the need for more examples. Not just pictures, but the actual parts in ready-made examples that both express what’s possible and easily get you most of the way there.

Systems must manage examples as an additional output to enable efficiency and experimentation. Ready-made examples are neither guidance docs nor component assets; instead, these scaffolded starting points represent a distinct deliverable of both designers and developers.

Key Challenges

Slots architected well and used effectively will improve flexibility, empower designers, and significantly accelerate efficiency. Slots done wrong carry consequences: undermined consistency, avoidable work, component fragmentation, design and code debt. Thoughtful design systems must carefully add slots so as to not break the promise of a consistent, high-quality and efficiently produced experience.

Adding slots throughout a catalog raises questions per component like:

• Depth: How low should a slot go in the component’s hierarchy of layers/nodes?

• Quantity: How many slots should a component have? Just a single general slot, or many named slots, or… both?

• Code Alignment: How strictly should slot depth, quantity and naming match between Figma and code libraries in web, iOS and Android?

• Layout: How difficult will designers find it to create intricate layout inside slots and hand off those details to developers?

• Styling: How much do you style a slot and what goes inside it by wrapping it, directly setting properties of it, and/or providing inherited theming into it?

• Permissiveness: How constrained should slots be in what and how much they include? Can they open up gradually over time without breaking how it works?

Slots will ask more of today’s designers and developers.

Over the past decade, design systems accelerated more designers with less interface design skills to create better experiences more quickly. This enablement is in no small part due to the expansion of consistent, well crafted libraries of configurable components. Insert a component, configure its properties, arranged in a broader view to solve a problem.

Today, system users need more than props. They demand control and flexibility. That the predominant design tool of the moment – Figma – will natively support slots will push our systems towards that flexibility towards composition inside components. Ready, set, go!

For years, we’ve toiled to maximize design system quality through collaboration from design through handoff to production. Today, our processes are boosted with AI, with component design intent hopping back and forth between codebases, LLM chats and design tools.

Through this period, our systems must improve how we get design intent out of (and back into) design tools as a part of a system’s broader pipeline. Not just efficiently, but precisely. Not just to vibe, but to record and version. Not just for us, but them (cough cough, AI) too.

If we are to use components as data, how do we do it without losing or degrading it as data shifts back and forth across our tools? We need a model to describe components, and tools to transform and move that description.

The Anova plugin, recently released in the Figma community, could be a part of that process. Built as a second generation the Specs plugin engine, the plugin produces component data with a more refined and extensible model. This post describes the plugin’s intent to output components as data, the data model it follows, and key principles that drove it’s conception and shape.

About the Anova plugin

The Anova plugin creates a component specification in data form. In particular, the plugin conducts an “analysis of variants” to audit component composition, visual styling, and prop configurations across all variants.

The plugin name alludes to traditional statistical analysis of variance, and is a hat tip to my college education. Yet the plugin isn’t actually doing statistical analysis. Instead, it crawls a Figma asset to produce a result that’s deterministic, repeatable, succinct and comprehensive. This output unlocks myriad opportunities for design system pros, as described in Components as Data:

1. Leverage component definitions in AI LLMs

2. Version component definitions over time

3. Analyze components across a catalog

4. Inspect component precision and quality

5. Handoff design to development

6. Generate documentation

7. Automate precise Figma asset generation (aka, the “round trip”)

Modeling the data

The Anova plugin’s engine is a more polished and better built second generation of the Specs plugin, which launched in 2023 and has output similar if less refined data for over a year.

The model of the plugin’s data output conforms to an available JSON schema and can be formatted as YAML or JSON. The data includes things you expect from a spec: an anatomy of elements, props and an analysis of how structure, styles and configurations shift by variant. It also hints at things you wouldn’t expect too, like a summary of invalid variants combinations.

Anatomy

The anatomy data includes a straightforward list of elements by type as well as growing metadata (such as component dependencies).

anatomy:
  root:
    type: container
  label:
    type: text
  icon:
    type: instance
    instanceOf: DS Icon

Props

The props section summarizes properties including type, enums, defaults and other relevant prop information.

props:
  label:
    type: string
    default: "{Label}"
  appearance:
    type: string
    default: critical
    enum:
      - critical
      - warning
      - success
      - info
  size:
    type: string
    default: large
    enum:
      - small
      - medium
      - large

Variant-by-variant analysis

The plugin evaluates a Figma asset a variant at a time. The plugin starts wih the default variant, identifying each element of the anatomy that is present from the root component layer down through the layer hierarchy to assess layer styles, layout structure and other properties.

default:
  elements:
    root:
      styles:
        fills: DS Color/Alert/Basic/Background filled
        cornerRadius: DS Shape/Border radius/Pill
        itemSpacing: DS Space/Item spacing/0_5x
        paddingLeft: DS Space/Padding/0_5x
        paddingRight: DS Space/Padding/0_5x
        paddingTop: DS Space/Padding/0_25x
        paddingBottom: DS Space/Padding/0_25x
    label:
      styles:
        fills: DS Color/Text/Primary
        textStyleId: Body/Large
      propReferences:
        characters:
          $ref: "#/props/Label"

From that established default, successive variants are evaluated, compared to other variants serving as baselines, and reduced into a succinct spec across all variants.

variants:
  - configuration:
      size: small
    elements:
      root:
        styles:
          itemSpacing: DS Space/Item spacing/0_25x
          paddingLeft: DS Space/Padding/0_25x
          paddingRight: DS Space/Padding/0_25x
          paddingTop: DS Space/Padding/0_125x
          paddingBottom: DS Space/Padding/0_125x
      label:
        styles:
          textStyleId: Body/Small
  - configuration:
      appearance: success
    elements:
      root:
        styles:
          fills: DS Color/Alert/Success/Element
      label:
        styles:
          fills: DS Color/Text/Primary Inverse

From the resulting variants data, you can layers styles and other data based on one or more matched configurations in a manner very similar to CSS’ cascade.

For example, if this component was configured as both size:small and type:success, then the data would layer in three matches (the default then matches for size and type) to resolve as:

elements:
  root:
    styles:
      fills: DS Color/Alert/Success/Element
      cornerRadius: DS Shape/Border radius/Pill
      itemSpacing: DS Space/Item spacing/0_25x
      paddingLeft: DS Space/Padding/0_25x
      paddingRight: DS Space/Padding/0_25x
      paddingTop: DS Space/Padding/0_125x
      paddingBottom: DS Space/Padding/0_125x
  label:
    styles:
      fills: DS Color/Text/Primary Inverse
      textStyleId: Body/Small    

Invalid variant combinations

The invalidVariantCombinations section summarizes prop combinations that are invalid based on the Figma asset. For example, an interactive component typically cannot be disabled and hover at the same time. Depending on how you’ve built your component in Figma, those combinations can be determined and summarized.

invalidConfigurations:
  - disabled: true
    state: hover
  - disabled: true
    state: active
  - disabled: true
    focused: true

Principles

Extensibility, interoperability, validation, and portability are table stakes for any data structure. On top of that, four more principles drove decisions: determinism, completeness, succinctness, and human-readability.

✅ Deterministic instead of stochastic

The problem: Data extracted from Figma’s Dev Mode MCP Server is impressive, but isn’t designed to produce a durable spec unless your spec is a React and Tailwind implementation. The extracted data, transformed further via LLMs, yields unpredictable results: sometimes imprecise, often incomplete, and frustratingly different run to run.

For example, I’ve observed an LLM starting with an Alert component’s appearance:success|critical|warning|info property behaving unpredictably. Over repeated runs, it renamed options (information), added options (neutral), remove options (warning) and renamed the property itself (to type or variant)! A design system can’t rely on an unstable workflow for a canonical component description.

props:
  appearance:
    type: string
    default: critical
    enum:
      - critical
      - warning
      - success
      - info

The plugin’s approach: The plugin extracts only the raw, intentional data directly from the asset. No guessing. No machine prediction. The same input yields the same output, every time. And each time, it’s easy to compare it to past versions to affirm and commit to the differences. You designed it to be appearance:success|critical|warning|info, so you get appearance:success|critical|warning|info.

✅ Complete instead of partial

The problem: The data derived from Specs Figma plugin ouptut is powerful. People upload screenshots of it to LLMs and it kinda works! However, it evaluates prop effects in isolation. It doesn’t inspect every variant in depth to find every potential effect on style and structure.

For example, it’s easier to document a component’s background color when hover:true or selected:true. How about when both are true? How about when both are true, and the component is also set to appearance:info? Did the component change more? These interactions are rare and harder to analyze, but they shouldn’t be missed by a shallow analysis.

variants:
  - configuration:
      hover: true
    elements:
      root:
        styles:
          backgroundColor: (a color)
  - configuration:
      hover: true
      selected: true
    elements:
      root:
        styles:
          backgroundColor: (a second color)
  - configuration:
      hover: true
      selected: true
      appearance: info
    elements:
      root:
        styles:
          backgroundColor: (a third color)

The plugin’s approach: The plugin can inspect every variant in-depth and then reduce what’s accumulated into a set of matches that layer into a rendered style. Instead of disjointed snapshots relying on one prop, you get the entire picture no matter the (valid) prop combination.

✅ Succinct instead of bloated

The problem: Figma provides access to a complete picture of component assets via its REST API. Unfortunately, its variant architecture is very bloated. To express a disabled:true state for a component like Text Input, could mean 24 more variants each with ~15 layers per variant each with ~40 properties.

Ask Figma’s REST API for component information, and you’ll get 14,400 additional properties in hierarchical data! 99.99% of that data tells you nothing new, but it needs to be processed and examined to make sure. All because a designer expressed a simple intent of “When disabled, set the root layer’s opacity to 0.36.”

variants:
  - configuration:
      disabled: true
    elements:
      root:
        styles:
          opacity: 0.36

The plugin’s approach: Instead of duplicating entire variants, it records only the difference: what changes when disabled. That’s compact, lossless, and easier to maintain.

✅ Human-readable instead of gobbledygook

The problem: Even if you get deterministic and complete data, it’s usually encoded in ways that only a machine can love — long and noisy JSON dumps with no obvious hierarchy of what matters.

title: {component name}
anatomy:
  {element name}:
     type: {type}
     instanceOf: {main component name}
  ...
props:
  {prop name}:
     type: {type}
     default: {default}
  ...
default:
  elements:
    {element name}:
       styles:
         {style name}: {value}
variants:
  - configuration:
      {prop name}: {value}
    elements:
      {element name}:
        styles:
          {style name}: {value}

The plugin’s approach: Outputs are structured so a human can scan them. Defaults come first. Overrides are grouped by condition. Names are consistent. Reading the data feels like reading a spec.

I’ll acknowledge right now that designers aren’t in love with reading a spec as data. It does require onboarding (a few good docs rich with examples seem to be enough). Yet, I’ve been pleasantly surprised at how quickly specs-as-data sprout up next to assets. It’s value becomes even clearer when Figma comments start showing up above the spec rather than asset to get things done.

Ideally, if Anova data proves valuable to the community, the plugin could go in many directions. At the forefront, I’d expect to integrate this new processing engine into the Specs plugin (or vice versa, overlaying the spec outputs onto Anova) in the future, consolidating the two.

I also can’t imagine this living long without strong, direct integration with other tools. This suggests that MCP server and/or Figma REST API integration could prove useful directions to pursue. Yet, for now, it’s certainly useful enough to share, get feedback, and grow.

Nearly a decade ago, I wrote of my passions stirred by crafting tokens in design systems. Those (sub?)atomic, minimal decisions were invigorating as we put structure to visual choices as data to spread across a system. The muse of that story? The Pill component.

This year, my team initiated a catalog-wide component-by-component refactor. This time, again, we started with the Pill component. It’s as if the Pill offers us a choice: see the truth of our explicit decisions, or stay in an illusion that manual handoffs and divergent tools carry our intentions into the work of others without failure. Ok, maybe that’s a bit heavy handed. Enough with the heady metaphors.

Throughout the project, my role is to architect how we record component decisions as structured data independent of any platform, including Figma. I’m responsible for ensuring consistent, scalable, and interoperable components that flow into and from Figma and a pipeline of generated, cross-platform code. It’s delightfully complicated. Tokens feels quaint by comparison.

This slot prop. That container element. Both are familiar and feel simple. Yet conveying visibility and children from one to the other, binding and unbinding references across an array of variants? That hits different. Chats evoke nullability. We’re overdosing on overloading. Figma’s threshold of what you can express and how you express it feels a barrier. Huh, hold up. What’s … nullability?

These days, I live much more in a text editor than a UI to plan, design, validate and deliver components as data with AI at my side. In this post, I provide a glimpse of components expressed as data and follow with why treating using data matters across a component’s life cycle in the era of AI.

Defining Components in Data

A component definition in data is a structured description of a UI component expressed in a neutral format (like YAML or JSON) instead of hard-coded in design tools or platform-specific code. Data breaks a component into parts like an anatomy of elements, props, styles, layout and how each varies when configurations change.

Anatomy

A component’s elements of various types (like container) organized into a hierarchy comprise its anatomy. Element concepts correspond to platform-specific constructs, such as a Figma FRAME layer or HTML DIV, SPAN, or SECTION.

anatomy:
  root:
    type: container
  content:
    type: container
  leadingVisual:
    type: slot
  label:
    type: text

Props

Props to configure a component’s behavior and appearance and can be various data types, such as booleans, strings, enums or slots.

props:
  disabled:
    type: boolean
    default: false
  selected:
    type: boolean
    default: false
  state:
    type: string
    default: rest
    enum:
      - rest
      - hover
      - active
  leadingVisual:
    type: slot
    nullable: true
    oneOf:
      - icon
      - avatar
      - image
  label:
    type: string
    default: Label
  accessibilityLabel:
    type: string

Within a seemingly simple prop list, subtleties complicate conversations for designers expressing ideas in Figma.

• Aren’t disabled and selected technically enumerated VARIANT props with enumerated values for true and false? Yes.

• Is leadingVisual an INSTANCE_SWAP prop, and don’t we need another BOOLEAN prop to control its visibility? Yes (that’s how slots work today in Figma) and yes (the need for a BOOLEAN relates to the nullable property).

• How do we even represent accessibility labels? Expose a TEXT prop in the Props panel but not visually. There’s a trick for that.

Those conversations highlight the act of translating a component definition to a platform, in this case Figma.

Styles

Styling is directly expressed in data in a human-readable way, too.

default:
  elements:
    root:
      children:
        - content
      styles:
        height: foundations/size/8x
        backgroundColor: foundations/color/surface/primary
        borderColor: foundations/color/outline/primary
        borderWeight: foundations/size/0_25x
        verticalAlign: CENTER
        itemSpacing: 4
        paddingLeft: foundations/spacing/4x
        paddingRight: foundations/spacing/4x
        layoutDirection: HORIZONTAL
        layoutSizingHorizontal: HUG
        cornerRadius: foundations/shape/circle

Here, a root element (in Figma parlance, the COMPONENT or INSTANCE layer) has a range of default styles that mix raw values (4, HUG) and token references (foundations/size/8x).

Yet, the element also omits presumed initial values (paddingTop: 0) and has implied values too (layoutSizingVertical must be FIXED because height is set). Even within styling alone, our team’s vocabulary must level up to describe concepts we’ve implicitly used before but never named.

Variants

Things get more interesting as prop configurations apply. In this simple example, a Pill's hover state changing the root’s background color.

variants:
  - configuration:
      state: hover
    elements:
      root:
        styles:
          backgroundColor: foundations/color/interactive/hover

Yet, variants can get complicated quickly, with two or more props interacting in a configuration to impact many elements at a time.

Broad, Detailed and yet Incomplete

When put together, these models combine to form a fuller picture of a component, in a structure like:

{component name}:
  anatomy:
    {element name}
    ...
  props:
    {property name}
    ...
  default:
    {element name}:
      styles:
        {style name}: {style value}
    ...
  variants:
    - configuration:
        {prop name}: {nondefault prop value}
        ...
      elements:
        {element name}:
          styles:
            {style name}: {style value}
     ...

Simple components (Divider 👀) may only need 20–50 lines of data. On the other hand, sophisticated core component like Alert, Text Input or Card often require 500 lines or more.

Yet, even with over 1,000 lines of data, a picture could remain incomplete, lacking considerations like:

• Binding configurations to an element’s values

• Motion and nontrivial Interaction that designers could express in Figma (using reactions) but rarely do.

• Accessibility that Figma lacks the ability to express in a structured way, although plugins help with that.

• Non-visual configurations, such as an Alert's autohide duration or TextArea's maxRows that a designer could decide for handoff.

Varyingly, teams expand the shape of data to include more and more of these considerations through a combination of Figma capabilities, plugins and team-specific conventions. That said, teams continue to pair component data with a separate, unstructured document to “handoff” a complete component definition. For now, anyway.

A component catalog

Teams produce, store and version data for an entire component catalog in a database or (usually, in my experience) as a JSON or YAML file.

components:
  alert:
    ...
  banner:
    ...
  breadcrumb:
    ...
  button:
    ...
  card:
    ...
  icon:
    ...
  iconButton:
    ...
  pill:
    ...
  tabs:
    ...
  textArea:
    ...
  textInput:
    ...

A core.yaml file for a design system’s core components may include 30–50 components (and their subcomponents, too) and be 10,000s lines long. Want to store a component per file? Sure, tool it up that way. Want to separate concerns of component API from theming via tokens? Sure, as you will. You decide.

The Impact of Components as Data

Definining components in data form rather than passing unstructured artifacts between collaborators unlocks many opportunities across a component’s life cycle.

Leverage components in LLMs

AI is everywhere, and it favors structured data. So express components that way. An LLM can answer questions about how the component works, compare it to implementations, and propose improvements via prompts.

Sure, you could leverage Figma’s Dev Mode MCP Server. But beware: that’s a stochastic, incomplete, and imprecise component description biased towards one platform (like React) and framework (like Tailwind). More formally approaching component data makes component knowledge reusable, scalable, and consistently interpretable across contexts.

Inspect component precision and quality

With countless design decisions woven into our Figma assets, it can be hard to wire up every detail without errors. Data exposes errant design decisions, making components easier to audit.

variants:
  - configuration:
      state: hover
    elements:
      root:
        styles:
          backgroundColor: #045bbc  ## Seriously? Token please!

If I had a nickel for every time I detected a raw value in a stray variant when a token is needed (like the hover backgroundColor above), I’d be rich. Seeing components as data make inspection straightforward and precise, raising the quality of both design and code implementations.

Generate components across code platforms

Instead of hard-coded spec documents or screenshots, developers receive machine-readable definitions. These definitions of structure, styles, and prop behaviors can be used to scaffold code directly. This reduces or even eliminates back-and-forth to ensures product matches design intent.

Generate Figma assets, too

And this isn’t just for code implementations. Teams generate Figma assets too. Soon to be gone are the tedious, manual hours to produce countless variants.

Instead, Figma component assets can be automated from a component definition in data that I plan in an hour and iterate with teammates for another. While we may go back and forth between Figma and data to refine and experiment, designers are increasingly focusing on architecture more and pointing and clicking and dragging and setting values in the Figma UI less.

Generate examples and documentation

The same data can be used to automatically create component reference pages, usage guidelines, and visual previews. This removes the need for manually maintaining documentation that quickly falls out of sync. As components evolve, the documentation updates with them, staying consistent and trustworthy.

Version component definitions over time

Component definitions as structured data be tracked in version control systems like Git. This allows teams to see how components evolve, compare differences, and roll back if necessary. It creates a durable record of a component’s lifecycle, just like other source code.

Analyze components across a catalog

With many components defined in the same format, you can prompt AI to find patterns and gaps like:

How and how often is the foundations/color/surface/secondary token used?
Are enumerated options for state handled consistently?
Are accessibilityLabels applied across all potential cases?

This enables data-driven insights into a system’s health and coverage.

As an architect at heart, I’m so excited that my work has evolved into increasingly formal structures to describe UI components. This era of AI demands that we shift and evolve how design systems work. It’s difficult to imagine returning to a time when I architected components only in a visual tool like Figma. Instead, my mind races faster seeing those impassioned decisions as data, moving through the connections we create.

Our design system effort was gaining momentum, and we’d reached a crossroads I’d seen coming a mile away.

“So, your main, most important brand color is red?” I asked.

“Yes,” the collaborator replied calmly.

“Then, what color will we use for errors?”

“Red,” they answered decisively.

“The same red?”

“Yes.”

“Got it. In mockups everywhere, I also see that red used to distinguish a sale price. So, we communicate things are on sale with … that red too?”

“Yes.”

“Ok, to be sure. Imagine I’m designing for a product that’s on sale, and the user configures an invalid quantity. In tight proximity, the UI will signal three things (brand, sale, error) all with the same red?”

“Yes.”

This tension between visual aesthetics and purposeful intent appears throughout interface design — in tokens, composition, and, as this article explores, component props and options.

In this post, I’ll contrast purposeful vs aesthetic naming schemes for component properties, describe hybrid approaches that are best avoided, and conclude with related techniques that are sometimes brought to bear.

Comparing purposeful and aesthetic naming

Consider a Badge component that can appear in different colors : red, green, blue, yellow, white, and gray. How should this visual variation be controlled? Typically, you create a set of options based on either purpose or aesthetics.

Purposeful options

Purposeful props use specific, self-documenting values that convey narrow meaning and intent. For example, a Badge may be offer choices like error, success, info, warning and new.

Purposeful naming focuses on what role a component serves, which approach offers several compelling advantages:

1. Self-documenting intent: When you see severity="error", you immediately understand component purpose without needing to reference docs or examples. The prop tells a clear story of intent.

2. Consistency across contexts: Purpose-driven props ensure that all “error” states look and behave consistently across components to create a more cohesive user experience.

3. Durability across redesigns: Visual treatments change, but semantic meaning tends to remain stable. A component using variant="warning" will survive brand refreshes better than one tied to color="yellow".

4. Built-in accessibility: Purpose-driven naming naturally supports accessibility considerations, such as screen readers announcing information like “error status” rather than just “red badge.”

Aesthetic options

Aesthetic-driven options use visual terms like color (red) or scale (1X, …) that lack semantic intent.

Aesthetic naming isn’t wrong — it serves different needs and contexts like:

1. Visual control and flexibility: Designers may need flexible control over appearance that doesn’t map neatly to semantics. Sometimes you need a light gray divider, and forcing semantic meaning feels artificial.

2. Decorative use: Some components serve purely visual roles where structural meaning is secondary, irrelevant or not yet defined.

3. Migration and legacy support: When retrofitting design systems onto existing products, aesthetic props can ease the transition by matching appearances that already exist.

4. Coverage over semantic gaps: Sometimes semantics simply don’t exist yet, or the use case is too specific to warrant a semantic abstraction.

Comparative examples across visual properties

This choice of between purpose versus aesthetic structures arises often across components for characteristics beyond just color, such as varying:

• Text input’s border weight to create more or less minimal look

• Card’s shadow strength to create a raised or overlay appearance

• Text’s font attributes to imply text role, hierarchy and structure

In addition, the choice may vary by component, and that’s ok. For example, a Badge component is more atomic and require more visual variety (orange! purple!) and flexible use. This suggests that an aesthetic naming system is preferred. On the other hand, an Alert component is more composed, has more limited options, and the need to use it flexibly is far more limited. As a result, Alerts almost always leverage purposeful variant names.

Blending approaches

When teams encounter the limitations of pure purpose or pure aesthetics, they sometimes stray towards blending both approaches into a single component property. Two common but problematic patterns — Purpose-first and Hybrid — are generally best avoided.

Purpose-first

Purpose-first options follow purposeful options (error, success, warning) with aesthetic fallbacks (white, black, light-gray) for cases lacking clear semantic meaning.

Benefits:

• Guides decision-making with clear hierarchy

• Covers gaps where semantics don’t apply

• Easier to document than forcing semantics everywhere

Drawbacks:

• Increases cognitive load with mixed mental models

• Creates ambiguous boundaries between “purposeful” and “aesthetic”

• Unclear extensibility as new options are needed

Consider purpose-first enumerations with particular caution, generally avoiding them if possible.

A hybrid trap

The most problematic approach combines all purposeful and aesthetic options into one massive enum: variant="error" | "success" | "red" | "green" | "white" | "black" | "light-gray" | "dark-gray".

This leads to:

• Cognitive paralysis from too many similar options

• Maintenance debt as the option list grows unwieldy

• Fragmented consistency that use different values for the same case

• Accessibility confusion when semantic and aesthetic values conflict

A system that tries to be both flexible and meaningful may sound ideal — but in practice, it’s not. Don’t go there.

Additional techniques

When confronting the tradeoffs of purposeful and aesthetic naming, teams also often debate the merits of escape hatches, migration-oriented deprecation, and separating the two into multiple properties.

Escape hatches

Escape hatches provide semantic options as the primary interface, supplemented by style override props for edge cases. For example, offering an interface to customize the styling of relevant properties.

interface BadgeProps {
  variant: 'error' | 'success' | 'warning' | 'info';
  customStyles?: {
    backgroundColor?: string;
    textColor?: string;
  };
}

This isn’t for the faint of heart (that is, design system professionals wanting firm control to limit uncontrollable designs). The model of exposing such overrides varies by team, whether it’s documented for everyone or a “back door” few know about. Regardless, escape hatches are a technique design systems apply make the common configurable and yet the uncommon visually composable.

Migration-oriented deprecation

When migrating from one system generation to another, deprecation can introduce semantic options while sustaining aesthetic ones with the intention to phase them out later.

interface BadgeProps {
  variant: 'error' | 'success' | 'warning' | 'info';
  /** @deprecated Use severity prop instead */
  color?: 'red' | 'green' | 'yellow' | 'blue';
}

Exercise this with caution. The migration is eased for sure, but there’s dangling properties spread throughout production code. It’s just kicking the can down the road — and eventually, you’ll have to clean up the mess.

Multiple properties

That said, never create competing props that could conflict, such as severity and color that require you to identify which takes precedence. In this case, it’d probably be color, which results in an interface where you can specify variant of success and a purple color, and … purple wins?

// DON'T DO THIS
interface BadgeProps {
  variant?: 'error' | 'success';
  color?: 'red' | 'green';  // What if both are specified?
}

Separating the same concern into multiple props is a terrible idea. Not only do the properties interact, but the component’s property shape is muddled. Don’t bother, please.

In general, I favor purpose over aesthetics because design systems use meaning to result in more consistent, accessible, and maintainable experiences. However, that principle doesn’t always mean purposeful is better, and I’ve worked with teams that justifiably used aesthetic naming schemes for some components. Don’t force artificial semantic meaning where none exists — sometimes a gray divider is just a gray divider or… just a divider.

Aesthetic props offer short-term flexibility, but often lead to long-term debt. Semantic investments, by contrast, tend to pay off as systems grow. Whatever approach you choose, be consistent. The best component API is one that guides users toward good decisions while remaining flexible enough to handle legitimate edge cases.

A few years back, I wrote Crafting component API together. Figma had become and remains the hegemonic design tool, and its capabilities for shaping components with a useful and usable API continue to strengthen. Libraries have taken deeper hold.

Yet, even the best system designers are missing opportunities to mimic how code actually works. No clearer is this than in the sorry state of the state prop of many interactive elements like text input, text area, dropdown, checkbox and radio button.

This post explores how design systems architect states in Figma assets inconsistent with how code works. The text input offers lessons about how to model props, from partial sets of option combinations and interdependent props to booleans versus enumerated options and just how far we should go — or not go — to purely model Figma assets.

The State of States Today

States is a generic term that designers and developers apply to a wide swath of situations. Eric Bailey’s lengthy list of all the user facing states highlights this well. There’s 38 in all, from rest, hover and active through disabled, readonly, selected, deselected to less common considerations like loading, ghost origin, and dirty.

Curious Chrome inspectors could select a text input, right click to select Inspect, and find a bevy of element states (:active, :hover, :focus, … ) including a robust set of HTML form validation hooks (:disabled, :valid, :invalid, … ) that front end developers can take advantage of with CSS combinations.

Trouble is, the term states is exceedingly generic. All possible states aren’t alternatives. Instead, available states are a mishmash of interdependent concerns often with logical relationships and used in combination.

Yet when used in design critiques discussions, design specification section headers, and particularly in Figma asset properties: state becomes a glorious catch-all of insufficiently modeled ideas.

For a text input, of course we’ll show hover and active. Given that, we’ll pause and ponder whether to call the first one base (don’t), default (that’s ok), enabled or initial (better) or rest (best?). Nah, let’s go with resting I guess. Our impulse is to move on.

Then complications arise. What about disabled? Of course, that’s needed. And readonly? Oh, I’d not thought of that. Obviously error state is a must. The states set grows gradually, stabilizing when we’re satisfied we’ve captured enough. Designers can be forgiven for not solving for every single “Eric Bailey State.” I never have. That list is crazy long!

States Today in Figma Assets

I examined the Text input / Input / etc Figma components published on the Figma community made by the following design systems:

• Material 3 Design Kit

• Material UI for Figma (and MUI X)

• Salesforce Components for Web | Lightning Design System v1

• Github Primer Web

• IBM Carbon Design System

• Atlassian ADS Components

• Oracle Redwood

• Newskit Component Library

• Shopify Polaris Components

state property patterns matched what I observe in teams I consult with:

• Hover: Six of ten support a state:hover (or state:hovered) option.

• Active: Two support a state:active option.

• Focus: Eight of ten support state:focus and none offered focus as a separate boolean property.

• Disabled: Nine of ten support state:disabled and only one (Atlassian) distinguished isDisabled as a separate boolean property.

• Read only: Six of ten support state:readonly, while none offered readonly as a boolean property.

• Error and Success: Eight of ten support an state:error (or similarly named validation) option, while one (Atlassian) offered error as a separate boolean property.

Components occasionally included other state options like warning, skeleton, and typing. One even included filled, which drifts towards the adjacent state challenge of value and placeholder properties not covered here.

No Figma assets supported plausible state combinations like readonly + focus or hover + error.

States Today in Code Libraries

A similar review of Text input component code from those libraries yields a different prevailing model.

• Hover and Active: Most code libraries implement these implicitly as states that respond to user interaction.

• Disabled and Read only: Nearly every code library implements these props, enough to consider both props as conventional.

• Error and Success: Many code libraries implement an error (or inInvalid, hasError or similar) boolean prop to present an error display. GitHub Primer expands from a binary to enumerated validationStatus prop to distinguish error from success. Some code libraries implement an error prop for error text.

Shopify Polaris’ React component implement Typescript interfaces for disabled and readonly suggesting that an intentional convention across components. This library also implements a forceable focused.

So design and code are different. So what?

The evidence is clear. Beyond interactive states like hover and active, Figma assets and code components offer distinct API signatures. Actually, let’s be more precise: design assets published for reuse by product designers are different from code assets that product developers use.

It could be that the design solution handed off by the system designer to a system developer is perfectly consistent with what happened in code. Nah. My experience suggests otherwise. Design iterations and specifications (often automated with the EightShapes Specs plugin) almost always reveal the same “States as kitchen sink” approach. Why should we care?

Corrosive impacts on efficiency, usability and satisfaction

At a minimum, most designers are aware of the common pitfalls of imprecise and/or incomplete design delivery. This leads to challenges like:

1. Handoff friction as product designers deliver to product developers using published Figma assets that use different models from code.

2. Poorly organized props in Figma assets that are harder to use, littering one or a few props with various choices that are actually independent.

3. Continued distrust and disrespect of developers seeing designers as less or ill-equipped to model component props effectively.

That last one hurts, perpetuating an at times justified “don’t touch my stuff” attitude that some developers persist have when instead we could be working to craft component API, together. That’s a subject for another day.

Limiting impacts on automation

Less visible to some but far more important to many of my current collaborators are the negative impacts to taking advantage of Figma’s API to automate and cleanse increasing areas of a system’s surface. Poorly modeled properties can:

1. Limit automation opportunities to audit and report on alignment across design and code libraries.

2. Limit the ability to use assets as data to inform, serve as a source of truth, or even automate code development.

3. Increase costs of mapping complicated (and brittle?) transformations in tools like Figma’s Code Connect that could be avoided.

My belief about API alignment across libraries including design has only hardened further since I wrote about it in 2021. When I see so many revered design systems unnecessarily diverge from code (just like those I work on too), I want us all to do better. This particular challenge isn’t hard.

Modeling Prop Combinations and Interactions

So let’s dig in, step by step, to think through stateful properties and how they work. We’ll start with the cleanly combined nature of selected and state found in radio buttons and checkboxes. From there, we’ll use Text input’s disabled, readonly, and validation states to learn how properties combine and interact with one another.

Complete sets of combination

Some types of states combine to form a complete set of relevant combinations. For example, Checkbox and Radio button combine interactive state (rest, hover, active and focus) and selected state (not selected and selected) into eight combinations.

The following table illustrates that for every combination of state and selected, the combination exists (depicted as ✅) and could warrant a distinct visual design.

To Radio button states in a Figma component, one could include a state property with options for hover, active, focus and selected. However, that would omit possible combinations like selected and hover simultaneously. Those could be added as additional state options like hover selected, but risks sliding down the slippery slope of providing all combinations via compound option names. Better to separate concerns with distinct Figma variant properties for selected (even if it’s options are true and false, the visual design varies) and state.

Checkbox’s potential of a third checked state — indeterminate — results in 12 possible combinations, make the enumerated state list of compound terms less desirable. Additionally, the checked property would shift from a binary variant to one revealing enumerated options of not checked (default), indeterminate and checked.

To those brave enough to review Eric Bailey’s states list in detail, you may notice even more relevant considerations such as Deselected. For most teams, it’s impractical to include Deselected (having been changed from Selected) as distinct from Rest (neither selected nor interacted with).

Partial sets of combinations

The disabled property is different, as a variant set to true or (by default) false. Disabled controls are essentially at rest, visually distinct and hover, active and focus states are irrelevant.

As a result, the designer has a choice: separate disabled from interactive state or include disabled as an option of state. Either choice results in a partial set of five out of eight possible combinations, so long as the Figma asset doesn’t implement disabled states not at rest.

Would it be convenient to stuff a disabled option into the state dimension? Sure, it feels easy. Yet, that’s not how code works. Plus, collapsing disabled into state reduces the model’s clarity and meaning, and disables (pun intended) you from properly modeling other relationships, as we’ll see next.

Interdependent properties

The plot thickens with readonly, also conventionally a boolean property in code. Like disabled, readonly is false by default. Unlike disabled, readonly supports rest and focus but typically not hover and active.

Additionally, disabled and readonly never occur simultaneously. When both readonly and disabled are set to true, disabled takes precedence and readonly is ignored, making these properties interdependent.

If a designer implements all seven valid combinations, Figma handles this case well enough. Since it takes precedence, disabled should be ordered first, followed by readonly, followed by state. Should a component user set disabled to false, the component would revert any other state to rest.

Could both disabled and readonly be collapsed into options of a state property? Yes, but properties combining multiple dimensions into a one property with compound names doesn’t match code and doesn’t scale well.

Choosing enumerated or boolean props

Error and success validation states raise more questions. Both disabled and readonly are delightfully binary, easily represented with true and false values (even if built as Figma variant properties).

Some design systems only offer error states, which raises the already familiar choice (and recommendation) to offer an error variant property one can set to false (default) or true.

The combination table below does raise interesting questions: can an input be set to both error : true and either readonly : true or disabled : true? From a purist’s perspective, yes, probably.

But such combinations of error (in HTML, invalid?) withdisabled or readonly carries heavier considerations like:

• Competing visual cues: what signals it’s in error versus disabled?

• Conflicting resolution: if an input is in error, the user should be able to interact with it to resolve the issue. If it’s disabled, they cannot.

These are user experience design issues rather than API design issues. Guidance may suggest avoiding the combination unless it’s necessary and intuitive to users and encourage other UI patterns instead. For the Figma component and it’s attendant communications to implementing developers, however, at least a conversation if not explicit asset is warranted to clarify what happens if both are set to true.

Properties evolve further if an input also implements a success state (often combining a green color with a checkmark icon) that’s the opposite of an error state (that could use red color and an X icon).

In this case, error (or, invalid) is mutually exclusive from success (or, valid), and a visualized success state is different than showing neither an error's red or success's green. Therefore, consider an enumerated validation variant property with options for none (default), error and success.

Standalone prop versus or option of another prop

All this time, focus has been presumed a mutually exclusive option in a set that also includes rest, hover and active. In fact, an element can be both hover+focus or active+focus simultaneously.

Should focus (true,false) be a separate property from iteractive state (rest, hover, active)?

A designer converted to be a purist by preceding sections may be incorrectly led to further separate concerns and add a focus variant property set to false by default. That’s likely going too far.

In a practical sense, separating a focus property from a state property isn’t practically necessary, because:

• Focus is almost always triggered client-side, not a developer’s configuration: focus, like hover, is an interactive state based on user interaction. Although some libraries offer it, most implementing developers don’t find themselves forcing focus with a prop, unlike disabled, readonly or error.

• Focus impacts distinct visual attributes, usually: focus typically impacts visual attributes (such as a container shadow or a showing a separate focus ring element) are distinct from those impacted by hover or active (usually, a container’s background or stroke color).

• Focus overrides the same visual attributes, otherwise: Even if focus impacts container stroke weight and color as hover does, once the element has focus, the weaker visual cues relevant to hover or active matter far less if at all. focus takes precendence over hover as disabled did over readonly, and there’s no relevant third, distinct appearance for focus + hover.

• Conventionally related as a set: The three are very closely related CSS pseudo classes, presented as and usually pursued as illustrated by their presence. If we’re going to distinguish focus, might as well distinguish hover from active. While we’re at it, is it time to further distinguish focus-within? I’ve never encountered a developer coding that yet, let alone a designer solving for it. We can all aspire for greatness, someday?

All but one code examples assessed lack a focused property. Only Shopify Polaris’ offered a focused property to force the focused state. I’m guessing at purpose: maybe interactions with elements slotted inside the input must force the focus state of the parent container? Additionally, Shopify Polaris’ focused property is additive to the focus interactive state triggered without applying the property.

I’m unconvinced that separating focus:true, false from an interactive state:rest, hover and active is necessary. That is, until collaboration fails (it won’t) or automation between libraries requires it (it could, someday).

Ending there is a useful illustration: the pursuit of perfect alignment — and a perfect model for configuring our design — loses steam before perfection. That three year old blog post was more than comfortable with diverging state across design and code assets.

Today, the threshold has moved towards deeper integration and stronger alignment. That’s the same journey many teams will be on over their years pursing systems. Maybe someday they’ll converge. Maybe soon.

Design systems come in many shapes and sizes, especially evident by how core catalogs of foundations and UI components are implemented across more than one code library.

As a system scales to meet expanding needs, it often grows to offer parallel component code libraries for web, iOS and Android along with commensurate Figma assets for designers. Four “core libraries” (three code, one design), parity of all relevant components, expanding and evolving over time. Let’s roll up our sleeves.

This post explores how expanding to support many platforms and frameworks impacts how you support and align it with a shared design source-of-truth. Success gets complicated as libraries increase, challenging how teams collaborate, designers test, everyone aligns API, and users still expect to see synced features each release.

The example of IBM’s Carbon design system offers a tantalizing public example of a core library implemented across many frameworks in parallel. Such a model inspires, even if it’s not necessarily a target to emulate for simpler problems most systems face.

Describing core libraries of design and code

A core library refers to a library of reusable assets implementing a design system’s core components like Text input, Button and Checkbox.

Platforms and frameworks

Each library implementation targets a specific platform (such as design, web, iOS and Android) and is built with a particular framework (such as Figma or Sketch, React or Lit or Angular, SwiftUI or Jetpack Compose).

Team model: central and/or federated?

For smaller design systems, design and code implementations are usually maintained by central teams dedicated to the work. As additional code implementations arise supporting other platforms and frameworks, the more likely each will be made by federated maintainers and contributors.

Design source-of-truth: specifications?

Designers and developers using a core libraries expect that library to support all core components like button, text input and checkbox. Each component is expected to implement a common design specification (that may include platform– and/or framework–specific considerations).

Code source-of-truth: the reference implementation?

In addition, one code library may serve as a reference implementation: a working component demonstrating how it should be correctly implemented and used. The reference is usually produced by the central team, showcases best practices, and reflects a recommended API. Such a “canonical” reference provides federated teams implementing additional libraries with a reasonable technical design to align with.

Example models, from simple to complicated

Managing and aligning one code library with design is delightfully simple compared to when two or more code libraries begin to scale. As a manager of design system work, it’s up to me to solve for concerns across libraries that include:

• Roadmap: How do we align features across code libraries over time?

• Collaboration: How do we enable collaborative best practices between design and multiple engineering teams, especically when federated?

• API: How do we align API architecture across frameworks, platforms?

• Testing: How do we integrate designers into testing code outputs?

• Release synchronization: Do we align releases and communications across libraries? If not, what does that mean?

The example models that follow will progress from simple to complicated to highlight how these concerns get more complicated.

One code library, by a central team

The majority of design systems I’ve led support one design library (these days, Figma) and one code library (such as React) through the work of a central team. Production aligns three primary outputs — (1) Figma assets, (2) React code packages, and (3) docs published to the “doc site” — released in synchronization in a step-by-step process.

• Roadmap, collaboration, designer VQA and release synchronization? As easy as it gets managing a single central team.

• API alignment? While crafting components with aligned features and API challenges designers and developers, a smaller group producing React and Figma can figure it out.

Many web core libraries, by a central team

A central team could implement multiple web code libraries, such as releasing parallel Angular, Web Components, and vanilla HTML/CSS libraries.

• Roadmap and collaboration? No different.

• API alignment: Vagaries of different web frameworks can fray API alignment subtly. When they differ, which should Figma assets favor?

• Designer VQA: As frameworks suggest an internal code waterfall, when are the right time(s) for design to test near-complete dev assets?

• Release synchronization: Is it ok to release some web code changes before others? While they remain locked together in a single, synced release, this setup could tempt teams to release one before others.

Code could also diverge due to per-framework conventions, feature requests or fix cadences. However, these low risks can be mitigated by team processes and a single, directly responsible dev lead.

Core libraries across platforms, by separate central teams

A “team of teams” responsible for three libraries serving web, iOS and Android is very common in today’s design systems. More often than not, each platform’s library has a distinct dev lead and or more additional developers. Anecdotally in my experience, web has often 2× the developers of iOS or Android, for whatever reason.

Given the multiple dev teams and leads, things get more complicated.

• Roadmap: Centralized but diversified into groups, persisting a shared roadmap takes a bit more effort.

• Collaboration: Distinct dev leads per “platform team” need their own ceremonies, which can begin to diverge decisions and understanding. Are there routines where designers should participate? Previously “hot potato” behaviors give way to increasing focus on handoffs and specs for provisional decision making. Are all three dev leads in handoff meetings, or do we need multiple handoffs?

• API alignment: Systems must allow for platform-specific conventions, so it’s up to leads to agree on guardrails of what’s shared or not. In this setup, I lean even more into component, property and option naming.

• Designer VQA: A designer responsible for specs gets called back into visually test different platforms at different times. Review timing is less predictable and more disruptive. Tracking needs deliberate attention.

• Release synchronization: The tug of independent releases strengthens considerably, allowing for code enhancements and fixes to release quickly to support business needs.

Once multiple development teams and/or platforms get involved, it’s often time to invoke a “Release individually, communicate collectively” model.

Here, React and iOS could release days or even weeks prior to Android, the Figma library and documentation site. Once Android is done, Figma and doc site materials complete the “Release” and communications across Slack, email and formal doc can broadcast new feature availability to the masses. This strikes a balance between enabling teams that need component code as soon as possible with a system driving (perceived) alignment across platforms.

If the gap between platforms is longer, then releases separate by platform. This is almost always the case when libraries are federated.

Web library by central team, iOS and Android federated

In my experience, it’s less common for iOS and Android to be centrally managed with and allocated with the same dedicated capacity as developers supporting a design system’s web code. Instead, I’m used to coordinating more loosely with iOS and Android library leads. These libraries emerge to serve their “main app,” and the benefit to teams making other apps is a secondary concern at best.

When working with those making federated libraries, ways-of-working diverge far more. Considerations include:

• Roadmap: Very often, the “main app” product leaders get involved. Different interests — deliver a library (my outcome), “main app” integration (their outcome) — become clear. Artifacts to plan, distinguish and connect those outcomes become essential.

• Collaboration: It’s very difficult to integrate federated dev leads into routine (weekly?) handoffs from design to the central dev team(s). Integrating them into critiques that precede handoff? Even more so. Therefore, collaborative value rises to the fore: do these libraries justify a separate handoff meeting? How about a separate planning meeting, and how often (tip: it ebbs and flows)?

• API alignment: In this example, web code undoubtedly becomes the reference library, especially if synced strongly with design specs. However, results are uneven in getting iOS and Android dev leads to use that reference. To that end, I’ll work involve web dev lead to lean into handoffs and coordination too.

• Designer VQA: No different, if spread more widely across the calendar.

• Release synchronization: Releases aren’t synced, and trying to sync them is the wrong focus. Federated releases tend to lag central ones by months, quarters or even a year. So your communication challenge is two fold: set expectations clearly and clearly communicate the status of each item in each library to those that use them.

Case study: IBM Carbon as the federated dream

I’ve not contributed to IBM Carbon, but have watched its impressive progress for years. IBM Carbon supports code libraries across many web frameworks, each with a public code repositories that provide a clear glimpse into it’s evolving catalog.

In 2022, I analyzed commit activity across public repositories of IBM Carbon’s core libraries supporting Vanilla HTML & CSS, React, Angular, Svelte, Web components (now integrated into the core library) and Vue. The libraries emerged over years, with varying levels of activity and growth over time.

Per contributor commits made evident one or few core maintainer(s), additional contributors and a long tail of one-commit wonders.

Conversation with Josh Black, the dev lead in charge of the React library at the time, confirmed that React served as the reference implementation and the other libraries were not supported by the core team and released independently. A recent conversation with current team members confirmed that the central team had taken responsibility for and integrated the Web Components library. Other library implementations live on.

Commit activity across repos visualized over time revealed trends like:

• Some libraries like React + Vanilla and then Carbon for IBM.com evidenced persistent activity, whereas Angular seemed to fade in 2021.

• As React + Vanilla spiked in late 2018 (due to generational change?), Angular similarly spiked as Vue and Web components entered the scene.

• Vue and Web Component activity was lower than React + Vanilla , yet seemed continuous enough to trust each was being maintained.

Despite my best intentions, there are situations where a federated dream is possible. However, my gut says IBM Carbon is more an exception than rule.

Virtually every other design system in the world will not achieve or even aim for IBM’s massive scale. Yet, seeing the models at play — central versus federated, web versus native, growth and strategic change over time — offer lessons we can all take away.

So get at it. Clearly communicate your system’s scope of core library support. Chip away at collaborative best practices to agree on API, critique each other’s ideas, test and ship as one. We’re in this together.

My inquiry of “So, how can I help?” was met with design system distress.

Six months back, the design system team disbanded. In its place, a “federated model” of design and engineering staff (none relieved of other responsibilities) was designated to drive design system progress. Yet, the system stalled. Assets are aging. Trust is shaken. Heads are scratched as everyone wonders what to do. Putting a prospective project at risk, I bluntly responded “Well, you deallocated people responsible for doing the work. What did you expect?”

In 2015, I established three models of forming teams for scaling design systems: solitary, central, and federated. The article progressed through each, scoffing at solitary, considering central, and favoring federated based on the section’s positioning and proportional length.

Since then, design system practitioners throughout our community (see articles as examples below) have leveraged and extended the models to frame thinking, promote opportunities, and sell stakeholders on how and why to pursue systems in a federated way.

Favoring federated was and is wrong. Since publishing nearly a decade ago, I’ve been clarifying, nuancing and even contradicting what I wrote. It’s time to set the record straight.

In this article, I’ll dig into how federated is not a choice, it’s a facet. In practice, it’s never pursued first and never without central investment. In most cases, it’s optional and its outcomes can be so expensive and frustrating that it’s not worth it. Even worse, positioning federated as a primary objective anchors so many stakeholder myths to unwind that it damages system potential and even threatens its existence.

Federated dreams are not most people’s reality

Organizations in general and system practitioners specifically strive to involve people. The “People” part of design systems is essential, effortful and often difficult. My colleague Jina Anne has made that people point in her long running, well known Design Systems are For People talk.

For, of, and by the people?

Couple that focus on people with expectations of governance, and conversations quickly veer into principled territory. A design system shouldn’t be just for the people, but also of and by the people, right? In many mindsets, that implies of and by all the people.

But from a practical and historical perspective, all people making the design system simply isn’t how it ends up working. Design systems I encounter are made by directly responsible, dedicated teams or individual designer(s) and/or developer(s). Aka, “Central people” making a design system as a product, serving products.

Sure, there’s also services supporting a community to steward participation, influence and even contribution (those are different concepts, mind you). Those contributions matter, right? I guess so. However, virtually all productive output is delivered by central people.

Federated-only exceptions distract and muddle conversations

I can hear a few of you now: “I got federated-only to work!”

Sure, maybe in a limited context or temporal endeavor. Those situations are inconsistent with how I define design systems: deliver foundations and UI components via evolving, ideally mirrored design and code libraries that scaling organizations depend on.

Sure, maybe it works if exceedingly rare conditions hold. I’m aware of a fellow expert that combines inarguable talent, sharp intelligence, supreme confidence, and unassailable authority to drive product outcomes without a central design system team. I’ve read righteous claims of a small group of collaboratively-tight, high-performing, coding-capable designers evolving a product without a design system at all (there are systems in there somewhere, nevertheless). The federated dream comes alive!

Federated people don’t and can’t prioritize (extra) system work

However, my experience suggests a different reality. The hope for aligned outputs emerging from independent federated contributors driven by altruism is at best misplaced. At its worst, it’s recklessly naive. I see organizations orient priorities to evolve products, individuals align to those priorities, and no one set aside an allowance for system contribution.

My consulting across 80+ design system spans diverse setups: product or marketing, adopter communities large (100s) or small (10s), design-only or design-and-code, etc. Every organization sought system success and was willing to invest.

How many had a wizard oozing confidence, tight-enough collaborative culture, or other secret that made federated–only magic happen?

In the spirit of Steve Carrell’s memorable portrayal of disdainful expert Mark Baum in The Big Short: “Zero. Zero. Zero percent [of design systems thrived without centrally allocated people to make and support it].”

None experienced federated-only success without a investment in central capacity. Federated-only is not a choice.

Federated is a False Choice

So let’s get to it. Why isn’t federated-only a choice?

The diagram’s arrangement implies choice, unfortunately. Should your design system be centrally managed or a federated community?

The article bridged to federated misleadingly with “if a central model doesn’t fit, there is a more complicated path to pursue…” The implication was clear: choose federated! Ugh. Positioning central versus federated as a mutually exclusive choice was a mistake.

Embracing federated doesn’t mean avoiding central

That’s thinking in binary, described well in Black and White Thinking:The Burden of a Binary Brain in a Complex World. Just because there’s two options doesn’t make them mutually exclusive. It certainly doesn’t mean that if federated is desirable, then central isn’t. Shift that or to an and.

In my practice, successful design systems always have a central team and always seek the participation (and, if worth it, contribution) from a federated community. Evolving models to invest in both to varying degrees.

Being only federated doesn’t work

When discussions get tough, bracket the conversation with an uncomfortable extreme. Injecting an intentionally impractical assertion can establish the value of centrally allocated people:

It’s not as if we should create an empty Figma library file, empty code repository, and empty ZeroHeight instance and encourage contributors to have at it.

Instead, central people setup architecture, create tools, define process, create playbooks, and support the platform. 100% of the time, those central people make and maintain the core components too.

Don’t choose federated. Instead, add federated. Gradually.

As you consider your system’s future, consider how to progressively add federated contribution gradually to a centrally supported endeavor.

If federated work really succeeds, you may even tune down central investment as circumstances permit. A stable and complete core architecture (when the design system isn’t going through a period of generational change) can evolve with federated contributions coupled with a lower investment in central curation. Don’t hold your breath, however. I’ve rarely experienced conditions in the past decade where either stable or complete hold for long, let alone both.

Federated is optional.

Some teams gradually incorporate federated influence, such as via tiers and shared libraries. However, many systems thrive and create tremendous value without a focus on contributions. Some systems even transcend contributions, shedding responsibility to let the community fend for itself.

I revere Atlassian’s design system and have cited the Atlaskit code catalog for years as a vibrant melting pot of contribution. Their community-supported Editor component hit major version 197 recently! Yet, Editor seems a concern now separate from the core system, which explicitly limits contributions to fixes:

We are currently accepting … fixes … At this time, we are unable to take [small enhancement, major enhancement, and new component or pattern] contributions.

Their rationale cites familiar values: build for widely shared need, ensure quality, avoid being a bottleneck. Just because Editor is a component, serving and evolved by a community doesn’t mean it “goes in the design system” (even though it’s clearly in a system). I love it!

Federated Anchors Damaging Myths

Stakeholders anchor assumptions the moment they see that diagram.

An anchoring bias is a cognitive bias by which stakeholders rely heavily on what’s first presented (and how they interpret it), and new information is referenced relative to that anchor rather than considered objectively. This distorts new information, impairing influence and decision making.

Many of those assumptions are damaging myths, including:

⚓︎ Everyone can, should and will contribute.
⚓︎ Every component made goes in the system.
⚓︎ Anyone that makes UI is capable of contributing.
⚓︎ All UI components of any level of composition are welcome.
⚓ ︎Federated contribution is a primary success indicator.
⚓ Federated gets you a design system for free.

When educating stakeholders, you want to be on the front foot. You want to confidently build a rational case so they understand impacts, opportunities, risks and efforts ahead. You don’t want to position yourself as saying “No” repeatedly to correct mistaken assumptions of superiors that approve or deny the system’s existence.

So, you face a choice: let the anchored myths stick, or contradict your stakeholders and unwind the myths. Weighing anchor is difficult, effortful and worst of all, risky. Let’s dig in to each one.

Myth: ⚓ Everyone can, should and will contribute.

Fact: Few if any contribute meaningful new features and enhancements.

Wait, if almost no one will contribute, then this isn’t made by everybody? 
(Yes.) 
That’s bad.

It can be very, very good to have central team makes a library everyone depends on. A central team can focus on details, solicit shared needs, architect small parts into a cohesive whole, document and release it, and support others. Federated people don’t, can’t and/or won’t do that.

Myth: ⚓ Every component made goes in the system.

Fact: Almost all components made across teams don’t belong in the system.

Wait, so the system will have barely any components our organization makes, and most of the UI everyone makes isn’t going to be shared? 
(Yes.) 
That stinks.

Design systems offer assets that serve widely shared needs and prioritize features that can evolve in a stable way to serve many groups.

You should expect that teams will still need to create considerable UI using system assets. You should also expect that most components that teams make — even low level components — will not serve a need shared by other teams, and thus don’t belong in any system.

Myth: ⚓ Anyone that makes UI is capable of contributing.

Fact: Most contributors lack systems experience generally and knowledge of this system’s architecture specifically to contribute efficiently.

Wait, so people can’t contribute because you say they lack skills? 
(Yes.) 
That’s terrible gatekeeping and risks morale.

Design systems are about business value. If the cost to steward a contribution (effort of all participants plus maintenance and opportunity costs) exceeds business benefits (value of reusable assets and staff personal development), then the contribution is a bad idea. Only do it if it’s worth it.

Additionally, identifying directly responsible individuals (DRI) and teams leads to the clarity needed for a satisfying workplace. Positioning capable and talented staff in DRI roles is a strength.

Finally, central systems practitioners are responsible to support system integration, pair with others, and curate contributions that do arise. Sharing knowledge and resolving incidents responsively are ways of how system practitioners can be a rising tide lifting everyone’s capability.

Myth: ⚓ Components of any level of composition are welcome.

Fact: Design systems are visual foundations threaded through a library of usually lower-level UI components that equip teams to compose digital experiences on their own teams.

Wait, system UI components are limited to a bunch of low-level widgets? 
(Yes, at least in the core library.) 
That’s lame and lacks business value.

There’s a ton of business value in that. Have you seen what goes into a system’s button, alert , textInput or modal? Each relies on 10s or 100s of visual attributes across a component’s anatomy, property configurations, layouts, behaviors and other stuff. That’s measurable work, done at a high-level of accessible quality, packaged as design and code libraries so that other teams don’t need to make that stuff.

Myth: ⚓ Federated contribution is our primary success indicator.

Fact: Core libraries made by a central team and containing no contributions from outsiders can be extremely valuable.

Wait, if our goals are to make a library and enable other people to use the library, how does users that contribute to the library matter?
(Exactly.)
That feels wrong.

When semi-annual or annual planning season comes along, federated contribution is rarely a published objective and never an existential one focusing a significant proportion of central people’s capacity (although efforts to like Figma Shared Libraries are pursued secondarily).

Instead, federated investments are often on the periphery, deprioritized in favor of other efforts. It’s never a galvanizing singular focus of a system’s team relative to responsible people making system outputs and enabling others to successfully use them.

Myth: ⚓ Federated gets you a design system for free.

Fact: Successful federated activity requires a non-trivial capital expense and ongoing operational costs to make and maintain a platform, support federated people, and curate contributions. It’s not free.

Wait, so I need to pay for a group of people to build a platform and make it all work when seconds ago I thought this was largely free?
(Yes.) 
That’s expensive.

Going federated in the long run means more than composing a designer’s playbook (often not read) and developer’s CONTRIBUTING.md. There’s far more work needed.

Once built, using platforms isn’t a long leap for developers. Coding in systems should be familiar: build modularly, manage dependencies, run test suites, commit to repos, review a pull request. Tasks are familiar (if with some system spice) such that once setup, running a platform can be predictable. However, there’s still the work of curation, quality and approval for core engineering maintainers to do.

Familiarity is less true for designers, where diverse tasks carry unfamiliar system-specific expectations. Audit and synthesize shared needs. Compare existing component examples. Devise an API. Document usage. Produce and test high quality Figma assets. The bar is higher and skills are different than “normal product design work.”

Learning takes practice and collaboration time with system experts (read: operational cost) to produce good things and grow individually. I love that work, which offers tremendous intrinsic reward. But it’s time consuming. You reap what you sow.

Did you notice how verbose it is explaining away those myths? Did you even read the text above, or did you skim it as your mind drifted?

Now, imagine you are a stakeholder that had to listen to someone — often lower level or from a different group — contradicting what you believe. So be careful. Explaining what you don’t get with federated contribution isn’t just complicated. It risks irritation, boredom, distraction, insufficient time, indignation, and dismissiveness. Such emotions are not to be trifled with.

References to Central v Federated Models

The following posts all reference the concepts of central and federated models described in Team Models for Scaling a Design System.

1. The Salesforce Team Model for Scaling a Design System by Jina Anne, 2015

2. Designing a Design System (a step by step guide) by Louis Henrich, 2017

3. Scaling Design as the Company Grows by Ian Armstrong, 2018

4. The Paradox of Design Systems by Brendon Manwaring and Josh Mateo, 2018

5. Tips For Managing Design Systems by Nick Babich, 2019

6. Design Systems: Why Do They Matter? by Marcela Morales, 2021

7. Remarkable UX Design Teams by Isadora Agency, After 2019

8. How do teams work with your Design System? by Raktim Chatterjee, 2022

9. Is your design system performing? by Alicia Cheung and Rebecca Holland, 2022

10. Design Systems: Investing in the People Behind the System by Reneé Cagnina Haynes, 2022

11. From Vision to Reality: The Roadmap to Building an Enterprise Design System by Oleksii Popovych, 2023

12. Opening up the Design System for Everyone — The Federated Model by Anirudh Hothur, 2023

13. Implementing a Design System in an Existing Product byJustyna Klimkowska, 2024

14. The merits of design systems by Balanet, 2024

15. ROI of Having a Design System by Kim Nguyen, 2024

16. How to build effective enterprise design systems for your company by Webflow, 2024

17. Design System: Pancake by Mikhail Belstar

18. Keeping design system contributions in check by Wart Burggraaf

#3 of 5 of the series Design Systems Generations:
Defining | Planning | Adopting | Naming |Retiring

What’s changing? All colors, typography, space and component designs. 
Why? Because executives decided to.
How big is the change? It’s big. More a revolution than a refinement.

Now that you’ve painted the big picture, it’s time to talk specifics. What does all this mean to how adopters must change? Each adopter’s questions reveal the bias of they may see their world:

“When can we start?” (→ Eager)
“By when must we be done?” (→ Pragmatic)
“Do we have to? What if we don’t?” (→ Reluctant)
“What if we didn’t use your system to do it?” (→ Individualist)

These questions aren’t complicated. Unfortunately, answers can be. Harried product owners and leaders may not be interested in what to them feel like complicated conversations. For generational changes, answering sufficiently requires you understanding who’s asking it and their patience to listen. Both may be in short supply. Under pressure, they just want to get on with it and see a system as blocking them from delivering the goods. Heck, will they even wait?

This post covers common challenges that emerge when aligning how a design system deliver changes to adopting teams to integrate that change into their experiences.

Challenge 1: A system IS a dependency. Or, lots of them.

When keen adopters ask “How long?”, you can’t keep responding “We’ll let you know.” A system generation may take three, six, twelve or even more months, and you must have a plan to clearly communicate. As you start to explain things, reality sets in. You deliver things like colors and components to them, and then they integrate them. That puts the system in a position of being “The Dependency.”

Yet, a design system library is made of many subsystems and component parts. That means you can decompose delivery into a succession of dependencies as relevant for adopters.

• Adopters must be encouraged to start before a system is done. To deliver incrementally means they could integrate incrementally too if it helps.

• Adopter should influence priorities to get what they need when they need it, which may give the system more time for other things too.

• Adopters could finish before the system finishes, since the system can defer features many don’t need to the end. Wouldn’t that be delightful?

Takeaway: Be generous with the time you invest in crafting, sharing, aligning and nurturing plans with adopters throughout the cycle. Critical is a shared sense of purpose in delivering value to end customers. We’re in this together. So let’s figure this out and deliver as best we can, together.

Challenge 2: The system HAS dependencies

What’s more challenging than the system being a dependency? A system that has dependencies causing it to move slowly, wait, or not even start.

A typical example: the system team may be blocked by an agency hired by design and brand VPs to establish a new design language. The agency may iterate, concept after concept. Delays arise when stakeholders schedules don’t align. Iterations continue to get things just right. Nobody seems to acknowledge that all the iteration impacts timing of delivering downstream work.

The system team may not control any of this. Heck, the system team may not be in many of these conversations. Such opaqueness and uncertainty can feel paralyzing. Even worse, it’s the system that seems “The Blocker.”

So, to serve adopters best, shift the mindset to getting “The Head Start” instead. Getting a head start can include:

• Quick passes to inject emerging design language choices into existing system assets to show the future (and expose gaps from here to there).

• Explore refactored system models — token taxomony, expanded modes, a spike of component code — based on emerging designs even if those designs are unstable or disposable.

• Coordinate with upstream providers to deliver incrementally, too. Could they finish color language before optimizing typography? Could semantic colors be delivered before data visualization palettes?

Takeaway: Challenge yourself to start the system engine without waiting for dependencies to finish. Possible setbacks and wasted work occur. That’s the game you play. But when time is short, it can be worth the risk.

Challenge 3: Adopters may be unwilling to wait

Separating an agency’s design language activities from a system team’s library production exposes most dangerous misperception: Once a design language is approved, adopters can get started, right? Not so fast. Most of the system team’s work to finalize, code, test and produce library assets may be just beginning.

Will adopters wait? If they don’t, what if they deliver the design directly themselves? When an external force triggers change, speed to market creates pressure on adopters to implement without system assets. They’ll push the system to the side or ignore it altogether. “It’ll look the same, right?” seems, to them, a reasonable compromise. If waiting for a design language is paralyzing, becoming “The Ignored” system is even worse.

This behavior may seem consistent with the first part of my third principle of my 2017 Principles of Designing Systems:

Products own their destiny…

Yet, design systems promise much more than making disparate experiences “look the same.” In this moment, the system must educate partners on tradeoffs grounded in system principles. If the adopter ignores the system, outcomes include:

• Redundancy to produce features the system team will also deliver.

• Inconsistency with a system when adopter implements an incomplete and often unstable design language the system ends up refining.

• Poor feature quality (such as accessibility) and completeness (such as states and variations) when they cut corners. Which adopters will.

• Inability to upgrade as the system delivers, fixes and extends features.

You don’t have come in too heavy handed, like:

“So, to be clear, you want to be the product building redundant, lower quality, incomplete things inconsistent with the other products? To be fast? Got it.”

I mean, you could. But you probably shouldn’t. And you shouldn’t need to. Instead, this is when I’d bridge to the second half of that principle:

…systems equip products to realize that destiny.

Unfortunately, “The Wait” — the time between the design language being complete and the adopter able to use system assets to achieve their destiny — is real, impactful, and largely out of an adopter’s control.

Design system planners must minimize “The Wait” to best suits interests of that adopter AND the organization overall to:

• Order features based on (prioritized) adopter needs.

• Prioritize minimum viable features, such that upgraded features not needed now can be delivered later but not impact component API.

• Delivering useful but not yet fully tested features so that adopters to can start implementing and the system can follow with stability and robustness later.

Takeaway: Assuaging the fears and tamping the tendencies of impatient adopters is hard. So equip yourself with talking points of system rationale, patience to tread difficult conversations, and peace in the control you don’t have over the decisions they make. But you can control what you deliver how well by when, so get to work optimizing that with your partners.

Challenge 4: Adopters fear migration is too complicated

Of course you’ve planned for roadshows, training materials, playgrounds and automations to help adopters bridge from here to there. Yet, the work ahead may feel daunting to even talented designers and engineers.

When work looks hard, unfamiliar, complicated or a distraction, that can lead to a “Rough Start.” Teams may delay getting going. Once they do get going, their progress seems slow and stunted.

Would you be willing to help get them started? In vast ecosystems across a big enterprise, the design system team isn’t responsible for integration work. However, system experts can be well equipped to demonstrate work in context rapidly, such as in the form of “Kickstarts” large and small.

Examples of kickstarts include:

• A front end system technologist migrating a flagship product from using old variables to new tokens in what becomes a massive pull request full of small edits. Ed, you rule!

• A system Figma-expert branching other team’s shared libraries, converting select components from styles to variables, and using outputs to train those library owners to do the rest. Plus, take learning outcomes back to improve system docs too.

• A system advocate auditing an existing build — whether code or Figma — to identify examples of items to upgrade or swap, impacts to API, and tips on how to order the work.

Kickstarts aren’t for everyone and require available system team capacity, adopter priority, and adopter interest. Plus, let’s be clear: the kickstart doesn’t do all the work (well, Ed’s did, but that’s because Ed is awesome). Usually, a kickstart can quicken integration in most-impactful places. Benefits go both ways, since the system can learn lessons that lead to improved features and documentation, too.

Takeaway: If willing and able, ask “How can we help?” Even if you have to say no to some ideas, conversations can lead to partnerships benefitting both and remove a fog of fear of how new things work.

Challenge 5: Adopters coordinating launches, particularly a big bang

When working with many adopters, a few things become clear quickly:

1. Adopters often start integrating at different times.

2. Adopters often launch integrations at different times.

3. Adopters may not coordinate when to launch integrations in concert, but are expected to launch in concert nonetheless.

4. Adopters own their own roadmaps and backlog, it’s often already full of other priorities, and it’s up to them to fit the system in.

Typically, the design system doesn’t own, drive, or is accountable for any of these decisions or outcomes. That’s up to other stakeholders, leaders, and business units that the system serves.

Adopter roadmaps and coordination are out of the design system’s control, but are certainly within the system team’s influence. In particular, I would expect that the system team is often best positioned to:

• Identify opportunities for and gaps of adopters lacking alignment when the should be (even if the system isn’t responsible for resolving them).

• Equip adopters launching in concert with shared needs that serve all of them, such as timely ongoing assets, updates and fixes.

• Communicate needs emerging from one adopter that are relevant to the rest of them, such as an updated logo, refined token values, or revised standard content (such as footer legal and link content).

Takeaway: You want a seat at the table? Then provide the value through mindful participation, helpful hints, and assertive problem solving when systems can have positive impacts. Just as much, don’t bear responsibilities you shouldn’t, such as product managing a coordinated launch across stakeholders you don’t control.

In summary, coordinating with many independent, self-interested adopters can be complicated and challenging. Turn those challenges into opportunities by being helpful to redirect and reorient conversations with:

• How can breaking down what we deliver help you?

• How can we integrate with upstream activities to move faster?

• How can we get you enough so you can get started?

• How can we help kickstart your efforts?

• How do your efforts relate to other teams?

All those questions — and, hopefully, useful answers and conversations that follow— demonstrate you are as interested in making them successful as you are in getting your token taxonomy and component API done.

Next: #5. Naming a generation

#2 of 5 of the series Design Systems Generations:
Defining | Planning | Adopting | Naming | Retiring

Changing the entire library is a daunting challenge. It takes months of work. Sometimes, over a year. Updates and refactors ripple across a catalog of complicated, interdependent features. Waves of tasks and reviews wash across disciplines and stakeholders. Brave early adopters crave access to anything as fast as possible to get work done. You burst ahead. Then backtrack and refactor as you learn. The scale of work is immense.

Design system leaders and managers, don’t fret. A well-devised plan can guide work across phases, deliver it gradually and communicate clearly at key milestones along the way.

This post describes a high-level approach to steward a design system’s library through a significant, generational change. Once demos and planning enable an organization to commit to a strategy, work on the implementation can progress across phases to deliver the library. Along the way, you can apply tactics to assign, group, and order the work. Once complete, launch the library while taking the previous generation through deprecation and end-of-life activities.

The Strategy Phase

Whether triggered by external needs or system-driven pursuits, a strategic phase can shift from discovery into agreements across concurrent tracks to explore directions, align stakeholders, and plan an implementation.

Common activities

• Discovering needs through gathering requirements, interviewing stakeholders, and auditing existing systems and backlog(s).

• Exploring potential future(s), whether evolving a visual language and/or coding proof(s)-of-concepts via technical spikes.

• Planning who will make what, how, and by when.

• Aligning stakeholders with explorations and plans to generate awareness and foster agreement.

Defining done

A strategy phase is done when all stakeholders align and commit to the plan (the “Commit”) to implement what’s been explored and demo’ed.

A strategy phase’s explorations can cascade into implementation. If the latter starts before the former ends, that’s fine. The planner’s focus should be on confident commitments and a clear path forward.

The Implementation Phase

The implementation phase produces the complete library and always progresses over multiple phases that end with meaningful milestones.

Over the years, I’ve settled on progressing through two periods:

• Alpha(s), where a few features (Color, Typography,Icon, Button, …) evolve sufficiently to demonstrate how features will be built.

• Beta(s), where enough features are built at sufficient quality and stability to permit production use by interested and willing adopters.

Common activities

• Regular progress demos, particularly influential community members.

• Regular status meetings to monitor doneness of features and outputs

• Per-milestone communications to show progress, generate excitement

• Pilots and testing cycles to validate approach, changes and migration

• Revisiting and refactoring completed portions based on what you learn

• Pre-launch teaser and expectation-setting communications

Defining done

The library “goes beta” when enough components are available at sufficient, production level quality that early adopters can use them with confidence. Implementation overall is complete when the library exits beta and launches as generally available.

Implementation Tactics

Augment main milestones with incremental delivery

The larger the scale of work, the longer it takes. As a result, break work down into milestones to communicate at key moments and incrementally deliver otherwise.

In recent years, the simplest “redesign” implementation I’ve led included an alpha release followed by three betas, roughly by month, before launch.

More often, a “redesign” cycle lasts nine to twelve months to deliver, with more alpha and beta moments to incrementally deliver the work.

Consider important moments across milestones. For example, one output (such as a documentation site) could emerge visible to all adopters for the first time later than other outputs (such as a published Figma library and Storybook docs).

Use dependencies to order the work

A complete generation of a library can include anywhere from 10 or 15 to upwards of 100+ components. How do you decide how to sequence the work? Certainly, you don’t start at A and end at Z.

In general, a component library is made or remade from small to large. It’s difficult to consider larger things complete if the smaller things they depend on are incomplete. Therefore, mapping the tree of a library’s dependencies directly informs how you order the work.

Simple components like Breadcrumb and Tabs have no dependencies. You can do those whenever. List Group ? That’s another story. It depends on Checkbox (if you have checkable items), which depends on Form label which depends on Tooltip (in a few systems I work on) which depends on Icon. Many paths trace back to Icon, so tackle that in the first batch.

Large libraries, particularly those with subcomponents, result in dependency tree maps that are complicated, difficult to create and annoying to maintain. Therefore, treat it less formally. Until you automate such diagrams, avoid perfecting and maintaining it. Instead, capture these relationships into a tool better equipped for it, like a spreadsheet or task management tool like Jira or Asana.

Group and assign based on dependencies and shared attributes

Don’t let the tree diagram deceive you. Arrange features and groups to respect dependencies while prioritizing and grouping effectively. For example, Button is needed early, resolving Text input opens the door to finish other form components, and Breadcrumbs are both isolated in layouts and a low priority. Order batches accordingly.

However, features are made by people. Distribute and assign across staff while respect dependencies, grouping components with similar attributes and aligning assignments with their interests.

In the revised example, designer 1 is clearly the “forms designer.” Early yet complicated considerations on Tooltip give way to doing Label and Error to deliver Text input and finishing batches of “selectables” (Checkbox, Radio button and Toggle) and other stuff.

Designer 2 focuses on Icon and Button, throws in “easy” components like List unordered and Breadcrumb along the way, and is responsible to deliver what can be a behemoth List group later. Notice the limited number dependency connectors between assignees, minimizing the risk of one blocking the other.

Feature assignments are now roughly equally distributed by effort, clearly divide work across teammates, and respect the flow of dependencies. Assuming both deliver as expected, that is 😉.

Increase feature quality, quantity and stability at different rates

As implementing a full generation of a design system progresses, component quantity, quality and stability increase across phases differently.

Such enable you to frame the alpha, beta and GA moments of a cycle:

The alpha release includes a few unstable features that, while of unproven quality, sufficiently demonstrate how things work.

The first beta release includes many increasingly stable features built at sufficient quality for production use.

The “GA” release includes every feature, completely stable at highest quality.

Feature quality starts high and stays high. System practitioners tend to consider architectural precision, usability, accessibility, performance and within library consistency as nonnegotiable. I love that about them. Yet, defects occur. Missed details need correcting. Perfection can become the enemy of progress. Quality compromises matter less for an alpha, but they will impact adopters delivering production work. So set expectations that quality need not be perfect early on, and that OK. Instead, focus on a vital inflection point: beta. Once the library is available for beta, early adopters must trust quality is good enough for production work.

The quantity of completed features resembles an “S curve” over time, accelerating gradually before flattening as launch approaches. An alpha need only include a few components. Then, the team churns out more and more, faster and faster. However, as launch approaches, perceived production can slow because:

• Focus shifts from making things to testing and documenting things

• Later components can be larger and more complicated

• Feedback necessitates revisiting things already considered complete

Each feature visual and API stability increases over the course of implementation. Yet, reversals happen. As you make more, expect to revisit things already presumed done based on what you learn. A commitment to a stable API need only be ironclad by launch. Some choices, like a component’s name should be stable as it’s introduced. On the other hand, property API, layout and visual detailing should be allowed to shift. During the cycle, a system team needs space to zoom out, compare and evaluate patterns and normalize them across features.

Each organization will define their own definition for how complete, stable and good a system is in each phase. Regardless, by the time you’re done, adopters need a generation that’s complete, stable and well made.

Report on work using a doneness matrix

Once work is scoped, planned and underway, the most concrete single visual I’ve used to summarize progress is a doneness matrix. The primary structure is top level tasks and/or outputs as columns, features as rows grouped by type (Foundations, Components, Patterns) and ordered by release milestones (Alpha, Beta 1, Beta 2…).

Unfortunately, it’s difficult automate producing this matrix in task management tools like Jira or Asana (although creating custom fields as columns in a release board can go a long way). Otherwise, it becomes a manual process to update a table maintained in Figma, Confluence or a presentation slide.

Launch and General availability (“GA”)

The formal launch. This “It’s done and ready for everyone!” moment is reinforced by heavy communications and can be followed by a brief if intense “warranty” period. Don’t dismiss how much adopters expect a system team to train them, help solve problems, and fix things.

Common activities

• Launch email, Slack and other notifications

• Live demos tailored to broad and diverse audiences

• Celebration(s) with parties for the system team and friends

• Training deep dives focused on migration and new capabilities

• Shifting system team capacity temporarily to favor more of support and consulting over less of “delivering the next component(s)”

• Taking a breath, calming the nerves, and letting the team recharge as plans for the next things shape up.

Defining done

A launch period ends when design system practices settle back into “business as usual” (BAU). Incremental work enhances what’s there, offers new things, and breaks smaller things slowly as needs require.

But, for most, periods of smaller, incremental change doesn’t last forever. Another generation shows up on the horizon, and…

Periods of generational change are the biggest, most momentous moments in the life of a design system. By planning and communicating how you’ll progress across phases of strategy, implementation and ultimately end-of-life, you set expectations and enable your partners to plan accordingly. Best to you and your team as you prepare for that next, big moment!

Next: #3. Naming a generation

#1 of 5 of the series Design Systems Generations:
Defining | Planning | Adopting | Naming | Retiring

You’ve made a library. Users adopted the library. The design system has settled into an operational rhythm. Days, weeks, and months go by as your design system kicks out new features, smooths rough edges, and help teams along. Then, the whispers. Something is afoot. Is that a VP working concepts with an agency? Is IT grumbling about frameworks? Something...

Bang! “It’s redesign time!” “Our visual foundation is stale!” “We’re shifting platforms!” “We’re switching from {this} to {that}!” Just like that, it’s time for the next generation of your design system. The entire library is in play to be made, delivered, and implemented (again) across adopters that upgrade immediately, sooner or later.

What is a generation, anyway?

I’ve been using the term design system generation for years, although it’s not a term used evenly and regularly across our community:

Design system generation: a stable and sufficient core library of assets, docs, tools and practices delivered for use by designers (in Figma?) and/or developers (React?, iOS?, Android?, …).

A new generation generally means:

1. The entire library’s features — “All the things” — can be impacted.

2. Upgrading requires attention yet may or may not be effortful, depending on the scale of breaking change, tooling and regression required.

3. Changes require aligning with partners like brand and/or architecture.

4. Because things are breaking, it’s time to revisit a backlog to do things a system couldn’t do before so as to not break things.

5. Other system work slows or stops, crowded out by the focus on updating “all the things” and enabling adoption.

Delivering a new generation is the largest, most complicated cycle a design system goes through. The system and its adopters may live with the outcome for years. Therefore, everyone must understand what it is, why it’s happening, and the scale of the effort and reward. This introductory post explores the big questions that define a generation:

• Cause: Why are we changing?

• Scope: What is changing?

• Scale: How expensive is the change? How big is the impact?

Equipped with high-level answers, you can orient your team, set expectations across an organization and start planning.

Cause: Why are we changing?

A design system’s next generation can arise from one of many triggers, including a system’s need to:

• Start from scratch as a “first generation,” because no library exists.

• Redesign features like foundations and components, such as a rebrand.

• Rearchitect features like tokens and component API extensively to support new capabilities, evolve with tools, or right all the old wrongs.

• Switch framework like going from Angular to React or Sketch to Figma, or possibly framework version, such as React 16 to 17.

Not every library-wide change is a “next generation,” however. Improving accessibility or adding component density and sizing controls across a catalog are considerable improvements.

Sometimes, the term generation doesn’t apply: a framework version update or a partial foundation overhaul also may not qualify. The characteristics of a rollout are the same, but at a far lower scale. Such library-wide fixes and enhancements are certainly worth communicating but fall short of the fanfare of a “next generation.”

Who’s driving change: external forces or the design system itself?

Sometimes change is triggered from a system team, other times the change is thrust upon a design system. Both types of triggers — external and internal — come with tradeoffs.

Brand updating a visual identity and IT norming on a “north star architecture” are examples of externally driven generational change. In these cases, a design system has no choice but to “hitch to the wagon” (credit: Alex Skougarevskaya, one-time Atlassian Design System design lead) to enable the outcome.

External forces make things complicated: executives decree timelines, other groups create plans, stakeholders unpredictably communicate. Amid the chaos, a design system can struggle for control. System aspirations can be lost in the din. Therefore, it’s critical to take a “seat at the table” to influence emerging design and the system’s role in implementation.

Communicating priority of generational change to adopters is easy when externally driven: they’ve heard about it, can’t object to it, and may already be planning for it. However, that pressure is double-edged: adopters may be unwilling to wait. A design system’s work translates and encodes a design language into reusable bits. That takes time. Communicating long term values — efficiency, quality, consistency — of that translation is essential to avoid adopters rushing to hardcode answers themselves.

On the other hand, generational change can be internally driven by the system team without external pressures. Stale visual language, outdated architecture, or unachievable new capabilities all drive change. There may be no broader wagon to hitch to, but why wait? There’s no reason a system team can’t rollout big changes themselves.

Adopters are less likely to request generational change, and can resist it once cognizant of the effort required to upgrade. When internally driven, system-led activities require more attention communicate scope (“What you get!”), process (“How to get it!”), and benefits (“Why it matters!”). For example, the design system may target advocates across design and development communities to present explorations, agree on API, and support pilots. Without a galvanizing external force, it’s the up to the system to form groups, drive consensus, and communicate outcomes.

Takeaway: Ensure you—and your team — know who’s driving the change in order to orient what role to play, what posture to take, how flexible to be with your time and how assertive to be when driving decisions.

Scope: What is changing?

Generational change opens minds. Moments that sweep change can lead teams to (re)consider everything they’ve ever wanted to do. It’s all on the table: new features, platforms, tools and ways of working.

Foundations and components … and other stuff?

Usually, adopters expect a new design system generation to refresh visual foundations (implemented as a token taxonomy) and UI components across the catalog. These updates can cascade to UX patterns, page layouts and templates. Less certain is the overlap of design and content, where a new generation may or may not impact content standards and practices.

This generation will update all components with a refreshed take on color and typography that means a new design token taxonomy. We expect minimal impacts to space and size, although shape is in play. Existing standards for accessibility and content (like voice and tone) aren’t expected to change.

To describe feature scope, use visible models that customers are familiar with. For example, sections and oft-used pages of a documentation site provide a foundation to succinctly describe change.

Takeaways: Establish boundaries of what is in and out, balance aspiration with time, resources and customer needs and take opportunities to expand the portfolio

Design assets or code packages or both?

Most generational moments synchronize change across design assets (like a Figma library) and code (like React, Angular, iOS and Android).

However, sometimes a generation can be output and discipline specific. For example, imagine shifting a Figma library from using props to variable/modes to enable color theming. Designers have a whole new model for fundamentals, yet code isn’t impacted. Alternatively, a system may update a React-based code library to support only React 17 and above. Developers must make careful updates, yet designers have no work to do.

In both cases, the work carried all the hallmarks of a generation: touch “all the things,” break and deprecate some things, slow the BAU work, and communicate heavily to system customers. Ironically, in this story, those events occurred at the same time in the same design system. The only overlap of this big moment was to balance program-level communications when they released simultaneously.

Takeaway: Generational change need not impact both design and code, libraries and docs all at the same time. Sometimes, it’s narrower to only one library or one type of output, and that’s ok. Just make sure each audience gets the message(s) they need.

Just docs content, or the publishing platform too?

When features change, so does documentation. The scale of copy, images and examples updates can feel like an approaching slog, but a familiar and predictable slog. Adopters, too, expect the system to update feature documentation. On the other hand, adopters fear is their ability to consume the changes cleanly.

So get past the conversations about “What are we doing with Foundations and Components content?” Get to the richer topic of how you’ll prepare adopters to change through documentation. Upgrades must feel straightforward, easy and risk free. Getting started, procedural migration guides, self guided training materials and demo and playgrounds can carry big payoffs. Done right, they also require meticulous attention and iteration to smooth out rough edges. As you set expectations about your big changes, it’s essential to think through and communicate all you’ll do to enable their changes too.

A generational moment also zooms a team out out to challenge platform assumptions, too. Beyond new content, does documentation need…

• …a site design refreshed to match the new visual foundation?

• …an overhaul to how to author, manage and publish content?

• …to migrate to or from a platform like ZeroHeight, Storybook, … or both?

Any of those transitions will be a major project within a major project (delivering a generation), warranting considerable strategy, planning and communication. Must you pursue any of them to deliver a new generation? Often, no. Should you consider pursuing some of them? Usually, absolutely. Bottom line: generational change usually impacts both and work typically exceeds a simple, fresh coat of paint on an existing site.

Takeaway: Use generational moments to challenge both what and how you publish docs of both what to use and how to change.

Tools and practices

Generational change in a library may be coupled with— or even require — changes to how a system approaches:

• Testing practices, such as Figma component testing, automated visual regression, unit testing and how you integrate accessibility

• Releasing pipelines and practices, such as new places and locations to publish assets or stewarding users through alphas and betas

• Ways-of-working for system makers and adopters and tooling in which they collaborate (such as Jira or Asana)

• Communications throughout implementation and past launch (including email distribution lists and platforms)

Such changes also present as projects within a bigger project. They can be disruptive, unfamiliar, and risk consuming considerable time (such as when licensing third party tools or getting security approvals).

Takeaway: Think upfront about potential new tools and practices rather than organically realize them as you go. Set aside session(s) for the team to explore implications and ambitions that change how the system works.

Scale: How big is the change?

When characterizing change, focus how the change matters to adopters:

• What’s impact of what I get?

• How much will it cost to upgrade?

When upgrading is hard, focus on core and long-term values

Generational terms like “redesign” and “refactor” trigger costs and fears of major changes. Whether a visual overhaul, transition to Figma, or a wholly rebuilt React library, impact may be massive but the switching cost can feel daunting, even paralyzing.

If you are hitching to a wagon carrying the whole organization, teams tend to bow to efforts that seem non-negotiable. There, the system has an opportunity to be perceived as a solution enabling, not albatross preventing, of realizing of that value. When the trigger is internal, the system must communicate how the generation makes an adopter’s present even better and/or describes a now-possible future that previously felt impossible. Let the slidemaking commence.

If upgrading can be easy, make it so and say so

Other times, impacts can be positive and catalog wide, but change costs are limited. At Morningstar, I led the delivery of a second major generation in 2018 refactored all components to synthesize sizing and support varying densities. Sure, every component technically had a breaking change. All the version numbers bumped to a next major version. But developers could integrate updates mostly using search and replace with little fuss.

More recently, I led a team to refactor the Figma library from color styles to variables to ease setting light and dark themes. Fill and stroke color attributes changed across the catalog. Over half of the component assets (including all with a surface property set to dark) were deprecated. Yet, upgrades were trivial (click “Update”), broke nothing in existing files, changed nothing visually, and made finding and swapping deprecated versions a breeze. Developers, apart from interpreting files differently during handoff, were not impacted.

Was the variables switch a next generation? Depends on how you want to apply the term. For tools? Definitely. It reinvented how to apply and use fundamentals, setting a new baseline to grow from. For fundamentals features like core colors and typography? No, those didn’t change.

In both cases sizing/density and variables, communications focused on what adopters got and how not hard and not risky it was to change.

Takeaway: Adopters will compare what’s in it for them with how hard change will be. Relating the value a system enables to the costs it incurs is something you must do succinctly, clearly and honestly.

From the outset, clarifying what will change (scope), why it’ll change (cause), and how big a change it’ll be (scale) is essential. Once those broad strokes are defined, it’s time to dig into how the system will align everyone to a vision and strategy, get the work done, and launch for adopters to use.

Next: #2. Planning a generation

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.