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.