Component properties

The production question

You're finishing the status badge and alert components for the recovery interface set, and for every editable element — the label, the leading icon, whether the icon shows at all, which icon appears — you have to decide whether it becomes a component property, a variant, or an unlocked override left for the instance owner to handle manually. Pick property when you meant variant (or the reverse) and the properties panel either explodes into confusing combinations or stays silent about the one thing three different screens keep detaching to change by hand.

How to decide

1. Ask whether the option is a bounded, finite state the component itself is in — size, hierarchy, interaction state. If yes, it belongs in the variant grid, not a property; state is a bounded system option, content is not.
2. If the option is content that varies per instance — a button label, an alert message, a badge count — expose it as a Text property instead of leaving it as a silent, undocumented override.
3. If an element's presence is a plain yes/no choice — does this row have a leading icon at all — bind that visibility to a Boolean property rather than expecting instance owners to delete the layer themselves.
4. If the choice is which specific icon or asset fills a slot, use an instance-swap property so any icon already in the library can drop in without touching the main component's structure.
5. Before shipping, count how many total combinations the variant grid plus properties could produce. If that number is climbing into the dozens, the component is doing two jobs and should split, not gain more controls.
6. Name every property the way you'd name a function parameter for a stranger — ‘Show icon,’ not ‘Property 1’ or ‘Boolean 2’ — because that name is the only documentation most instance owners will ever read.

Correct vs. incorrect

Practice it, then try to break it

Build a small card: an icon frame, a title text layer, and a description text layer. Add a Text property for the title, a Boolean property named “Show icon” bound to the icon frame's visibility, and an instance-swap property for the icon itself. Place three instances, override the title and icon independently on each, then edit the main component's corner radius. Confirm the radius change propagates to all three without disturbing your per-instance overrides — that propagation is the entire reason to use properties instead of duplicating frames.

Stress test: Rename your Boolean to something meaningless like “Property 1,” hand the file to someone who didn't build it, and ask them to add a new instance without an icon using only the properties panel — no layer names, no asking you. If they hesitate, open the layers panel, or guess wrong, the mechanism worked but the naming step failed, and in practice that failure costs the same as skipping properties altogether.

Common mistakes

• Modeling a bounded state — button hierarchy, interaction state — as a Boolean property instead of a variant, which hides a structural decision inside a control meant for content.
• Exposing every layer as a property ‘just in case,’ so the properties panel lists a dozen controls and instance owners can't tell which three actually matter.
• Leaving an optional icon or badge to be manually deleted per instance instead of wiring a Boolean, which quietly breaks the update path the moment the main component changes that layer.
• Using instance-swap for a slot that only ever holds one icon, adding a choice nobody needs and making the component look more flexible than it actually is.

Accessibility and handoff

Property names carry almost directly into a developer's mental model of the component's API during handoff — a Boolean called “Show icon” reads as a prop, while “Property 1” forces a guess from the rendered instance alone, which is exactly the ambiguity handoff notes exist to remove.

FAQ

Isn't a variant technically a component property too?

Yes — the properties panel lists your variant combination alongside Boolean, text, and instance-swap controls. The useful working distinction is that variant covers bounded system state (size, hierarchy, interaction state), while property covers what an instance owner should be able to change about one instance's content or configuration.

How many properties is too many?

There's no fixed number, but if you can't describe what each one does in a few words, or the total combinations are climbing into the dozens, you're past ‘small and legible’ — split the component instead of adding more controls.

Should every optional element get a Boolean property?

Only if hiding or showing it is something an instance owner genuinely needs across real screens; a Boolean for an element nobody ever turns off just adds noise to the panel.

If I don't add a text property, can someone still edit the label?

Yes — plain overrides work without a defined property. Adding the property just makes that edit visible and structured in the panel instead of something only discoverable by clicking into the layer.