{"id":17345121,"url":"https://github.com/afonsopacifer/web-components-good-practices","last_synced_at":"2025-07-28T22:40:00.439Z","repository":{"id":69055104,"uuid":"87876394","full_name":"afonsopacifer/web-components-good-practices","owner":"afonsopacifer","description":":sunglasses::ballot_box_with_check: Good Practices for build Web Components.","archived":false,"fork":false,"pushed_at":"2017-04-17T22:58:05.000Z","size":3,"stargazers_count":81,"open_issues_count":0,"forks_count":3,"subscribers_count":5,"default_branch":"master","last_synced_at":"2025-06-20T08:02:28.540Z","etag":null,"topics":["a11y","performance","polymer","tests","unix-philosophy","web-co","web-components"],"latest_commit_sha":null,"homepage":"","language":null,"has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/afonsopacifer.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2017-04-11T01:58:05.000Z","updated_at":"2024-06-04T21:30:38.000Z","dependencies_parsed_at":null,"dependency_job_id":"7ad9ed4e-fd86-466f-8b78-47c5082d513c","html_url":"https://github.com/afonsopacifer/web-components-good-practices","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/afonsopacifer/web-components-good-practices","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/afonsopacifer%2Fweb-components-good-practices","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/afonsopacifer%2Fweb-components-good-practices/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/afonsopacifer%2Fweb-components-good-practices/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/afonsopacifer%2Fweb-components-good-practices/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/afonsopacifer","download_url":"https://codeload.github.com/afonsopacifer/web-components-good-practices/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/afonsopacifer%2Fweb-components-good-practices/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":260906939,"owners_count":23080601,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["a11y","performance","polymer","tests","unix-philosophy","web-co","web-components"],"created_at":"2024-10-15T16:29:30.039Z","updated_at":"2025-07-28T22:40:00.432Z","avatar_url":"https://github.com/afonsopacifer.png","language":null,"funding_links":[],"categories":[],"sub_categories":[],"readme":"# Good Practices for build Web Components\n\n**Note:** The best practices presented here are about [polymer](polymer-project.org), but you can follow these recommendations for any [Web Components](https://www.webcomponents.org/introduction) or other type of component based on Libraries or frameworks (like [React](https://facebook.github.io/react/) or any other).\n\n**Tip:** For open source projects [see the Open Source Checklist](https://afonsopacifer.github.io/open-source-checklist/).\n\n## Table of contents\n\n  - [ ] [Make reusable and composable](#make-reusable-and-composable)\n  - [ ] [Cover the basics](#cover-the-basics)\n  - [ ] [Make maintainable](#make-maintainable)\n  - [ ] [Improve performance](#improve-performance)\n  - [ ] [A11y](#a11y)\n  - [ ] [Make customizable](#make-customizable)\n  - [ ] [Document all](#document-all)\n  - [ ] [Publish to the world](#publish-to-the-world)\n  - [ ] [Resources for learning](#resources-for-learning)\n\n## Make reusable and composable\n\n  - [ ] Learn the 17 Rules of [Unix philosophy](https://en.wikipedia.org/wiki/Unix_philosophy).\n  - [ ] Learn about [Atomic Design](http://bradfrost.com/blog/post/atomic-web-design/).\n\n## Cover the basics\n\n  - [ ] Make [Responsive](https://en.wikipedia.org/wiki/Responsive_web_design).\n  - [ ] When necessary, think in [Progressive enhancement](https://en.wikipedia.org/wiki/Progressive_enhancement).\n\n## Make maintainable\n\n  - [ ] Follow the [Semantic Versioning](http://semver.org/).\n  - [ ] Use `_` as a prefix convention for private methods.\n  - [ ] Lint with [eslint](http://eslint.org/).\n  - [ ] Lint with [polylint](https://github.com/PolymerLabs/polylint).\n  - [ ] Write unit tests with [Web Component Tester WCT](https://github.com/Polymer/web-component-tester).\n  - [ ] Write the [UI regression test](https://github.com/Huddle/PhantomCSS) with whatever you want.\n  - [ ] Run the tests in all browser with [Selenium](http://www.seleniumhq.org/) and [Source Labs](https://saucelabs.com/).\n  - [ ] Integrate all tests with [CI](https://travis-ci.org/).\n\n## Improve performance\n\n  - [ ] Optimize [first paint](https://www.smashingmagazine.com/2016/12/front-end-performance-checklist-2017-pdf-pages/).\n  - [ ] Write a [test for first paint](https://youtu.be/zfQoleQEa4w?t=1307) performance.\n  - [ ] Implement [do less \u0026 be lazy](https://youtu.be/zfQoleQEa4w?t=1386) concepts.\n\n## A11y\n\n  - [ ] Add [Aria](https://www.youtube.com/watch?v=g9Qff0b-lHk\u0026index=4\u0026list=PLNYkxOF6rcICWx0C9LVWWVqvHlYJyqw7g) labels.\n  - [ ] Use the [focus](https://www.youtube.com/watch?v=EFv9ubbZLKw\u0026index=14\u0026list=PLNYkxOF6rcICWx0C9LVWWVqvHlYJyqw7g) event.\n  - [ ] Think in [tab index](https://www.youtube.com/watch?v=Pe0Ce1WtnUM\u0026index=13\u0026list=PLNYkxOF6rcICWx0C9LVWWVqvHlYJyqw7g) order.\n  - [ ] Test all with [Accessibility Developer Tools](https://github.com/GoogleChrome/accessibility-developer-tools).\n\n## Make [customizable](https://www.youtube.com/watch?v=IbOaJwqLgog)\n\n  - [ ] Use [custom properties](https://www.w3.org/TR/css-variables/) and expose the API for users with docs.\n  - [ ] Use [@apply rule](https://tabatkins.github.io/specs/css-apply-rule/) for most generic style and expose the API for users with docs.\n\n## Document all\n\n  - [ ] Provide a quick demo (like [webcomponents.org inline demo](https://www.webcomponents.org/publish)).\n  - [ ] Provide a full demo (Polymer [iron-demo-helpers](https://github.com/PolymerElements/iron-demo-helpers) is recommended).\n  - [ ] Describe how to download and use the component.\n  - [ ] Describe how to style the component.\n  - [ ] Specify the component support.\n  - [ ] Describe your API. ([example](https://www.webcomponents.org/element/PolymerElements/paper-button/paper-button))\n  - [ ] Describe how to run the development environment.\n  - [ ] Describe how to run all the tests.\n\n## Publish to the world\n\n  - [ ] Publish in [bower](https://bower.io/).\n  - [ ] Publish in [webcomponents.org](https://www.webcomponents.org/) following the [requirements](https://www.webcomponents.org/publish).\n\n## Resources for learning\n- [Practical lessons from a year of building web components - Google I/O 2016](https://www.youtube.com/watch?v=zfQoleQEa4w\u0026feature=youtu.be) - [@notwaldorf](https://twitter.com/notwaldorf)\n- [Production-Ready Polymer Elements - A How-To-Guide (Polymer Summit 2016)](https://www.youtube.com/watch?v=T35IgjN9IwY\u0026index=22\u0026list=PLNYkxOF6rcICc687SxHQRuo9TVNOJelSZ) - [@danfreedman](https://twitter.com/danfreedman)\n- [Polymer's Styling System (The Polymer Summit 2015)](https://www.youtube.com/watch?v=IbOaJwqLgog) - [@notwaldorf](https://twitter.com/notwaldorf)\n- [A11ycasts](https://www.youtube.com/watch?v=HtTyRajRuyY\u0026index=16\u0026list=PLNYkxOF6rcICWx0C9LVWWVqvHlYJyqw7g) - [@rob_dodson](https://twitter.com/rob_dodson)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fafonsopacifer%2Fweb-components-good-practices","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fafonsopacifer%2Fweb-components-good-practices","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fafonsopacifer%2Fweb-components-good-practices/lists"}