addressing feedback from quarry team

Author: LFDanLu

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

@@ -17,6 +17,7 @@ The `style` macro supports a constrained set of values per property that conform
 ## Colors
 
 All Spectrum 2 color tokens are available across color properties (e.g., `backgroundColor`, `color`, `borderColor`).
+`baseColors` consists of the semantic and global colors listed below.
 
 <S2Colors />
 

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

@@ -14,7 +14,9 @@ React Spectrum includes a build-time `style` macro that generates atomic CSS and
 
 ## Style macro
 
-The `style` macro runs at build time and returns a class name for applying Spectrum 2 design tokens (colors, spacing, sizing, typography, etc.).
+The `style` macro runs at build time and returns a class name for applying Spectrum 2 design tokens (colors, spacing, sizing, typography, etc.). As can been seen below,
+the keys of the object passed to the `style` macro correspond to a CSS property, each paired with the property's desired value. See [here](./reference.html) for a full list
+of supported values.
 
 ```tsx
 import {style} from '@react-spectrum/s2/style' with {type: 'macro'};
@@ -39,7 +41,7 @@ Colocating styles with your component code means:
 <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).
+    Due to the atomic nature of the generated CSS rules, it is strongly recommended that you follow the CSS optimization guide listed [below](#css-optimization).
     Failure to do so can result in large number of duplicate rules and obtuse styling bugs.
   </Content>
 </InlineAlert>
@@ -96,23 +98,28 @@ import {Button} from '@react-spectrum/s2';
 ## 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,
-      '@media (min-width: 2560px)': 64,
+      '@media (min-width: 2560px)': 64
     }
   })}
 />
 ```
 
+In the example above, the keys of the nested object now map out the "conditions" that govern the padding of the `div`. This translates to the following:
+
+- If the viewport is larger than `2560px`, as specified by a user defined [media query](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_media_queries/Using_media_queries), the padding of the `div` is set to `64px`.
+- If the viewport matches the `style` macro's predefined `lg` [breakpoint](./reference.html#conditions) (i.e. the viewport is larger than `1024px`), but does not exceed previous condition, the padding of the `div` is set to `32px`
+- Otherwise, default to a padding of `8px`.
+
 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.
 
@@ -310,6 +317,8 @@ The `style` macro relies on CSS bundling and minification for optimal output. Fo
 - 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).

packages/dev/s2-docs/src/S2FAQ.tsx

@@ -1,4 +1,4 @@
-import {Disclosure, DisclosurePanel, DisclosureTitle} from '@react-spectrum/s2';
+import {Disclosure, DisclosurePanel, DisclosureTitle, Link} from '@react-spectrum/s2';
 import React from 'react';
 import {style} from '@react-spectrum/s2/style' with {type: 'macro'};
 
@@ -32,6 +32,12 @@ export function S2FAQ() {
           These no longer exist. Please style <code>&lt;div&gt;</code>, <code>&lt;span&gt;</code>, and other standard HTML elements with the <code>style</code> macro instead.
         </DisclosurePanel>
       </Disclosure>
+      <Disclosure isQuiet>
+        <DisclosureTitle>Where can I find a list of what values are supported by the style macro?</DisclosureTitle>
+        <DisclosurePanel>
+          See the <Link href="./reference.html">following page</Link> for a full list of what values are supported by the <code>style</code> macro.
+        </DisclosurePanel>
+      </Disclosure>
     </div>
   );
 }