Decide on convention of type, kind, and variant for v11

[joshblack]

Background

We would like to be consistent in our terminology with how a user can configure a component to render differently in terms of appearance. In our codebase currently, we use several style of props to indicate that a component can have different visual appearances, including:

• type
• kind

In this proposal, we would like to define what the exact term used must be for components and when to use these other prop names, if at all.

Links & Resources

• Design Tools
  • Framer
    • A Variant is any visual state specified for a component. With Variants, components can be given unique states to which they can animate when an event is happening or has occurred.
• Design Systems
  • Components using variant
    • https://spectrum.adobe.com/page/button/
    • https://primer.style/react/Buttons

[joshblack]

• Button
  • Uses kind because type conflicts with <button type="...">

[joshblack]

Figma Research

Overview

Figma uses a term called a Component Set to describe a collection of components, called variants, that all share their properties. However, the variants will have different combinations of values for these properties.

A Property is the name of some variable aspect of a component. For example, the property names of a button component could be the type, size, state, or whether it has an icon.

A Property value is the different options available for a property. For example, the state property for a button could have default, hover, pressed, and disabled values.

To recap, a Component Set is made up of Variants. A Variant is a unique combination of properties and their values.

Deep Dive

A Component Set could be one-dimensional. For example, a button could have a state property with the values: standard, hover, pressed, or disabled.

Our Button Component Set, in this case, would contain the following variants:

In this case, the variants are specifically:

• Button with state: standard
• Button with state: hover
• Button with state: pressed
• Button with state: disabled

A Component Set could also be multi-dimensional. For example, a button could have several types such as primary and secondary. In this case, our Button Component Set would look like:

In this case, the variants are:

• Button, type: primary, state: standard
• Button, type: primary, state: hover
• Button, type: primary, state: pressed
• Button, type: primary, state: disabled
• Button, type: secondary, state: standard
• Button, type: secondary, state: hover
• Button, type: secondary, state: pressed
• Button, type: secondary, state: disabled

Note: all variants within the component set will use the same properties and values, but each variant needs to be a unique combination of them. You don’t need to have a component for every possible combination of properties and values.

Background

We would like to standardize on terms used to describe components and how they change between visual appearance and behavior. Examples of this include:

• A button that has several visual appearances (primary, secondary, tertiary, danger, etc)
• A notification component
  • Different behavior: toast, inline
  • Modifier: low contrast
  • Notification type: info, warn, error

Industry Analysis

Design Systems

Name	URL	Property	Notes
ANT Design	Link	type
Salesforce	Link	type
Shopify	Link	type
Primer	Link	type
Chakra UI	Link	variant
Atlassian	Link	none	They use separate components
Fluent		none	They use separate components

Conclusion

The recommendation is to use the variant terminology based on Figma along with the type terminology. A type should refer to functional or visual differences in a component. Modifiers should be a distinct property (like low contrast) so that they can be combined with type.

If a component has both visual AND behavior differences, then we create distinct components based on the behavior. For example, a notification has two different behaviors for toast and inline. These would become two distinct components, Toast Notification and Inline Notification with a type prop that corresponds to the notification type.

Links & Resources

• https://www.youtube.com/watch?v=y29Xwt9dET0
• https://help.figma.com/hc/en-us/articles/360056440594-Create-and-use-variants
• https://www.designsystemsforfigma.com/

Definitions

Component Set

A collection of components, called variants, that all share their properties,but have different combinations of values for those properties

Variant

A unique combination of the properties and values in a component set

Properties

The variable aspects of our component. For example: the properties of a button component could be the `type`, `size`, `state`, or whether it has an icon.

Values

The different options available for each property. For example: the state property could have `default`, `hover`, `pressed`, and `disabled` values.

[joshblack]

Figma Research (Migration)

An interesting aspect of: https://help.figma.com/hc/en-us/articles/360056440594-Create-and-use-variants#Manage_variants is that the default name of the first property when creating variants will be: variant.

They also show renaming this automatic field to type later on:

[vpicone]

Great stuff! Thanks for putting in the time researching. Do we have any idea how many components might need to be renamed ala Notification? I'm wary of using a totally new component for a thing that could be a prop, but agree it makes sense in some cases.

I might have missed it, but if we use type for primary, secondary etc. how does a dev pass in the native "type" attribute?

[aagonzales]

I still worry about the term type in the larger context. It can mean different things depending on your context throughout the system:

• type = component "variant"
• type = typography, text, type styles

Type (variant) and type (text) can be seen a lot on the same page through out component docs.

I could be more ok with type if we labeled it "Component type" instead of just "type" by itself.

[joshblack]

@vpicone thankfully no name changes! And for ambiguity, I think we'll need to have a prop like nativeType or htmlType that will point to the underlying HTML Element type.

@aagonzales totally agreed

[aagonzales]

Another factor that we should consider is how these terms are being used in the ecosystem. This is what teams are using in their docs (not sure if its the same in their code).

• Jan said .com uses "variant"
• Looks like Cloud PAL uses "variations"
• AI Apps actually uses both "type" and "variant"
• CC&C use "type"

[aagonzales]

I think we're missing a term somewhere.

1. There are two [insert term] of notification components. Inline and Toast. This have major functional, behavioral, and style differences.
   

2. Within inline notification there are four [insert terms] of inline notifications, error, warning, info and success. These most commonly only have usage differences. (This is the term we're missing)
   

3. Within an success-inline-notification there are two [style modifiers], high contrast and low contrast. These are only aesthetic style differences.
   

4. Within an inline notification you can add a [modifier] such as an action to enhance minor functionality.
   

---

If 1. Type then is 2. Kind? Or is 1. Variant and 2. is type?

[joshblack]

@aagonzales here's one attempt at thinking about it:

There are two types of notification components: Inline and Toast. These have major functional, behavioral, and style differences but still fall under the umbrella of notifications

An inline notification component has a status/state/type property that can be one of error, warning, info, and success.

The success-inline-notification by default uses a low contrast style. It has a high contrast property to create high contrast variants.

Within an inline notification you can add a [modifier] such as an action to enhance minor functionality.

I think when we have items inside of a component it could fall under the umbrella of component composition versus types/variants of a component. The guidance then becomes around the types of content a component allows versus it being a variant distinction.