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/styling.mdx

@@ -3,15 +3,20 @@ 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';
 export const tags = ['style', 'macro', 'spectrum', 'custom'];
 export const description = 'Styling in React Spectrum';
+export const relatedPages = [
+  {title: 'Advanced', url: './styling/advanced.html'},
+  {title: 'Reference Table', url: './styling/reference.html'}
+];
 
 # 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 +42,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,32 +99,9 @@ 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.
+The `style` macro supports a constrained set of values per property that conform to Spectrum 2. This improves consistency and maintainability. See the [reference](./styling/reference.html) page for a full list of available style macro properties.
 
 ### Colors
 
@@ -135,6 +125,7 @@ Size props like `width` and `height` accept arbitrary pixel values. Values are c
 ### 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.
+Note that you should always specify the `font` at the element level, setting it globally is insufficient since this will often differ per component.
 
 ```tsx
 <main>
@@ -153,164 +144,17 @@ Type scales include: UI, Body, Heading, Title, Detail, and Code. Each scale has
 <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.
+    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.
-
-```tsx
-<div
-  className={style({
-    padding: {
-      default: 8,
-      lg: 32
-    }
-  })}
-/>
-```
-
-Conditions are mutually exclusive and ordered. The macro uses CSS cascade layers so the last matching condition wins without specificity issues.
-
-### Runtime conditions
+### Breakpoints
 
-When runtime conditions are detected (e.g., variants, UI states), the macro returns a function to resolve styles at runtime.
-
-```tsx
-import {style} from '@react-spectrum/s2/style' with {type: 'macro'};
-
-const styles = style({
-  backgroundColor: {
-    variant: {
-      primary: 'accent',
-      secondary: 'neutral'
-    }
-  }
-});
-
-function MyComponent({variant}: {variant: 'primary' | 'secondary'}) {
-  return <div className={styles({variant})} />
-}
-```
-
-Boolean conditions starting with `is` can be used directly without nesting:
-
-```tsx
-const styles = style({
-  backgroundColor: {
-    default: 'gray-100',
-    isSelected: 'gray-900'
-  }
-});
-
-<div className={styles({isSelected: true})} />
-```
-
-Runtime conditions work well with render props in React Aria Components. If you inline styles, you’ll get autocomplete for available conditions.
-
-```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'
-    }
-  })}
-/> 
-```
-
-### Nesting conditions
-
-Nest conditions to apply styles when multiple conditions are true. Conditions at the same level are mutually exclusive; order determines precedence.
-
-```tsx
-const styles = style({
-  backgroundColor: {
-    default: 'gray-25',
-    isSelected: {
-      default: 'neutral',
-      isEmphasized: 'accent',
-      forcedColors: 'Highlight',
-      isDisabled: {
-        default: 'gray-400',
-        forcedColors: 'GrayText'
-      }
-    }
-  }
-});
-
-<div className={styles({isSelected, isEmphasized, isDisabled})} />
-```
-
-## Reusing styles
-
-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
-const horizontalStack = {
-  display: 'flex',
-  alignItems: 'center',
-  columnGap: 8
-} as const;
-
-const styles = style({
-  ...horizontalStack,
-  columnGap: 4
-});
-```
-
-Create custom utilities by defining your own macros.
-
-```ts
-// style-utils.ts
-export function horizontalStack(gap: number) {
-  return {
-    display: 'flex',
-    alignItems: 'center',
-    columnGap: gap
-  } as const;
-}
-```
-
-Usage:
-
-```tsx
-// component.tsx
-import {horizontalStack} from './style-utils' with {type: 'macro'};
-import {style} from '@react-spectrum/s2/style' with {type: 'macro'};
-
-const styles = style({
-  ...horizontalStack(4),
-  backgroundColor: 'base'
-});
-```
-
-### Built-in utilities
-
-Use `focusRing()` to add the standard Spectrum focus ring.
-
-```tsx
-"use client";
-import {style, focusRing} from '@react-spectrum/s2/style' with {type: 'macro'};
-import {Button} from '@react-spectrum/s2';
-
-const buttonStyle = style({
-  ...focusRing(),
-  // ...other styles
-});
-
-<Button styles={buttonStyle}>Press me</Button>
-```
+The style macro has several predefined [breakpoints](./styling/reference.html#conditions), but you can use arbitrary CSS media or container queries as [conditional values](./styling/advanced.html#conditional-styles) in your style macro as well.
 
 ## 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 +206,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 />