Merge branch 'main' into main

apps/docs/docs/api/configuration/babel-plugin.mdx

@@ -147,7 +147,7 @@ unstable_moduleResolution: // Default: undefined
     }
 ```
 
-Strategy to use for resolving variables defined with `stylex.defineVars()`
+Strategy to use for resolving variables defined with `stylex.defineVars()`.
 This is required if you plan to use StyleX's theming APIs.
 
 **NOTE**: While theming APIs are stable, the shape of this configuration option

apps/docs/docs/learn/02-thinking-in-stylex.mdx

@@ -25,7 +25,7 @@ There are benefits of DRY code, but we don't think that's usually true when it
 comes to authoring styles. The best and most readable way to write styles is to
 write them in the same file as the markup.
 
-StyleX is designed to for authoring, applying and reasoning about styles locally.
+StyleX is designed for authoring, applying, and reasoning about styles locally.
 
 ### Deterministic resolution
 
@@ -45,9 +45,9 @@ Most existing solutions to this problem rely on rules and conventions.
 
 <details>
   <summary>Utility Classes</summary>
-  Atomic utility class names like Tailwind CSS and Tachyons rely on a conventions and lint rules
+  Atomic utility class names like Tailwind CSS and Tachyons rely on conventions and lint rules
   to ensure that conflicting class names are not applied on the same element. Such tooling adds
-  constraints on where and how styles can be applied putting architectural limitations on styling.
+  constraints on where and how styles can be applied, putting architectural limitations on styling.
 </details>
 
 StyleX aims to improve on both the consistency and predictability of styles
@@ -159,7 +159,7 @@ function MyComponent({style}) {
 }
 ```
 
-This definitely a little more code, but the runtime cost is still minimal
+This is a little more code, but the runtime cost is still minimal
 because of how fast the `stylex()` and `stylex.props()` functions are.
 
 Most other styling solutions don't enable composition of styles across file
@@ -172,7 +172,7 @@ don't want to invent too many APIs. Instead, we want to be able to lean on
 common JavaScript patterns where possible and provide the smallest API surface
 possible.
 
-At its core StyleX can be boiled down to two functions:
+At its core, StyleX can be boiled down to two functions:
 
 1. `stylex.create`
 2. `stylex.props`
@@ -181,7 +181,7 @@ At its core StyleX can be boiled down to two functions:
 those styles to an element.
 
 Within these two functions, we choose to rely on common JS patterns rather than
-introduce unique API or patterns for StyleX. e.g. we don't have an API for
+introduce unique API or patterns for StyleX. For example, we don't have an API for
 conditional styles. Instead we support applying styles conditionally with
 boolean or ternary expressions.
 
@@ -190,23 +190,23 @@ There should be no surprises.
 
 ### Type-Safe styles
 
