diff --git a/_includes/markdown/CSS.md b/_includes/markdown/CSS.md index 5910cdbf..f5aec4d5 100644 --- a/_includes/markdown/CSS.md +++ b/_includes/markdown/CSS.md @@ -38,7 +38,7 @@ Performance best practices are not only for the browser experience, but for code

Responsive Design {% include Util/top %}

-We build our websites mobile first. We do not rely on JavaScript libraries such as `respond.js` as it does not work well in certain environments. Instead, we leverage a natural, mobile-first build process and allow sites gracefully degrade. +We build our websites mobile first. We do not rely on JavaScript libraries such as `respond.js` as it does not work well in certain environments. Instead, we leverage a natural, mobile-first build process and allow sites to gracefully degrade. ### Min-width media queries diff --git a/_includes/markdown/JavaScript.md b/_includes/markdown/JavaScript.md index e37ecda5..139b7173 100644 --- a/_includes/markdown/JavaScript.md +++ b/_includes/markdown/JavaScript.md @@ -1,6 +1,6 @@

Code Style, Tooling & Documentation {% include Util/link_anchor anchor="code-style" %} {% include Util/top %}

-10up maintains a [eslint shareable config](https://github.com/10up/eslint-config) that is used across all 10up projects. It exposes several different configs and engineers should opt-in to the config that best fits the project. We also maintain a [babel-preset](https://github.com/10up/babel-preset-default/) that works well for most of our projects. +10up maintains an [eslint shareable config](https://github.com/10up/eslint-config) that is used across all 10up projects. It exposes several different configs and engineers should opt-in to the config that best fits the project. We also maintain a [babel-preset](https://github.com/10up/babel-preset-default/) that works well for most of our projects. As far as JavaScript documentation goes, we conform to the [WordPress JavaScript documentation standards](https://make.wordpress.org/core/handbook/best-practices/inline-documentation-standards/javascript/) and those standards are enforced by 10up's eslint config. @@ -203,7 +203,7 @@ Avoid using classes unless there's a good reason to. Consider the following exam ```javascript import Module from './mymodule'; -/* Module is a ES6 class */ +/* Module is an ES6 class */ new Module('.element-selector', { /* options */ onEvent1: () => {}, @@ -226,7 +226,7 @@ module1.doSomething(); module1.hide(); ``` -The example above changes the design of the module API a bit and assumes multiple and separate instance of the module are desired. However, sometimes that might not even be necessary. If all you need is to abstract some complex logic and accept a couple of parameter, exposing a factory/init function is all you need. +The example above changes the design of the module API a bit and assumes multiple and separate instances of the module are desired. However, sometimes that might not even be necessary. If all you need is to abstract some complex logic and accept a couple of parameters, exposing a factory/init function is all you need. ```javascript // Option 2: not using classes diff --git a/_includes/markdown/Markup.md b/_includes/markdown/Markup.md index bf1892af..e30a23c1 100644 --- a/_includes/markdown/Markup.md +++ b/_includes/markdown/Markup.md @@ -199,10 +199,10 @@ Images are the most common for of media we encounter in our day to day work. WCA Between audio and video, we certainly deal with video more often, but there are some WCAG guidelines that encompass both, such as: [1.2.2 Audio/Video-only](https://www.w3.org/WAI/WCAG21/quickref/#audio-only-and-video-only-prerecorded) and [1.2.3 Audio Descriptions or Media Alternative](https://www.w3.org/WAI/WCAG21/quickref/#audio-description-prerecorded). Both these guidelines address the creation of text-based versions of the media being presented to a user. This typically comes in the form of an audio track on a video, or a transcript outputted on the page somewhere. As an aside, outputting a transcript will help the content get indexed by search engines, rather than just having the content inside a media element (audio/video) ### Audio -Audio is an important part of the work we do; making that content accessible to all users is extremely valuable. Guideline [1.4.1 Audio Control](https://www.w3.org/WAI/WCAG21/quickref/#audio-control) is related to autoplaying audio. The general rule is: don't autoplay audio. However, if you do, and that audio is playing for more than three seconds 1.4.1 states that either a mechanism must be available to pause or stop the audio, or a mechanism must be available to control audio volume independently from the overall system volume level. This is important for any user with and auditory disorder. +Audio is an important part of the work we do; making that content accessible to all users is extremely valuable. Guideline [1.4.1 Audio Control](https://www.w3.org/WAI/WCAG21/quickref/#audio-control) is related to autoplaying audio. The general rule is: don't autoplay audio. However, if you do, and that audio is playing for more than three seconds 1.4.1 states that either a mechanism must be available to pause or stop the audio, or a mechanism must be available to control audio volume independently from the overall system volume level. This is important for any user with an auditory disorder. ### Video -When putting video on the Web (that contains dialog), [guideline 1.2.2](https://www.w3.org/WAI/WCAG21/quickref/#captions-prerecorded) states that captions must be present, without exception. While we can't always control the content that's placed on a site, we can be sure to guide clients towards a situation for compliance but suggesting transcription services. Other than alternative text, dealing with captions is the most common media accessibility issue you'll likely have to deal with. +When putting video on the Web (that contains dialog), [guideline 1.2.2](https://www.w3.org/WAI/WCAG21/quickref/#captions-prerecorded) states that captions must be present, without exception. While we can't always control the content that's placed on a site, we can be sure to guide clients towards a situation for compliance by suggesting transcription services. Other than alternative text, dealing with captions is the most common media accessibility issue you'll likely have to deal with.

SVG {% include Util/link_anchor anchor="svg" %}

SVG has become a prevalent means for displaying rich vector graphics. SVG images are great for graphics with well-defined lines and simple color palettes that can be defined algorithmically, e.g. logos, iconography, and illustrations. Here are a few known benefits of SVG: diff --git a/_includes/markdown/PHP.md b/_includes/markdown/PHP.md index bb5ff628..54a9e807 100644 --- a/_includes/markdown/PHP.md +++ b/_includes/markdown/PHP.md @@ -84,7 +84,7 @@ Here are a few key points: ?> ``` - See [WordPress VIP](https://vip.wordpress.com/documentation/performance-improvements-by-removing-usage-of-post__not_in/). + See [WordPress VIP](https://docs.wpvip.com/technical-references/code-quality-and-best-practices/using-post__not_in/). * A [taxonomy](https://wordpress.org/support/article/taxonomies/) is a tool that lets us group or classify posts. @@ -206,7 +206,7 @@ However, the cache rebuild in this example would always be triggered by a visito That said, a relatively easy solution for this problem is to make sure that your users would ideally always hit a primed cache. To accomplish this, you need to think about the conditions that need to be met to make the cached value invalid. In our case this would be the change of a comment. -The easiest hook we could identify that would be triggered for any of this actions would be [```wp_update_comment_count```](https://developer.wordpress.org/reference/hooks/wp_update_comment_count/) set as ```do_action( 'wp_update_comment_count', $post_id, $new, $old )```. +The easiest hook we could identify that would be triggered for any of these actions would be [```wp_update_comment_count```](https://developer.wordpress.org/reference/hooks/wp_update_comment_count/) set as ```do_action( 'wp_update_comment_count', $post_id, $new, $old )```. With this in mind, the function could be changed so that the cache would always be primed when this action is triggered. @@ -363,7 +363,7 @@ There are a number of performance considerations for each WordPress storage vehi * [Custom Post Types](https://wordpress.org/support/article/post-types/) - WordPress has the notion of "post types". "Post" is a post type which can be confusing. We can register custom post types to store all sorts of interesting pieces of data. If we have a variable amount of data to store such as a product, a custom post type might be a good fit. * [Object Cache](https://developer.wordpress.org/reference/classes/wp_object_cache/) - See the "[Caching](#caching)" section. -While it is possible to use WordPress' [Filesystem API](https://developer.wordpress.org/apis/handbook/filesystem/) to interact with a huge variety of storage endpoints, using the filesystem to store and deliver data outside of regular asset uploads should be avoided as this methods conflict with most modern / secure hosting solutions. +While it is possible to use WordPress' [Filesystem API](https://developer.wordpress.org/apis/handbook/filesystem/) to interact with a huge variety of storage endpoints, using the filesystem to store and deliver data outside of regular asset uploads should be avoided as these methods conflict with most modern / secure hosting solutions. ### Database Writes @@ -626,7 +626,7 @@ Here is another example: ``` -[```esc_js()```](https://developer.wordpress.org/reference/functions/esc_js/) ensures that whatever is returned is safe to be printed within a JavaScript string. This function is intended to be used for inline JS, inside a tag attribute (onfocus="...", for example). +[```esc_js()```](https://developer.wordpress.org/reference/functions/esc_js/) ensures that whatever is returned is safe to be printed within a JavaScript string. This function is intended to be used for inline JS, inside a tag attribute (`onfocus="..."`, for example). We should not be writing JavaScript inside tag attributes anymore, this means that ```esc_js()``` should never be used. To escape strings for JS another function should be used. diff --git a/_includes/markdown/Performance.md b/_includes/markdown/Performance.md index 614c54e2..83624ac4 100644 --- a/_includes/markdown/Performance.md +++ b/_includes/markdown/Performance.md @@ -87,7 +87,7 @@ As defined by Google, the 3 Core Web Vitals are currently: * [Largest Contentful Paint (a.k.a. LCP)](https://web.dev/lcp/) * [Cumulative Layout Shift (a.k.a. CLS)](https://web.dev/cls/) -* [First Input Delay (a.k.a. FIP)](https://web.dev/fid/) +* [First Input Delay (a.k.a. FID)](https://web.dev/fid/) ### Largest Contentful Paint Largest Contentful Paint is an important metric for measuring perceived user performance, specifically *loading performance*. @@ -244,7 +244,7 @@ By maintaining a low FID score, users will *feel* like the page is loading faste First Input Delay is specifically purposed for measuring how quickly the page becomes interactive to the user on their first impression, where as a vital such as First Contentful Paint measures how quickly the page becomes visible. These are 2 important concepts to grasp when it comes to debugging and diagnosing Core Web Vitals. -> An FID score of 100 milliseconds (ms) or less is considering to be a conducive measurement for good user experience. +> An FID score of 100 milliseconds (ms) or less is considered to be a conducive measurement for good user experience. FID is a unique Core Web Vital and is not actually tracked in Lighthouse or other service metrics. FID is a field metric, meaning that its score is generated by collating data from millions of websites accessed by Google Chrome users. When it comes to generating a score for FID "in the lab" or otherwise through Lighthouse, you will be looking to improve the [Total Blocking Time (TBT)](https://web.dev/tbt/) metric. You can think of TBT as a proxy to FID. This is because FID requires a real user and real users cannot be "spoofed" by Lighthouse. diff --git a/_includes/markdown/React.md b/_includes/markdown/React.md index d4137fff..8e635754 100644 --- a/_includes/markdown/React.md +++ b/_includes/markdown/React.md @@ -256,8 +256,9 @@ React accessibility is not so different than standard accessibility support. It Using the the most relevant HTML elements is always preferred, and doesn’t change when using React. Sometimes we can break HTML semantics when we add div elements to our JSX to make our React code work, especially with a set of elements such as lists. In these cases we should use Fragments. [Fragments](https://reactjs.org/docs/accessibility.html/#semantic-html) are a pattern used in React which allow a component to return multiple elements, without an encompassing div component. Using div elements in certain contexts may break HTML semantics. -Use fragment when a key prop is required -Use `` syntax everywhere else + +Use fragments when a key prop is required. +Use `` syntax everywhere else. ### Accessible Forms Standard HTML practices should be used for forms. One caveat though is making sure all inputs have proper labeling. In React the `“for”` attribute is written as `“htmlFor”` in JSX. @@ -270,7 +271,7 @@ Standard HTML practices should be used for forms. One caveat though is making su React applications continuously modify the HTML DOM during runtime, sometimes leading to keyboard focus being lost or set to an unexpected element. React provides “Refs” in order to modify child components or elements outside of the standard flow. These can help us specifically manage keyboard focus. -The ref attribute can be placed on any React component, with a function value. This function will be executed as soon as the component is mounted or unmounted. The first parameter of the function will be a reference to the element or the component the ref is on. +The `“ref”` attribute can be placed on any React component, with a function value. This function will be executed as soon as the component is mounted or unmounted. The first parameter of the function will be a reference to the element or the component the `ref` is on. [Read more about creating refs and focus control in React](https://reactjs.org/docs/accessibility.html#focus-control) diff --git a/_includes/markdown/Site-Security.md b/_includes/markdown/Site-Security.md index 68b5f801..4c216480 100644 --- a/_includes/markdown/Site-Security.md +++ b/_includes/markdown/Site-Security.md @@ -26,7 +26,7 @@ By default, always set the ```X-Frame-Options``` header to ```SAMEORIGIN```. Thi ## Disable XML-RPC -Always disable XML-RPC since it can be used for brute force or DDoS attacks. XML_RPC is an older and mostly unused feature. Perfer the JSON API when available. +Always disable XML-RPC since it can be used for brute force or DDoS attacks. XML_RPC is an older and mostly unused feature. Prefer the JSON API when available. ## WordPress updates