Edit documentation content

apps/docs/components/FeatureCard.js

@@ -79,9 +79,9 @@ const styles = stylex.create({
 
 export default function FeatureCard({emoji, title, subtitle, children, style}) {
   return (
-    <div {...stylex.props(styles.card, style)}>
+    <article {...stylex.props(styles.card, style)}>
       <div {...stylex.props(styles.layout)}>
-        <div role="presentation" {...stylex.props(styles.emoji)}>
+        <div {...stylex.props(styles.emoji)} aria-hidden>
           {emoji}
         </div>
         <div>
@@ -90,6 +90,6 @@ export default function FeatureCard({emoji, title, subtitle, children, style}) {
           <p {...stylex.props(styles.body)}>{children}</p>
         </div>
       </div>
-    </div>
+    </article>
   );
 }

apps/docs/docs/learn/01-installation.mdx

@@ -69,8 +69,9 @@ StyleX plugin. See the API reference for more details on the
 To make this easier for commonly used packagers and meta-frameworks, StyleX
 provides plugins for Webpack, Rollup, and Next.js.
 
-<Tabs>
-<TabItem label="Rollup" value="rollup">
+<details>
+  <summary>Rollup</summary>
+
   <DevInstallExample dev={[`@stylexjs/rollup-plugin`]} />
 
   ```tsx title="rollup.config.js"
@@ -103,9 +104,11 @@ provides plugins for Webpack, Rollup, and Next.js.
 
   export default config;
   ```
+</details>
+
+<details>
+  <summary>Webpack</summary>
 
-</TabItem>
-<TabItem label="Webpack" value="webpack">
   <DevInstallExample dev={[`@stylexjs/webpack-plugin`]} />
 
   ```tsx title="webpack.config.js"
@@ -153,8 +156,11 @@ provides plugins for Webpack, Rollup, and Next.js.
   module.exports = config;
   ```
 
-</TabItem>
-<TabItem label="NextJS" value="next">
+</details>
+
+<details>
+  <summary>Next.js</summary>
+
   <DevInstallExample dev={[`@stylexjs/nextjs-plugin`]} />
 
   ```tsx title=".babelrc.js"
@@ -185,8 +191,7 @@ provides plugins for Webpack, Rollup, and Next.js.
   })({});
   ```
 
-</TabItem>
-</Tabs>
+</details>
 
 Please refer to the
 [StyleX examples apps](https://github.com/facebookexternal/stylex/tree/main/apps)

apps/docs/docs/learn/01-introduction/01-Introduction.mdx

@@ -21,8 +21,8 @@ superior to what could be authored and maintained by hand.
 
 ### Predictable
 
-- Style Encapsulation - All styles are caused by class names applied directly set
-  on an element
+- Style Encapsulation - All styles are applied as class names applied directly
+  on elements
 - No specificity issues
 - “The last style applied always wins!”
 
@@ -41,7 +41,7 @@ superior to what could be authored and maintained by hand.
 
 ### Static & Fast
 
-- No runtime style injections
+- No runtime style injection
 - All styles are bundled in a static CSS file at compile-time
 - Optimized runtime for merging class names
 
@@ -54,23 +54,18 @@ superior to what could be authored and maintained by hand.
 
 ## Ideal conditions for using StyleX?
 
-StyleX works well in a wide variety of projects, and you will usually not regret
-choosing it. However, there are some conditions that are more ideal for using StyleX than
-others.
+StyleX works well in a wide variety of projects. However, there are some conditions 
+that are more ideal for using StyleX than others.
 
 ### When authoring your UI in JavaScript
 
-StyleX is a CSS-in-JS library, which means that it is most useful when you are
-authoring your UI in JavaScript. If you're using a framework such as React,
-Preact, Solid, lit-html, or Angular, using StyleX should be a breeze.
+StyleX is a CSS-in-JS library, which means that it is most useful when an app's UI is
+authored in Javascript. If an application uses a framework like React, Preact, Solid,
+lit-html, or Angular, using StyleX should be a good fit.
 
 Some frameworks, such as Svelte and Vue use custom file formats that are
 compiled to JavaScript at build time. StyleX can still be used in these
-frameworks, but may need some extra configuration.
-
-There are also UI solutions such as `htmx` and various templating engines where
-you author your markup in files that can't contain arbitrary JavaScript. Even if
-you can make StyleX work in these environments, it may not be worth the effort.
+frameworks, but may need some custom configuration.
 
 ### Large or growing projects
 
@@ -80,20 +75,17 @@ applications.
 Since StyleX compiles to atomic class names, a big performance benefit is that
 the size of your CSS bundle plateaus as your project grows.
 
-For smaller projects, it may still make sense to choose StyleX for its
-expressive API, but the performance benefits may not be as meaningful.
-
 ### Reusable components
 
-StyleX makes the most sense when being used alongside reusable UI components.
+The benefits of StyleX are greatest when used alongside reusable UI components.
 
 For years, we have had to choose between "Design System" components that come
 with styles baked in but can be difficult to customize or "Headless" components
 that are completely unstyled.
 
-StyleX finally lets you build UI components that can have default styles _and_
+StyleX empowers developers to build UI components that can have default styles _and_
 still be customizable.
 
 Further, the consistency enables sharing these components by publishing them to
-NPM. As long as the consumer of your component is also using StyleX, the styles
+NPM. As long as the consumer of a component is also using StyleX, the styles
 will be merged and composed correctly without any additional configuration.

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

@@ -13,13 +13,16 @@ import TabItem from '@theme/TabItem';
 
 ## Core Principles
 
-To understand why StyleX exists and the reasoning behind its decisions, it may be beneficial to familiarize oneself with the fundamental principles that guide it. This may help you decide if StyleX is the right solution for you.
+To understand why StyleX exists and the reasoning behind its decisions, it may be 
+beneficial to familiarize oneself with the fundamental principles that guide it. 
+This may help you decide if StyleX is the right solution for you.
 
 These principles should also be helpful when designing new APIs for StyleX.
 
 ### Co-location
 
-There are benefits to making your code DRY, but we don't think that's true when it comes to writing your styles.
+There are benefits to making your code DRY, but we don't think that's true when it 
+comes to writing your styles.
 
 The best and most readable way to write your styles is to write them in the same
 file as the markup where you use them. Repeating yourself is not a bad thing
@@ -57,7 +60,9 @@ _and_ the expressive power available. We believe this is possible through
 build-tools.
 
 StyleX provides a completely predictable and deterministic styling
-system that works across files. It produces deterministic results not only when merging multiple selectors, but also when merging multiple shorthand and longhand properties. (e.g. `margin` vs `margin-top`).
+system that works across files. It produces deterministic results not only when 
+merging multiple selectors, but also when merging multiple shorthand and longhand
+properties. (e.g. `margin` vs `margin-top`).
 
 > "The last style applied always wins."
 
@@ -73,7 +78,9 @@ Here's how this plays out in practice:
 
 #### 1. Styles created and applied locally
 
-When authoring and consuming styles within the same file, the cost of StyleX is zero. This is because in addition to compiling away your `stylex.create` calls, StyleX also compiles away your `stylex.props` calls when possible.
+When authoring and consuming styles within the same file, the cost of StyleX is zero.
+This is because in addition to compiling away your `stylex.create` calls, StyleX also
+compiles away your `stylex.props` calls when possible.
 
 So,
 
@@ -115,8 +122,7 @@ There is no runtime overhead here.
 When passing styles across file boundaries, you pay a small cost for the
 additional power and expressivity. The `stylex.create` call is not deleted
 entirely and instead leaves behind an object mapping keys to
-class names. And the `stylex()` or `stylex.props()` calls are executed at
-runtime.
+class names. And the `stylex.props()` calls are executed at runtime.
 
 This code, for example:
 
@@ -311,12 +317,13 @@ 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 some
-patterns in CSS impossible:
-
-- e.g. It is currently impossible for a child element to have conditional styles
-  when it's parent is hovered.
+patterns in CSS impossible: e.g. It is currently impossible for a child element
+to have conditional styles when it's parent is hovered.
 
 Our goal is to support these patterns without sacrificing style encapsulation.
+For example, child elements can be conditionally styled when their parent is
+hovered by setting a variable in the parent styles and using that variable in the
+child styles.
 
 StyleX is not CSS pre-processor. It intentionally puts constraints on the power
 of CSS selectors in order to give you a fast and predictable system.
@@ -335,11 +342,8 @@ direction while the tooling gets noisy and tries to keep you within the bounds.
 
 ### Readability & Maintainabity over Terseness
 
-Many recent styling solutions are extremely terse and easy to write. Tailwind
-CSS is popular and lets you author your styles by putting extremely terse
-utility class names directly on your markup. This is great for authoring styles
-quickly, but in our opinion, in the long run, it makes the styles harder to read
-and maintain. It can also have a steeper learning curve up-front.
+Many recent utility-based styling solutions are extremely terse and easy to write.
+StyleX chooses to prioritize readability and maintainability over terseness.
 
 StyleX makes the choice to use the same CSS property names that you're already
 used to. _(We did decide to use camelCase instead of kebab-case as that makes

apps/docs/src/css/custom.css

@@ -71,6 +71,9 @@
   --pink-s: 62%;
   --pink-l: 60%;
 
+  --ifm-alert-border-color: hsla(202, 100%, 50%, 1);
+  --ifm-alert-background-color: hsla(202, 100%, 50%, 1);
+
   --ifm-navbar-background-color: var(--bg2);
   --ifm-footer-background-color: var(--bg1);
   --ifm-heading-font-family: 'Avenir Next', system-ui, -apple-system, 'Segoe UI',
@@ -153,6 +156,9 @@ html[data-theme='dark']:root {
   --pink-s: 62%;
   --pink-l: 66%;
 
+  --ifm-alert-border-color: hsl(249, 70%, 57%);
+  --ifm-alert-background-color: hsl(249, 70%, 57%);
+
   --purple-navy: hsla(251, 19%, 39%, 1);
   --black-coffee: hsla(330, 6%, 20%, 1);
   --ifm-toc-border-color: hsla(330, 6%, 75%, 0.1);
@@ -232,7 +238,7 @@ html[data-theme='dark'] .aa-DetachedSearchButton {
 
 .navbar-github-link:after {
   transition: opacity 0.2s;
-  content: "";
+  content: '';
   width: 24px;
   height: 24px;
   display: flex;

apps/docs/src/pages/index.js

@@ -134,37 +134,38 @@ export default function Home() {
               emoji="🧗‍♂️"
               subtitle="Atomic CSS for small bundles"
               title="Scalable">
-              Scale new heights without worrying about the weight CSS bundles.
+              Scale new heights without being weighed down by the size of CSS
+              bundles.
             </FeatureCard>
             <FeatureCard
               emoji="🔮"
               style={styles.double}
               subtitle="“The last style applied always wins”"
               title="Predictable">
-              You shouldn't need a crystal ball to know what your styles are
-              applied on an element.
+              You shouldn't need a crystal ball to know what styles are applied
+              on an element.
             </FeatureCard>
             <FeatureCard
               emoji="🧩"
               subtitle="Styles are data too"
               title="Composable">
-              Composing styles as component props fit together like a puzzle.
+              Styles can be passed around as props, and merged
+              deterministically. It all fits together.
             </FeatureCard>
             <FeatureCard
               emoji="🏎️"
               style={styles.smallOnLarge}
               subtitle="Ship a single static CSS file"
               title="Fast">
               The StyleX compiler bundles styles into a static CSS file. No
-              runtime style injections!
+              runtime style injection.
             </FeatureCard>
             <FeatureCard
               emoji="🥽"
               style={styles.small}
               subtitle="Strongly types for all styles"
               title="Type-Safe">
-              Safety first! Static types catch common styling mistakes as you
-              code.
+              Safety first! Static types catch common styling mistakes in code.
             </FeatureCard>
           </div>
         </section>

apps/docs/src/theme/MDXComponents/Details.js

@@ -0,0 +1,74 @@
+import React from 'react';
+import * as stylex from '@stylexjs/stylex';
+
+export default function MDXDetails({children: _children, style, ...props}) {
+  const items = React.Children.toArray(_children);
+  // Split summary item from the rest to pass it as a separate prop to the
+  // Details theme component
+  const summary = items.find(
+    (item) => React.isValidElement(item) && item.props?.mdxType === 'summary',
+  );
+  const children = <>{items.filter((item) => item !== summary)}</>;
+
+  return (
+    <details {...props} {...stylex.props(styles.details, style)}>
+      <summary {...summary.props} {...stylex.props(styles.summary)} />
+      {children}
+    </details>
+  );
+}
+
+const RETINA =
+  '@media (-webkit-min-device-pixel-ratio: 2), (min-resolution: 192dpi)';
+
+const styles = stylex.create({
+  details: {
+    display: 'grid',
+    gridTemplateRows: 'auto 1fr',
+    borderRadius: 8,
+    padding: '1rem',
+    marginBottom: '1rem',
+    backgroundColor: 'hsla(var(--cyan-h), var(--cyan-s), var(--cyan-l), 0.1)',
+    borderWidth: {
+      default: 1,
+      [RETINA]: 0.5,
+    },
+    borderStyle: 'solid',
+    borderColor: 'hsla(var(--cyan-h), var(--cyan-s), var(--cyan-l), 0.5)',
+    // HACK: This is a temprory workaround
+    ':is([open]) > summary::before': {
+      transform: 'rotate(90deg)',
+    },
+    ':is([open]) > summary': {
+      marginBottom: '1rem',
+    },
+  },
+  summary: {
+    position: 'relative',
+    paddingInlineStart: '1.2rem',
+    cursor: 'pointer',
+    fontWeight: 'bold',
+    // marginBottom: '0.5rem',
+    listStyleType: 'none',
+    '::-webkit-details-marker': {
+      display: 'none',
+    },
+    '::marker': {
+      display: 'none',
+    },
+    '::before': {
+      content: '',
+      marginRight: '0.5rem',
+      borderWidth: '.4rem',
+      borderStyle: 'solid',
+      borderColor: 'transparent',
+      borderInlineStartColor: 'var(--pink)',
+      position: 'absolute',
+      top: '0.5rem',
+      insetInlineStart: '0.25rem',
+      transform: 'rotate(0)',
+      transformOrigin: '0.2rem 50%',
+      transition: 'transform 0.2s ease-in-out',
+    },
+  },
+});