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.

Originally published at https://nathanacurtis.substack.com.

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:

• 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.

Make the common configurable, make the uncommon composable

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 Pillselected'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!

Originally published at https://nathanacurtis.substack.com.

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.

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.

Originally published at https://nathanacurtis.substack.com.

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.

Originally published at https://nathanacurtis.substack.com.

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!

Originally published at https://nathanacurtis.substack.com.

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.

How you align design and engineering and synchronize releases depends on the frameworks, platforms and teams involved

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.