review comments

Author: LFDanLu

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

@@ -99,29 +99,6 @@ 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. See the [reference](./styling/reference.html) page for a full list of available style macro properties.
@@ -148,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>
@@ -170,6 +148,10 @@ Type scales include: UI, Body, Heading, Title, Detail, and Code. Each scale has
   </Content>
 </InlineAlert>
 
+### Breakpoints
+
+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:
@@ -238,7 +220,7 @@ in a non-atomic format, making it easier to scan.
 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](#TODO) and [React Spectrum](https://www.npmjs.com/package/@react-spectrum/mcp) respectively that interface with the docs.
+we have MCP servers for [React Aria](../react-aria/mcp.html) and [React Spectrum](./mcp.html) respectively that interface with the docs.
 
 ## FAQ
 

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

@@ -3,11 +3,11 @@ export default Layout;
 
 export const omitFromNav = true;
 export const tags = ['style', 'macro', 'spectrum', 'custom', 'advanced'];
-export const description = 'Style macro advanced usage guide';
+export const description = 'A guide to advanced styling use cases for React Spectrum';
 
-# Advanced style macro usage
+# Advanced styling guide
 
-A guide to advanced use cases with the `style` macro.
+A guide to advanced styling use cases for React Spectrum.
 
 ## Conditional styles
 
@@ -18,7 +18,8 @@ Define conditional values as objects to handle media queries, UI states (hover/p
   className={style({
     padding: {
       default: 8,
-      lg: 32
+      lg: 32,
+      '@media (min-width: 2560px)': 64,
     }
   })}
 />
@@ -215,3 +216,26 @@ function MyComponent({isQuiet, styles}: {isQuiet?: boolean, styles?: StyleString
 ```
 
 The `iconStyle` macro should be used when styling Icons, see the [docs](../icons.html#iconstyle) for more information.
+
+## 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;
+}
+```