afonsopacifer / web-components-good-practices

:sunglasses::ballot_box_with_check: Good Practices for build Web Components.

Good Practices for build Web Components

Note: The best practices presented here are about polymer, but you can follow these recommendations for any Web Components or other type of component based on Libraries or frameworks (like React or any other).

Tip: For open source projects see the Open Source Checklist.

Table of contents

• Make reusable and composable
• Cover the basics
• Make maintainable
• Improve performance
• A11y
• Make customizable
• Document all
• Publish to the world
• Resources for learning

Make reusable and composable

• Learn the 17 Rules of Unix philosophy.
• Learn about Atomic Design.

Cover the basics

• Make Responsive.
• When necessary, think in Progressive enhancement.

Make maintainable

• Follow the Semantic Versioning.
• Use _ as a prefix convention for private methods.
• Lint with eslint.
• Lint with polylint.
• Write unit tests with Web Component Tester WCT.
• Write the UI regression test with whatever you want.
• Run the tests in all browser with Selenium and Source Labs.
• Integrate all tests with CI.

Improve performance

• Optimize first paint.
• Write a test for first paint performance.
• Implement do less & be lazy concepts.

A11y

• Add Aria labels.
• Use the focus event.
• Think in tab index order.
• Test all with Accessibility Developer Tools.

Make customizable

• Use custom properties and expose the API for users with docs.
• Use @apply rule for most generic style and expose the API for users with docs.

Document all

• Provide a quick demo (like webcomponents.org inline demo).
• Provide a full demo (Polymer iron-demo-helpers is recommended).
• Describe how to download and use the component.
• Describe how to style the component.
• Specify the component support.
• Describe your API. (example)
• Describe how to run the development environment.
• Describe how to run all the tests.

Publish to the world

• Publish in bower.
• Publish in webcomponents.org following the requirements.

Resources for learning

• Practical lessons from a year of building web components - Google I/O 2016 - @notwaldorf
• Production-Ready Polymer Elements - A How-To-Guide (Polymer Summit 2016) - @danfreedman
• Polymer's Styling System (The Polymer Summit 2015) - @notwaldorf
• A11ycasts - @rob_dodson