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.