rewording pass

Author: keithamus

.remarkrc.mjs

@@ -67,7 +67,7 @@ export default {
       {
         noBinary: true,
         // TODO: Reduce this list
-        ignore: ["primitive", "just", "easy", "easily", "straightforward", "invalid", "obvious"],
+        ignore: ["primitive", "just", "easy", "easily", "straightforward", "invalid", "obvious", "host", "hosts"],
       },
     ],
     // TODO: Lower this threshold to 5 / 7

.spelling

@@ -141,3 +141,11 @@ http
 metasyntactic
 callout
 callouts
+stylesheet
+stylesheets
+Stylesheets
+programmatically
+deeppink
+unstyled
+preload
+Constructable

CONTRIBUTING.md

@@ -11,17 +11,17 @@ Contributions are always welcome! Before contributing, please read the
   [good first issue label](https://github.com/WebComponentsGuide/webcomponents.guide/labels/good%20first%20issue).
 - If you're contributing to larger pieces, like an idea or new section, tutorial, or blog post, then please raise an
   issue first! This way we can discuss an action plan and figure out a high level overview of what we should write.
-- [Reading the styleguide](./STYLEGUIDE.md) will help you write content that fits with our intended style.
+- [Reading the style guide](./STYLEGUIDE.md) will help you write content that fits with our intended style.
 
 ### Setup
 
 You can run the code locally by cloning the repository, and running `npm install` followed by `npm start`:
 
 ```sh
-$ git clone [email protected]:WebComponentsGuide/webcomponents.guide
-$ cd webcomponents.guide
-$ npm install
-$ npm start
+git clone [email protected]:WebComponentsGuide/webcomponents.guide
+cd webcomponents.guide
+npm install
+npm start
 ```
 
 You can now visit <http://localhost:8080/> to see the local copy of the website. As you edit files the website will

STYLEGUIDE.md

@@ -252,7 +252,7 @@ Do not try to write prose transitioning to the next page, as not only is this un
 pages around more difficult.
 
 Summaries can be useful for reinforcing complex information throughout the document, but use them sparingly. A summary
-should stand a lone as useful content, and not attempt to clarify unclear content.
+should stand a lone as useful content, and not try to clarify unclear content.
 
 [how-users-read-web]: https://www.nngroup.com/articles/how-users-read-on-the-web/
 [active-voice]: https://en.wikipedia.org/wiki/Active_voice

learn/components/autonomous-vs-customized-elements.md

@@ -3,13 +3,10 @@ title: Autonomous vs Customized Elements
 order: 2
 ---
 
-In the [previous section][defining-a-component] we learned about _Autonomous Custom Elements_ vs _Customized Built-in
-Elements_. The most popular way to make elements is to use the _Autonomous Custom Element_ style, by making up your own
-tag and extending `HTMLElement`. Each style comes with different trade-offs.
-
-Choosing a type of component to build will depend on a lot of factors. _Autonomous Custom Elements_ give you a blank
-canvas to work with. _Customized Built-ins_ **extend** the element you're customizing. Here are some considerations to
-think about:
+The most popular way to make elements is to use the _Autonomous Custom Element_ style, by making up your own tag and
+extending `HTMLElement`. Each style comes with different trade-offs. Choosing a type of component to build will depend
+on a lot of factors. _Autonomous Custom Elements_ give you a blank canvas to work with. _Customized Built-ins_
+**extend** the element you're customizing. Here are some considerations to think about:
 
 ### Tag Name
 
@@ -136,7 +133,6 @@ Custom Element_ is a good choice. To help drive your decision, here's a table su
 
 {% stub %}
 
-[defining-a-component]: /learn/components/
 [shadowdom]: /learn/components/shadowdom
 [content-categories]: https://developer.mozilla.org/en-US/docs/Web/HTML/Content_categories
 [phrasing-content]: https://developer.mozilla.org/en-US/docs/Web/HTML/Content_categories#phrasing_content

learn/components/rendering.md

@@ -3,10 +3,10 @@ title: Rendering
 order: 5
 ---
 
-When a Web Component is initialized, it can start interacting with the document and make changes to it. While a
-component **could** make changes to the DOM the element is within, there's a better way. Each component can have its own
-DOM, that is _encapsulated_ from the rest of the page. This is called the _ShadowDOM_. A component can create and attach
-a _ShadowDOM_ to itself by using `attachShadow({ mode: 'open' })`:
+When a Web Component initializes, it can start interacting with the document and make changes to it. While a component
+**could** make manipulate other parts of DOM or even it's children, there's a better way. Each component can have its
+own DOM, _encapsulated_ from the rest of the page. This is called the _ShadowDOM_. A component can create and attach a
+_ShadowDOM_ to itself by using `attachShadow({ mode: 'open' })`:
 
 ```js
 class StopWatchElement extends HTMLElement {
@@ -19,14 +19,21 @@ class StopWatchElement extends HTMLElement {
 }
 ```
 
-This DOM tree is exclusive to your Web Component, and the rest of the document can't accidentally influence it. You can
-append new elements into a components _ShadowDOM_ (even stylesheets) and it won't impact other parts of the page. Other
-elements can't accidentally reach in to another elements _ShadowDOM_; DOM APIs like `.querySelector()` won't reach into
-different _ShadowDOMs_. All this means the _ShadowDOM_ is your components safe space to put whatever content it needs to
-render.
+{% tip "info" %}
 
-One way to make use of this _ShadowDOM_ is to set the `.innerHTML` whenever your element gets connected. To do this you
-can use the `connectedCallback()` lifecycle function:
+The `.shadowRoot` property is always present on an element. It will return an elements _open shadow root_ or `null` if
+it doesn't have one. Setting `shadowRoot =` isn't necessary - it's redundant - but it makes the code more readable.
+
+{% endtip %}
+
+This _ShadowDOM_ tree is exclusive to your Web Component. The rest of the document can't accidentally influence it. You
+can add new elements into a _ShadowDOM_ - even stylesheets - and it won't impact the rest of the DOM. Other logic or
+styles won't get access to a components _ShadowDOM_. CSS selectors do not cross the boundary between the main _light
+DOM_ and the _ShadowDOM_. APIs like `.querySelector()`, or `.children` also don't cross this boundary. All this means
+the _ShadowDOM_ is your components safe space to put whatever content it needs to render.
+
+One way to make use of this _ShadowDOM_ is to use the same DOM APIs to construct the contents. For example setting the
+`.innerHTML` whenever your element gets connected. To do this you can use the `connectedCallback()` lifecycle function:
 
 ```js
 class StopWatchElement extends HTMLElement {
@@ -46,12 +53,13 @@ class StopWatchElement extends HTMLElement {
 <my-component></my-component>
 ```
 
-Perhaps a slightly better way to do this is using a `<template>` element, and cloning the contents of it. A key reason
-for this is that cloning from a template requires less computation than setting `innerHTML`. It also separates your
-template from your logic, which will keep code cleaner as your component grows in complexity.
+You can define a `<template>` element up front. Using the `cloneNode()` API efficiently copies the template into the
+_Shadow Root_. This requires less computation than setting `innerHTML` each time, and can be easier to read. It also
+separates your template from your logic. Keeping templates away from logic keeps code cleaner as your component grows in
+complexity.
 
 ```js
-// The template can be defined up front
+// The template can be defined up front and re-used
 const template = document.createElement("template")
 template.innerHTML = `<p>Hello World!</p>`
 

learn/components/styling.md

@@ -1,16 +1,15 @@
 ---
 title: Styling
-order: 5
+order: 6
 ---
 
 Web Components have powerful styling capabilities which make them portable and extensible. Styles declared within the
-Shadow DOM serve as a Web Component’s default styling. It’s similar to writing a user-agent stylesheet for your custom
-element and it works quite similarily as well.
+Shadow DOM serve as a Web Component's default styling. They work similarly to writing a user-agent stylesheet.
 
 ## Shadow Encapsulation: Scoped Styles
 
 Shadow DOM offers a boundary line between styles outside the tree, and styles inside the tree. Styles cannot cross this
-boundary unintentionally. This is different to regular CSS where a selector can effect every element on a page.
+boundary unintentionally. This is different to regular CSS where a selector can affect every element on a page.
 
 ```html
 <style>
@@ -33,7 +32,7 @@ boundary unintentionally. This is different to regular CSS where a selector can
 </fancy-p>
 ```
 
-The `<p>` element within the shadow tree is not effected by the styles declared outside of the shadow tree.
+The `<p>` element within the shadow tree is not affected by the styles declared outside of the shadow tree.
 
 ## Inheritance
 
@@ -65,20 +64,19 @@ element itself (also known as the shadow host).
 </article>
 ```
 
-The `<article-meta>` custom element inherits its `color` from the `<article>` element where it is set to `deeppink`. The
+The `<article-meta>` custom element inherits its `color` from the `<article>` element where it's set to `deeppink`. The
 `<span>` element within the shadow tree inherits its `color` from the `<article-meta>` custom element which means the
 value will also be `deeppink`.
 
 ## Styling elements outside of a shadow tree
 
-In order to be portable, Web Components can provide default styles for the element itself (also known as the shadow
-host). They can also style slotted elements with some default styles.
+In order to be portable, Web Components can add default styles for the element itself (also known as the shadow host).
+They can also style slotted elements with some default styles.
 
 ### Writing default styles for the shadow host with `:host` and `:host()`
 
-There are two selectors which can be used to style the shadow host from within the shadow tree. They are the `:host`
-pseudo-class and the `:host()` pseudo-class function. The first will always select the shadow host. Here’s `:host` in
-action:
+You can use host selectors to style an element from within the shadow tree. The `:host` pseudo-class always applies
+styles to the custom element, aka the _shadow host_:
 
 ```html
 <fancy-p>
@@ -92,9 +90,10 @@ action:
 </fancy-p>
 ```
 
-The `:host()` selector will select the shadow host if it matches a given selector. For example, it can be used to select
-for hosts that have a given attribute. While `:host` may apply to `<fancy-p>` component, `:host([extra])` would apply
-only to `<fancy-p extra>` elements:
+You can also add conditional styles to the _shadow host_ using `:host()` _selector function_. This can be used to style
+the host so long as it matches the given selector. For example, it can be used to select for hosts that have a given
+attribute. While `:host` may apply to `<fancy-p>` component, `:host([extra])` would apply only to `<fancy-p extra>`
+elements:
 
 ```css
 :host([extra]) {
@@ -239,11 +238,12 @@ fancy-article::part(header) slot {
 
 ## How to include default styles for a Web Component
 
-There are a variety of methods to include styles for a Web Component. Some will be familiar, but others are newer.
+You can load a stylesheet for a Web Component with a variety of methods. Some may be familiar, but others are newer.
 
 ### Using `<style>`
 
-The `<style>` tag is the most simple way to write styles for a Web Component. Just include it in your shadow tree:
+You can include a `<style>` tag within your Shadow Tree, and it'll only apply to the Shadow Tree itself - it won't
+affect the rest of the page:
 
 ```html
 <style>
@@ -261,16 +261,16 @@ Using a `<link rel="stylesheet">` element in the shadow tree will allow you to w
 <link rel="stylesheet" href="/fancy-article-element.css" />
 ```
 
-If you do this, the stylesheet will be loaded after the script is loaded. This will likely cause a “flash of unstyled
-content” (FOUC). To circumvent this, you can preload the stylesheet like this:
+If you do this, the stylesheet will be loaded after the script is loaded. This will likely cause a _flash of unstyled
+content_ (FOUC). To circumvent this, you can preload the stylesheet like this:
 
 ```html
 <link rel="preload" href="/fancy-article-element.css" as="style" />
 ```
 
 ### Using Constructable Stylesheets
 
-Constructable Stylesheets are stylesheets which are programmatically created in JavaScript. You can create a new
+_Constructable Stylesheets_ are stylesheets which are programmatically created in JavaScript. You can create a new
 stylesheet using the `CSSStyleSheet` constructor and set styles with the `.replaceSync()` method:
 
 ```js
@@ -293,7 +293,7 @@ class FancyArticleElement extends HTMLElement {
 
 CSS Module scripts allow developers to import stylesheets as if they were a module script. To do so, use an import
 assertion where the `type` is `css` and then you can add the imported stylesheet to the `adoptedStyleSheets` array for
-the element’s shadow root.
+the element's shadow root.
 
 ```js
 import stylesheet from "./fancy-article-element.css" assert { type: "css" }

learn/javascript/classes.md

@@ -177,7 +177,7 @@ myupper.#original = "Hello"
 Private fields work like public fields with regards to evaluation. They get evaluated with the class _instantiation_, so
 `this` will refer to the class instance, and function calls will be called each time the class is constructed.
 
-### Using private fields with public APIs to make changeable, _read only state_
+### _Read only fields_ using private state & public APIs
 
 _Private fields_ are useful to have a value that the internals of a class can change, but that outside code cannot. It's
 also often useful to allow outside code to _read_ a classes _private state_, but not change it. To do this you can
@@ -212,7 +212,7 @@ myupper.sentence = "Hello Universe"
 myupper.firstWord = "Hola"
 ```
 
-### Using private fields with public APIs to make reactive fields
+### _Reactive fields_ using private state & public APIs
 
 A _public field_ can be changed on a class instance, and the class will not know when that happens. To make a class
 react to a change in its public fields, you can combine a private field with `get` and `set` functions, like so:

learn/javascript/events-in-more-detail.md

@@ -3,14 +3,6 @@ title: Events in more detail
 order: 4
 ---
 
-In the [previous section][events] we learned about `EventTarget` - the class that gives us an event system, with
-`addEventListener` and `dispatchEvent`. We also learned about the `Event` class which `EventTarget` takes and propagates
-to all listeners.
-
-In this section we'll learn about these features in more detail, covering some more advanced topics, techniques, and
-potential pitfalls you'll need to watch out for. It's a good idea to make sure you've got a good understanding of
-everything covered in the [previous section][events] before reading on.
-
 #### Adding multiple listeners
 
 The [previous section][events] showed how you can add an _Event listener_ with `.addEventListener()`, but you can add

learn/javascript/events.md

@@ -5,11 +5,8 @@ order: 3
 
 Web browsers (and server side engines like [NodeJS][node] and [Deno][deno]) include an Event API which has become a
 foundational concept in JavaScript, and is particularly important when we talk about Web Components. The two classes
-that drive all these events are the `Event` class, and the `EventTarget` class.
-
-This section will go over the concepts of Events, the basics of the `EventTarget` and `Event` classes, and the next
-section will touch on some more advanced topics but - as always - if you're interested in learning more MDN has many
-resources that cover Events:
+that drive all these events are the `Event` class, and the `EventTarget` class. MDN has some great in depth guides for
+dealing with Events that go beyond this guide:
 
 - [Introduction to Events](https://developer.mozilla.org/en-US/docs/Learn/JavaScript/Building_blocks/Events)
 - [The EventTarget API](https://developer.mozilla.org/en-US/docs/Web/API/EventTarget)