Components

Component principals

Best practices for creating global components.

Global components should…

Have a specific and easily statable purpose.

Do
Attempt to describe the component in a maximum of 1-3 sentences.
Don't
Make components so specific or vague that they can’t be reused.

Attempt to solve a single concern.

Do
Make concisely scoped components that can serve the same purpose in a wide variety of situations.
Do
Make components that have at least three identified use cases in our products.

Have well-documented props and usage guidelines.

Do
Explain the purpose of each prop and provide ample examples and guidelines for using the component.
Don't
Add overly verbose prop descriptions.

Follow native semantic HTML and keyboard workflows.

Do
Rely on built-in, conventional functionality to make the components that are predictable to use and accessible.
Don't
Avoid adding custom or non-standard keyboard navigation workflows or blocking native behavior.

Be context agnostic.

Do
Assume the component will be used a wide variety of products in a variety of situations.
Don't
Make layout, sizes, color or spacing assumptions that may hinder reusability.

Be tested in all relevant supported browsers and platforms.

Do
Gracefully degrade component or use a polyfill when technology limitations are incurred.
Do
Make components that can be used for its stated purpose in all supported browsers and platforms.

Contain real-world examples in its documentation.

Do
Use as many real-world examples as necessary to convey a component’s intended use cases.
Don't
Use hypothetical examples that could convolute the documentation.

Encapsulate its own styles.

Do
Constrain styles to the scope of the component to avoid unintended global overrides.
Don't
Style or override a component’s styles from other components or global stylesheets.

Resources