Figma Component Variants and Properties: A Library Guide

A Figma component set can become enormous without becoming more useful. If every icon, label, state, and content arrangement becomes a separate variant, maintainers spend more time aligning frames than improving the system. The goal is to expose supported decisions while keeping ordinary content changes easy.

Inventory the decisions consumers need

Start with actual usage from two or three product screens. List which differences change the component contract and which merely replace content. Size, emphasis, and layout may deserve deliberate options. A button label usually does not require a new variant for every phrase used across the product.

Use the JSON Formatter to inspect a draft property inventory shared with developers. Represent each proposed axis, its allowed values, and its purpose in JSON, then format it for review. This is a discussion artifact rather than an automatic representation of every capability in Figma.

Establish a property budget as a review prompt, not a rigid universal limit. If a component needs many independent controls, ask whether it combines multiple concepts or exposes implementation details that consumers should not manage.

Choose the right property mechanism

Use variants for meaningful alternatives that need distinct configurations. Use text properties for editable text, boolean properties for intentional visibility controls, and instance swaps for replaceable nested components when appropriate. Check current capabilities in the Figma Help Center before building workflows around a feature your plan may not support.

A variant axis should have a clear sentence behind it. “Emphasis changes the visual priority of the action” is understandable. “Type changes between several unrelated layouts” signals a component boundary problem. Avoid a catch-all option that accumulates every exception requested by product teams.

Separate content flexibility from layout promises. An icon slot can support approved icons without guaranteeing that any arbitrary nested illustration will fit. Record expected dimensions and alignment behavior for slots so designers and developers interpret the same control consistently.

When considering implementation, consult React's composition guidance for how content and configuration differ in code. The design property model need not mirror framework syntax, but it should not imply combinations the public implementation cannot support.

Write a supported configuration contract

Document allowed combinations before multiplying variants. For a compact action, you might support two sizes and three emphasis levels, but reserve loading as a state controlled by behavior. If a property is design-preview-only, identify it explicitly so consumers do not expect an equivalent production prop.

A review record can distinguish these concerns:

{
"component": "Action",
"axes": {
  "size": ["compact", "regular"],
  "emphasis": ["primary", "secondary", "quiet"]
},
"content": ["label", "leadingIcon"],
"previewStates": ["default", "loading", "disabled"],
"unsupported": ["icon-only-without-accessible-label"]
}

This schema is illustrative and should be adapted to your actual API. The last restriction is a usage requirement, not something the JSON itself enforces. Link the exact implementation contract from the component description.

Use state boundaries carefully. Hover, focus, pressed, selected, disabled, and loading are not interchangeable labels. A design preview can display these conditions, while code may derive them from browser interaction or application state. The WAI-ARIA Authoring Practices helps distinguish interaction patterns without turning your component set into a substitute for behavioral documentation.

Test resizing, overrides, and nesting

Build a test page that places instances in narrow and wide containers. Replace short labels with long translations, remove optional icons, and swap approved nested assets. Confirm that automatic layout behaves as intended and that the component does not silently depend on the original example text.

Check override stability by updating the main component after making typical instance edits. Observe whether text, nested choices, and visibility settings survive. A library update that repeatedly destroys consumer overrides creates hidden maintenance costs, even when the source component looks cleaner.

Inspect nested components independently. If a public property controls a nested instance, confirm the relationship is understandable from the consumer panel. Avoid exposing every internal setting simply because the tool allows it. Private construction details should remain private unless they solve a repeated consumer need.

Pair this testing with a review of the code implementation. A design component that offers arbitrary vertical alignment while code supports one alignment creates predictable handoff disputes. Use related development guidance for implementation questions, but keep the shared contract on the component page where both disciplines can find it.

Publish a usable component set

Arrange variants for maintainers, but optimize descriptions and property labels for consumers. Provide one recommended starting configuration and a few examples showing legitimate alternatives. A wall of every possible permutation is useful for auditing, not necessarily for teaching the right choice.

Create a release review that covers property renames, removed options, nested replacements, and changed defaults. Explain which updates preserve existing instances and which may require manual work. Do not assume consumers will infer migration steps from the visual difference alone.

Retire obsolete options gradually when their usage is unclear. Mark the replacement, stop using the old option in first-party templates, and help teams move active files. A component library becomes easier to use when unsupported paths disappear predictably, not when maintainers preserve every historical experiment forever.

Keep the Design Systems category as a route to broader governance guidance, while each component page remains focused on its own supported decisions. Review support questions after release; repeated confusion usually points to a property name, example, or boundary that needs improvement.

Estimate the cost of another axis

A set with three sizes, three emphasis levels, two icon positions, and four preview states already describes 72 combinations if every choice is multiplied together. Adding a binary badge option doubles that to 144. This combination count is a maintenance warning, not proof that every combination needs its own master or screenshot.

Before adding the badge axis, ask whether the badge is supported content, a separate composition, or a genuine configuration that changes the component's layout contract. Test the proposed mechanism with the smallest size and longest label. Those cases often reveal whether an apparently simple option needs a clearer boundary.

Choose representative coverage deliberately: inspect each axis value, every prohibited combination, and interactions likely to affect layout. Keep a few full-product examples alongside the isolated set. Record the reason for excluding combinations so future maintainers do not recreate them simply to fill an empty grid. If consumers routinely need unsupported combinations, reopen the contract discussion rather than encouraging detached instances that bypass future library updates.

Key takeaways

• Model meaningful decisions rather than every visual permutation.
• Separate variants, editable content, nested swaps, and preview states.
• Document supported combinations before expanding a component set.
• Test resizing and override preservation in real consuming files.
• Publish property changes with explicit migration guidance.