forked from thoughtbot/guides
-
Notifications
You must be signed in to change notification settings - Fork 0
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Ensure that guides have consistent formatting (thoughtbot#618)
Fixes thoughtbot#617. This change ensures that all the guides have consistent Markdown formatting. It does not make any changes to the content. Formatting changes include: - Use GitHub style markdown - Make heading levels consistent and incremental - Make external links extracted instead of inline Additionally, I came across and fixed some editorial issues while reviewing all the guides: - Fixed/removed broken links - Fixed capitalization of technologies - Fixed spelling errors - Improved the link text for some external links - Replaced references to "Slack" with "Basecamp"
- Loading branch information
Showing
59 changed files
with
1,393 additions
and
1,145 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
| 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 |
|---|---|---|
| @@ -1,24 +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. | ||
| 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. | ||
| 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] | ||
| 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 | ||
|
|
||
| [guidelines]: /README.md#a-note-on-the-language | ||
|
|
||
| ## 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`. | ||
| 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) | ||
| - [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 |
|---|---|---|
| @@ -1,3 +1,3 @@ | ||
| ## How to Do Something Else | ||
|
|
||
| This is an example how-to guide. Write anything you want here! | ||
| 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 |
|---|---|---|
| @@ -1,3 +1,3 @@ | ||
| ## How to Do Something | ||
|
|
||
| This is an example how-to guide. Write anything you want here! | ||
| 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 |
|---|---|---|
| @@ -1,96 +1,123 @@ | ||
| Accessibility | ||
| ============= | ||
| # Accessibility | ||
|
|
||
| A guide for auditing and maintaining accessible web sites and apps. | ||
|
|
||
| Basics | ||
| ------ | ||
| ## Basics | ||
|
|
||
| thoughtbot strives for AA level [Web Content Accessibility Guideline (WCAG)][wcag] compliance. Perform one or more of these checks to ensure your work is accessible. | ||
| 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][wave] or [axe's browser extensions][axe-web] to run audits on your local build | ||
| * Use a CI/CD solution such as [AccessLint][accesslint] or [axe][axe] | ||
| - 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][manual-testing]. | ||
| [Manual usability testing] ensures things work as intended. | ||
|
|
||
| * Test your local build using a screen reader such as [VoiceOver][voiceover] or [NVDA][nvda] | ||
| * Use tools such as [Accessibility Insights][accessibility-insights] to catch | ||
| issues that cannot be found using automated checks | ||
| * Hire assistive technology users to user test your product | ||
| - 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 | ||
| ------------ | ||
| ## Quick checks | ||
|
|
||
| ### Design | ||
|
|
||
| * Ensure all content's foreground color values meet the [minimum contrast ratio][color-contrast] 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][readability] | ||
| * 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][vestibular-seizure] | ||
| * 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][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 | ||
| - 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. | ||
| 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 | ||
| [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-web]: https://www.deque.com/axe/axe-for-web/ | ||
| [color-contrast]: https://webaim.org/resources/linkcontrastchecker/ | ||
| [manual-testing]: https://www.smashingmagazine.com/2018/09/importance-manual-accessibility-testing/ | ||
| [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 | ||
| [readability]: https://datayze.com/readability-analyzer.php | ||
| [vestibular-seizure]: https://alistapart.com/article/designing-safer-web-animation-for-motion-sensitivity/ | ||
| [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/ | ||
| [wcag]: https://www.w3.org/WAI/standards-guidelines/wcag/ | ||
| [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
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,15 +1,14 @@ | ||
| Angular | ||
| ------- | ||
| # Angular | ||
|
|
||
| * [Avoid manual dependency annotations][annotations]. Disable mangling or use a | ||
| [pre-processor][ngannotate] for annotations. | ||
| * Prefer `factory` to `service`. If you desire a singleton, wrap the singleton | ||
| - [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][angular-translate]. | ||
| * Don't use the `jQuery` or `$` global. Access jQuery via `angular.element`. | ||
| - Prefer the `translate` directive to the `translate` filter for [performance | ||
| reasons]. | ||
| - Don't use the `jQuery` or `$` global. Access jQuery via `angular.element`. | ||
|
|
||
| [annotations]: http://robots.thoughtbot.com/avoid-angularjs-dependency-annotation-with-rails | ||
| [avoid manual dependency annotations]: http://robots.thoughtbot.com/avoid-angularjs-dependency-annotation-with-rails | ||
| [ngannotate]: https://github.com/kikonen/ngannotate-rails | ||
| [angular-translate]: https://github.com/angular-translate/angular-translate/wiki/Getting-Started#using-translate-directive | ||
| [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 |
|---|---|---|
| @@ -1,4 +1,4 @@ | ||
| ## Bash | ||
| # Bash | ||
|
|
||
| In addition to [shell](/shell/) best practices: | ||
|
|
||
|
|
||
Oops, something went wrong.