docs: Style macro docs

packages/@react-spectrum/s2/style/index.ts

@@ -77,7 +77,7 @@ const iconSizes = {
 
 export function iconStyle(this: MacroContext | void, options: IconStyle): StyleString<Exclude<keyof IconStyle, 'color' | 'size'>> {
   let {size = 'M', color, ...styles} = options;
-  
+
   if (color) {
     styles['--iconPrimary'] = {
       type: 'fill',

packages/dev/s2-docs/pages/react-aria/styling.mdx

@@ -242,6 +242,25 @@ With this configured, all states for React Aria Components can be accessed with
 </ListBoxItem>
 ```
 
+## Style macro
+
+If you want to build custom components that follow Spectrum design tokens and styling, you can use the [style macro](../s2/styling.html) from React Spectrum. The `style` macro is a build-time CSS generator that provides type safe access to Spectrum 2 design tokens including colors, spacing, sizing, and typography.
+
+```tsx
+import {Checkbox} from 'react-aria-components';
+import {style} from '@react-spectrum/s2/style' with {type: 'macro'};
+
+<Checkbox
+  className={style({
+    backgroundColor: {
+      default: 'gray-100',
+      isHovered: 'gray-200',
+      isSelected: 'gray-900'
+    }
+  })}
+/>
+```
+
 ## Animation
 
 React Aria Components supports both [CSS transitions](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_transitions/Using_CSS_transitions) and [keyframe animations](https://developer.mozilla.org/en-US/docs/Web/CSS/@keyframes), and works with JavaScript animation libraries like [Framer Motion](https://www.framer.com/motion/).

packages/dev/s2-docs/pages/s2/reference.mdx

@@ -0,0 +1,80 @@
+import {Layout} from '../../src/Layout';
+import {InlineAlert, Heading, Content, Link} from '@react-spectrum/s2';
+import {S2Colors} from '../../src/S2Colors';
+import {S2Typography} from '../../src/S2Typography';
+import {StyleMacroProperties} from '../../src/types';
+import {getPropertyDefinitions, getShorthandDefinitions} from '../../src/styleProperties';
+export default Layout;
+
+export const section = 'Components';
+export const tags = ['style', 'macro', 'spectrum', 'custom', 'values', 'reference'];
+export const description = 'Reference table for the style macro';
+
+# Style Macro
+
+The `style` macro supports a constrained set of values per property that conform to Spectrum 2.
+
+## Colors
+
+All Spectrum 2 color tokens are available across color properties (e.g., `backgroundColor`, `color`, `borderColor`).
+
+<S2Colors />
+
+<StyleMacroProperties properties={getPropertyDefinitions('color')} />
+
+## Dimensions
+
+Spacing props like `margin` and `padding` accept values on a **4px grid**. These are specified in `px` and get converted to `rem`. In addition to numbers, these named options are available:
+
+- `edge-to-text` – default spacing between the edge of a control and its text. Relative to control height.
+- `pill` – default spacing between the edge of a pill-shaped control and its text. Relative to control height.
+- `text-to-control` – default spacing between text and a control (e.g., label and input). Scales with font size.
+- `text-to-visual` – default spacing between text and a visual element (e.g., icon). Scales with font size.
+
+Size props like `width` and `height` accept arbitrary pixel values. Values are converted to `rem` and multiplied by 1.25x on touch devices to increase hit targets.
+
+<StyleMacroProperties properties={getPropertyDefinitions('dimensions')} />
+
+## Text
+
+Spectrum 2 typography can be applied via the `font` [shorthand](#shorthand), which sets `fontFamily`, `fontSize`, `fontWeight`, `lineHeight`, and `color`. You can override any of these individually.
+
+```tsx
+<main>
+  <h1 className={style({font: 'heading-xl'})}>Heading</h1>
+  <p className={style({font: 'body'})}>Body</p>
+  <ul className={style({font: 'body-sm', fontWeight: 'bold'})}>
+    <li>List item</li>
+  </ul>
+</main>
+```
+
+Type scales include: UI, Body, Heading, Title, Detail, and Code. Each scale has a default and additional t-shirt sizes (e.g., `ui-sm`, `heading-2xl`, `code-xl`).
+
+<S2Typography />
+
+
+<StyleMacroProperties properties={getPropertyDefinitions('text')} />
+
+
+## Effects
+
+<StyleMacroProperties properties={getPropertyDefinitions('effects')} />
+
+## Layout
+
+<StyleMacroProperties properties={getPropertyDefinitions('layout')} />
+
+## Misc
+
+<StyleMacroProperties properties={getPropertyDefinitions('misc')} />
+
+## Shorthands
+
+Shorthands apply their provided value to commonly grouped properties.
+
+<StyleMacroProperties properties={getShorthandDefinitions('shorthand')} />
+
+## Conditions
+
+<StyleMacroProperties properties={getPropertyDefinitions('conditions')} />

packages/dev/s2-docs/pages/s2/styling.mdx

@@ -1,8 +1,7 @@
 import {Layout} from '../../src/Layout';
 import {InlineAlert, Heading, Content, Link} from '@react-spectrum/s2';
-import {S2Colors} from '../../src/S2Colors';
-import {S2Typography} from '../../src/S2Typography';
 import {S2StyleProperties} from '../../src/S2StyleProperties';
+import {S2FAQ} from '../../src/S2FAQ';
 export default Layout;
 
 export const section = 'Guides';
@@ -11,7 +10,7 @@ export const description = 'Styling in React Spectrum';
 
 # Styling
 
-React Spectrum includes a build-time style macro that generates atomic CSS and lets you apply Spectrum tokens directly in your components with type-safe autocompletion.
+React Spectrum includes a build-time `style` macro that generates atomic CSS and lets you apply Spectrum tokens directly in your components with type-safe autocompletion.
 
 ## Style macro
 
@@ -37,6 +36,14 @@ Colocating styles with your component code means:
 - Develop more efficiently – no switching files or writing selectors.
 - Refactor with confidence – changes are isolated; deleting a component removes its styles.
 
+<InlineAlert variant="informative">
+  <Heading>Important Note</Heading>
+  <Content>
+    Due to the atomic nature of the generated CSS rules, it is strongly recommended that you follow the best practices listed [below](#css-optimization).
+    Failure to do so can result in large number of duplicate rules and obtuse styling bugs.
+  </Content>
+</InlineAlert>
+
 ## Spectrum components
 
 The `styles` prop accepts a limited set of CSS properties, including layout, spacing, sizing, and positioning. Other styles such as colors and internal padding cannot be customized within Spectrum components.
@@ -86,95 +93,26 @@ import {Button} from '@react-spectrum/s2';
   'visibility'
 ]} />
 
-### UNSAFE Style Overrides
-
-We highly discourage overriding the styles of React Spectrum components because it may break at any time when we change our implementation, making it difficult for you to update in the future. Consider using [React Aria Components](https://react-spectrum.adobe.com/react-aria/) with our style macro to build a custom component with Spectrum styles instead.
-
-With that being said, the `UNSAFE_className` and `UNSAFE_style` props are supported on Spectrum 2 components as last-resort escape hatches.
-
-```tsx
-/* YourComponent.tsx */
-import {Button} from '@react-spectrum/s2';
-import './YourComponent.css';
-
-function YourComponent() {
-  return <Button UNSAFE_className="your-unsafe-class">Button</Button>;
-}
-```
-
-```css
-/* YourComponent.css */
-.your-unsafe-class {
-  background: red;
-}
-```
-
-## Values
-
-The `style` macro supports a constrained set of values per property that conform to Spectrum 2. This improves consistency and maintainability.
-
-### Colors
-
-All Spectrum 2 color tokens are available across color properties (e.g., `backgroundColor`, `color`, `borderColor`).
-
-<S2Colors />
-
-### Spacing
-
-Spacing props like `margin` and `padding` accept values on a **4px grid**. These are specified in `px` and get converted to `rem`. In addition to numbers, these named options are available:
-
-- `edge-to-text` – default spacing between the edge of a control and its text. Relative to control height.
-- `pill` – default spacing between the edge of a pill-shaped control and its text. Relative to control height.
-- `text-to-control` – default spacing between text and a control (e.g., label and input). Scales with font size.
-- `text-to-visual` – default spacing between text and a visual element (e.g., icon). Scales with font size.
-
-### Sizing
-
-Size props like `width` and `height` accept arbitrary pixel values. Values are converted to `rem` and multiplied by 1.25x on touch devices to increase hit targets.
-
-### Typography
-
-Spectrum 2 typography is applied via the `font` shorthand, which sets `fontFamily`, `fontSize`, `fontWeight`, `lineHeight`, and `color`. You can override any of these individually.
-
-```tsx
-<main>
-  <h1 className={style({font: 'heading-xl'})}>Heading</h1>
-  <p className={style({font: 'body'})}>Body</p>
-  <ul className={style({font: 'body-sm', fontWeight: 'bold'})}>
-    <li>List item</li>
-  </ul>
-</main>
-```
-
-Type scales include: UI, Body, Heading, Title, Detail, and Code. Each scale has a default and additional t-shirt sizes (e.g., `ui-sm`, `heading-2xl`, `code-xl`).
-
-<S2Typography />
-
-<InlineAlert variant="notice">
-  <Heading>Important Note</Heading>
-  <Content>
-    Only use `<Heading>` and `<Text>` inside Spectrum components with predefined styles (e.g., `<Dialog>`, `<MenuItem>`). They are unstyled by default and should not be used standalone. Use HTML elements with the style macro instead.
-  </Content>
-</InlineAlert>
-
 ## Conditional styles
 
 Define conditional values as objects to handle media queries, UI states (hover/press), and variants. This keeps all values for a property together.
+Note how the example below uses a predefined [breakpoint](./reference.html#conditions) alongside a custom media query.
 
 ```tsx
 <div
   className={style({
     padding: {
       default: 8,
-      lg: 32
+      lg: 32,
+      '@media (min-width: 2560px)': 64,
     }
   })}
 />
 ```
 
 Conditions are mutually exclusive and ordered. The macro uses CSS cascade layers so the last matching condition wins without specificity issues.
 
-### Runtime conditions
+## Runtime conditions
 
 When runtime conditions are detected (e.g., variants, UI states), the macro returns a function to resolve styles at runtime.
 
@@ -195,13 +133,14 @@ function MyComponent({variant}: {variant: 'primary' | 'secondary'}) {
 }
 ```
 
-Boolean conditions starting with `is` can be used directly without nesting:
+Boolean conditions starting with `is` or `allows` can be used directly without nesting:
 
 ```tsx
 const styles = style({
   backgroundColor: {
     default: 'gray-100',
-    isSelected: 'gray-900'
+    isSelected: 'gray-900',
+    allowsRemoving: 'gray-400'
   }
 });
 
@@ -222,7 +161,7 @@ import {style} from '@react-spectrum/s2/style' with {type: 'macro'};
       isSelected: 'gray-900'
     }
   })}
-/> 
+/>
 ```
 
 ### Nesting conditions
@@ -253,6 +192,11 @@ const styles = style({
 Extract common styles into constants and spread them into `style` calls. These must be in the same file or imported from another file as a macro.
 
 ```tsx
+// style-utils.ts
+export const bannerBackground = () => 'blue-1000' as const;
+
+// component.tsx
+import {bannerBackground} from './style-utils' with {type: 'macro'};
 const horizontalStack = {
   display: 'flex',
   alignItems: 'center',
@@ -261,6 +205,7 @@ const horizontalStack = {
 
 const styles = style({
   ...horizontalStack,
+  backgroundColor: bannerBackground(),
   columnGap: 4
 });
 ```
@@ -308,9 +253,58 @@ const buttonStyle = style({
 <Button styles={buttonStyle}>Press me</Button>
 ```
 
+## Setting CSS variables
+
+CSS variables can be directly defined in a `style` macro, allowing child elements to then access them in their own styles.
+A `type` should be provided to specify the CSS property type the `value` represents.
+
+```tsx
+const parentStyle = style({
+  '--rowBackgroundColor': {
+    type: 'backgroundColor',
+    value: 'gray-400'
+  }
+});
+
+const childStyle = style({
+  backgroundColor: '--rowBackgroundColor'
+});
+```
+
+## Creating custom components
+
+In-depth examples are coming soon!
+
+`mergeStyles` can be used to merge the style strings from multiple macros together, with the latter styles taking precedence similar to object spreading.
+This behavior can be leveraged to create a component API that allows an end user to only override specific styles conditionally.
+
+```tsx
+// User can override the component's background color ONLY if it isn't "quiet"
+const baselineStyles = style({backgroundColor: 'gray-100'}, ['backgroundColor']);
+const quietStyles = style({backgroundColor: 'transparent'});
+const userStyles = style({backgroundColor: 'celery-600'});
+
+function MyComponent({isQuiet, styles}: {isQuiet?: boolean, styles?: StyleString}) {
+  let result = mergeStyles(
+    baselineStyles(null, styles),
+    isQuiet ? quietStyles : null
+  );
+
+  return <div className={result}>My component</div>
+}
+
+// Displays quiet styles
+<MyComponent isQuiet styles={userStyles} />
+
+// Displays user overrides
+<MyComponent styles={userStyles} />
+```
+
+The `iconStyle` macro should be used when styling Icons, see the [docs](./Icons.html#iconstyle) for more information.
+
 ## CSS optimization
 
-The style macro relies on CSS bundling and minification for optimal output. Follow these best practices:
+The `style` macro relies on CSS bundling and minification for optimal output. Follow these best practices:
 
 - Ensure styles are extracted into a CSS bundle; do not inject at runtime with `<style>` tags.
 - Use a CSS minifier like `lightningcss` to deduplicate common rules (consider in dev for easier debugging).
@@ -362,4 +356,22 @@ CSS resets are strongly discouraged. Global CSS selectors can unintentionally af
 /* App.css */
 @layer reset, _;
 @import "reset.css" layer(reset);
-```
+```
+
+## Developing with style macros
+
+Since `style` macros are quite different from using `className`/`style` directly, many may find it initially challenging to debug and develop against.
+Below are some useful tools that may benefit your developer experience:
+
+- The [atomic-css-devtools](https://github.com/astahmer/atomic-css-devtools) extension presents an inspected element's atomic CSS rules
+in a non-atomic format, making it easier to scan.
+
+- This [sandbox](https://codesandbox.io/p/devbox/react-spectrum-s2-style-macro-template-h6fpsq) is preconfigured to support React Spectrum S2, React Aria Components, and
+the `style` macros for quick prototyping.
+
+- If you are using Cursor, we offer a set of [Cursor rules](https://github.com/adobe/react-spectrum/blob/main/rules/style-macro.mdc) to use when developing with style macros. Additionally,
+we have MCP servers for [React Aria](../react-aria/mcp.html) and [React Spectrum](./mcp.html) respectively that interface with the docs.
+
+## FAQ
+
+<S2FAQ />