Component Prop Organization: Structure and Hierarchy

Why does Prop order matter?

Imagine a complex component (e.g., an Input with a label, icon, error message, and help text). If the configuration properties are disorganized, the design system user (the designer or developer) will waste time looking for how to change the icon color or text size.

A logical organization of props follows a mental order of importance: Identity > Content > Appearance > Behavior.

The Layers of Organization Model

For optimal organization, it is recommended to group properties into the following categories, always maintaining this top-to-bottom order:

1. Identity and Type Properties (Context)

These are the ones that define what “class” of component we are using.

• Examples: variant="primary | secondary", size="small | medium | large".
• Usage: They determine the base structure of the component and often affect other available properties.

2. Content Properties (Raw Materials)

Everything the user sees and reads.

• Examples: label, placeholder, helperText, iconName.
• Usage: In Figma, these are usually Text Properties and Instance Swap Properties.

3. Appearance and Style Properties (Visuals)

Fine adjustments that do not change the type or content.

• Examples: color, isRounded, hasBorder, alignment.
• Usage: Should be used sparingly to prevent designers from creating unauthorized system variations.

4. Status and Behavior Properties (Logic)

Define how the component reacts to external situations or interactivity.

• Examples: isLoading, isDisabled, isError, isFocused.
• Usage: They are fundamental for the interactivity and business logic of the application.

Best Practices for Grouping and Naming

• Use Separators: Both in Figma (using the properties panel) and in documentation, group related props under titles or sections (e.g., “Settings,” “Content,” “Status”).
• Prioritize the most used: Properties that are changed 90% of the time (like button text) should be at the top of the list.
• Consistency between tools: Try so the property order in the Figma panel exactly matches the order in which props are passed in code (e.g., in React or Vue).
• Booleans at the end (sometimes): On/off properties (hasIcon, showLabel) are usually grouped at the end of their respective sections so as not to interrupt the reading flow of more critical props.

Benefits for the Design System

• Reduced Learning Curve: New team members quickly understand how to configure any component.
• Error-free Handoff: By sharing the same order and logic, developers know exactly what to expect from the design file.
• Scalability: Adding new functionality to an existing component is much simpler if a defined structure already exists.
• Design Speed: In Figma, an ordered properties panel allows designers to prototype full screens much faster.

Mentor’s Tips

• Don’t assume, ask: Watch a fellow designer using your component for the first time. If it takes them more than 3 seconds to find a common property, your prop organization needs a review.
• Document the hierarchy: Include a “Standard Prop Order” example in your design system manual so all contributors follow the same logic when creating new components.
• Beware of Hidden Props: Use Figma’s ability to “hide” properties that aren’t relevant based on other selections (e.g., hide the “Icon Name” prop if hasIcon is false).

Useful Resources and Tools

• Figma Blog: Organizing Component Properties
• Storybook Docs: Controls and Props Sorting
• Atlassian Design System: An excellent example of hierarchy and order in component documentation.
• Books: Refactoring UI by Adam Wathan and Steve Schoger.

component-api-design variant-explosion-control