review comments

Author: LFDanLu

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

@@ -263,7 +263,7 @@ import {style} from '@react-spectrum/s2/style' with {type: 'macro'};
 
 ## 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/).
+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 [Motion](https://motion.dev/).
 
 ### CSS transitions
 

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

@@ -39,6 +39,7 @@ Size props like `width` and `height` accept arbitrary pixel values. Values are c
 ## Text
 
 Spectrum 2 typography can be applied via the `font` [shorthand](#shorthands), which sets `fontFamily`, `fontSize`, `fontWeight`, `lineHeight`, and `color`. You can override any of these individually.
+Note that `font` should be applied on a per element basis rather than globally so as to properly conform with Spectrum designs.
 
 ```tsx
 <main>

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

@@ -278,47 +278,15 @@ const childStyle = style({
 });
 ```
 
-## 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. Failure to perform this optimization will result in a suboptimal developer experience and obtuse styling bugs.
+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).
 - Bundle all CSS for S2 components and style macros into a single CSS bundle rather than code splitting to avoid duplicate rules across chunks.
 
-**Failure to perform this optimization will result in a suboptimal developer experience and obtuse styling bugs.**
-
 ### Parcel
 
 Parcel supports macros out of the box and optimizes CSS with [Lightning CSS](https://lightningcss.dev). You can bundle all S2 and macro CSS into a single file using [manual shared bundles](https://parceljs.org/features/code-splitting/#manual-shared-bundles).