Component design

Learn the best practices for designing components.

A key aspect of working with components is balancing simplicity with functionality. Following some guiding principles can help you avoid common pitfalls, build flexible designs, and save time in the long run.

This guide covers design best practices and strategies for refactoring components when they become too complex.

Best practices

Designing components may take a few iterations before you find the optimal approach. However, you can get there faster by making the right choices from the start.

Below are some general best practices to consider when planning your components.

Focus on modularity

Instead of using a single, complex component to represent multiple elements, create smaller, simpler components and combine them as needed. That gives you greater flexibility and reusability. For example, instead of creating one large component for a page section, break it down into an image, a bulleted list, and a button component.

Use descriptive names

Naming your components and attributes clearly and descriptively helps you and your team understand the purpose of each component, making it easier to work with the content structure. Use names that clearly communicate the component's purpose, such as "Product Feature List" or "Product Image Gallery" rather than "Product Cards" or "Product Grid", for example.

Keep it simple

Try to keep components as simple as possible, and avoid designing components near the complexity limit. Not doing so may prevent them and any dependent components from evolving later to include new attributes.

Split complex components

If a component is near the complexity limit, consider restructuring it by splitting it into smaller components and using multiple slots to accommodate them. That will improve the maintainability and readability of your content.

Avoid unnecessary components

Creating components for simple elements like titles or images may not be necessary. Instead, use structures or primitives to represent them. A good rule of thumb is to ask yourself if the element needs the flexibility to change without affecting other parts or ensuring consistency. If you need flexibility, use a structure attribute instead of another component. If you need consistency, a new component is the way to go.

By following these best practices, you can optimize your component design, making it easier to manage complex content structures while ensuring a seamless content creation and update process.

Refactoring strategies

In certain situations, you may find yourself unable to add a new attribute or nesting level to a component because another component linked to it has already reached some of the above-mentioned limits. Or perhaps you need to add a new attribute to a component that is used in many places across your content, but not all of them require the new attribute.

The following sections discuss several refactoring strategies to help you update your component's structure with minimal effort.

Clone and replace

Use this approach if only a few places need changes and most do not.

For example, suppose you have a component for a call-to-action button that you use in many places across your content. This component has a link attribute that contains a label and a URL. But now you need a new attribute to control its style in the hero section.

That is where the clone and replace pattern comes in handy.

In this approach, you clone the component and use the clone only where the change is needed, leaving the original component unchanged.

These are the steps to follow:

Identify the component that is causing the complexity issue.
Clone the component.
Update the places that need the changes to use the clone instead.

Clone and modify

Use this approach if most places need changes and only a few do not.

Let's use the same example as before, but now assuming you need to add a new attribute to the call-to-action button that is useful for most places — but not all.

In this case, the best approach is to clone the original component, update those few places to use the clone, and then make the necessary changes to the original component.

Breaking it down into steps:

Identify the component that is causing the complexity issue.
Clone the component and make the necessary changes.
Update all places not requiring the change to use the clone instead.

Flatten and merge

Consider this approach if you need to make changes in all places that use the component.

In this case, the alternative is to flatten the nested structures and merge them into the parent component. That reduces the depth and makes room for the new nesting level.

For example, suppose you have a Product Info component that uses a Product Details structure with price, brand, and description attributes. This design worked well until you had to include a Product Reviews structure with ratings and comments. Because the Product Info component is already at the maximum nesting level, you cannot add the new structure.

To work around this, you can flatten the Product Details structure and merge its attributes into the Product Info component, as shown below:

One thing to consider is that this requires you to update content in all places where the component is used. Yet, since flattening the structure is inevitable, adjusting the content will take some effort, no matter your approach.

In summary, these are the steps to follow:

Identify the component that is causing the complexity issue.
Flatten as many nested structures as needed to accommodate the required changes.
Update the content in all places that use the component.

Considerations

Each of these approaches has its tradeoffs. If you are not sure which one to use, consider the following factors:

Time: How much time do you have to implement the changes?
Effort: How much content will you need to adjust?
Maintenance: Will you have to change it again in the near future?

By weighing these factors, you can choose the approach that best meets your needs and time constraints.