Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Merge branch 'main' into eb-add-language-guidance
* main: Expand the stack to include client-side frameworks Add HTML validation best practice (#588) Wrap in code to be consistent with line above’s factories.rb (#625) Remove the deprecated jscs configuration (#622) Restore Rubocop & Hound configuration (#623) Prefer MVVM on Android Update our Android best practices Added def tags to Data Glossary (#620) Fix typo in function components URL (#624) Fix broken link Ensure that guides have consistent formatting (#618) Combine style, best practice, and protocol guides (#615) Remove private/protected style guideline Rename Testing guide to Testing with RSpec (#614) Add back .rubocop.yml # Conflicts: # README.md
- Loading branch information
Showing
118 changed files
with
3,168 additions
and
2,404 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,6 +1,6 @@ | ||
| # Code of Conduct | ||
|
|
||
| By participating in this project, you agree to abide by the | ||
| [thoughtbot code of conduct][tb-coc]. | ||
| By participating in this project, you agree to abide by the [thoughtbot code of | ||
| conduct]. | ||
|
|
||
| [tb-coc]: https://thoughtbot.com/open-source-code-of-conduct | ||
| [thoughtbot code of conduct]: https://thoughtbot.com/open-source-code-of-conduct |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,28 @@ | ||
| # Template | ||
|
|
||
| In a sentence or two, describe what this guide is about. A guide can be about a | ||
| programming language or framework, a design or development tool, or an entirely | ||
| non-technical topic. | ||
|
|
||
| ## Best Practices | ||
|
|
||
| In this section (or as many sections as you need) convey the best practices | ||
| around the topic of the guide. | ||
|
|
||
| This typically takes one of three forms: | ||
|
|
||
| 1. A section or sections with lists of specific | ||
| [guidelines](/README.md#a-note-on-the-language) | ||
| 2. Primarily textual sections | ||
| 3. A combination of both | ||
|
|
||
| ## How to... | ||
|
|
||
| This section, if applicable, should index a list of "How-to" guides for this | ||
| guide's topic. These should be stored relative to this `README.md` file in a | ||
| folder named `how-to`. | ||
|
|
||
| Here are some examples: | ||
|
|
||
| - [Do something](./how-to/do-something.md) | ||
| - [Do something else](./how-to/do-something-else.md) |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,3 @@ | ||
| ## How to Do Something Else | ||
|
|
||
| This is an example how-to guide. Write anything you want here! |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,3 @@ | ||
| ## How to Do Something | ||
|
|
||
| This is an example how-to guide. Write anything you want here! |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,123 @@ | ||
| # Accessibility | ||
|
|
||
| A guide for auditing and maintaining accessible web sites and apps. | ||
|
|
||
| ## Basics | ||
|
|
||
| thoughtbot strives for AA level [Web Content Accessibility Guideline (WCAG)] | ||
| compliance. Perform one or more of these checks to ensure your work is | ||
| accessible. | ||
|
|
||
| ### Automation | ||
|
|
||
| Automated checks can catch a lot of common issues before they reach production. | ||
|
|
||
| - Use tools such as [WAVE] or [axe's browser extensions] to run audits on your | ||
| local build | ||
| - Use a CI/CD solution such as [AccessLint] or [axe] | ||
|
|
||
| ### Usability | ||
|
|
||
| [Manual usability testing] ensures things work as intended. | ||
|
|
||
| - Test your local build using a screen reader such as [VoiceOver] or [NVDA] | ||
| - Use tools such as [Accessibility Insights] to catch issues that cannot be | ||
| found using automated checks | ||
| - Hire assistive technology users to user test your product | ||
|
|
||
| ## Quick checks | ||
|
|
||
| ### Design | ||
|
|
||
| - Ensure all content's foreground color values meet the [minimum contrast ratio] | ||
| for the background color they are placed over | ||
| - Ensure all interactive content has distinct hover and focus states to help | ||
| indicate interactivity | ||
| - Ensure color is not the only way to determine meaning | ||
| - Ensure interactive components use common UI affordances where applicable, to | ||
| help users understand how they can be operated | ||
| - Prefer icons and glyphs that don't rely on specialized knowledge to understand | ||
| their meaning, unless being used in a domain-specific context | ||
| - Prefer language that is [simple and direct] | ||
| - Ensure form inputs have labels that are visible in every state | ||
| - Ensure link and button text is descriptive and distinct | ||
| - Prefer content that is broken into logical sections, with headings that | ||
| explain the content that follows | ||
| - Prefer text sizing that is set to 16px or larger | ||
| - Ensure animation does not auto-play, can be paused, and avoids [vestibular and | ||
| seizure triggers] | ||
| - Ensure video content has captions | ||
| - Prefer larger interactive target sizes, with some space between grouped | ||
| interactive controls | ||
|
|
||
| ### Development | ||
|
|
||
| - Ensure semantic markup is used to describe content | ||
| - Ensure content does not disappear off the screen when zoomed | ||
| - Ensure that interactive content can be tabbed to and activated using the | ||
| keyboard, and that the tab order matches reading order | ||
| - Ensure that heading elements are used, and that heading levels are placed in a | ||
| logical order | ||
| - Ensure that landmarks are used to describe the overall layout of the page or | ||
| view | ||
| - Ensure that alternative descriptions for image content are concise, | ||
| descriptive, and use punctuation (`alt` attributes for images, `title` | ||
| elements for SVGs) | ||
| - Ensure labels are programmatically associated with their inputs | ||
| - Prefer implementing a method to allow users to skip sections of repeated | ||
| content | ||
| - Ensure each page or view has a unique title that describes the content it | ||
| contains | ||
| - The `title` attribute is only used to describe `iframe` element contents | ||
| - Ensure that links are used to navigate to other locations and buttons are used | ||
| to trigger actions | ||
| - Ensure that focus is trapped inside of modal interactions | ||
| - Ensure `fieldset` and `legend` elements are used to group related inputs and | ||
| label them | ||
| - Ensure form feedback messaging is programmatically associated with the | ||
| relevant inputs | ||
|
|
||
| ## Full audit | ||
|
|
||
| When at all possible, use the guidelines in the basics and quick check sections | ||
| to attempt to address accessibility in a proactive way. | ||
|
|
||
| If a thorough analysis needs to be performed, use the following workflow to | ||
| perform a comprehensive accessibility audit that checks against most WCAG | ||
| criterion: | ||
|
|
||
| 1. Create a copy of the [Accessibility Audit Template] spreadsheet in Google | ||
| Drive | ||
| 1. Break apart the site or app to be audited into discrete user flow sections, | ||
| ordered by importance | ||
| 1. Add yourself as the section lead on the audit template, document the relevant | ||
| URL and date, and set a status | ||
| 1. For each user flow, identify each component that enables the user flow to | ||
| function | ||
| 1. For each component, check against the test criteria for each row, and then | ||
| assign it one of four ratings: | ||
| - **N/A**: This test does not apply to this component | ||
| - **Pass**: This component meets this test's criteria | ||
| - **Moderate**: This component does not meet this test's criteria, but can | ||
| worked around | ||
| - **Critical**: This component does not meet this test's criteria, and cannot | ||
| be worked around | ||
| 1. Once a component is completed, update its status | ||
| 1. Continue until all user flows have been audited | ||
|
|
||
| Use the Notes sheet to leave per-cell comments when necessary, referencing them | ||
| with a link. The next steps for an audit are handled on a per-project basis. | ||
|
|
||
| [accessibility audit template]: https://docs.google.com/spreadsheets/d/1Ys-0U5BY-Ct_phy7gk9XJmn4nBTMFTh08aTQ6U1kB_4/edit?usp=sharing | ||
| [accesslint]: https://github.com/marketplace/accesslint | ||
| [axe]: https://www.deque.com/axe/axe-for-web/integrations/ | ||
| [axe's browser extensions]: https://www.deque.com/axe/axe-for-web/ | ||
| [minimum contrast ratio]: https://webaim.org/resources/linkcontrastchecker/ | ||
| [manual usability testing]: https://www.smashingmagazine.com/2018/09/importance-manual-accessibility-testing/ | ||
| [nvda]: https://a11yproject.com/posts/getting-started-with-nvda/ | ||
| [accessibility insights]: https://accessibilityinsights.io | ||
| [simple and direct]: https://datayze.com/readability-analyzer.php | ||
| [vestibular and seizure triggers]: https://alistapart.com/article/designing-safer-web-animation-for-motion-sensitivity/ | ||
| [voiceover]: https://a11yproject.com/posts/getting-started-with-voiceover/ | ||
| [wave]: https://wave.webaim.org/extension/ | ||
| [web content accessibility guideline (wcag)]: https://www.w3.org/WAI/standards-guidelines/wcag/ |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,12 @@ | ||
| # Android | ||
|
|
||
| - Properties of views should be alphabetized, with the exception of `id`, | ||
| `layout_width`, and `layout_height` which should be placed first in that | ||
| order. | ||
| - Use Kotlin for all new code. | ||
| - Prefer pull request reviews from other Android developers but be open to | ||
| reviews from iOS and React Native developers as well. | ||
| - Prefer non-null types. | ||
| - Use string resources for all user-visible text. | ||
| - Prefer vector drawables over PNGs or JPEGs. | ||
| - Prefer Model-View-ViewModel (MVVM) for your app architecture. |
File renamed without changes.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,14 @@ | ||
| # Angular | ||
|
|
||
| - [Avoid manual dependency annotations]. Disable mangling or use a pre-processor | ||
| such as [ngannotate] for annotations. | ||
| - Prefer `factory` to `service`. If you desire a singleton, wrap the singleton | ||
| class in a factory function and return a new instance of that class from the | ||
| factory. | ||
| - Prefer the `translate` directive to the `translate` filter for [performance | ||
| reasons]. | ||
| - Don't use the `jQuery` or `$` global. Access jQuery via `angular.element`. | ||
|
|
||
| [avoid manual dependency annotations]: http://robots.thoughtbot.com/avoid-angularjs-dependency-annotation-with-rails | ||
| [ngannotate]: https://github.com/kikonen/ngannotate-rails | ||
| [performance reasons]: https://github.com/angular-translate/angular-translate/wiki/Getting-Started#using-translate-directive |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,9 @@ | ||
| # Bash | ||
|
|
||
| In addition to [shell](/shell/) best practices: | ||
|
|
||
| - Prefer `${var,,}` and `${var^^}` over `tr` for changing case. | ||
| - Prefer `${var//from/to}` over `sed` for simple string replacements. | ||
| - Prefer `[[` over `test` or `[`. | ||
| - Prefer process substitution over a pipe in `while read` loops. | ||
| - Use `((` or `let`, not `$((` when you don't need the result |
Oops, something went wrong.