Creating new Variants in Paragon

What is a variant?

The meaning of variant in the context of design systems has changed over time because interface design tools such as Sketch and Figma have adopted the term to describe any change in visual appearance for a single component. If you have a Card component, any visual difference that is unrelated to the value of the content inside would be considered a new variant in Figma.

In the context of Paragon, we mean something more specific when we say variant. A variant should be any variation of appearance or behavior that would cause significant code duplication or component re-abstraction if a consumer of the prospectus design system had to replicate this visual variation themself. In other words, it’s not enough to have one use case where a component looks different to justify a new variant. There needs to be thematic reason why some consumers of prospectus would want one variant and others would want it a second way (or the same consumer wants different variants for different contexts).

Should you create a new variant?

If you have an idea for a situation where an existing component is missing the behavior you need for your application, ask the following questions.

Have I tried to use one of the existing variants to accomplish my intended behavior even if it doesn’t look the way I expected? One of the goals of a Design System is to avoid duplicate components. If you see an existing variant that serves the same purpose as what you have in mind, it's a good rule of thumb to use it even if it doesn’t look the way you pictured in your head.
Am I sure this new behavior is a variant of the current component? It’s possible that the new behavior should be its own, new component. Don’t create a new variant based on appearance, create a variant based on behavior.
Will this new variant be useful to a wide range of users across different businesses?

If the answer to all of the questions above is, “yes,” then you probably have a solid candidate for a new variant of a Paragon component

Should you create a variant or a subcomponents?

Many Paragon components have subcomponents. For example, the <Card /> component has Card.Header, Card.Footer, Card.Section, etc. which are subcomponents designed to live inside a <Card></Card> container.

This distinction should only matter when you’re dealing with a component that acts as a container that surrounds other content. The key distinction is whether the change you want to make to the component is a change to the container itself or if you want to add a new type of content that can live in the container. There isn’t always an easy answer, you could argue that the Card.Header and Card.Footer are a part of the container itself. However, because the header is not always at the top of the container (it could be below an image for example) we decided the Header would be content that is defined as a subcomponent which can be used inside the Card container in Paragon.

By contrast, the actionIcon prop on the Card cannot exist in any place relative to the container other than the top right. In that way it is as much a part of the container itself as the padding and borderRadius.

Boolean prop vs list of options vs React Element

Use a boolean prop when: you have a feature of a component that you want to either be completely off/invisible or completely on. Examples include isClickable, hasCloseButton, and invertColors.