-Typescript has becomes massively popular due to the experience and safety it
-provides. Our styles, however, have largly remained untyped and unreliable.
+Typescript has become massively popular due to the experience and safety it
+provides. Our styles, however, have largely remained untyped and unreliable.
 Other than some path-breaking projects such as
 [Vanilla Extract](https://vanilla-extract.style/), styles are just bags of
 strings in most styling solutions.
 
-StyleX is authored in Flow with strong static types. It's packages on NPM come
+StyleX is authored in Flow with strong static types. Its packages on NPM come
 with auto-generated types for both Flow and TypeScript. When there are
-incompatibilies between the two type-systems we take the time to ensure that we
+incompatibilities between the two type-systems, we take the time to ensure that we
 write custom Typescript types to achieve at least the same level of power and safety
 as the original Flow.
 
 _All styles are typed_. When accepting styles as props, types can be used to
 constrain what styles are accepted. Styles should be as type-safe as
 any other component props.
 
-The StyleX API is strongly typed. The styles defiend with StyleX are typed too.
+The StyleX API is strongly typed. The styles defined with StyleX are typed too.
 This is made possible by using JavaScript objects to author raw styles. This is
 one of the big reasons we have chosen objects over template strings.
 
@@ -249,16 +249,16 @@ type Props = {
 ```
 
 Styles being typed enables extremely sophisticated rules about the ways in which
-a component styles can be customized with **zero-runtime cost**.
+a component's styles can be customized with **zero-runtime cost**.
 
 ### Shareable constants
 
-CSS class names, CSS variables and other CSS identifiers are defined in a global
-namespace. The obvious and common API to bring them into JavaScript is as
-strings. However, this means losing type-safety and composability.
+CSS class names, CSS variables, and other CSS identifiers are defined in a global
+namespace. Bringing CSS strings into JavaScript can mean losing type-safety and 
+composability.
 
-We want styles to be type-safe and so we've spent a lot of time coming up with
-APIs to replace these magic strings with references to Javacript constants. So
+We want styles to be type-safe, so we've spent a lot of time coming up with
+APIs to replace these magic strings with references to JavaScript constants. So
 far this is reflected in the following APIs:
 
 1. `stylex.create` Abstracts away the generated class names entirely. You deal
@@ -274,9 +274,9 @@ We're looking into ways to make other CSS identifiers such as
 
 ### Framework-agnostic
 
-StyleX is a CSS-in-JS solution, not a CSS-in-React solution. Although StyleX
-been tailored to works best with React today, It's designed to be used with any
-JavaScript framework that allows authoring markup in Javacript. This includes frameworks
+StyleX is a CSS-in-JS solution, not a CSS-in-React solution. Although StyleX has
+been tailored to work best with React today, it is designed to be used with any
+JavaScript framework that allows authoring markup in JavaScript. This includes frameworks
 that use JSX, template strings, etc.
 
 `stylex.props` returns an object with `className` and `style` properties. A wrapper
@@ -295,27 +295,27 @@ distance":
 - `.className:hover > div:first-child`
 
 All of these patterns, while powerful, makes styles fragile and less predictable.
-Applying class names on one element and can affect a completely different element.
+Applying class names on one element can affect a completely different element.
 
 Inheritable styles such as `color` will still be inherited, but that is the
 _only_ form of style-at-a-distance that StyleX allows. And in those cases too,
 the styles applied directly on an element always take precedence over inherited
 styles.
 
-This is often not the case when using complex selectors as the complex selectors
+This is often not the case when using complex selectors, as the complex selectors
 usually have higher specificity than the simple classname selectors used for
 styles applied directly on the element.
 
 StyleX disallows this entire class of selectors. This currently makes certain CSS
 patterns impossible to achieve with StyleX. Our goal is to support these patterns
 without sacrificing style encapsulation.
 
-StyleX is not CSS pre-processor. It intentionally puts constraints on the power
+StyleX is not a CSS pre-processor. It intentionally puts constraints on the power
 of CSS selectors in order to build a fast and predictable system. The API, based
-on Javascript objects instead of template strings, is designed to make these
+on JavaScript objects instead of template strings, is designed to make these
 constraints feel natural.
 
-### Readability & maintainabity over terseness
+### Readability & maintainability over terseness
 
 Some recent utility-based styling solutions are extremely terse and easy to write.
 StyleX chooses to prioritize readability and maintainability over terseness.
@@ -325,9 +325,9 @@ and a shallow learning curve. _(We did decide to use camelCase instead of kebab-
 for convenience.)_
 
 We also enforce that styles are authored in objects separate from the HTML
-elements where they are used. We made this decision to help with the readabiliy
-of HTML markup and so appropriate names for styles to indicate their purpose.
-E.g. Using a name `styles.active` like emphasizes *why* styles are being applied
+elements where they are used. We made this decision to help with the readability
+of HTML markup and for appropriate names for styles to indicate their purpose.
+For example, using a name `styles.active` like emphasizes *why* styles are being applied
 without having to dig through *what* styles are being applied.
 
 This principle leads to trade-offs where authoring styles may take more typing
@@ -353,7 +353,7 @@ change for every style change.
 ### Modularity and composability
 
 NPM has made it extremely easy to share code across projects. However, sharing
-CSS has remained a challenge. Third-party components, either have styles baked
+CSS has remained a challenge. Third-party components either have styles baked
 in that are hard or impossible to customize, or are completely unstyled.
 
 The lack of a good system to predictably merge and compose styles across
@@ -376,15 +376,15 @@ styling rules for a project.
 
 ### One small file over many smaller files
 
-When dealing with a large amount CSS, lazy loading CSS is a way to speed up
-the initial load time of a page. However, it comes at the cost of a slower
-update times, or the *Interation to Next Paint (INP)* metric. Lazy loading
+When dealing with a large amount of CSS, lazy-loading CSS is a way to speed up
+the initial load time of a page. However, it comes at the cost of slower
+update times, or the *Interation to Next Paint (INP)* metric. Lazy-loading
 any CSS on a page triggers a recalculation of styles for the entire page.
 
 StyleX is optimized for generating a single, highly optimized, CSS bundle that
-is loaded upfront. Our is to create a system where the total amount of CSS is
-small-enough that all the CSS can be loaded upfront without a noticeable
+is loaded upfront. Our goal is to create a system where the total amount of CSS is
+small enough that all the CSS can be loaded upfront without a noticeable
 performance impact.
 
 Other techniques to make the initial load times faster, such as "critical CSS"
-are compatible with StyleX, but should usually be unnecessary.
+are compatible with StyleX, but should normally be unnecessary.