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.