From eab819093f4df649c808214b7ee404d6558c5e19 Mon Sep 17 00:00:00 2001 From: Corentin <36472830+Corentints@users.noreply.github.com> Date: Tue, 5 Dec 2023 23:58:12 +0100 Subject: [PATCH 1/2] Fix documentation typo --- apps/docs/docs/api/configuration/babel-plugin.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/apps/docs/docs/api/configuration/babel-plugin.mdx b/apps/docs/docs/api/configuration/babel-plugin.mdx index 14885f90..f54bb221 100644 --- a/apps/docs/docs/api/configuration/babel-plugin.mdx +++ b/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 From 4bbe8b8ecbf499cf3afc94c65f72186b2091b416 Mon Sep 17 00:00:00 2001 From: Samuel Alex Marrujo Date: Tue, 5 Dec 2023 19:06:39 -0800 Subject: [PATCH 2/2] Grammar and spelling fixes across the doc (#35) Grammar and spelling fixes across the doc --------- Co-authored-by: Nicolas Gallagher --- .../docs/docs/learn/02-thinking-in-stylex.mdx | 72 +++++++++---------- 1 file changed, 36 insertions(+), 36 deletions(-) diff --git a/apps/docs/docs/learn/02-thinking-in-stylex.mdx b/apps/docs/docs/learn/02-thinking-in-stylex.mdx index cfbd98b4..d3e5850d 100755 --- a/apps/docs/docs/learn/02-thinking-in-stylex.mdx +++ b/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.
Utility Classes - 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.
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,15 +190,15 @@ 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. @@ -206,7 +206,7 @@ _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,14 +295,14 @@ 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. @@ -310,12 +310,12 @@ StyleX disallows this entire class of selectors. This currently makes certain CS 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 @@ -364,7 +364,7 @@ components within packages on NPM. ### Avoid global configuration -StyleX should work similarly across projects. Creating preoject-specific +StyleX should work similarly across projects. Creating project-specific configurations that change the syntax or behaviour of StyleX should be avoided. We have chosen to prioritise composability and consistency over short-term convenience. @@ -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.