Adding a new component

How do we recognize a component?

Soul defines four acceptance criteria to create clear expectations for a component's standards.

These expectations allow you to recognize and define the new components and help you to feel comfortable collaborating with the Design System team.

Criteria to recognize a possible component:

1. Does the new component solve a problem that can’t be solved with the existing one?
2. Does it meet user and business needs across multiple areas?
3. Does it match customers’ needs?
4. Does it meet the accessibility standards?

---

What have to do?

Each component has to be well-defined and documented. This helps us keep components consistent across the platform in every known use case.

This process is set up to help us recognize new components and bring a straightforward checklist to avoid missing any particular part.

1. ✏️ Design specification
2. 🔍 Testing
3. 📝 Documentation
4. 🏗️ Developing
5. 🛠️ Implementation

It doesn't matter if you add a new or update an existing component. In both cases, you should respect the process and be sure everything is documented and specified. In case of a component update, you should update the existing specification (in the dedicated Figma file) and documentation instead of creating a new one.

✏️ Design specification

We differentiate two types of actions. Adding a new entity in case it does not exist in the Soul. And updating existing ones in case the entity already exists and needs to be updated or extended with a new feature.

Adding a new entity

• In this case, you should specify dimensions, typography, colors, and all interactive states, including transitions, or be part of an already specified group or entity.

Updating existing

• If you need to update an entity, you should use an existing specification to keep everything in one place.

This step should be done before a component is added to the design system and approved by the UI design team. As a part of this process, you should ask to provide an update of the Figma libraries.

🔍 Testing

Especially when preparing a new component, you have a chance to test the design to improve the component's usability and find issues you haven’t seen. Take this as an opportunity to elevate the design to the next level.

You shouldn't skip this point even in case of updating an existing component. Keep in mind there is always a space to improve user experience.

📝 Documentation

A new foundation, element, component, or pattern has to be documented or added as an update to the already existing documentation.

This step may be done asynchronously with the developing entity as a part of the design system. However, we recommended creating proper documentation before to avoid last-minute updates.

The component documentation consists of the following:

1. Introduction — gives a brief definition and overview of the component.
2. Dev Characteristics — contains all the information developers need while building the component. It includes the component props details and the variables used to design the component.
3. Variants — shows all possible variants of the component at an overview level.
4. Usage guidelines — has information on what practices should be followed while using the component and tells how the component should or should not be used in different use cases.
5. Accessibility guidelines — has information about accessibility practices that everyone should take care of while using the component.
6. Motion guidelines — has all the details regarding the animation of the particular component.

🏗️ Developing

Once a component is specified and possibly documented, a task can be created for the dev team to add a component to the design system.

The following points help you to cover all aspects of the task. Design and specification have to be done in Figma.

1. Add links to the Figma file
2. design specification
3. prototype to demonstrate interactions
4. Add a link to documentation (if available)
5. Create detailed acceptance criteria to be sure all cases are covered
6. Mention the DesignOPS team in case you did everything by yourself

🛠️ Implementation

If a component is approved, developed, and tested, the team can implement and use it.

In case the component should be implemented in several repos and your dev team does not have the capacity to cover everything, you may ask team coders to help. For this case, you should create a task in their Jira board with all the necessary information.

You may find new cases of usage or needs during the implementation. If so, you should create another task to update the component.