From edeaa2f1bb65e2a11ab7b1ae207ca1061b31bdde Mon Sep 17 00:00:00 2001
From: Daniel Lu <dl1644@gmail.com>
Date: Thu, 23 Oct 2025 11:48:10 -0700
Subject: [PATCH 01/27] add FAQ and other sections

---
 packages/dev/s2-docs/pages/s2/styling.mdx | 89 +++++++++++++++++++++--
 packages/dev/s2-docs/src/Layout.tsx       | 23 +++++-
 2 files changed, 101 insertions(+), 11 deletions(-)

diff --git a/packages/dev/s2-docs/pages/s2/styling.mdx b/packages/dev/s2-docs/pages/s2/styling.mdx
index 3735835c868..4f2d70bf6f3 100644
--- a/packages/dev/s2-docs/pages/s2/styling.mdx
+++ b/packages/dev/s2-docs/pages/s2/styling.mdx
@@ -11,7 +11,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 +37,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.
@@ -88,7 +96,7 @@ import {Button} from '@react-spectrum/s2';
 
 ### 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.
+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.
 
@@ -153,7 +161,7 @@ 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>
 
@@ -195,13 +203,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 +231,7 @@ import {style} from '@react-spectrum/s2/style' with {type: 'macro'};
       isSelected: 'gray-900'
     }
   })}
-/> 
+/>
 ```
 
 ### Nesting conditions
@@ -308,9 +317,31 @@ 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 with style macros
+
+TODO: I want to add the usuage of mergeStyles here from that one thread. Maybe an example with RAC + style macros 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 +393,46 @@ CSS resets are strongly discouraged. Global CSS selectors can unintentionally af
 /* App.css */
 @layer reset, _;
 @import "reset.css" layer(reset);
-```
\ No newline at end of file
+```
+
+### 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](#TODO) and [React Spectrum](https://www.npmjs.com/package/@react-spectrum/mcp) respectively that interface with the docs.
+
+
+- TODO: link to the dev tool Rob is making, perhaps replacing the atomic css dev tool. Any others we wanna call out
+
+
+## FAQ
+
+> I'm getting a "Could not statically evaluate macro argument" error.
+
+This happens if your `style` macro has a condition that isn't evaluable at build time. This can happen for a variety of reasons such
+as if you've referenced non-constant variables within your `style` macro or if you've called non-macro functions within your `style` macro.
+If you are using Typescript, it can be as simple as forgetting to add `as const` to your own defined reusable macro.
+TODO: create an example here, should I link to the sections above like "reusing styles"?
+
+> I'm seeing a ton of duplicate rules being generated and/or my dev tools are very slow.
+
+Please make sure you've followed the [best practices listed above](#css-optimization).
+
+> I tried to pass my `style` macro to `UNSAFE_className` but it doesn't work.
+
+The `style` macro is not meant to be used with `UNSAFE_className`. Overrides to the Spectrum styles is highly discouraged,
+consider styling an equivalent React Aria Component instead.
+TODO: we already touch on this via the UNSAFE Style Overrides section
+TODO: example of RAC + style macros? maybe later
+
+> I'm coming from S1, but where are Flex/Grid/etc?
+
+These no longer exist. Please style `<div>`, `<span>`, and other standard HTML elements with the `style` macro instead.
diff --git a/packages/dev/s2-docs/src/Layout.tsx b/packages/dev/s2-docs/src/Layout.tsx
index a1b9b88641d..e832f982772 100644
--- a/packages/dev/s2-docs/src/Layout.tsx
+++ b/packages/dev/s2-docs/src/Layout.tsx
@@ -31,6 +31,23 @@ const components = {
   p: ({children, ...props}) => <p {...props} className={style({font: {default: 'body', lg: 'body-lg'}, marginY: 24})}>{children}</p>,
   ul: (props) => <ul {...props} />,
   li: ({children, ...props}) => <li {...props} className={style({font: {default: 'body', lg: 'body-lg'}, marginY: 0})}>{children}</li>,
+  blockquote: ({children, ...props}) => (
+    <blockquote
+      {...props}
+      className={style({
+        borderStartWidth: 4,
+        borderEndWidth: 0,
+        borderTopWidth: 0,
+        borderBottomWidth: 0,
+        borderStyle: 'solid',
+        borderColor: 'gray-400',
+        paddingStart: 12,
+        font: {default: 'body', lg: 'body-lg'},
+        margin: 'unset'
+      })}>
+      {children}
+    </blockquote>
+  ),
   Figure: (props) => <figure {...props} className={style({display: 'flex', flexDirection: 'column', alignItems: 'center', marginY: 32, marginX: 0})} />,
   Caption: (props) => <figcaption {...props} className={style({font: 'body-sm'})} />,
   CodeBlock: CodeBlock,
@@ -56,14 +73,14 @@ const getTitle = (currentPage: Page): string => {
   if (explicitTitle && explicitTitle !== currentPage.tableOfContents?.[0]?.title && explicitTitle !== currentPage.name) {
     return explicitTitle as string;
   }
-  
+
   let library = getLibraryLabel(getLibraryFromPage(currentPage));
   const pageTitle = currentPage.tableOfContents?.[0]?.title ?? currentPage.name;
-  
+
   if (currentPage.name === 'index.html' || currentPage.name.endsWith('/index.html')) {
     return library || 'React Spectrum';
   }
-  
+
   return library ? `${pageTitle} | ${library}` : pageTitle;
 };
 

From 8a1f97e17c7c8171bc5771a81eeea9e646ae003a Mon Sep 17 00:00:00 2001
From: Daniel Lu <dl1644@gmail.com>
Date: Thu, 23 Oct 2025 16:58:26 -0700
Subject: [PATCH 02/27] add section for creating custom components

---
 packages/dev/s2-docs/pages/s2/styling.mdx | 42 +++++++++++++++++------
 1 file changed, 31 insertions(+), 11 deletions(-)

diff --git a/packages/dev/s2-docs/pages/s2/styling.mdx b/packages/dev/s2-docs/pages/s2/styling.mdx
index 4f2d70bf6f3..25ae0ec8ae1 100644
--- a/packages/dev/s2-docs/pages/s2/styling.mdx
+++ b/packages/dev/s2-docs/pages/s2/styling.mdx
@@ -335,9 +335,36 @@ const childStyle = style({
 });
 ```
 
-## Creating custom components with style macros
+## Creating custom components
 
-TODO: I want to add the usuage of mergeStyles here from that one thread. Maybe an example with RAC + style macros as well
+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
 
@@ -395,7 +422,7 @@ CSS resets are strongly discouraged. Global CSS selectors can unintentionally af
 @import "reset.css" layer(reset);
 ```
 
-### Developing with style macros
+## 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:
@@ -409,18 +436,13 @@ 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.
 
-
-- TODO: link to the dev tool Rob is making, perhaps replacing the atomic css dev tool. Any others we wanna call out
-
-
 ## FAQ
 
 > I'm getting a "Could not statically evaluate macro argument" error.
 
-This happens if your `style` macro has a condition that isn't evaluable at build time. This can happen for a variety of reasons such
+This indicates that your `style` macro has a condition that isn't evaluable at build time. This can happen for a variety of reasons such
 as if you've referenced non-constant variables within your `style` macro or if you've called non-macro functions within your `style` macro.
 If you are using Typescript, it can be as simple as forgetting to add `as const` to your own defined reusable macro.
-TODO: create an example here, should I link to the sections above like "reusing styles"?
 
 > I'm seeing a ton of duplicate rules being generated and/or my dev tools are very slow.
 
@@ -430,8 +452,6 @@ Please make sure you've followed the [best practices listed above](#css-optimiza
 
 The `style` macro is not meant to be used with `UNSAFE_className`. Overrides to the Spectrum styles is highly discouraged,
 consider styling an equivalent React Aria Component instead.
-TODO: we already touch on this via the UNSAFE Style Overrides section
-TODO: example of RAC + style macros? maybe later
 
 > I'm coming from S1, but where are Flex/Grid/etc?
 

From 28eb78849c0ba876cf72ca259bb65bdbb3cae77a Mon Sep 17 00:00:00 2001
From: Daniel Lu <dl1644@gmail.com>
Date: Fri, 24 Oct 2025 14:36:51 -0700
Subject: [PATCH 03/27] initial stab at extracting types from style macro

---
 packages/@react-spectrum/s2/style/index.ts    |  4 +-
 .../s2/style/spectrum-theme.ts                |  6 +-
 packages/dev/s2-docs/pages/s2/Reference.mdx   | 76 +++++++++++++++++
 packages/dev/s2-docs/src/styleProperties.ts   | 83 +++++++++++++++++++
 packages/dev/s2-docs/src/types.tsx            | 70 +++++++++++++++-
 5 files changed, 234 insertions(+), 5 deletions(-)
 create mode 100644 packages/dev/s2-docs/pages/s2/Reference.mdx
 create mode 100644 packages/dev/s2-docs/src/styleProperties.ts

diff --git a/packages/@react-spectrum/s2/style/index.ts b/packages/@react-spectrum/s2/style/index.ts
index fb2c934e69a..86fce36f5e4 100644
--- a/packages/@react-spectrum/s2/style/index.ts
+++ b/packages/@react-spectrum/s2/style/index.ts
@@ -15,7 +15,7 @@ import {Inset, fontRelative as internalFontRelative, size as internalSize, space
 import type {MacroContext} from '@parcel/macros';
 import {StyleString} from './types';
 
-export {baseColor, color, edgeToText, lightDark, linearGradient, colorMix, style} from './spectrum-theme';
+export {baseColor, color, edgeToText, lightDark, linearGradient, colorMix, style, themeConfig} from './spectrum-theme';
 export type {StyleString} from './types';
 
 // Wrap these functions in arbitrary value syntax when called from the outside.
@@ -81,7 +81,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',
diff --git a/packages/@react-spectrum/s2/style/spectrum-theme.ts b/packages/@react-spectrum/s2/style/spectrum-theme.ts
index c217db1b0cd..7664925b9a8 100644
--- a/packages/@react-spectrum/s2/style/spectrum-theme.ts
+++ b/packages/@react-spectrum/s2/style/spectrum-theme.ts
@@ -535,7 +535,7 @@ const minFontSize = 10;
 const maxFontSize = 32;
 const lineHeightCalc = `round(1em * (${minFontScale} + (1 - ((min(${maxFontSize}, ${fontSizeCalc}) - ${minFontSize})) / ${maxFontSize - minFontSize}) * ${(maxFontScale - minFontScale).toFixed(2)}), 2px)`;
 
-export const style = createTheme({
+export const themeConfig = {
   properties: {
     // colors
     color: new SpectrumColorProperty('color', {
@@ -1044,4 +1044,6 @@ export const style = createTheme({
     xl: `@media (min-width: ${pxToRem(1280)})`,
     '2xl': `@media (min-width: ${pxToRem(1536)})`
   }
-});
+} as const;
+
+export const style = createTheme(themeConfig);
diff --git a/packages/dev/s2-docs/pages/s2/Reference.mdx b/packages/dev/s2-docs/pages/s2/Reference.mdx
new file mode 100644
index 00000000000..44cf8919adb
--- /dev/null
+++ b/packages/dev/s2-docs/pages/s2/Reference.mdx
@@ -0,0 +1,76 @@
+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} from '../../src/styleProperties';
+export default Layout;
+
+export const section = 'Guides';
+export const tags = ['style', 'macro', 'spectrum', 'custom', 'values', 'reference'];
+export const description = 'Reference table for the `style` macro';
+
+# Style Macro Reference
+
+Reference table for the properties and values supported by React Spectrum `style` macro.
+
+## 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.
+
+### top
+
+<StyleMacroProperties properties={getPropertyDefinitions(['top'])} />
+
+## Text
+
+// TODO: edit copy
+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 />
+
+
+## Effects
+
+
+## Layout
+
+### display
+
+<StyleMacroProperties properties={getPropertyDefinitions(['display'])} />
+
+
+## Misc
+
+
+## Shorthands
+
+
+## Conditions
diff --git a/packages/dev/s2-docs/src/styleProperties.ts b/packages/dev/s2-docs/src/styleProperties.ts
new file mode 100644
index 00000000000..9e2420a1b62
--- /dev/null
+++ b/packages/dev/s2-docs/src/styleProperties.ts
@@ -0,0 +1,83 @@
+/*
+ * Copyright 2025 Adobe. All rights reserved.
+ * This file is licensed to you under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License. You may obtain a copy
+ * of the License at http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under
+ * the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
+ * OF ANY KIND, either express or implied. See the License for the specific language
+ * governing permissions and limitations under the License.
+ */
+
+interface StyleMacroPropertyDefinition {
+  type: 'mapped' | 'percentage' | 'sizing' | 'arbitrary',
+  values: string[],
+  additionalTypes?: string[]
+}
+
+// Properties that use PercentageProperty (accept LengthPercentage in addition to mapped values)
+const percentageProperties = new Set([
+  'top', 'left', 'bottom', 'right',
+  'insetStart', 'insetEnd',
+  'marginTop', 'marginBottom', 'marginStart', 'marginEnd',
+  'paddingTop', 'paddingBottom', 'paddingStart', 'paddingEnd',
+  'textIndent', 'translateX', 'translateY'
+]);
+
+// Properties that use SizingProperty (accept number and LengthPercentage in addition to mapped values)
+const sizingProperties = new Set([
+  'width', 'height', 'minWidth', 'minHeight', 'maxWidth', 'maxHeight',
+  'flexBasis', 'containIntrinsicWidth', 'containIntrinsicHeight'
+]);
+
+// Manually defined property values from spectrum-theme.ts
+// These are extracted from the theme definition
+const propertyValues: {[key: string]: string[]} = {
+  display: ['block', 'inline-block', 'inline', 'flex', 'inline-flex', 'grid', 'inline-grid', 'contents', 'list-item', 'none'],
+  top: ['0', '2', '4', '8', '12', '16', '20', '24', '28', '32', '36', '40', '44', '48', '56', '64', '80', '96', '-2', '-4', '-8', '-12', '-16', '-20', '-24', '-28', '-32', '-36', '-40', '-44', '-48', '-56', '-64', '-80', '-96', 'auto', 'full'],
+  position: ['absolute', 'fixed', 'relative', 'sticky', 'static'],
+  width: ['auto', 'full', 'min', 'max', 'fit', 'screen'],
+  height: ['auto', 'full', 'min', 'max', 'fit', 'screen'],
+  minWidth: ['auto', 'full', 'min', 'max', 'fit', 'screen'],
+  minHeight: ['auto', 'full', 'min', 'max', 'fit', 'screen'],
+  maxWidth: ['auto', 'full', 'min', 'max', 'fit', 'screen', 'none'],
+  maxHeight: ['auto', 'full', 'min', 'max', 'fit', 'screen', 'none'],
+  flexDirection: ['row', 'column', 'row-reverse', 'column-reverse'],
+  justifyContent: ['normal', 'start', 'end', 'center', 'space-between', 'space-around', 'space-evenly', 'stretch'],
+  alignItems: ['start', 'end', 'center', 'baseline', 'stretch'],
+  gap: ['0', '2', '4', '8', '12', '16', '20', '24', '28', '32', '36', '40', '44', '48', '56', '64', '80', '96', 'text-to-control', 'text-to-visual', 'edge-to-text', 'pill']
+};
+
+export function getPropertyDefinition(propertyName: string): StyleMacroPropertyDefinition {
+  const values = propertyValues[propertyName] || [];
+
+  if (sizingProperties.has(propertyName)) {
+    return {
+      type: 'sizing',
+      values,
+      additionalTypes: ['number', 'LengthPercentage']
+    };
+  }
+
+  if (percentageProperties.has(propertyName)) {
+    return {
+      type: 'percentage',
+      values,
+      additionalTypes: ['LengthPercentage']
+    };
+  }
+
+  return {
+    type: 'mapped',
+    values
+  };
+}
+
+export function getPropertyDefinitions(propertyNames: string[]): {[key: string]: StyleMacroPropertyDefinition} {
+  const result: {[key: string]: StyleMacroPropertyDefinition} = {};
+  for (const name of propertyNames) {
+    result[name] = getPropertyDefinition(name);
+  }
+  return result;
+}
diff --git a/packages/dev/s2-docs/src/types.tsx b/packages/dev/s2-docs/src/types.tsx
index edd33c02c94..0eaffb0aadd 100644
--- a/packages/dev/s2-docs/src/types.tsx
+++ b/packages/dev/s2-docs/src/types.tsx
@@ -47,7 +47,7 @@ export type TKeyof = {type: 'keyof', keyof: TType};
 export type TLink = {type: 'link', id: string};
 export type TReference =  {type: 'reference', local: string, imported: string, specifier: string};
 export type TMapped = {type: 'mapped', readonly: boolean | '+' | '-', typeParameter: TTypeParameter, typeAnnotation: TType};
-export type TType = 
+export type TType =
   | TKeyword
   | TIdentifier
   | TString
@@ -694,3 +694,71 @@ function TemplateLiteral({elements}: TTemplate) {
     </>
   );
 }
+
+interface StyleMacroPropertyDefinition {
+  type: 'mapped' | 'percentage' | 'sizing' | 'arbitrary',
+  values: string[],
+  additionalTypes?: string[]
+}
+
+interface StyleMacroPropertiesProps {
+  properties: {[propertyName: string]: StyleMacroPropertyDefinition}
+}
+
+export function StyleMacroProperties({properties}: StyleMacroPropertiesProps) {
+  let propertyNames = Object.keys(properties);
+
+  return (
+    <Table>
+      <TableHeader>
+        <tr>
+          <TableColumn>Property</TableColumn>
+          <TableColumn>Values</TableColumn>
+        </tr>
+      </TableHeader>
+      <TableBody>
+        {propertyNames.map((propertyName, index) => {
+          let propDef = properties[propertyName];
+          let values = propDef.values;
+
+          return (
+            <TableRow key={index}>
+              <TableCell role="rowheader">
+                <code className={codeStyle}>
+                  <span className={codeStyles.attribute}>{propertyName}</span>
+                </code>
+              </TableCell>
+              <TableCell>
+                <code className={codeStyle}>
+                  {values.map((value, i) => (
+                    <React.Fragment key={i}>
+                      {i > 0 && <Punctuation>{' | '}</Punctuation>}
+                      <span className={codeStyles.string}>'{value}'</span>
+                    </React.Fragment>
+                  ))}
+                  {propDef.additionalTypes && propDef.additionalTypes.map((typeName, i) => (
+                    <React.Fragment key={`type-${i}`}>
+                      <Punctuation>{' | '}</Punctuation>
+                      <TypePopover name={typeName}>
+                        {typeName === 'LengthPercentage' && (
+                          <p className={style({font: 'body'})}>
+                            A CSS length value with percentage or viewport units. Examples: <code className={codeStyle}>'50%'</code>, <code className={codeStyle}>'100vw'</code>, <code className={codeStyle}>'50vh'</code>
+                          </p>
+                        )}
+                        {typeName === 'number' && (
+                          <p className={style({font: 'body'})}>
+                            A numeric value in pixels. Will be converted to rem and scaled on touch devices.
+                          </p>
+                        )}
+                      </TypePopover>
+                    </React.Fragment>
+                  ))}
+                </code>
+              </TableCell>
+            </TableRow>
+          );
+        })}
+      </TableBody>
+    </Table>
+  );
+}

From 457c59aaafc49598c415680f4a3f76dd015f7fee Mon Sep 17 00:00:00 2001
From: Daniel Lu <dl1644@gmail.com>
Date: Fri, 24 Oct 2025 15:11:34 -0700
Subject: [PATCH 04/27] testing sizing properties

---
 packages/dev/s2-docs/pages/s2/Reference.mdx |  6 +-----
 packages/dev/s2-docs/src/styleProperties.ts | 16 +++-------------
 2 files changed, 4 insertions(+), 18 deletions(-)

diff --git a/packages/dev/s2-docs/pages/s2/Reference.mdx b/packages/dev/s2-docs/pages/s2/Reference.mdx
index 44cf8919adb..dfb8258dd6b 100644
--- a/packages/dev/s2-docs/pages/s2/Reference.mdx
+++ b/packages/dev/s2-docs/pages/s2/Reference.mdx
@@ -33,9 +33,7 @@ Spacing props like `margin` and `padding` accept values on a **4px grid**. These
 
 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.
 
-### top
-
-<StyleMacroProperties properties={getPropertyDefinitions(['top'])} />
+<StyleMacroProperties properties={getPropertyDefinitions(['top', 'height'])} />
 
 ## Text
 
@@ -62,8 +60,6 @@ Type scales include: UI, Body, Heading, Title, Detail, and Code. Each scale has
 
 ## Layout
 
-### display
-
 <StyleMacroProperties properties={getPropertyDefinitions(['display'])} />
 
 
diff --git a/packages/dev/s2-docs/src/styleProperties.ts b/packages/dev/s2-docs/src/styleProperties.ts
index 9e2420a1b62..08b46c10e18 100644
--- a/packages/dev/s2-docs/src/styleProperties.ts
+++ b/packages/dev/s2-docs/src/styleProperties.ts
@@ -31,22 +31,12 @@ const sizingProperties = new Set([
   'flexBasis', 'containIntrinsicWidth', 'containIntrinsicHeight'
 ]);
 
-// Manually defined property values from spectrum-theme.ts
-// These are extracted from the theme definition
+// manually defined
 const propertyValues: {[key: string]: string[]} = {
   display: ['block', 'inline-block', 'inline', 'flex', 'inline-flex', 'grid', 'inline-grid', 'contents', 'list-item', 'none'],
+  // TODO: this doesn't actually seem to reflect the actual usage?
   top: ['0', '2', '4', '8', '12', '16', '20', '24', '28', '32', '36', '40', '44', '48', '56', '64', '80', '96', '-2', '-4', '-8', '-12', '-16', '-20', '-24', '-28', '-32', '-36', '-40', '-44', '-48', '-56', '-64', '-80', '-96', 'auto', 'full'],
-  position: ['absolute', 'fixed', 'relative', 'sticky', 'static'],
-  width: ['auto', 'full', 'min', 'max', 'fit', 'screen'],
-  height: ['auto', 'full', 'min', 'max', 'fit', 'screen'],
-  minWidth: ['auto', 'full', 'min', 'max', 'fit', 'screen'],
-  minHeight: ['auto', 'full', 'min', 'max', 'fit', 'screen'],
-  maxWidth: ['auto', 'full', 'min', 'max', 'fit', 'screen', 'none'],
-  maxHeight: ['auto', 'full', 'min', 'max', 'fit', 'screen', 'none'],
-  flexDirection: ['row', 'column', 'row-reverse', 'column-reverse'],
-  justifyContent: ['normal', 'start', 'end', 'center', 'space-between', 'space-around', 'space-evenly', 'stretch'],
-  alignItems: ['start', 'end', 'center', 'baseline', 'stretch'],
-  gap: ['0', '2', '4', '8', '12', '16', '20', '24', '28', '32', '36', '40', '44', '48', '56', '64', '80', '96', 'text-to-control', 'text-to-visual', 'edge-to-text', 'pill']
+  height: ['auto', 'full', 'min', 'max', 'fit', 'screen']
 };
 
 export function getPropertyDefinition(propertyName: string): StyleMacroPropertyDefinition {

From 819c0760c7138e7725162fc8cc66795065b93672 Mon Sep 17 00:00:00 2001
From: Daniel Lu <dl1644@gmail.com>
Date: Fri, 24 Oct 2025 15:28:28 -0700
Subject: [PATCH 05/27] revert export of theme object since it was breaking
 inference

---
 packages/@react-spectrum/s2/style/index.ts          | 2 +-
 packages/@react-spectrum/s2/style/spectrum-theme.ts | 6 ++----
 packages/dev/s2-docs/src/styleProperties.ts         | 1 -
 3 files changed, 3 insertions(+), 6 deletions(-)

diff --git a/packages/@react-spectrum/s2/style/index.ts b/packages/@react-spectrum/s2/style/index.ts
index 86fce36f5e4..dee860425e2 100644
--- a/packages/@react-spectrum/s2/style/index.ts
+++ b/packages/@react-spectrum/s2/style/index.ts
@@ -15,7 +15,7 @@ import {Inset, fontRelative as internalFontRelative, size as internalSize, space
 import type {MacroContext} from '@parcel/macros';
 import {StyleString} from './types';
 
-export {baseColor, color, edgeToText, lightDark, linearGradient, colorMix, style, themeConfig} from './spectrum-theme';
+export {baseColor, color, edgeToText, lightDark, linearGradient, colorMix, style} from './spectrum-theme';
 export type {StyleString} from './types';
 
 // Wrap these functions in arbitrary value syntax when called from the outside.
diff --git a/packages/@react-spectrum/s2/style/spectrum-theme.ts b/packages/@react-spectrum/s2/style/spectrum-theme.ts
index 7664925b9a8..c217db1b0cd 100644
--- a/packages/@react-spectrum/s2/style/spectrum-theme.ts
+++ b/packages/@react-spectrum/s2/style/spectrum-theme.ts
@@ -535,7 +535,7 @@ const minFontSize = 10;
 const maxFontSize = 32;
 const lineHeightCalc = `round(1em * (${minFontScale} + (1 - ((min(${maxFontSize}, ${fontSizeCalc}) - ${minFontSize})) / ${maxFontSize - minFontSize}) * ${(maxFontScale - minFontScale).toFixed(2)}), 2px)`;
 
-export const themeConfig = {
+export const style = createTheme({
   properties: {
     // colors
     color: new SpectrumColorProperty('color', {
@@ -1044,6 +1044,4 @@ export const themeConfig = {
     xl: `@media (min-width: ${pxToRem(1280)})`,
     '2xl': `@media (min-width: ${pxToRem(1536)})`
   }
-} as const;
-
-export const style = createTheme(themeConfig);
+});
diff --git a/packages/dev/s2-docs/src/styleProperties.ts b/packages/dev/s2-docs/src/styleProperties.ts
index 08b46c10e18..bba3cb8d951 100644
--- a/packages/dev/s2-docs/src/styleProperties.ts
+++ b/packages/dev/s2-docs/src/styleProperties.ts
@@ -34,7 +34,6 @@ const sizingProperties = new Set([
 // manually defined
 const propertyValues: {[key: string]: string[]} = {
   display: ['block', 'inline-block', 'inline', 'flex', 'inline-flex', 'grid', 'inline-grid', 'contents', 'list-item', 'none'],
-  // TODO: this doesn't actually seem to reflect the actual usage?
   top: ['0', '2', '4', '8', '12', '16', '20', '24', '28', '32', '36', '40', '44', '48', '56', '64', '80', '96', '-2', '-4', '-8', '-12', '-16', '-20', '-24', '-28', '-32', '-36', '-40', '-44', '-48', '-56', '-64', '-80', '-96', 'auto', 'full'],
   height: ['auto', 'full', 'min', 'max', 'fit', 'screen']
 };

From 3b991eaa1abbb664873852fe2b5f245037aa6598 Mon Sep 17 00:00:00 2001
From: Daniel Lu <dl1644@gmail.com>
Date: Mon, 27 Oct 2025 17:05:11 -0700
Subject: [PATCH 06/27] adding more values

---
 packages/dev/s2-docs/pages/s2/Reference.mdx | 13 +++++
 packages/dev/s2-docs/src/styleProperties.ts | 57 ++++++++++++++++++++-
 packages/dev/s2-docs/src/types.tsx          |  8 ++-
 3 files changed, 75 insertions(+), 3 deletions(-)

diff --git a/packages/dev/s2-docs/pages/s2/Reference.mdx b/packages/dev/s2-docs/pages/s2/Reference.mdx
index dfb8258dd6b..6842b4ba532 100644
--- a/packages/dev/s2-docs/pages/s2/Reference.mdx
+++ b/packages/dev/s2-docs/pages/s2/Reference.mdx
@@ -16,12 +16,20 @@ Reference table for the properties and values supported by React Spectrum `style
 
 ## Colors
 
+TODO: do we just want the table or preserve the same formatting as the styling guide?
+
 All Spectrum 2 color tokens are available across color properties (e.g., `backgroundColor`, `color`, `borderColor`).
 
 <S2Colors />
 
+Below are the rest of the `style` macro supported color properties.
+
+<StyleMacroProperties properties={getPropertyDefinitions(['outlineColor', 'fill', 'stroke'])} />
+
 ## Spacing
 
+TODO: decide what to do with Spacing/Sizing since they are pretty much rolled up into 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.
@@ -38,6 +46,7 @@ Size props like `width` and `height` accept arbitrary pixel values. Values are c
 ## Text
 
 // TODO: edit copy
+
 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
@@ -55,8 +64,12 @@ Type scales include: UI, Body, Heading, Title, Detail, and Code. Each scale has
 <S2Typography />
 
 
+<StyleMacroProperties properties={getPropertyDefinitions(['fontFamily', 'listStyleType', 'listStylePosition'])} />
+
+
 ## Effects
 
+<StyleMacroProperties properties={getPropertyDefinitions(['boxShadow', 'filter'])} />
 
 ## Layout
 
diff --git a/packages/dev/s2-docs/src/styleProperties.ts b/packages/dev/s2-docs/src/styleProperties.ts
index bba3cb8d951..219dc18563b 100644
--- a/packages/dev/s2-docs/src/styleProperties.ts
+++ b/packages/dev/s2-docs/src/styleProperties.ts
@@ -11,11 +11,20 @@
  */
 
 interface StyleMacroPropertyDefinition {
-  type: 'mapped' | 'percentage' | 'sizing' | 'arbitrary',
+  // TODO: unneeded for now
+  type: 'color' | 'mapped' | 'percentage' | 'sizing' | 'arbitrary',
+  // Values tied to the property, usually manually defined for now
   values: string[],
+  // Additional value types to append, usually used to add type links to generalize a type that
+  // the property extends aka a css length percentage or a number that needs more explaination
   additionalTypes?: string[]
 }
 
+// properties that extend from baseColors
+const baseColorProperties = new Set([
+  'color', 'backgroundColor', 'borderColor', 'outlineColor', 'fill', 'stroke'
+])
+
 // Properties that use PercentageProperty (accept LengthPercentage in addition to mapped values)
 const percentageProperties = new Set([
   'top', 'left', 'bottom', 'right',
@@ -32,15 +41,59 @@ const sizingProperties = new Set([
 ]);
 
 // manually defined
+// TODO: maybe spit these up into groups, and have getPropertyDefinitions grab via category name instead
 const propertyValues: {[key: string]: string[]} = {
+  // Color
+  // This should append baseColors in getPropertyDefinition
+  outlineColor: ['focus-ring'],
+  // This should append what seems to be a combination of semantic colors and background/global colors
+  fill: ['none', 'currentColor'],
+  stroke: ['none', 'currentColor'],
+
+
   display: ['block', 'inline-block', 'inline', 'flex', 'inline-flex', 'grid', 'inline-grid', 'contents', 'list-item', 'none'],
   top: ['0', '2', '4', '8', '12', '16', '20', '24', '28', '32', '36', '40', '44', '48', '56', '64', '80', '96', '-2', '-4', '-8', '-12', '-16', '-20', '-24', '-28', '-32', '-36', '-40', '-44', '-48', '-56', '-64', '-80', '-96', 'auto', 'full'],
-  height: ['auto', 'full', 'min', 'max', 'fit', 'screen']
+  height: ['auto', 'full', 'min', 'max', 'fit', 'screen'],
+
+
+  // text
+  fontFamily: ['sans', 'serif', 'code'],
+  // todo: skipped font-size, font-weight, line height though these will also just be manually defined here
+  listStyleType: ['none', 'disc', 'decimal'],
+  listStylePosition: ['inside', 'outside'],
+  textTransform: ['uppercase', 'lowercase', 'capitalize', 'none'],
+  textAlign: ['start', 'center', 'end', 'justify'],
+  verticalAlign: ['baseline', 'top', 'middle', 'bottom', 'text-top', 'text-bottom', 'sub', 'super'],
+  textDecoration: ['none' , 'underline' , 'overline' , 'line-through'],
+
+  textOverflow: ['ellipsis', 'clip'],
+  lineClamp: ['number'],
+  hyphens: ['none', 'manual', 'auto'],
+  whiteSpace: ['normal', 'nowrap', 'pre', 'pre-line', 'pre-wrap', 'break-spaces'],
+  textWrap: ['wrap', 'nowrap', 'balance', 'pretty'],
+  wordBreak: ['normal', 'break-all', 'keep-all', 'break-word'],
+  overflowWrap: ['normal', 'anywhere', 'break-word'],
+  boxDecorationBreak: ['slice', 'clone'],
+
+  // effects
+  // TODO: should the below have a typelink explaining more details
+  boxShadow: ['emphasized', 'elevated', 'dragged', 'none'],
+  filter: ['emphasized', 'elevated', 'dragged', 'none'],
+
 };
 
+// TODO: will we need something specific for short hand?
 export function getPropertyDefinition(propertyName: string): StyleMacroPropertyDefinition {
   const values = propertyValues[propertyName] || [];
 
+  if (baseColorProperties.has(propertyName)) {
+    return {
+      type: 'color',
+      values,
+      additionalTypes: ['baseColors']
+    }
+  }
+
   if (sizingProperties.has(propertyName)) {
     return {
       type: 'sizing',
diff --git a/packages/dev/s2-docs/src/types.tsx b/packages/dev/s2-docs/src/types.tsx
index 0eaffb0aadd..953f59407c0 100644
--- a/packages/dev/s2-docs/src/types.tsx
+++ b/packages/dev/s2-docs/src/types.tsx
@@ -696,7 +696,7 @@ function TemplateLiteral({elements}: TTemplate) {
 }
 
 interface StyleMacroPropertyDefinition {
-  type: 'mapped' | 'percentage' | 'sizing' | 'arbitrary',
+  type: 'color' | 'mapped' | 'percentage' | 'sizing' | 'arbitrary',
   values: string[],
   additionalTypes?: string[]
 }
@@ -705,6 +705,7 @@ interface StyleMacroPropertiesProps {
   properties: {[propertyName: string]: StyleMacroPropertyDefinition}
 }
 
+// TODO: fix the width of the columns so that they are consistent
 export function StyleMacroProperties({properties}: StyleMacroPropertiesProps) {
   let propertyNames = Object.keys(properties);
 
@@ -740,6 +741,11 @@ export function StyleMacroProperties({properties}: StyleMacroPropertiesProps) {
                     <React.Fragment key={`type-${i}`}>
                       <Punctuation>{' | '}</Punctuation>
                       <TypePopover name={typeName}>
+                        {typeName === 'baseColors' && (
+                          <p className={style({font: 'body'})}>
+                            A base set of colors defined by Spectrum. See the global and semantic colors in the color reference above.
+                          </p>
+                        )}
                         {typeName === 'LengthPercentage' && (
                           <p className={style({font: 'body'})}>
                             A CSS length value with percentage or viewport units. Examples: <code className={codeStyle}>'50%'</code>, <code className={codeStyle}>'100vw'</code>, <code className={codeStyle}>'50vh'</code>

From 42b04064f6d33a80696fccde75702d56135effba Mon Sep 17 00:00:00 2001
From: Daniel Lu <dl1644@gmail.com>
Date: Tue, 28 Oct 2025 10:23:27 -0700
Subject: [PATCH 07/27] reorg

---
 packages/dev/s2-docs/pages/s2/Reference.mdx | 11 +--
 packages/dev/s2-docs/src/styleProperties.ts | 99 +++++++++++----------
 packages/dev/s2-docs/src/types.tsx          |  1 -
 3 files changed, 59 insertions(+), 52 deletions(-)

diff --git a/packages/dev/s2-docs/pages/s2/Reference.mdx b/packages/dev/s2-docs/pages/s2/Reference.mdx
index 6842b4ba532..42c868e57b3 100644
--- a/packages/dev/s2-docs/pages/s2/Reference.mdx
+++ b/packages/dev/s2-docs/pages/s2/Reference.mdx
@@ -24,7 +24,7 @@ All Spectrum 2 color tokens are available across color properties (e.g., `backgr
 
 Below are the rest of the `style` macro supported color properties.
 
-<StyleMacroProperties properties={getPropertyDefinitions(['outlineColor', 'fill', 'stroke'])} />
+<StyleMacroProperties properties={getPropertyDefinitions('color')} />
 
 ## Spacing
 
@@ -41,7 +41,7 @@ Spacing props like `margin` and `padding` accept values on a **4px grid**. These
 
 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(['top', 'height'])} />
+<StyleMacroProperties properties={getPropertyDefinitions('dimensions')} />
 
 ## Text
 
@@ -64,20 +64,21 @@ Type scales include: UI, Body, Heading, Title, Detail, and Code. Each scale has
 <S2Typography />
 
 
-<StyleMacroProperties properties={getPropertyDefinitions(['fontFamily', 'listStyleType', 'listStylePosition'])} />
+<StyleMacroProperties properties={getPropertyDefinitions('text')} />
 
 
 ## Effects
 
-<StyleMacroProperties properties={getPropertyDefinitions(['boxShadow', 'filter'])} />
+<StyleMacroProperties properties={getPropertyDefinitions('effects')} />
 
 ## Layout
 
-<StyleMacroProperties properties={getPropertyDefinitions(['display'])} />
+<StyleMacroProperties properties={getPropertyDefinitions('layout')} />
 
 
 ## Misc
 
+<StyleMacroProperties properties={getPropertyDefinitions('misc')} />
 
 ## Shorthands
 
diff --git a/packages/dev/s2-docs/src/styleProperties.ts b/packages/dev/s2-docs/src/styleProperties.ts
index 219dc18563b..743e97c01cf 100644
--- a/packages/dev/s2-docs/src/styleProperties.ts
+++ b/packages/dev/s2-docs/src/styleProperties.ts
@@ -10,16 +10,6 @@
  * governing permissions and limitations under the License.
  */
 
-interface StyleMacroPropertyDefinition {
-  // TODO: unneeded for now
-  type: 'color' | 'mapped' | 'percentage' | 'sizing' | 'arbitrary',
-  // Values tied to the property, usually manually defined for now
-  values: string[],
-  // Additional value types to append, usually used to add type links to generalize a type that
-  // the property extends aka a css length percentage or a number that needs more explaination
-  additionalTypes?: string[]
-}
-
 // properties that extend from baseColors
 const baseColorProperties = new Set([
   'color', 'backgroundColor', 'borderColor', 'outlineColor', 'fill', 'stroke'
@@ -40,23 +30,21 @@ const sizingProperties = new Set([
   'flexBasis', 'containIntrinsicWidth', 'containIntrinsicHeight'
 ]);
 
-// manually defined
-// TODO: maybe spit these up into groups, and have getPropertyDefinitions grab via category name instead
-const propertyValues: {[key: string]: string[]} = {
-  // Color
+
+const colorPropertyValues: {[key: string]: string[]} = {
   // This should append baseColors in getPropertyDefinition
   outlineColor: ['focus-ring'],
   // This should append what seems to be a combination of semantic colors and background/global colors
   fill: ['none', 'currentColor'],
   stroke: ['none', 'currentColor'],
+};
 
-
-  display: ['block', 'inline-block', 'inline', 'flex', 'inline-flex', 'grid', 'inline-grid', 'contents', 'list-item', 'none'],
+const dimensionsPropertyValues: {[key: string]: string[]} = {
   top: ['0', '2', '4', '8', '12', '16', '20', '24', '28', '32', '36', '40', '44', '48', '56', '64', '80', '96', '-2', '-4', '-8', '-12', '-16', '-20', '-24', '-28', '-32', '-36', '-40', '-44', '-48', '-56', '-64', '-80', '-96', 'auto', 'full'],
   height: ['auto', 'full', 'min', 'max', 'fit', 'screen'],
+};
 
-
-  // text
+const textPropertyValues: {[key: string]: string[]} = {
   fontFamily: ['sans', 'serif', 'code'],
   // todo: skipped font-size, font-weight, line height though these will also just be manually defined here
   listStyleType: ['none', 'disc', 'decimal'],
@@ -65,7 +53,6 @@ const propertyValues: {[key: string]: string[]} = {
   textAlign: ['start', 'center', 'end', 'justify'],
   verticalAlign: ['baseline', 'top', 'middle', 'bottom', 'text-top', 'text-bottom', 'sub', 'super'],
   textDecoration: ['none' , 'underline' , 'overline' , 'line-through'],
-
   textOverflow: ['ellipsis', 'clip'],
   lineClamp: ['number'],
   hyphens: ['none', 'manual', 'auto'],
@@ -74,52 +61,72 @@ const propertyValues: {[key: string]: string[]} = {
   wordBreak: ['normal', 'break-all', 'keep-all', 'break-word'],
   overflowWrap: ['normal', 'anywhere', 'break-word'],
   boxDecorationBreak: ['slice', 'clone'],
+};
 
-  // effects
+const effectsPropertyValues: {[key: string]: string[]} = {
   // TODO: should the below have a typelink explaining more details
   boxShadow: ['emphasized', 'elevated', 'dragged', 'none'],
   filter: ['emphasized', 'elevated', 'dragged', 'none'],
+};
+
+const layoutPropertyValues: {[key: string]: string[]} = {
 
+  display: ['block', 'inline-block', 'inline', 'flex', 'inline-flex', 'grid', 'inline-grid', 'contents', 'list-item', 'none'],
 };
 
-// TODO: will we need something specific for short hand?
-export function getPropertyDefinition(propertyName: string): StyleMacroPropertyDefinition {
-  const values = propertyValues[propertyName] || [];
+const miscPropertyValues: {[key: string]: string[]} = {
+
+};
+
+const shorthandMapping: {[key: string]: string[]} = {
 
+};
+
+const conditionMapping: {[key: string]: string[]} = {
+
+};
+
+const properties: {[key: string]: {[key: string]: string[]}} = {
+  color: colorPropertyValues,
+  dimensions: dimensionsPropertyValues,
+  text: textPropertyValues,
+  effects: effectsPropertyValues,
+  layout: layoutPropertyValues,
+  misc: miscPropertyValues
+};
+
+// TODO: will we need something specific for short hand?
+// TODO: see if there are any others that we will need to add additional shared types for
+export function getAdditionalTypes(propertyName: string): string[] {
   if (baseColorProperties.has(propertyName)) {
-    return {
-      type: 'color',
-      values,
-      additionalTypes: ['baseColors']
-    }
+    return ['baseColors']
   }
 
   if (sizingProperties.has(propertyName)) {
-    return {
-      type: 'sizing',
-      values,
-      additionalTypes: ['number', 'LengthPercentage']
-    };
+    return ['number', 'LengthPercentage']
   }
 
   if (percentageProperties.has(propertyName)) {
-    return {
-      type: 'percentage',
-      values,
-      additionalTypes: ['LengthPercentage']
-    };
+    return ['LengthPercentage']
   }
 
-  return {
-    type: 'mapped',
-    values
-  };
+  return [];
+}
+
+interface StyleMacroPropertyDefinition {
+  values: string[],
+  additionalTypes?: string[]
 }
 
-export function getPropertyDefinitions(propertyNames: string[]): {[key: string]: StyleMacroPropertyDefinition} {
-  const result: {[key: string]: StyleMacroPropertyDefinition} = {};
-  for (const name of propertyNames) {
-    result[name] = getPropertyDefinition(name);
+export function getPropertyDefinitions(propertyCategory: string): {[key: string]: StyleMacroPropertyDefinition} {
+  let result: {[key: string]: StyleMacroPropertyDefinition} = {};
+  let propertiesMapping = properties[propertyCategory] || {};
+
+  for (let [name, values] of Object.entries(propertiesMapping)) {
+    result[name] = {
+      values,
+      additionalTypes: getAdditionalTypes(name)
+    }
   }
   return result;
 }
diff --git a/packages/dev/s2-docs/src/types.tsx b/packages/dev/s2-docs/src/types.tsx
index 953f59407c0..7f05bd7239c 100644
--- a/packages/dev/s2-docs/src/types.tsx
+++ b/packages/dev/s2-docs/src/types.tsx
@@ -696,7 +696,6 @@ function TemplateLiteral({elements}: TTemplate) {
 }
 
 interface StyleMacroPropertyDefinition {
-  type: 'color' | 'mapped' | 'percentage' | 'sizing' | 'arbitrary',
   values: string[],
   additionalTypes?: string[]
 }

From 36f1a6f1f72b8caca86c95c2b310a7e6669f68f5 Mon Sep 17 00:00:00 2001
From: Daniel Lu <dl1644@gmail.com>
Date: Tue, 28 Oct 2025 14:15:27 -0700
Subject: [PATCH 08/27] add the rest of the properties and double check them

---
 packages/dev/s2-docs/src/styleProperties.ts | 322 ++++++++++++++++++--
 1 file changed, 302 insertions(+), 20 deletions(-)

diff --git a/packages/dev/s2-docs/src/styleProperties.ts b/packages/dev/s2-docs/src/styleProperties.ts
index 743e97c01cf..6aa637074a9 100644
--- a/packages/dev/s2-docs/src/styleProperties.ts
+++ b/packages/dev/s2-docs/src/styleProperties.ts
@@ -10,10 +10,10 @@
  * governing permissions and limitations under the License.
  */
 
-// properties that extend from baseColors
+// Properties that extend from baseColors
 const baseColorProperties = new Set([
   'color', 'backgroundColor', 'borderColor', 'outlineColor', 'fill', 'stroke'
-])
+]);
 
 // Properties that use PercentageProperty (accept LengthPercentage in addition to mapped values)
 const percentageProperties = new Set([
@@ -30,61 +30,342 @@ const sizingProperties = new Set([
   'flexBasis', 'containIntrinsicWidth', 'containIntrinsicHeight'
 ]);
 
+// Spacing values used across multiple properties
+// TODO: double check these values, and maybe add them as additional types so we get a type link instead since they are quite long
+const baseSpacingValues = ['0', '2', '4', '8', '12', '16', '20', '24', '28', '32', '36', '40', '44', '48', '56', '64', '80', '96',];
+const negativeBaseSpacingValues = ['-2', '-4', '-8', '-12', '-16', '-20', '-24', '-28', '-32', '-36', '-40', '-44', '-48', '-56', '-64', '-80', '-96'];
+const relativeSpacingValues = [ 'text-to-control', 'text-to-visual', 'edge-to-text', 'pill'];
+const spacingValues = [...baseSpacingValues, ...relativeSpacingValues];
+const marginValues = [...spacingValues, ...negativeBaseSpacingValues, 'auto'];
+const insetValues = [...baseSpacingValues, ...negativeBaseSpacingValues, 'auto', 'full'];
+const translateValues = [...baseSpacingValues, ...negativeBaseSpacingValues, 'full'];
+const heightBaseValues = ['auto', 'full', 'min', 'max', 'fit', 'screen'];
+const fontSize = [
+  'ui-xs', 'ui-sm', 'ui', 'ui-lg', 'ui-xl', 'ui-2xl', 'ui-3xl',
+  'heading-2xs', 'heading-xs', 'heading-sm', 'heading', 'heading-lg', 'heading-xl', 'heading-2xl', 'heading-3xl',
+  'title-xs', 'title-sm', 'title', 'title-lg', 'title-xl', 'title-2xl', 'title-3xl',
+  'body-2xs', 'body-xs', 'body-sm', 'body', 'body-lg', 'body-xl', 'body-2xl', 'body-3xl',
+  'detail-sm', 'detail', 'detail-lg', 'detail-xl',
+  'code-xs', 'code-sm', 'code', 'code-lg', 'code-xl'
+];
 
 const colorPropertyValues: {[key: string]: string[]} = {
-  // This should append baseColors in getPropertyDefinition
+  color: ['accent', 'neutral', 'neutral-subdued', 'negative', 'disabled', 'heading', 'title', 'body', 'detail', 'code', 'auto'],
+  backgroundColor: [
+    'accent', 'accent-subtle', 'neutral', 'neutral-subdued', 'neutral-subtle',
+    'negative', 'negative-subtle', 'informative', 'informative-subtle',
+    'positive', 'positive-subtle', 'notice', 'notice-subtle',
+    'gray', 'gray-subtle', 'red', 'red-subtle', 'orange', 'orange-subtle',
+    'yellow', 'yellow-subtle', 'chartreuse', 'chartreuse-subtle',
+    'celery', 'celery-subtle', 'green', 'green-subtle',
+    'seafoam', 'seafoam-subtle', 'cyan', 'cyan-subtle',
+    'blue', 'blue-subtle', 'indigo', 'indigo-subtle',
+    'purple', 'purple-subtle', 'fuchsia', 'fuchsia-subtle',
+    'magenta', 'magenta-subtle', 'pink', 'pink-subtle',
+    'turquoise', 'turquoise-subtle', 'cinnamon', 'cinnamon-subtle',
+    'brown', 'brown-subtle', 'silver', 'silver-subtle',
+    'disabled', 'base', 'layer-1', 'layer-2', 'pasteboard', 'elevated'
+  ],
+  borderColor: ['negative', 'disabled'],
   outlineColor: ['focus-ring'],
-  // This should append what seems to be a combination of semantic colors and background/global colors
-  fill: ['none', 'currentColor'],
-  stroke: ['none', 'currentColor'],
+  fill: [
+    'none', 'currentColor',
+    'accent', 'neutral', 'negative', 'informative', 'positive', 'notice',
+    'gray', 'red', 'orange', 'yellow', 'chartreuse', 'celery', 'green',
+    'seafoam', 'cyan', 'blue', 'indigo', 'purple', 'fuchsia', 'magenta',
+    'pink', 'turquoise', 'cinnamon', 'brown', 'silver'
+  ],
+  stroke: ['none', 'currentColor']
 };
 
 const dimensionsPropertyValues: {[key: string]: string[]} = {
-  top: ['0', '2', '4', '8', '12', '16', '20', '24', '28', '32', '36', '40', '44', '48', '56', '64', '80', '96', '-2', '-4', '-8', '-12', '-16', '-20', '-24', '-28', '-32', '-36', '-40', '-44', '-48', '-56', '-64', '-80', '-96', 'auto', 'full'],
-  height: ['auto', 'full', 'min', 'max', 'fit', 'screen'],
+  borderSpacing: baseSpacingValues,
+  flexBasis: ['auto', 'full'],
+  rowGap: spacingValues,
+  columnGap: spacingValues,
+  height: heightBaseValues,
+  width: heightBaseValues,
+  containIntrinsicWidth: heightBaseValues,
+  containIntrinsicHeight: heightBaseValues,
+  minHeight: heightBaseValues,
+  maxHeight: [...heightBaseValues, 'none'],
+  minWidth: heightBaseValues,
+  maxWidth: [...heightBaseValues, 'none'],
+  borderStartWidth: ['0', '1', '2', '4'],
+  borderEndWidth: ['0', '1', '2', '4'],
+  borderTopWidth: ['0', '1', '2', '4'],
+  borderBottomWidth: ['0', '1', '2', '4'],
+  borderStyle: ['solid', 'dashed', 'dotted', 'double', 'hidden', 'none'],
+  strokeWidth: ['0', '1', '2'],
+  marginStart: marginValues,
+  marginEnd: marginValues,
+  marginTop: marginValues,
+  marginBottom: marginValues,
+  paddingStart: spacingValues,
+  paddingEnd: spacingValues,
+  paddingTop: spacingValues,
+  paddingBottom: spacingValues,
+  scrollMarginStart: baseSpacingValues,
+  scrollMarginEnd: baseSpacingValues,
+  scrollMarginTop: baseSpacingValues,
+  scrollMarginBottom: baseSpacingValues,
+  scrollPaddingStart: baseSpacingValues,
+  scrollPaddingEnd: baseSpacingValues,
+  scrollPaddingTop: baseSpacingValues,
+  scrollPaddingBottom: baseSpacingValues,
+  textIndent: baseSpacingValues,
+  translateX: translateValues,
+  translateY: translateValues,
+  // TODO would be good if these numbers/strings were types links instead
+  rotate: ['number', '${number}deg', '${number}rad', '${number}grad', '${number}turn'],
+  scaleX: ['number', '${number}%'],
+  scaleY: ['number', '${number}%'],
+  transform: ['string'],
+  position: ['absolute', 'fixed', 'relative', 'sticky', 'static'],
+  insetStart: insetValues,
+  insetEnd: insetValues,
+  top: insetValues,
+  left: insetValues,
+  bottom: insetValues,
+  right: insetValues,
+  // TODO: also would like this number/number to be code formatted, not a string? Maybe make it a type link as well
+  aspectRatio: ['auto', 'square', 'video', 'number/number (e.g. 4/3)']
 };
 
 const textPropertyValues: {[key: string]: string[]} = {
   fontFamily: ['sans', 'serif', 'code'],
-  // todo: skipped font-size, font-weight, line height though these will also just be manually defined here
+  fontSize: fontSize,
+  fontWeight: ['normal', 'medium', 'bold', 'extra-bold', 'black', 'heading', 'title', 'detail'],
+  lineHeight: ['ui', 'heading', 'title', 'body', 'detail', 'code'],
   listStyleType: ['none', 'disc', 'decimal'],
   listStylePosition: ['inside', 'outside'],
   textTransform: ['uppercase', 'lowercase', 'capitalize', 'none'],
   textAlign: ['start', 'center', 'end', 'justify'],
   verticalAlign: ['baseline', 'top', 'middle', 'bottom', 'text-top', 'text-bottom', 'sub', 'super'],
-  textDecoration: ['none' , 'underline' , 'overline' , 'line-through'],
+  textDecoration: ['none', 'underline', 'overline', 'line-through'],
   textOverflow: ['ellipsis', 'clip'],
+  // TODO: how to get this as an actual type link like boolean
   lineClamp: ['number'],
   hyphens: ['none', 'manual', 'auto'],
   whiteSpace: ['normal', 'nowrap', 'pre', 'pre-line', 'pre-wrap', 'break-spaces'],
   textWrap: ['wrap', 'nowrap', 'balance', 'pretty'],
   wordBreak: ['normal', 'break-all', 'keep-all', 'break-word'],
   overflowWrap: ['normal', 'anywhere', 'break-word'],
-  boxDecorationBreak: ['slice', 'clone'],
+  boxDecorationBreak: ['slice', 'clone']
 };
 
+// TODO: also missing values that are ArbitraryProperties/ExpandedProperties, etc
 const effectsPropertyValues: {[key: string]: string[]} = {
-  // TODO: should the below have a typelink explaining more details
   boxShadow: ['emphasized', 'elevated', 'dragged', 'none'],
   filter: ['emphasized', 'elevated', 'dragged', 'none'],
+  borderTopStartRadius: ['none', 'sm', 'default', 'lg', 'xl', 'full', 'pill'],
+  borderTopEndRadius: ['none', 'sm', 'default', 'lg', 'xl', 'full', 'pill'],
+  borderBottomStartRadius: ['none', 'sm', 'default', 'lg', 'xl', 'full', 'pill'],
+  borderBottomEndRadius: ['none', 'sm', 'default', 'lg', 'xl', 'full', 'pill'],
+  forcedColorAdjust: ['auto', 'none'],
+  colorScheme: ['light', 'dark', 'light dark'],
+  // TODO: ideally would be type links for string and LinearGradient
+  backgroundImage: ['string', 'LinearGradient'],
+  backgroundPosition: ['bottom', 'center', 'left', 'left bottom', 'left top', 'right', 'right bottom', 'right top', 'top'],
+  backgroundSize: ['auto', 'cover', 'contain'],
+  backgroundAttachment: ['fixed', 'local', 'scroll'],
+  backgroundClip: ['border-box', 'padding-box', 'content-box', 'text'],
+  backgroundRepeat: ['repeat', 'no-repeat', 'repeat-x', 'repeat-y', 'round', 'space'],
+  backgroundOrigin: ['border-box', 'padding-box', 'content-box'],
+  backgroundBlendMode: ['normal', 'multiply', 'screen', 'overlay', 'darken', 'lighten', 'color-dodge', 'color-burn', 'hard-light', 'soft-light', 'difference', 'exclusion', 'hue', 'saturation', 'color', 'luminosity'],
+  mixBlendMode: ['normal', 'multiply', 'screen', 'overlay', 'darken', 'lighten', 'color-dodge', 'color-burn', 'hard-light', 'soft-light', 'difference', 'exclusion', 'hue', 'saturation', 'color', 'luminosity', 'plus-darker', 'plus-lighter'],
+  // TODO: ideally would be a type link
+  opacity: ['number'],
+  outlineStyle: ['none', 'solid', 'dashed', 'dotted', 'double', 'inset'],
+  outlineOffset: ['number'],
+  outlineWidth: ['0', '1', '2', '4'],
+  transition: ['default', 'colors', 'opacity', 'shadow', 'transform', 'all', 'none'],
+
+  // TODO: type link
+  transitionDelay: ['string', 'number'],
+  transitionDuration: ['string', 'number'],
+
+  transitionTimingFunction: ['default', 'linear', 'in', 'out', 'in-out'],
+
+  // TODO: type link, maybe some of these type links should just be links to MDN?
+  // Could make it similar to getAdditionalTypes and have a links object that has the type (aka string | number) and then links it to MDN
+  animation: ['string', 'number'],
+  animationDuration: ['string', 'number'],
+  animationDelay: ['string', 'number'],
+
+
+
+  animationDirection: ['normal', 'reverse', 'alternate', 'alternate-reverse'],
+  animationFillMode: ['none', 'forwards', 'backwards', 'both'],
+
+  // TODO: type link, see above
+  animationIterationCount: ['string', 'number'],
+
+
+  animationTimingFunction: ['default', 'linear', 'in', 'out', 'in-out'],
+  animationPlayState: ['paused', 'running']
 };
 
+// TODO this is missing the values that are ArbitraryProperties, will need to add them
 const layoutPropertyValues: {[key: string]: string[]} = {
-
   display: ['block', 'inline-block', 'inline', 'flex', 'inline-flex', 'grid', 'inline-grid', 'contents', 'list-item', 'none'],
+  alignContent: ['normal', 'center', 'start', 'end', 'space-between', 'space-around', 'space-evenly', 'baseline', 'stretch'],
+  alignItems: ['start', 'end', 'center', 'baseline', 'stretch'],
+  justifyContent: ['normal', 'start', 'end', 'center', 'space-between', 'space-around', 'space-evenly', 'stretch'],
+  justifyItems: ['start', 'end', 'center', 'stretch'],
+  alignSelf: ['auto', 'start', 'end', 'center', 'stretch', 'baseline'],
+  justifySelf: ['auto', 'start', 'end', 'center', 'stretch'],
+  flexDirection: ['row', 'column', 'row-reverse', 'column-reverse'],
+  flexWrap: ['wrap', 'wrap-reverse', 'nowrap'],
+
+
+  // TODO: the below definitely link to MDN
+  // flexShrink: new ArbitraryProperty<CSS.Property.FlexShrink>('flexShrink'),
+  // flexGrow: new ArbitraryProperty<CSS.Property.FlexGrow>('flexGrow'),
+  // gridColumnStart: new ArbitraryProperty<CSS.Property.GridColumnStart>('gridColumnStart'),
+  // gridColumnEnd: new ArbitraryProperty<CSS.Property.GridColumnEnd>('gridColumnEnd'),
+  // gridRowStart: new ArbitraryProperty<CSS.Property.GridRowStart>('gridRowStart'),
+  // gridRowEnd: new ArbitraryProperty<CSS.Property.GridRowEnd>('gridRowEnd'),
+
+
+  gridAutoFlow: ['row', 'column', 'dense', 'row dense', 'column dense'],
+
+  // TODO: make these link to MDN and also have baseSpacingValue type link
+  gridAutoRows:[...baseSpacingValues, 'auto', 'min-content', 'max-content', '${number}fr', 'minmax(${string}, ${string})', 'string'],
+  gridAutoColumns: [...baseSpacingValues, 'auto', 'min-content', 'max-content', '${number}fr', 'minmax(${string}, ${string})', 'string'],
+  gridTemplateColumns: [...baseSpacingValues, 'auto', 'min-content', 'max-content', '${number}fr', 'minmax(${string}, ${string})', 'none', 'subgrid', 'string',],
+  gridTemplateRows: [...baseSpacingValues, 'auto', 'min-content', 'max-content', '${number}fr', 'minmax(${string}, ${string})', 'none', 'subgrid', 'string'],
+  gridTemplateAreas: ['string[]'],
+
+
+  float: ['inline-start', 'inline-end', 'right', 'left', 'none'],
+  clear: ['inline-start', 'inline-end', 'left', 'right', 'both', 'none'],
+  contain: ['none', 'strict', 'content', 'size', 'inline-size', 'layout', 'style', 'paint'],
+  boxSizing: ['border-box', 'content-box'],
+  tableLayout: ['auto', 'fixed'],
+  captionSide: ['top', 'bottom'],
+  borderCollapse: ['collapse', 'separate'],
+  breakBefore: ['auto', 'avoid', 'all', 'avoid-page', 'page', 'left', 'right', 'column'],
+  breakInside: ['auto', 'avoid', 'avoid-page', 'avoid-column'],
+  breakAfter: ['auto', 'avoid', 'all', 'avoid-page', 'page', 'left', 'right', 'column'],
+  overflowX: ['auto', 'hidden', 'clip', 'visible', 'scroll'],
+  overflowY: ['auto', 'hidden', 'clip', 'visible', 'scroll'],
+  overscrollBehaviorX: ['auto', 'contain', 'none'],
+  overscrollBehaviorY: ['auto', 'contain', 'none'],
+  scrollBehavior: ['auto', 'smooth'],
+
+  // TODO: make type link
+  order: ['number'],
 };
 
+// TODO: some of these aren't interactions really? Will need to classify them later
+// Add this to the docs, the table is called misc
 const miscPropertyValues: {[key: string]: string[]} = {
-
+  pointerEvents: ['none', 'auto'],
+  touchAction: ['auto', 'none', 'pan-x', 'pan-y', 'manipulation', 'pinch-zoom'],
+  userSelect: ['none', 'text', 'all', 'auto'],
+  visibility: ['visible', 'hidden', 'collapse'],
+  isolation: ['isolate', 'auto'],
+  transformOrigin: ['center', 'top', 'top right', 'right', 'bottom right', 'bottom', 'bottom left', 'left', 'top right'],
+  cursor: ['auto', 'default', 'pointer', 'wait', 'text', 'move', 'help', 'not-allowed', 'none', 'context-menu', 'progress', 'cell', 'crosshair', 'vertical-text', 'alias', 'copy', 'no-drop', 'grab', 'grabbing', 'all-scroll', 'col-resize', 'row-resize', 'n-resize', 'e-resize', 's-resize', 'w-resize', 'ne-resize', 'nw-resize', 'se-resize', 'ew-resize', 'ns-resize', 'nesw-resize', 'nwse-resize', 'zoom-in', 'zoom-out'],
+  resize: ['none', 'vertical', 'horizontal', 'both'],
+  scrollSnapType: ['x', 'y', 'both', 'x mandatory', 'y mandatory', 'both mandatory'],
+  scrollSnapAlign: ['start', 'end', 'center', 'none'],
+  scrollSnapStop: ['normal', 'always'],
+  appearance: ['none', 'auto'],
+  objectFit: ['contain', 'cover', 'fill', 'none', 'scale-down'],
+  objectPosition: ['bottom', 'center', 'left', 'left bottom', 'left top', 'right', 'right bottom', 'right top', 'top'],
+  willChange: ['auto', 'scroll-position', 'contents', 'transform'],
+  // TODO: need type link
+  zIndex: ['number'],
+  disableTapHighlight: ['true'],
+  unicodeBidi: ['normal', 'embed', 'bidi-override', 'isolate', 'isolate-override', 'plaintext'],
+  caretColor: ['auto', 'transparent']
 };
 
+
+// TODO add shorthand mapping and conditions to the docs
 const shorthandMapping: {[key: string]: string[]} = {
+  padding: ['paddingTop', 'paddingBottom', 'paddingStart', 'paddingEnd'],
+  paddingX: ['paddingStart', 'paddingEnd'],
+  paddingY: ['paddingTop', 'paddingBottom'],
+  margin: ['marginTop', 'marginBottom', 'marginStart', 'marginEnd'],
+  marginX: ['marginStart', 'marginEnd'],
+  marginY: ['marginTop', 'marginBottom'],
+  scrollPadding: ['scrollPaddingTop', 'scrollPaddingBottom', 'scrollPaddingStart', 'scrollPaddingEnd'],
+  scrollPaddingX: ['scrollPaddingStart', 'scrollPaddingEnd'],
+  scrollPaddingY: ['scrollPaddingTop', 'scrollPaddingBottom'],
+  scrollMargin: ['scrollMarginTop', 'scrollMarginBottom', 'scrollMarginStart', 'scrollMarginEnd'],
+  scrollMarginX: ['scrollMarginStart', 'scrollMarginEnd'],
+  scrollMarginY: ['scrollMarginTop', 'scrollMarginBottom'],
+  borderWidth: ['borderTopWidth', 'borderBottomWidth', 'borderStartWidth', 'borderEndWidth'],
+  borderXWidth: ['borderStartWidth', 'borderEndWidth'],
+  borderYWidth: ['borderTopWidth', 'borderBottomWidth'],
+  borderRadius: ['borderTopStartRadius', 'borderTopEndRadius', 'borderBottomStartRadius', 'borderBottomEndRadius'],
+  borderTopRadius: ['borderTopStartRadius', 'borderTopEndRadius'],
+  borderBottomRadius: ['borderBottomStartRadius', 'borderBottomEndRadius'],
+  borderStartRadius: ['borderTopStartRadius', 'borderBottomStartRadius'],
+  borderEndRadius: ['borderTopEndRadius', 'borderBottomEndRadius'],
+  translate: ['translateX', 'translateY'],
+  scale: ['scaleX', 'scaleY'],
+  inset: ['top', 'bottom', 'insetStart', 'insetEnd'],
+  insetX: ['insetStart', 'insetEnd'],
+  insetY: ['top', 'bottom'],
+  placeItems: ['alignItems', 'justifyItems'],
+  placeContent: ['alignContent', 'justifyContent'],
+  placeSelf: ['alignSelf', 'justifySelf'],
+  gap: ['rowGap', 'columnGap'],
+  size: ['width', 'height'],
+  minSize: ['minWidth', 'minHeight'],
+  maxSize: ['maxWidth', 'maxHeight'],
+  overflow: ['overflowX', 'overflowY'],
+  overscrollBehavior: ['overscrollBehaviorX', 'overscrollBehaviorY'],
+  gridArea: ['gridColumnStart', 'gridColumnEnd', 'gridRowStart', 'gridRowEnd'],
+
+  // TODO: is it more important to display the mapping that each short hand corresponds to or the value that it accepts?
+  // I was hoping that I would just display the mapping and then have people reference the value for the corresponding
+  // values in the sections above
+  font: fontSize
 
+  // TODO: For the below, similar question as the above
+  // transition: (value: keyof typeof transitionProperty) => ({
+  //   transition: value,
+  //   transitionDuration: 150,
+  //   transitionTimingFunction: 'default'
+  // }),
+  // animation: (value: string) => ({
+  //   animation: value,
+  //   animationDuration: 150,
+  //   animationTimingFunction: 'default'
+  // }),
+  // // eslint-disable-next-line @typescript-eslint/no-unused-vars
+  // truncate: (_value: true) => ({
+  //   overflowX: 'hidden',
+  //   overflowY: 'hidden',
+  //   textOverflow: 'ellipsis',
+  //   whiteSpace: 'nowrap'
+  // }),
+  // font: (value: keyof typeof fontSize) => {
+  //   let type = value.split('-')[0];
+  //   return {
+  //     fontFamily: type === 'code' ? 'code' : 'sans',
+  //     fontSize: value,
+  //     fontWeight: type === 'heading' || type === 'title' || type === 'detail' ? type : 'normal',
+  //     lineHeight: type,
+  //     color: type === 'ui' ? 'body' : type
+  //   };
+  // }
 };
 
 const conditionMapping: {[key: string]: string[]} = {
-
-};
+  forcedColors: ['@media (forced-colors: active)'],
+  touch: ['@media not ((hover: hover) and (pointer: fine))'],
+  sm: ['@media (min-width: ${pxToRem(640)})'],
+  md: ['@media (min-width: ${pxToRem(768)})'],
+  lg: ['@media (min-width: ${pxToRem(1024)})'],
+  xl: ['@media (min-width: ${pxToRem(1280)})'],
+  '2xl': ['@media (min-width: ${pxToRem(1536)})']
+}
 
 const properties: {[key: string]: {[key: string]: string[]}} = {
   color: colorPropertyValues,
@@ -97,17 +378,18 @@ const properties: {[key: string]: {[key: string]: string[]}} = {
 
 // TODO: will we need something specific for short hand?
 // TODO: see if there are any others that we will need to add additional shared types for
+// this is less additional types and more that we want to represent the below as a type link
 export function getAdditionalTypes(propertyName: string): string[] {
   if (baseColorProperties.has(propertyName)) {
-    return ['baseColors']
+    return ['baseColors'];
   }
 
   if (sizingProperties.has(propertyName)) {
-    return ['number', 'LengthPercentage']
+    return ['number', 'LengthPercentage'];
   }
 
   if (percentageProperties.has(propertyName)) {
-    return ['LengthPercentage']
+    return ['LengthPercentage'];
   }
 
   return [];
@@ -126,7 +408,7 @@ export function getPropertyDefinitions(propertyCategory: string): {[key: string]
     result[name] = {
       values,
       additionalTypes: getAdditionalTypes(name)
-    }
+    };
   }
   return result;
 }

From e2b29c9d6502105561ee29a3e3cb930c9dd759f4 Mon Sep 17 00:00:00 2001
From: Daniel Lu <dl1644@gmail.com>
Date: Tue, 28 Oct 2025 16:24:54 -0700
Subject: [PATCH 09/27] add more type links

---
 packages/dev/s2-docs/pages/s2/Reference.mdx |  15 +--
 packages/dev/s2-docs/src/styleProperties.ts | 133 ++++++++++++--------
 packages/dev/s2-docs/src/types.tsx          |  92 +++++++++++---
 3 files changed, 161 insertions(+), 79 deletions(-)

diff --git a/packages/dev/s2-docs/pages/s2/Reference.mdx b/packages/dev/s2-docs/pages/s2/Reference.mdx
index 42c868e57b3..6c312c3caa0 100644
--- a/packages/dev/s2-docs/pages/s2/Reference.mdx
+++ b/packages/dev/s2-docs/pages/s2/Reference.mdx
@@ -12,23 +12,17 @@ export const description = 'Reference table for the `style` macro';
 
 # Style Macro Reference
 
-Reference table for the properties and values supported by React Spectrum `style` macro.
+Reference for the properties and values supported by React Spectrum `style` macro.
 
 ## Colors
 
-TODO: do we just want the table or preserve the same formatting as the styling guide?
-
 All Spectrum 2 color tokens are available across color properties (e.g., `backgroundColor`, `color`, `borderColor`).
 
 <S2Colors />
 
-Below are the rest of the `style` macro supported color properties.
-
 <StyleMacroProperties properties={getPropertyDefinitions('color')} />
 
-## Spacing
-
-TODO: decide what to do with Spacing/Sizing since they are pretty much rolled up into Dimensions?
+## 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:
 
@@ -37,8 +31,6 @@ Spacing props like `margin` and `padding` accept values on a **4px grid**. These
 - `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.
 
 <StyleMacroProperties properties={getPropertyDefinitions('dimensions')} />
@@ -47,7 +39,7 @@ Size props like `width` and `height` accept arbitrary pixel values. Values are c
 
 // TODO: edit copy
 
-Spectrum 2 typography is applied via the `font` shorthand, which sets `fontFamily`, `fontSize`, `fontWeight`, `lineHeight`, and `color`. You can override any of these individually.
+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>
@@ -75,7 +67,6 @@ Type scales include: UI, Body, Heading, Title, Detail, and Code. Each scale has
 
 <StyleMacroProperties properties={getPropertyDefinitions('layout')} />
 
-
 ## Misc
 
 <StyleMacroProperties properties={getPropertyDefinitions('misc')} />
diff --git a/packages/dev/s2-docs/src/styleProperties.ts b/packages/dev/s2-docs/src/styleProperties.ts
index 6aa637074a9..ac44d5326e8 100644
--- a/packages/dev/s2-docs/src/styleProperties.ts
+++ b/packages/dev/s2-docs/src/styleProperties.ts
@@ -30,15 +30,32 @@ const sizingProperties = new Set([
   'flexBasis', 'containIntrinsicWidth', 'containIntrinsicHeight'
 ]);
 
+// Properties that accept baseSpacing values
+const baseSpacingProperties = new Set([
+  'borderSpacing', 'rowGap', 'columnGap',
+  'paddingStart', 'paddingEnd', 'paddingTop', 'paddingBottom',
+  'scrollMarginStart', 'scrollMarginEnd', 'scrollMarginTop', 'scrollMarginBottom',
+  'scrollPaddingStart', 'scrollPaddingEnd', 'scrollPaddingTop', 'scrollPaddingBottom',
+  'textIndent', 'gridAutoRows', 'gridAutoColumns', 'gridTemplateColumns', 'gridTemplateRows',
+  'marginStart', 'marginEnd', 'marginTop', 'marginBottom', 'translateX', 'translateY',
+  'insetStart', 'insetEnd', 'top', 'left', 'bottom', 'right'
+]);
+
+// Properties that accept negative spacing values
+const negativeSpacingProperties = new Set([
+  'marginStart', 'marginEnd', 'marginTop', 'marginBottom',
+  'translateX', 'translateY',
+  'insetStart', 'insetEnd', 'top', 'left', 'bottom', 'right'
+]);
+
 // Spacing values used across multiple properties
-// TODO: double check these values, and maybe add them as additional types so we get a type link instead since they are quite long
 const baseSpacingValues = ['0', '2', '4', '8', '12', '16', '20', '24', '28', '32', '36', '40', '44', '48', '56', '64', '80', '96',];
 const negativeBaseSpacingValues = ['-2', '-4', '-8', '-12', '-16', '-20', '-24', '-28', '-32', '-36', '-40', '-44', '-48', '-56', '-64', '-80', '-96'];
 const relativeSpacingValues = [ 'text-to-control', 'text-to-visual', 'edge-to-text', 'pill'];
-const spacingValues = [...baseSpacingValues, ...relativeSpacingValues];
-const marginValues = [...spacingValues, ...negativeBaseSpacingValues, 'auto'];
-const insetValues = [...baseSpacingValues, ...negativeBaseSpacingValues, 'auto', 'full'];
-const translateValues = [...baseSpacingValues, ...negativeBaseSpacingValues, 'full'];
+// const spacingValues = [...baseSpacingValues, ...relativeSpacingValues];
+// const marginValues = [...spacingValues, ...negativeBaseSpacingValues, 'auto'];
+// const insetValues = [...baseSpacingValues, ...negativeBaseSpacingValues, 'auto', 'full'];
+// const translateValues = [...baseSpacingValues, ...negativeBaseSpacingValues, 'full'];
 const heightBaseValues = ['auto', 'full', 'min', 'max', 'fit', 'screen'];
 const fontSize = [
   'ui-xs', 'ui-sm', 'ui', 'ui-lg', 'ui-xl', 'ui-2xl', 'ui-3xl',
@@ -79,10 +96,10 @@ const colorPropertyValues: {[key: string]: string[]} = {
 };
 
 const dimensionsPropertyValues: {[key: string]: string[]} = {
-  borderSpacing: baseSpacingValues,
+  borderSpacing: [],
   flexBasis: ['auto', 'full'],
-  rowGap: spacingValues,
-  columnGap: spacingValues,
+  rowGap: relativeSpacingValues,
+  columnGap: relativeSpacingValues,
   height: heightBaseValues,
   width: heightBaseValues,
   containIntrinsicWidth: heightBaseValues,
@@ -97,39 +114,44 @@ const dimensionsPropertyValues: {[key: string]: string[]} = {
   borderBottomWidth: ['0', '1', '2', '4'],
   borderStyle: ['solid', 'dashed', 'dotted', 'double', 'hidden', 'none'],
   strokeWidth: ['0', '1', '2'],
-  marginStart: marginValues,
-  marginEnd: marginValues,
-  marginTop: marginValues,
-  marginBottom: marginValues,
-  paddingStart: spacingValues,
-  paddingEnd: spacingValues,
-  paddingTop: spacingValues,
-  paddingBottom: spacingValues,
-  scrollMarginStart: baseSpacingValues,
-  scrollMarginEnd: baseSpacingValues,
-  scrollMarginTop: baseSpacingValues,
-  scrollMarginBottom: baseSpacingValues,
-  scrollPaddingStart: baseSpacingValues,
-  scrollPaddingEnd: baseSpacingValues,
-  scrollPaddingTop: baseSpacingValues,
-  scrollPaddingBottom: baseSpacingValues,
-  textIndent: baseSpacingValues,
-  translateX: translateValues,
-  translateY: translateValues,
-  // TODO would be good if these numbers/strings were types links instead
+  marginStart: ['auto'],
+  marginEnd: ['auto'],
+  marginTop: ['auto'],
+  marginBottom: ['auto'],
+  paddingStart: relativeSpacingValues,
+  paddingEnd: relativeSpacingValues,
+  paddingTop: relativeSpacingValues,
+  paddingBottom: relativeSpacingValues,
+  scrollMarginStart: [],
+  scrollMarginEnd: [],
+  scrollMarginTop: [],
+  scrollMarginBottom: [],
+  scrollPaddingStart: [],
+  scrollPaddingEnd: [],
+  scrollPaddingTop: [],
+  scrollPaddingBottom: [],
+  textIndent: [],
+  translateX: ['full'],
+  translateY: ['full'],
+
+
+  // TODO These ones should have a description for the supported values, make a type link for number however
   rotate: ['number', '${number}deg', '${number}rad', '${number}grad', '${number}turn'],
   scaleX: ['number', '${number}%'],
   scaleY: ['number', '${number}%'],
+
+
   transform: ['string'],
   position: ['absolute', 'fixed', 'relative', 'sticky', 'static'],
-  insetStart: insetValues,
-  insetEnd: insetValues,
-  top: insetValues,
-  left: insetValues,
-  bottom: insetValues,
-  right: insetValues,
+  insetStart: ['auto', 'full'],
+  insetEnd: ['auto', 'full'],
+  top: ['auto', 'full'],
+  left: ['auto', 'full'],
+  bottom: ['auto', 'full'],
+  right: ['auto', 'full'],
+
   // TODO: also would like this number/number to be code formatted, not a string? Maybe make it a type link as well
-  aspectRatio: ['auto', 'square', 'video', 'number/number (e.g. 4/3)']
+  aspectRatio: ['auto', 'square', 'video', 'number / number']
 };
 
 const textPropertyValues: {[key: string]: string[]} = {
@@ -144,7 +166,7 @@ const textPropertyValues: {[key: string]: string[]} = {
   verticalAlign: ['baseline', 'top', 'middle', 'bottom', 'text-top', 'text-bottom', 'sub', 'super'],
   textDecoration: ['none', 'underline', 'overline', 'line-through'],
   textOverflow: ['ellipsis', 'clip'],
-  // TODO: how to get this as an actual type link like boolean
+  // TODO: make common type link for number, link to mdn
   lineClamp: ['number'],
   hyphens: ['none', 'manual', 'auto'],
   whiteSpace: ['normal', 'nowrap', 'pre', 'pre-line', 'pre-wrap', 'break-spaces'],
@@ -154,7 +176,7 @@ const textPropertyValues: {[key: string]: string[]} = {
   boxDecorationBreak: ['slice', 'clone']
 };
 
-// TODO: also missing values that are ArbitraryProperties/ExpandedProperties, etc
+
 const effectsPropertyValues: {[key: string]: string[]} = {
   boxShadow: ['emphasized', 'elevated', 'dragged', 'none'],
   filter: ['emphasized', 'elevated', 'dragged', 'none'],
@@ -164,7 +186,7 @@ const effectsPropertyValues: {[key: string]: string[]} = {
   borderBottomEndRadius: ['none', 'sm', 'default', 'lg', 'xl', 'full', 'pill'],
   forcedColorAdjust: ['auto', 'none'],
   colorScheme: ['light', 'dark', 'light dark'],
-  // TODO: ideally would be type links for string and LinearGradient
+  // TODO: ideally would be type links for string and LinearGradient, will need to decide if we wanna export LinearGradient
   backgroundImage: ['string', 'LinearGradient'],
   backgroundPosition: ['bottom', 'center', 'left', 'left bottom', 'left top', 'right', 'right bottom', 'right top', 'top'],
   backgroundSize: ['auto', 'cover', 'contain'],
@@ -206,7 +228,6 @@ const effectsPropertyValues: {[key: string]: string[]} = {
   animationPlayState: ['paused', 'running']
 };
 
-// TODO this is missing the values that are ArbitraryProperties, will need to add them
 const layoutPropertyValues: {[key: string]: string[]} = {
   display: ['block', 'inline-block', 'inline', 'flex', 'inline-flex', 'grid', 'inline-grid', 'contents', 'list-item', 'none'],
   alignContent: ['normal', 'center', 'start', 'end', 'space-between', 'space-around', 'space-evenly', 'baseline', 'stretch'],
@@ -231,10 +252,10 @@ const layoutPropertyValues: {[key: string]: string[]} = {
   gridAutoFlow: ['row', 'column', 'dense', 'row dense', 'column dense'],
 
   // TODO: make these link to MDN and also have baseSpacingValue type link
-  gridAutoRows:[...baseSpacingValues, 'auto', 'min-content', 'max-content', '${number}fr', 'minmax(${string}, ${string})', 'string'],
-  gridAutoColumns: [...baseSpacingValues, 'auto', 'min-content', 'max-content', '${number}fr', 'minmax(${string}, ${string})', 'string'],
-  gridTemplateColumns: [...baseSpacingValues, 'auto', 'min-content', 'max-content', '${number}fr', 'minmax(${string}, ${string})', 'none', 'subgrid', 'string',],
-  gridTemplateRows: [...baseSpacingValues, 'auto', 'min-content', 'max-content', '${number}fr', 'minmax(${string}, ${string})', 'none', 'subgrid', 'string'],
+  gridAutoRows:['auto', 'min-content', 'max-content', '${number}fr', 'minmax(${string}, ${string})', 'string'],
+  gridAutoColumns: ['auto', 'min-content', 'max-content', '${number}fr', 'minmax(${string}, ${string})', 'string'],
+  gridTemplateColumns: ['auto', 'min-content', 'max-content', '${number}fr', 'minmax(${string}, ${string})', 'none', 'subgrid', 'string',],
+  gridTemplateRows: ['auto', 'min-content', 'max-content', '${number}fr', 'minmax(${string}, ${string})', 'none', 'subgrid', 'string'],
   gridTemplateAreas: ['string[]'],
 
 
@@ -258,8 +279,6 @@ const layoutPropertyValues: {[key: string]: string[]} = {
   order: ['number'],
 };
 
-// TODO: some of these aren't interactions really? Will need to classify them later
-// Add this to the docs, the table is called misc
 const miscPropertyValues: {[key: string]: string[]} = {
   pointerEvents: ['none', 'auto'],
   touchAction: ['auto', 'none', 'pan-x', 'pan-y', 'manipulation', 'pinch-zoom'],
@@ -380,21 +399,37 @@ const properties: {[key: string]: {[key: string]: string[]}} = {
 // TODO: see if there are any others that we will need to add additional shared types for
 // this is less additional types and more that we want to represent the below as a type link
 export function getAdditionalTypes(propertyName: string): string[] {
+  let types: string[] = [];
+
   if (baseColorProperties.has(propertyName)) {
-    return ['baseColors'];
+    types.push('baseColors');
+  }
+
+  if (baseSpacingProperties.has(propertyName)) {
+    types.push('baseSpacing');
+  }
+
+  if (negativeSpacingProperties.has(propertyName)) {
+    types.push('negativeSpacing');
   }
 
   if (sizingProperties.has(propertyName)) {
-    return ['number', 'LengthPercentage'];
+    types.push('number', 'LengthPercentage');
   }
 
   if (percentageProperties.has(propertyName)) {
-    return ['LengthPercentage'];
+    types.push('LengthPercentage');
   }
 
-  return [];
+  return types;
 }
 
+// Export spacing values for use in TypePopover
+export const spacingTypeValues = {
+  baseSpacing: baseSpacingValues,
+  negativeSpacing: negativeBaseSpacingValues
+};
+
 interface StyleMacroPropertyDefinition {
   values: string[],
   additionalTypes?: string[]
diff --git a/packages/dev/s2-docs/src/types.tsx b/packages/dev/s2-docs/src/types.tsx
index 7f05bd7239c..88330e8492c 100644
--- a/packages/dev/s2-docs/src/types.tsx
+++ b/packages/dev/s2-docs/src/types.tsx
@@ -16,6 +16,7 @@ import {ColorLink, Link as SpectrumLink} from './Link';
 import {getDoc} from 'globals-docs';
 import Markdown from 'markdown-to-jsx';
 import React, {ReactNode} from 'react';
+import {spacingTypeValues} from './styleProperties';
 import {style} from '@react-spectrum/s2/style' with {type: 'macro'};
 import {Table, TableBody, TableCell, TableColumn, TableHeader, TableRow} from './Table';
 import {TypePopover} from './TypePopover';
@@ -695,6 +696,64 @@ function TemplateLiteral({elements}: TTemplate) {
   );
 }
 
+const styleMacroTypeLinks = {
+  'baseColors': {
+    // TODO: will need to have this link work somehow
+    description: 'A base set of colors defined by Spectrum. Contains a various global and semantic colors as well as high contrast color values for accessibility high contrast mode. See [above](#colors) for more info.'
+  },
+  'baseSpacing': {
+    description: 'Base spacing values in pixels, following a 4px grid. Will be converted to rem.',
+    body: (
+      <code className={codeStyle}>
+        {spacingTypeValues['baseSpacing'].map((val, idx) => (
+          <React.Fragment key={idx}>
+            {idx > 0 && <Punctuation>{' | '}</Punctuation>}
+            <span className={codeStyles.string}>'{val}'</span>
+          </React.Fragment>
+        ))}
+      </code>
+    )
+  },
+  'negativeSpacing': {
+    description: 'Negative spacing values in pixels, following a 4px grid. Will be converted to rem.',
+    body: (
+      <code className={codeStyle}>
+        {spacingTypeValues['negativeSpacing'].map((val, idx) => (
+          <React.Fragment key={idx}>
+            {idx > 0 && <Punctuation>{' | '}</Punctuation>}
+            <span className={codeStyles.string}>'{val}'</span>
+          </React.Fragment>
+        ))}
+      </code>
+    )
+  },
+  'LengthPercentage': {
+    description: <>A CSS length value with percentage or viewport units. e.g. <code className={codeStyle}>'50%'</code>, <code className={codeStyle}>'100vw'</code>, <code className={codeStyle}>'50vh'</code></>
+  },
+  'number': {
+    description: <>A numeric value in pixels e.g. <code className={codeStyle}>20</code>. Will be converted to rem and scaled on touch devices.</>
+  }
+}
+
+interface StyleMacroTypePopoverProps {
+  typeName: string,
+  description: ReactNode,
+  body?: ReactNode
+}
+
+function StyleMacroTypePopover({typeName, description, body}: StyleMacroTypePopoverProps) {
+  return (
+    <TypePopover name={typeName}>
+      <>
+        <p className={style({font: 'body'})}>
+          {description}
+        </p>
+        {body}
+      </>
+    </TypePopover>
+  )
+}
+
 interface StyleMacroPropertyDefinition {
   values: string[],
   additionalTypes?: string[]
@@ -738,24 +797,11 @@ export function StyleMacroProperties({properties}: StyleMacroPropertiesProps) {
                   ))}
                   {propDef.additionalTypes && propDef.additionalTypes.map((typeName, i) => (
                     <React.Fragment key={`type-${i}`}>
-                      <Punctuation>{' | '}</Punctuation>
-                      <TypePopover name={typeName}>
-                        {typeName === 'baseColors' && (
-                          <p className={style({font: 'body'})}>
-                            A base set of colors defined by Spectrum. See the global and semantic colors in the color reference above.
-                          </p>
-                        )}
-                        {typeName === 'LengthPercentage' && (
-                          <p className={style({font: 'body'})}>
-                            A CSS length value with percentage or viewport units. Examples: <code className={codeStyle}>'50%'</code>, <code className={codeStyle}>'100vw'</code>, <code className={codeStyle}>'50vh'</code>
-                          </p>
-                        )}
-                        {typeName === 'number' && (
-                          <p className={style({font: 'body'})}>
-                            A numeric value in pixels. Will be converted to rem and scaled on touch devices.
-                          </p>
-                        )}
-                      </TypePopover>
+                      {(values.length > 0 || i > 0) && <Punctuation>{' | '}</Punctuation>}
+                      {styleMacroTypeLinks[typeName] ?
+                        <StyleMacroTypePopover typeName={typeName} description={styleMacroTypeLinks[typeName].description} body={styleMacroTypeLinks[typeName].body} /> :
+                        undefined
+                      }
                     </React.Fragment>
                   ))}
                 </code>
@@ -767,3 +813,13 @@ export function StyleMacroProperties({properties}: StyleMacroPropertiesProps) {
     </Table>
   );
 }
+
+
+// TODO: for the below, will need to figure out how to get the same kind of mdx styling in the popover
+// TODO: for the baseColors, either link up or expose a type that displays the visual colors in the popover
+// for some reason trying to render the S2 colors example into the popover crashes the build?
+//  same for spacing, perhaps do the type that contains the same explaination, and remove the text blob
+// TODO: add to the table a description col span 2 to describe what things like aspectRatio and such accept (aka This takes a). this exists in the Prop table so look there
+
+// TODO: For the Shorthands, have a column for Name, value (what values it accepts), and mapping where mapping is what properties it maps to
+//

From 4c94cd08391634157fcb7dedcf7260afeea212a7 Mon Sep 17 00:00:00 2001
From: Daniel Lu <dl1644@gmail.com>
Date: Tue, 28 Oct 2025 17:25:22 -0700
Subject: [PATCH 10/27] add mdn links for common types and specific css
 properties

---
 packages/dev/s2-docs/src/styleProperties.ts | 99 ++++++++++++---------
 packages/dev/s2-docs/src/types.tsx          | 10 ++-
 2 files changed, 66 insertions(+), 43 deletions(-)

diff --git a/packages/dev/s2-docs/src/styleProperties.ts b/packages/dev/s2-docs/src/styleProperties.ts
index ac44d5326e8..a78a2c31a1e 100644
--- a/packages/dev/s2-docs/src/styleProperties.ts
+++ b/packages/dev/s2-docs/src/styleProperties.ts
@@ -133,14 +133,10 @@ const dimensionsPropertyValues: {[key: string]: string[]} = {
   textIndent: [],
   translateX: ['full'],
   translateY: ['full'],
-
-
-  // TODO These ones should have a description for the supported values, make a type link for number however
+  // TODO These ones should have a description for the supported values
   rotate: ['number', '${number}deg', '${number}rad', '${number}grad', '${number}turn'],
   scaleX: ['number', '${number}%'],
   scaleY: ['number', '${number}%'],
-
-
   transform: ['string'],
   position: ['absolute', 'fixed', 'relative', 'sticky', 'static'],
   insetStart: ['auto', 'full'],
@@ -149,8 +145,7 @@ const dimensionsPropertyValues: {[key: string]: string[]} = {
   left: ['auto', 'full'],
   bottom: ['auto', 'full'],
   right: ['auto', 'full'],
-
-  // TODO: also would like this number/number to be code formatted, not a string? Maybe make it a type link as well
+  // TODO: add description for this one
   aspectRatio: ['auto', 'square', 'video', 'number / number']
 };
 
@@ -166,7 +161,6 @@ const textPropertyValues: {[key: string]: string[]} = {
   verticalAlign: ['baseline', 'top', 'middle', 'bottom', 'text-top', 'text-bottom', 'sub', 'super'],
   textDecoration: ['none', 'underline', 'overline', 'line-through'],
   textOverflow: ['ellipsis', 'clip'],
-  // TODO: make common type link for number, link to mdn
   lineClamp: ['number'],
   hyphens: ['none', 'manual', 'auto'],
   whiteSpace: ['normal', 'nowrap', 'pre', 'pre-line', 'pre-wrap', 'break-spaces'],
@@ -186,7 +180,7 @@ const effectsPropertyValues: {[key: string]: string[]} = {
   borderBottomEndRadius: ['none', 'sm', 'default', 'lg', 'xl', 'full', 'pill'],
   forcedColorAdjust: ['auto', 'none'],
   colorScheme: ['light', 'dark', 'light dark'],
-  // TODO: ideally would be type links for string and LinearGradient, will need to decide if we wanna export LinearGradient
+  // TODO: ideally would be type for LinearGradient, will need to decide if we wanna export LinearGradient
   backgroundImage: ['string', 'LinearGradient'],
   backgroundPosition: ['bottom', 'center', 'left', 'left bottom', 'left top', 'right', 'right bottom', 'right top', 'top'],
   backgroundSize: ['auto', 'cover', 'contain'],
@@ -196,34 +190,20 @@ const effectsPropertyValues: {[key: string]: string[]} = {
   backgroundOrigin: ['border-box', 'padding-box', 'content-box'],
   backgroundBlendMode: ['normal', 'multiply', 'screen', 'overlay', 'darken', 'lighten', 'color-dodge', 'color-burn', 'hard-light', 'soft-light', 'difference', 'exclusion', 'hue', 'saturation', 'color', 'luminosity'],
   mixBlendMode: ['normal', 'multiply', 'screen', 'overlay', 'darken', 'lighten', 'color-dodge', 'color-burn', 'hard-light', 'soft-light', 'difference', 'exclusion', 'hue', 'saturation', 'color', 'luminosity', 'plus-darker', 'plus-lighter'],
-  // TODO: ideally would be a type link
   opacity: ['number'],
   outlineStyle: ['none', 'solid', 'dashed', 'dotted', 'double', 'inset'],
   outlineOffset: ['number'],
   outlineWidth: ['0', '1', '2', '4'],
   transition: ['default', 'colors', 'opacity', 'shadow', 'transform', 'all', 'none'],
-
-  // TODO: type link
   transitionDelay: ['string', 'number'],
   transitionDuration: ['string', 'number'],
-
   transitionTimingFunction: ['default', 'linear', 'in', 'out', 'in-out'],
-
-  // TODO: type link, maybe some of these type links should just be links to MDN?
-  // Could make it similar to getAdditionalTypes and have a links object that has the type (aka string | number) and then links it to MDN
   animation: ['string', 'number'],
   animationDuration: ['string', 'number'],
   animationDelay: ['string', 'number'],
-
-
-
   animationDirection: ['normal', 'reverse', 'alternate', 'alternate-reverse'],
   animationFillMode: ['none', 'forwards', 'backwards', 'both'],
-
-  // TODO: type link, see above
   animationIterationCount: ['string', 'number'],
-
-
   animationTimingFunction: ['default', 'linear', 'in', 'out', 'in-out'],
   animationPlayState: ['paused', 'running']
 };
@@ -238,17 +218,13 @@ const layoutPropertyValues: {[key: string]: string[]} = {
   justifySelf: ['auto', 'start', 'end', 'center', 'stretch'],
   flexDirection: ['row', 'column', 'row-reverse', 'column-reverse'],
   flexWrap: ['wrap', 'wrap-reverse', 'nowrap'],
-
-
-  // TODO: the below definitely link to MDN
-  // flexShrink: new ArbitraryProperty<CSS.Property.FlexShrink>('flexShrink'),
-  // flexGrow: new ArbitraryProperty<CSS.Property.FlexGrow>('flexGrow'),
-  // gridColumnStart: new ArbitraryProperty<CSS.Property.GridColumnStart>('gridColumnStart'),
-  // gridColumnEnd: new ArbitraryProperty<CSS.Property.GridColumnEnd>('gridColumnEnd'),
-  // gridRowStart: new ArbitraryProperty<CSS.Property.GridRowStart>('gridRowStart'),
-  // gridRowEnd: new ArbitraryProperty<CSS.Property.GridRowEnd>('gridRowEnd'),
-
-
+  // these will be handled via specific links
+  flexShrink: [],
+  flexGrow: [],
+  gridColumnStart: [],
+  gridColumnEnd: [],
+  gridRowStart: [],
+  gridRowEnd: [],
   gridAutoFlow: ['row', 'column', 'dense', 'row dense', 'column dense'],
 
   // TODO: make these link to MDN and also have baseSpacingValue type link
@@ -258,7 +234,6 @@ const layoutPropertyValues: {[key: string]: string[]} = {
   gridTemplateRows: ['auto', 'min-content', 'max-content', '${number}fr', 'minmax(${string}, ${string})', 'none', 'subgrid', 'string'],
   gridTemplateAreas: ['string[]'],
 
-
   float: ['inline-start', 'inline-end', 'right', 'left', 'none'],
   clear: ['inline-start', 'inline-end', 'left', 'right', 'both', 'none'],
   contain: ['none', 'strict', 'content', 'size', 'inline-size', 'layout', 'style', 'paint'],
@@ -274,8 +249,6 @@ const layoutPropertyValues: {[key: string]: string[]} = {
   overscrollBehaviorX: ['auto', 'contain', 'none'],
   overscrollBehaviorY: ['auto', 'contain', 'none'],
   scrollBehavior: ['auto', 'smooth'],
-
-  // TODO: make type link
   order: ['number'],
 };
 
@@ -295,7 +268,6 @@ const miscPropertyValues: {[key: string]: string[]} = {
   objectFit: ['contain', 'cover', 'fill', 'none', 'scale-down'],
   objectPosition: ['bottom', 'center', 'left', 'left bottom', 'left top', 'right', 'right bottom', 'right top', 'top'],
   willChange: ['auto', 'scroll-position', 'contents', 'transform'],
-  // TODO: need type link
   zIndex: ['number'],
   disableTapHighlight: ['true'],
   unicodeBidi: ['normal', 'embed', 'bidi-override', 'isolate', 'isolate-override', 'plaintext'],
@@ -424,15 +396,41 @@ export function getAdditionalTypes(propertyName: string): string[] {
   return types;
 }
 
-// Export spacing values for use in TypePopover
 export const spacingTypeValues = {
   baseSpacing: baseSpacingValues,
   negativeSpacing: negativeBaseSpacingValues
 };
 
+const mdnTypeLinks: {[key: string]: string} = {
+  'string': 'https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String',
+  'number': 'https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number',
+};
+
+const mdnPropertyLinks: {[key: string]: {[value: string]: string}} = {
+  'flexShrink': {
+    'number': 'https://developer.mozilla.org/en-US/docs/Web/CSS/flex-shrink'
+  },
+  'flexGrow': {
+    'number': 'https://developer.mozilla.org/en-US/docs/Web/CSS/flex-grow'
+  },
+  'gridColumnStart': {
+    'string': 'https://developer.mozilla.org/en-US/docs/Web/CSS/grid-column-start'
+  },
+  'gridColumnEnd': {
+    'string': 'https://developer.mozilla.org/en-US/docs/Web/CSS/grid-column-end'
+  },
+  'gridRowStart': {
+    'string': 'https://developer.mozilla.org/en-US/docs/Web/CSS/grid-row-start'
+  },
+  'gridRowEnd': {
+    'string': 'https://developer.mozilla.org/en-US/docs/Web/CSS/grid-row-end'
+  }
+};
+
 interface StyleMacroPropertyDefinition {
   values: string[],
-  additionalTypes?: string[]
+  additionalTypes?: string[],
+  links?: {[value: string]: string}
 }
 
 export function getPropertyDefinitions(propertyCategory: string): {[key: string]: StyleMacroPropertyDefinition} {
@@ -440,9 +438,28 @@ export function getPropertyDefinitions(propertyCategory: string): {[key: string]
   let propertiesMapping = properties[propertyCategory] || {};
 
   for (let [name, values] of Object.entries(propertiesMapping)) {
+    let links: {[value: string]: string} = {};
+
+    if (mdnPropertyLinks[name]) {
+      links = {...mdnPropertyLinks[name]};
+      values = [Object.keys(links)[0]];
+    } else {
+      // see if the property has any common types that should link to MDN instead
+      for (let value of values) {
+        if (mdnTypeLinks[value]) {
+          // make sure not to overwrite number in sizing properties
+          if (value === 'number' && sizingProperties.has(name)) {
+            continue;
+          }
+          links[value] = mdnTypeLinks[value];
+        }
+      }
+    }
+
     result[name] = {
       values,
-      additionalTypes: getAdditionalTypes(name)
+      additionalTypes: getAdditionalTypes(name),
+      links: Object.keys(links).length > 0 ? links : undefined
     };
   }
   return result;
diff --git a/packages/dev/s2-docs/src/types.tsx b/packages/dev/s2-docs/src/types.tsx
index 88330e8492c..2c394e0b277 100644
--- a/packages/dev/s2-docs/src/types.tsx
+++ b/packages/dev/s2-docs/src/types.tsx
@@ -756,7 +756,8 @@ function StyleMacroTypePopover({typeName, description, body}: StyleMacroTypePopo
 
 interface StyleMacroPropertyDefinition {
   values: string[],
-  additionalTypes?: string[]
+  additionalTypes?: string[],
+  links?: {[value: string]: string}
 }
 
 interface StyleMacroPropertiesProps {
@@ -779,6 +780,7 @@ export function StyleMacroProperties({properties}: StyleMacroPropertiesProps) {
         {propertyNames.map((propertyName, index) => {
           let propDef = properties[propertyName];
           let values = propDef.values;
+          let links = propDef.links || {};
 
           return (
             <TableRow key={index}>
@@ -792,7 +794,11 @@ export function StyleMacroProperties({properties}: StyleMacroPropertiesProps) {
                   {values.map((value, i) => (
                     <React.Fragment key={i}>
                       {i > 0 && <Punctuation>{' | '}</Punctuation>}
-                      <span className={codeStyles.string}>'{value}'</span>
+                      {links[value] ? (
+                        <ColorLink href={links[value]} type="variable" rel="noreferrer" target="_blank">{value}</ColorLink>
+                      ) : (
+                        <span className={codeStyles.string}>'{value}'</span>
+                      )}
                     </React.Fragment>
                   ))}
                   {propDef.additionalTypes && propDef.additionalTypes.map((typeName, i) => (

From 83262eff3c03a7ee93bff4cc477aad9e1548feb8 Mon Sep 17 00:00:00 2001
From: Daniel Lu <dl1644@gmail.com>
Date: Wed, 29 Oct 2025 16:44:40 -0700
Subject: [PATCH 11/27] add relative links so basecolors and various dimension
 strings link back to the visual

---
 packages/dev/s2-docs/src/styleProperties.ts | 78 +++++++++++++--------
 packages/dev/s2-docs/src/types.tsx          | 50 +++++++------
 2 files changed, 77 insertions(+), 51 deletions(-)

diff --git a/packages/dev/s2-docs/src/styleProperties.ts b/packages/dev/s2-docs/src/styleProperties.ts
index a78a2c31a1e..21c8ee7d44f 100644
--- a/packages/dev/s2-docs/src/styleProperties.ts
+++ b/packages/dev/s2-docs/src/styleProperties.ts
@@ -10,11 +10,6 @@
  * governing permissions and limitations under the License.
  */
 
-// Properties that extend from baseColors
-const baseColorProperties = new Set([
-  'color', 'backgroundColor', 'borderColor', 'outlineColor', 'fill', 'stroke'
-]);
-
 // Properties that use PercentageProperty (accept LengthPercentage in addition to mapped values)
 const percentageProperties = new Set([
   'top', 'left', 'bottom', 'right',
@@ -67,7 +62,7 @@ const fontSize = [
 ];
 
 const colorPropertyValues: {[key: string]: string[]} = {
-  color: ['accent', 'neutral', 'neutral-subdued', 'negative', 'disabled', 'heading', 'title', 'body', 'detail', 'code', 'auto'],
+  color: ['accent', 'neutral', 'neutral-subdued', 'negative', 'disabled', 'heading', 'title', 'body', 'detail', 'code', 'auto', 'baseColors'],
   backgroundColor: [
     'accent', 'accent-subtle', 'neutral', 'neutral-subdued', 'neutral-subtle',
     'negative', 'negative-subtle', 'informative', 'informative-subtle',
@@ -81,18 +76,18 @@ const colorPropertyValues: {[key: string]: string[]} = {
     'magenta', 'magenta-subtle', 'pink', 'pink-subtle',
     'turquoise', 'turquoise-subtle', 'cinnamon', 'cinnamon-subtle',
     'brown', 'brown-subtle', 'silver', 'silver-subtle',
-    'disabled', 'base', 'layer-1', 'layer-2', 'pasteboard', 'elevated'
+    'disabled', 'base', 'layer-1', 'layer-2', 'pasteboard', 'elevated', 'baseColors'
   ],
-  borderColor: ['negative', 'disabled'],
-  outlineColor: ['focus-ring'],
+  borderColor: ['negative', 'disabled', 'baseColors'],
+  outlineColor: ['focus-ring', 'baseColors'],
   fill: [
     'none', 'currentColor',
     'accent', 'neutral', 'negative', 'informative', 'positive', 'notice',
     'gray', 'red', 'orange', 'yellow', 'chartreuse', 'celery', 'green',
     'seafoam', 'cyan', 'blue', 'indigo', 'purple', 'fuchsia', 'magenta',
-    'pink', 'turquoise', 'cinnamon', 'brown', 'silver'
+    'pink', 'turquoise', 'cinnamon', 'brown', 'silver', 'baseColors'
   ],
-  stroke: ['none', 'currentColor']
+  stroke: ['none', 'currentColor', 'baseColors']
 };
 
 const dimensionsPropertyValues: {[key: string]: string[]} = {
@@ -170,7 +165,6 @@ const textPropertyValues: {[key: string]: string[]} = {
   boxDecorationBreak: ['slice', 'clone']
 };
 
-
 const effectsPropertyValues: {[key: string]: string[]} = {
   boxShadow: ['emphasized', 'elevated', 'dragged', 'none'],
   filter: ['emphasized', 'elevated', 'dragged', 'none'],
@@ -370,13 +364,10 @@ const properties: {[key: string]: {[key: string]: string[]}} = {
 // TODO: will we need something specific for short hand?
 // TODO: see if there are any others that we will need to add additional shared types for
 // this is less additional types and more that we want to represent the below as a type link
+// special custom types that should be appended to the property but need special handling (render a type popover)
 export function getAdditionalTypes(propertyName: string): string[] {
   let types: string[] = [];
 
-  if (baseColorProperties.has(propertyName)) {
-    types.push('baseColors');
-  }
-
   if (baseSpacingProperties.has(propertyName)) {
     types.push('baseSpacing');
   }
@@ -401,36 +392,58 @@ export const spacingTypeValues = {
   negativeSpacing: negativeBaseSpacingValues
 };
 
+// opted NOT to link to Fonts from 'ui', 'code', etc since the visual example
+// is so close to the area in the table where those are rendered
+const relativeLinks: {[key: string]: string} = {
+  'text-to-control': '#dimensions',
+  'text-to-visual': '#dimensions',
+  'edge-to-text': '#dimensions',
+  'pill': '#dimensions',
+  'baseColors': '#colors'
+}
+
 const mdnTypeLinks: {[key: string]: string} = {
   'string': 'https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String',
-  'number': 'https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number',
+  'number': 'https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number'
 };
 
-const mdnPropertyLinks: {[key: string]: {[value: string]: string}} = {
+const mdnPropertyLinks: {[key: string]: {[value: string]: {href: string, isRelative?: boolean}}} = {
   'flexShrink': {
-    'number': 'https://developer.mozilla.org/en-US/docs/Web/CSS/flex-shrink'
+    'number': {
+      href: 'https://developer.mozilla.org/en-US/docs/Web/CSS/flex-shrink',
+    }
   },
   'flexGrow': {
-    'number': 'https://developer.mozilla.org/en-US/docs/Web/CSS/flex-grow'
+    'number': {
+      href: 'https://developer.mozilla.org/en-US/docs/Web/CSS/flex-grow'
+    }
   },
   'gridColumnStart': {
-    'string': 'https://developer.mozilla.org/en-US/docs/Web/CSS/grid-column-start'
+    'string': {
+      href: 'https://developer.mozilla.org/en-US/docs/Web/CSS/grid-column-start'
+    }
   },
   'gridColumnEnd': {
-    'string': 'https://developer.mozilla.org/en-US/docs/Web/CSS/grid-column-end'
+    'string': {
+      href: 'https://developer.mozilla.org/en-US/docs/Web/CSS/grid-column-end'
+    }
   },
   'gridRowStart': {
-    'string': 'https://developer.mozilla.org/en-US/docs/Web/CSS/grid-row-start'
+    'string': {
+      href: 'https://developer.mozilla.org/en-US/docs/Web/CSS/grid-row-start'
+    }
   },
   'gridRowEnd': {
-    'string': 'https://developer.mozilla.org/en-US/docs/Web/CSS/grid-row-end'
+    'string': {
+      href: 'https://developer.mozilla.org/en-US/docs/Web/CSS/grid-row-end'
+    }
   }
 };
 
 interface StyleMacroPropertyDefinition {
   values: string[],
   additionalTypes?: string[],
-  links?: {[value: string]: string}
+  links?: {[value: string]: {href: string, isRelative?: boolean}}
 }
 
 export function getPropertyDefinitions(propertyCategory: string): {[key: string]: StyleMacroPropertyDefinition} {
@@ -438,7 +451,7 @@ export function getPropertyDefinitions(propertyCategory: string): {[key: string]
   let propertiesMapping = properties[propertyCategory] || {};
 
   for (let [name, values] of Object.entries(propertiesMapping)) {
-    let links: {[value: string]: string} = {};
+    let links: {[value: string]: {href: string, isRelative?: boolean}} = {};
 
     if (mdnPropertyLinks[name]) {
       links = {...mdnPropertyLinks[name]};
@@ -446,12 +459,15 @@ export function getPropertyDefinitions(propertyCategory: string): {[key: string]
     } else {
       // see if the property has any common types that should link to MDN instead
       for (let value of values) {
+        // make sure not to overwrite number in sizing properties and pill in other sections aka effects
+        if ((value === 'number' && sizingProperties.has(name)) || (value === 'pill' && propertyCategory !== 'dimensions') ) {
+          continue;
+        }
+
         if (mdnTypeLinks[value]) {
-          // make sure not to overwrite number in sizing properties
-          if (value === 'number' && sizingProperties.has(name)) {
-            continue;
-          }
-          links[value] = mdnTypeLinks[value];
+          links[value] = {href: mdnTypeLinks[value]};
+        } else if (relativeLinks[value]) {
+          links[value] = {href: relativeLinks[value], isRelative: true};
         }
       }
     }
diff --git a/packages/dev/s2-docs/src/types.tsx b/packages/dev/s2-docs/src/types.tsx
index 2c394e0b277..0071a796ed5 100644
--- a/packages/dev/s2-docs/src/types.tsx
+++ b/packages/dev/s2-docs/src/types.tsx
@@ -697,10 +697,6 @@ function TemplateLiteral({elements}: TTemplate) {
 }
 
 const styleMacroTypeLinks = {
-  'baseColors': {
-    // TODO: will need to have this link work somehow
-    description: 'A base set of colors defined by Spectrum. Contains a various global and semantic colors as well as high contrast color values for accessibility high contrast mode. See [above](#colors) for more info.'
-  },
   'baseSpacing': {
     description: 'Base spacing values in pixels, following a 4px grid. Will be converted to rem.',
     body: (
@@ -738,7 +734,8 @@ const styleMacroTypeLinks = {
 interface StyleMacroTypePopoverProps {
   typeName: string,
   description: ReactNode,
-  body?: ReactNode
+  body?: ReactNode,
+  link?: string
 }
 
 function StyleMacroTypePopover({typeName, description, body}: StyleMacroTypePopoverProps) {
@@ -757,7 +754,7 @@ function StyleMacroTypePopover({typeName, description, body}: StyleMacroTypePopo
 interface StyleMacroPropertyDefinition {
   values: string[],
   additionalTypes?: string[],
-  links?: {[value: string]: string}
+  links?: {[value: string]: {href: string, isRelative?: boolean}}
 }
 
 interface StyleMacroPropertiesProps {
@@ -795,21 +792,38 @@ export function StyleMacroProperties({properties}: StyleMacroPropertiesProps) {
                     <React.Fragment key={i}>
                       {i > 0 && <Punctuation>{' | '}</Punctuation>}
                       {links[value] ? (
-                        <ColorLink href={links[value]} type="variable" rel="noreferrer" target="_blank">{value}</ColorLink>
+                        <ColorLink
+                          href={links[value].href}
+                          type="variable"
+                          rel={links[value].isRelative ? undefined : "noreferrer"}
+                          target={links[value].isRelative ? undefined : "_blank"}>
+                          {value}
+                        </ColorLink>
                       ) : (
                         <span className={codeStyles.string}>'{value}'</span>
                       )}
                     </React.Fragment>
                   ))}
-                  {propDef.additionalTypes && propDef.additionalTypes.map((typeName, i) => (
-                    <React.Fragment key={`type-${i}`}>
-                      {(values.length > 0 || i > 0) && <Punctuation>{' | '}</Punctuation>}
-                      {styleMacroTypeLinks[typeName] ?
-                        <StyleMacroTypePopover typeName={typeName} description={styleMacroTypeLinks[typeName].description} body={styleMacroTypeLinks[typeName].body} /> :
-                        undefined
-                      }
-                    </React.Fragment>
-                  ))}
+                  {propDef.additionalTypes && propDef.additionalTypes.map((typeName, i) => {
+                    let typeLink = styleMacroTypeLinks[typeName];
+                    return (
+                      <React.Fragment key={`type-${i}`}>
+                        {(values.length > 0 || i > 0) && <Punctuation>{' | '}</Punctuation>}
+                        {typeLink ? (
+                          // only if the type link has a description and/or body do we want to render the type popover
+                          // this is to make things like baseColor
+                          typeLink.link && !typeLink.description && !typeLink.body ? (
+                            <ColorLink href={typeLink.link} type="variable">{typeName}</ColorLink>
+                          ) : (
+                            <StyleMacroTypePopover
+                              typeName={typeName}
+                              description={typeLink.description}
+                              body={typeLink.body} />
+                          )
+                        ) : undefined}
+                      </React.Fragment>
+                    );
+                  })}
                 </code>
               </TableCell>
             </TableRow>
@@ -820,10 +834,6 @@ export function StyleMacroProperties({properties}: StyleMacroPropertiesProps) {
   );
 }
 
-
-// TODO: for the below, will need to figure out how to get the same kind of mdx styling in the popover
-// TODO: for the baseColors, either link up or expose a type that displays the visual colors in the popover
-// for some reason trying to render the S2 colors example into the popover crashes the build?
 //  same for spacing, perhaps do the type that contains the same explaination, and remove the text blob
 // TODO: add to the table a description col span 2 to describe what things like aspectRatio and such accept (aka This takes a). this exists in the Prop table so look there
 

From 5d2b172b4287619af199a3a40eafd15e7b74c7d1 Mon Sep 17 00:00:00 2001
From: Daniel Lu <dl1644@gmail.com>
Date: Wed, 29 Oct 2025 17:16:04 -0700
Subject: [PATCH 12/27] add descriptions to table and get rid of unessasary
 isRelative

---
 packages/dev/s2-docs/pages/s2/Reference.mdx |   2 -
 packages/dev/s2-docs/src/styleProperties.ts |  47 ++++-----
 packages/dev/s2-docs/src/types.tsx          | 107 ++++++++++----------
 3 files changed, 79 insertions(+), 77 deletions(-)

diff --git a/packages/dev/s2-docs/pages/s2/Reference.mdx b/packages/dev/s2-docs/pages/s2/Reference.mdx
index 6c312c3caa0..283d8ebb724 100644
--- a/packages/dev/s2-docs/pages/s2/Reference.mdx
+++ b/packages/dev/s2-docs/pages/s2/Reference.mdx
@@ -37,8 +37,6 @@ Size props like `width` and `height` accept arbitrary pixel values. Values are c
 
 ## Text
 
-// TODO: edit copy
-
 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
diff --git a/packages/dev/s2-docs/src/styleProperties.ts b/packages/dev/s2-docs/src/styleProperties.ts
index 21c8ee7d44f..b307eeb0fa3 100644
--- a/packages/dev/s2-docs/src/styleProperties.ts
+++ b/packages/dev/s2-docs/src/styleProperties.ts
@@ -392,6 +392,7 @@ export const spacingTypeValues = {
   negativeSpacing: negativeBaseSpacingValues
 };
 
+// a mapping of value to relative links that should be replaced in place
 // opted NOT to link to Fonts from 'ui', 'code', etc since the visual example
 // is so close to the area in the table where those are rendered
 const relativeLinks: {[key: string]: string} = {
@@ -402,48 +403,46 @@ const relativeLinks: {[key: string]: string} = {
   'baseColors': '#colors'
 }
 
+// a mapping of value to mdn links that should be replaced in place
 const mdnTypeLinks: {[key: string]: string} = {
   'string': 'https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String',
   'number': 'https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number'
 };
 
-const mdnPropertyLinks: {[key: string]: {[value: string]: {href: string, isRelative?: boolean}}} = {
+// a mapping of value to links that should be replaced in place with the provided string
+const mdnPropertyLinks: {[key: string]: {[value: string]: string}} = {
   'flexShrink': {
-    'number': {
-      href: 'https://developer.mozilla.org/en-US/docs/Web/CSS/flex-shrink',
-    }
+    'number':  'https://developer.mozilla.org/en-US/docs/Web/CSS/flex-shrink'
   },
   'flexGrow': {
-    'number': {
-      href: 'https://developer.mozilla.org/en-US/docs/Web/CSS/flex-grow'
-    }
+    'number': 'https://developer.mozilla.org/en-US/docs/Web/CSS/flex-grow'
   },
   'gridColumnStart': {
-    'string': {
-      href: 'https://developer.mozilla.org/en-US/docs/Web/CSS/grid-column-start'
-    }
+    'string': 'https://developer.mozilla.org/en-US/docs/Web/CSS/grid-column-start'
   },
   'gridColumnEnd': {
-    'string': {
-      href: 'https://developer.mozilla.org/en-US/docs/Web/CSS/grid-column-end'
-    }
+    'string': 'https://developer.mozilla.org/en-US/docs/Web/CSS/grid-column-end'
   },
   'gridRowStart': {
-    'string': {
-      href: 'https://developer.mozilla.org/en-US/docs/Web/CSS/grid-row-start'
-    }
+    'string': 'https://developer.mozilla.org/en-US/docs/Web/CSS/grid-row-start'
   },
   'gridRowEnd': {
-    'string': {
-      href: 'https://developer.mozilla.org/en-US/docs/Web/CSS/grid-row-end'
-    }
+    'string': 'https://developer.mozilla.org/en-US/docs/Web/CSS/grid-row-end'
   }
 };
 
+const propertyDescriptions: {[key: string]: string} = {
+  'rotate': 'Accepts a number (treated as degrees) or a string with units (deg, rad, grad, turn).',
+  'scaleX': 'Accepts a number or percentage string.',
+  'scaleY': 'Accepts a number or percentage string.',
+  'aspectRatio': 'Also accepts a ratio in the format number/number (e.g., 16/9, 4/3).'
+};
+
 interface StyleMacroPropertyDefinition {
   values: string[],
   additionalTypes?: string[],
-  links?: {[value: string]: {href: string, isRelative?: boolean}}
+  links?: {[value: string]: {href: string, isRelative?: boolean}},
+  description?: string
 }
 
 export function getPropertyDefinitions(propertyCategory: string): {[key: string]: StyleMacroPropertyDefinition} {
@@ -454,8 +453,9 @@ export function getPropertyDefinitions(propertyCategory: string): {[key: string]
     let links: {[value: string]: {href: string, isRelative?: boolean}} = {};
 
     if (mdnPropertyLinks[name]) {
-      links = {...mdnPropertyLinks[name]};
-      values = [Object.keys(links)[0]];
+      let [key, value] = Object.entries(mdnPropertyLinks[name])[0];
+      links[key] = {href: value};
+      values = [key];
     } else {
       // see if the property has any common types that should link to MDN instead
       for (let value of values) {
@@ -475,7 +475,8 @@ export function getPropertyDefinitions(propertyCategory: string): {[key: string]
     result[name] = {
       values,
       additionalTypes: getAdditionalTypes(name),
-      links: Object.keys(links).length > 0 ? links : undefined
+      links: Object.keys(links).length > 0 ? links : undefined,
+      description: propertyDescriptions[name]
     };
   }
   return result;
diff --git a/packages/dev/s2-docs/src/types.tsx b/packages/dev/s2-docs/src/types.tsx
index 0071a796ed5..be59df53216 100644
--- a/packages/dev/s2-docs/src/types.tsx
+++ b/packages/dev/s2-docs/src/types.tsx
@@ -754,14 +754,14 @@ function StyleMacroTypePopover({typeName, description, body}: StyleMacroTypePopo
 interface StyleMacroPropertyDefinition {
   values: string[],
   additionalTypes?: string[],
-  links?: {[value: string]: {href: string, isRelative?: boolean}}
+  links?: {[value: string]: {href: string, isRelative?: boolean}},
+  description?: string
 }
 
 interface StyleMacroPropertiesProps {
   properties: {[propertyName: string]: StyleMacroPropertyDefinition}
 }
 
-// TODO: fix the width of the columns so that they are consistent
 export function StyleMacroProperties({properties}: StyleMacroPropertiesProps) {
   let propertyNames = Object.keys(properties);
 
@@ -780,53 +780,60 @@ export function StyleMacroProperties({properties}: StyleMacroPropertiesProps) {
           let links = propDef.links || {};
 
           return (
-            <TableRow key={index}>
-              <TableCell role="rowheader">
-                <code className={codeStyle}>
-                  <span className={codeStyles.attribute}>{propertyName}</span>
-                </code>
-              </TableCell>
-              <TableCell>
-                <code className={codeStyle}>
-                  {values.map((value, i) => (
-                    <React.Fragment key={i}>
-                      {i > 0 && <Punctuation>{' | '}</Punctuation>}
-                      {links[value] ? (
-                        <ColorLink
-                          href={links[value].href}
-                          type="variable"
-                          rel={links[value].isRelative ? undefined : "noreferrer"}
-                          target={links[value].isRelative ? undefined : "_blank"}>
-                          {value}
-                        </ColorLink>
-                      ) : (
-                        <span className={codeStyles.string}>'{value}'</span>
-                      )}
-                    </React.Fragment>
-                  ))}
-                  {propDef.additionalTypes && propDef.additionalTypes.map((typeName, i) => {
-                    let typeLink = styleMacroTypeLinks[typeName];
-                    return (
-                      <React.Fragment key={`type-${i}`}>
-                        {(values.length > 0 || i > 0) && <Punctuation>{' | '}</Punctuation>}
-                        {typeLink ? (
-                          // only if the type link has a description and/or body do we want to render the type popover
-                          // this is to make things like baseColor
-                          typeLink.link && !typeLink.description && !typeLink.body ? (
-                            <ColorLink href={typeLink.link} type="variable">{typeName}</ColorLink>
-                          ) : (
-                            <StyleMacroTypePopover
-                              typeName={typeName}
-                              description={typeLink.description}
-                              body={typeLink.body} />
-                          )
-                        ) : undefined}
+            <React.Fragment key={index}>
+              <TableRow>
+                <TableCell role="rowheader" hideBorder={!!propDef.description}>
+                  <code className={codeStyle}>
+                    <span className={codeStyles.attribute}>{propertyName}</span>
+                  </code>
+                </TableCell>
+                <TableCell hideBorder={!!propDef.description}>
+                  <code className={codeStyle}>
+                    {values.map((value, i) => (
+                      <React.Fragment key={i}>
+                        {i > 0 && <Punctuation>{' | '}</Punctuation>}
+                        {links[value] ? (
+                          <ColorLink
+                            href={links[value].href}
+                            type="variable"
+                            rel={links[value].isRelative ? undefined : "noreferrer"}
+                            target={links[value].isRelative ? undefined : "_blank"}>
+                            {value}
+                          </ColorLink>
+                        ) : (
+                          <span className={codeStyles.string}>'{value}'</span>
+                        )}
                       </React.Fragment>
-                    );
-                  })}
-                </code>
-              </TableCell>
-            </TableRow>
+                    ))}
+                    {propDef.additionalTypes && propDef.additionalTypes.map((typeName, i) => {
+                      let typeLink = styleMacroTypeLinks[typeName];
+                      return (
+                        <React.Fragment key={`type-${i}`}>
+                          {(values.length > 0 || i > 0) && <Punctuation>{' | '}</Punctuation>}
+                          {typeLink ? (
+                            // only if the type link has a description and/or body do we want to render the type popover
+                            // this is to make things like baseColor
+                            typeLink.link && !typeLink.description && !typeLink.body ? (
+                              <ColorLink href={typeLink.link} type="variable">{typeName}</ColorLink>
+                            ) : (
+                              <StyleMacroTypePopover
+                                typeName={typeName}
+                                description={typeLink.description}
+                                body={typeLink.body} />
+                            )
+                          ) : undefined}
+                        </React.Fragment>
+                      );
+                    })}
+                  </code>
+                </TableCell>
+              </TableRow>
+              {propDef.description && (
+                <TableRow>
+                  <TableCell colSpan={2}>{propDef.description}</TableCell>
+                </TableRow>
+              )}
+            </React.Fragment>
           );
         })}
       </TableBody>
@@ -834,8 +841,4 @@ export function StyleMacroProperties({properties}: StyleMacroPropertiesProps) {
   );
 }
 
-//  same for spacing, perhaps do the type that contains the same explaination, and remove the text blob
-// TODO: add to the table a description col span 2 to describe what things like aspectRatio and such accept (aka This takes a). this exists in the Prop table so look there
-
 // TODO: For the Shorthands, have a column for Name, value (what values it accepts), and mapping where mapping is what properties it maps to
-//

From 980d3d62fff63b758c4ecf2151456448a20a95b6 Mon Sep 17 00:00:00 2001
From: Daniel Lu <dl1644@gmail.com>
Date: Thu, 30 Oct 2025 12:03:18 -0700
Subject: [PATCH 13/27] add short hand and condition tables

---
 packages/dev/s2-docs/pages/s2/Reference.mdx |   7 +-
 packages/dev/s2-docs/src/styleProperties.ts | 283 ++++++++++++++------
 packages/dev/s2-docs/src/types.tsx          |  21 +-
 3 files changed, 225 insertions(+), 86 deletions(-)

diff --git a/packages/dev/s2-docs/pages/s2/Reference.mdx b/packages/dev/s2-docs/pages/s2/Reference.mdx
index 283d8ebb724..5d23ce5fbd6 100644
--- a/packages/dev/s2-docs/pages/s2/Reference.mdx
+++ b/packages/dev/s2-docs/pages/s2/Reference.mdx
@@ -3,7 +3,7 @@ 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} from '../../src/styleProperties';
+import {getPropertyDefinitions, getShorthandDefinitions} from '../../src/styleProperties';
 export default Layout;
 
 export const section = 'Guides';
@@ -71,5 +71,10 @@ Type scales include: UI, Body, Heading, Title, Detail, and Code. Each scale has
 
 ## Shorthands
 
+Shorthands apply their provided value to commonly grouped properties.
+
+<StyleMacroProperties properties={getShorthandDefinitions('shorthand')} />
 
 ## Conditions
+
+<StyleMacroProperties properties={getPropertyDefinitions('conditions')} />
diff --git a/packages/dev/s2-docs/src/styleProperties.ts b/packages/dev/s2-docs/src/styleProperties.ts
index b307eeb0fa3..98b94ba7fec 100644
--- a/packages/dev/s2-docs/src/styleProperties.ts
+++ b/packages/dev/s2-docs/src/styleProperties.ts
@@ -128,7 +128,6 @@ const dimensionsPropertyValues: {[key: string]: string[]} = {
   textIndent: [],
   translateX: ['full'],
   translateY: ['full'],
-  // TODO These ones should have a description for the supported values
   rotate: ['number', '${number}deg', '${number}rad', '${number}grad', '${number}turn'],
   scaleX: ['number', '${number}%'],
   scaleY: ['number', '${number}%'],
@@ -140,7 +139,6 @@ const dimensionsPropertyValues: {[key: string]: string[]} = {
   left: ['auto', 'full'],
   bottom: ['auto', 'full'],
   right: ['auto', 'full'],
-  // TODO: add description for this one
   aspectRatio: ['auto', 'square', 'video', 'number / number']
 };
 
@@ -192,7 +190,7 @@ const effectsPropertyValues: {[key: string]: string[]} = {
   transitionDelay: ['string', 'number'],
   transitionDuration: ['string', 'number'],
   transitionTimingFunction: ['default', 'linear', 'in', 'out', 'in-out'],
-  animation: ['string', 'number'],
+  animation: ['string'],
   animationDuration: ['string', 'number'],
   animationDelay: ['string', 'number'],
   animationDirection: ['normal', 'reverse', 'alternate', 'alternate-reverse'],
@@ -220,14 +218,11 @@ const layoutPropertyValues: {[key: string]: string[]} = {
   gridRowStart: [],
   gridRowEnd: [],
   gridAutoFlow: ['row', 'column', 'dense', 'row dense', 'column dense'],
-
-  // TODO: make these link to MDN and also have baseSpacingValue type link
   gridAutoRows:['auto', 'min-content', 'max-content', '${number}fr', 'minmax(${string}, ${string})', 'string'],
   gridAutoColumns: ['auto', 'min-content', 'max-content', '${number}fr', 'minmax(${string}, ${string})', 'string'],
   gridTemplateColumns: ['auto', 'min-content', 'max-content', '${number}fr', 'minmax(${string}, ${string})', 'none', 'subgrid', 'string',],
   gridTemplateRows: ['auto', 'min-content', 'max-content', '${number}fr', 'minmax(${string}, ${string})', 'none', 'subgrid', 'string'],
   gridTemplateAreas: ['string[]'],
-
   float: ['inline-start', 'inline-end', 'right', 'left', 'none'],
   clear: ['inline-start', 'inline-end', 'left', 'right', 'both', 'none'],
   contain: ['none', 'strict', 'content', 'size', 'inline-size', 'layout', 'style', 'paint'],
@@ -268,78 +263,163 @@ const miscPropertyValues: {[key: string]: string[]} = {
   caretColor: ['auto', 'transparent']
 };
 
-
-// TODO add shorthand mapping and conditions to the docs
-const shorthandMapping: {[key: string]: string[]} = {
-  padding: ['paddingTop', 'paddingBottom', 'paddingStart', 'paddingEnd'],
-  paddingX: ['paddingStart', 'paddingEnd'],
-  paddingY: ['paddingTop', 'paddingBottom'],
-  margin: ['marginTop', 'marginBottom', 'marginStart', 'marginEnd'],
-  marginX: ['marginStart', 'marginEnd'],
-  marginY: ['marginTop', 'marginBottom'],
-  scrollPadding: ['scrollPaddingTop', 'scrollPaddingBottom', 'scrollPaddingStart', 'scrollPaddingEnd'],
-  scrollPaddingX: ['scrollPaddingStart', 'scrollPaddingEnd'],
-  scrollPaddingY: ['scrollPaddingTop', 'scrollPaddingBottom'],
-  scrollMargin: ['scrollMarginTop', 'scrollMarginBottom', 'scrollMarginStart', 'scrollMarginEnd'],
-  scrollMarginX: ['scrollMarginStart', 'scrollMarginEnd'],
-  scrollMarginY: ['scrollMarginTop', 'scrollMarginBottom'],
-  borderWidth: ['borderTopWidth', 'borderBottomWidth', 'borderStartWidth', 'borderEndWidth'],
-  borderXWidth: ['borderStartWidth', 'borderEndWidth'],
-  borderYWidth: ['borderTopWidth', 'borderBottomWidth'],
-  borderRadius: ['borderTopStartRadius', 'borderTopEndRadius', 'borderBottomStartRadius', 'borderBottomEndRadius'],
-  borderTopRadius: ['borderTopStartRadius', 'borderTopEndRadius'],
-  borderBottomRadius: ['borderBottomStartRadius', 'borderBottomEndRadius'],
-  borderStartRadius: ['borderTopStartRadius', 'borderBottomStartRadius'],
-  borderEndRadius: ['borderTopEndRadius', 'borderBottomEndRadius'],
-  translate: ['translateX', 'translateY'],
-  scale: ['scaleX', 'scaleY'],
-  inset: ['top', 'bottom', 'insetStart', 'insetEnd'],
-  insetX: ['insetStart', 'insetEnd'],
-  insetY: ['top', 'bottom'],
-  placeItems: ['alignItems', 'justifyItems'],
-  placeContent: ['alignContent', 'justifyContent'],
-  placeSelf: ['alignSelf', 'justifySelf'],
-  gap: ['rowGap', 'columnGap'],
-  size: ['width', 'height'],
-  minSize: ['minWidth', 'minHeight'],
-  maxSize: ['maxWidth', 'maxHeight'],
-  overflow: ['overflowX', 'overflowY'],
-  overscrollBehavior: ['overscrollBehaviorX', 'overscrollBehaviorY'],
-  gridArea: ['gridColumnStart', 'gridColumnEnd', 'gridRowStart', 'gridRowEnd'],
-
-  // TODO: is it more important to display the mapping that each short hand corresponds to or the value that it accepts?
-  // I was hoping that I would just display the mapping and then have people reference the value for the corresponding
-  // values in the sections above
-  font: fontSize
-
-  // TODO: For the below, similar question as the above
-  // transition: (value: keyof typeof transitionProperty) => ({
-  //   transition: value,
-  //   transitionDuration: 150,
-  //   transitionTimingFunction: 'default'
-  // }),
-  // animation: (value: string) => ({
-  //   animation: value,
-  //   animationDuration: 150,
-  //   animationTimingFunction: 'default'
-  // }),
-  // // eslint-disable-next-line @typescript-eslint/no-unused-vars
-  // truncate: (_value: true) => ({
-  //   overflowX: 'hidden',
-  //   overflowY: 'hidden',
-  //   textOverflow: 'ellipsis',
-  //   whiteSpace: 'nowrap'
-  // }),
-  // font: (value: keyof typeof fontSize) => {
-  //   let type = value.split('-')[0];
-  //   return {
-  //     fontFamily: type === 'code' ? 'code' : 'sans',
-  //     fontSize: value,
-  //     fontWeight: type === 'heading' || type === 'title' || type === 'detail' ? type : 'normal',
-  //     lineHeight: type,
-  //     color: type === 'ui' ? 'body' : type
-  //   };
-  // }
+const shorthandMapping: {[key: string]: {values: string[], mapping: string[]}} = {
+  padding: {
+    values: relativeSpacingValues,
+    mapping: ['paddingTop', 'paddingBottom', 'paddingStart', 'paddingEnd']
+  },
+  paddingX: {
+    values: relativeSpacingValues,
+    mapping: ['paddingStart', 'paddingEnd']
+  },
+  paddingY: {
+    values: relativeSpacingValues,
+    mapping: ['paddingTop', 'paddingBottom']
+  },
+  margin: {
+    values: ['auto'],
+    mapping: ['marginTop', 'marginBottom', 'marginStart', 'marginEnd']
+  },
+  marginX: {
+    values: ['auto'],
+    mapping: ['marginStart', 'marginEnd']
+  },
+  marginY: {
+    values: ['auto'],
+    mapping: ['marginTop', 'marginBottom']
+  },
+  scrollPadding: {
+    values: [],
+    mapping: ['scrollPaddingTop', 'scrollPaddingBottom', 'scrollPaddingStart', 'scrollPaddingEnd']
+  },
+  scrollPaddingX: {
+    values: [],
+    mapping: ['scrollPaddingStart', 'scrollPaddingEnd']
+  },
+  scrollPaddingY: {
+    values: [],
+    mapping: ['scrollPaddingTop', 'scrollPaddingBottom']
+  },
+  scrollMargin: {
+    values: [],
+    mapping: ['scrollMarginTop', 'scrollMarginBottom', 'scrollMarginStart', 'scrollMarginEnd']
+  },
+  scrollMarginX: {
+    values: [],
+    mapping: ['scrollMarginStart', 'scrollMarginEnd']
+  },
+  scrollMarginY: {
+    values: [],
+    mapping: ['scrollMarginTop', 'scrollMarginBottom']
+  },
+  borderWidth: {
+    values: ['0', '1', '2', '4'],
+    mapping: ['borderTopWidth', 'borderBottomWidth', 'borderStartWidth', 'borderEndWidth']
+  },
+  borderXWidth: {
+    values: ['0', '1', '2', '4'],
+    mapping: ['borderStartWidth', 'borderEndWidth']
+  },
+  borderYWidth: {
+    values: ['0', '1', '2', '4'],
+    mapping: ['borderTopWidth', 'borderBottomWidth']
+  },
+  borderRadius: {
+    values: ['none', 'sm', 'default', 'lg', 'xl', 'full', 'pill'],
+    mapping: ['borderTopStartRadius', 'borderTopEndRadius', 'borderBottomStartRadius', 'borderBottomEndRadius']
+  },
+  borderTopRadius: {
+    values: ['none', 'sm', 'default', 'lg', 'xl', 'full', 'pill'],
+    mapping: ['borderTopStartRadius', 'borderTopEndRadius']
+  },
+  borderBottomRadius: {
+    values: ['none', 'sm', 'default', 'lg', 'xl', 'full', 'pill'],
+    mapping: ['borderBottomStartRadius', 'borderBottomEndRadius']
+  },
+  borderStartRadius: {
+    values: ['none', 'sm', 'default', 'lg', 'xl', 'full', 'pill'],
+    mapping: ['borderTopStartRadius', 'borderBottomStartRadius']
+  },
+  borderEndRadius: {
+    values: ['none', 'sm', 'default', 'lg', 'xl', 'full', 'pill'],
+    mapping: ['borderTopEndRadius', 'borderBottomEndRadius']
+  },
+  translate: {
+    values: ['full'],
+    mapping: ['translateX', 'translateY']
+  },
+  scale: {
+    values: ['number', '${number}%'],
+    mapping: ['scaleX', 'scaleY']
+  },
+  inset: {
+    values: ['auto', 'full'],
+    mapping: ['top', 'bottom', 'insetStart', 'insetEnd']
+  },
+  insetX: {
+    values: ['auto', 'full'],
+    mapping: ['insetStart', 'insetEnd']
+  },
+  insetY: {
+    values: ['auto', 'full'],
+    mapping: ['top', 'bottom']
+  },
+  placeItems: {
+    values: ['start', 'end', 'center', 'stretch'],
+    mapping: ['alignItems', 'justifyItems']
+  },
+  placeContent: {
+    values: ['normal', 'center', 'start', 'end', 'space-between', 'space-around', 'space-evenly', 'baseline', 'stretch'],
+    mapping: ['alignContent', 'justifyContent']
+  },
+  placeSelf: {
+    values: ['auto', 'start', 'end', 'center', 'stretch', 'baseline'],
+    mapping: ['alignSelf', 'justifySelf']
+  },
+  gap: {
+    values: relativeSpacingValues,
+    mapping: ['rowGap', 'columnGap']
+  },
+  size: {
+    values: heightBaseValues,
+    mapping: ['width', 'height']
+  },
+  minSize: {
+    values: heightBaseValues,
+    mapping: ['minWidth', 'minHeight']
+  },
+  maxSize: {
+    values: [...heightBaseValues, 'none'],
+    mapping: ['maxWidth', 'maxHeight']
+  },
+  overflow: {
+    values: ['auto', 'hidden', 'clip', 'visible', 'scroll'],
+    mapping: ['overflowX', 'overflowY']
+  },
+  overscrollBehavior: {
+    values: ['auto', 'contain', 'none'],
+    mapping: ['overscrollBehaviorX', 'overscrollBehaviorY']
+  },
+  gridArea: {
+    values: ['string'],
+    mapping: ['gridColumnStart', 'gridColumnEnd', 'gridRowStart', 'gridRowEnd']
+  },
+  transition: {
+    values: ['default', 'colors', 'opacity', 'shadow', 'transform', 'all', 'none'],
+    mapping: ['transition', 'transitionDuration', 'transitionTimingFunction']
+  },
+  animation: {
+    values: ['string'],
+    mapping: ['animation', 'animationDuration', 'animationTimingFunction']
+  },
+  truncate: {
+    values: ['true'],
+    mapping: ['overflowX', 'overflowY', 'textOverflow', 'whiteSpace']
+  },
+  font: {
+    values: ['fontSize'],
+    mapping: ['fontFamily', 'fontSize', 'fontWeight', 'lineHeight', 'color']
+  }
 };
 
 const conditionMapping: {[key: string]: string[]} = {
@@ -358,7 +438,8 @@ const properties: {[key: string]: {[key: string]: string[]}} = {
   text: textPropertyValues,
   effects: effectsPropertyValues,
   layout: layoutPropertyValues,
-  misc: miscPropertyValues
+  misc: miscPropertyValues,
+  conditions: conditionMapping
 };
 
 // TODO: will we need something specific for short hand?
@@ -400,7 +481,8 @@ const relativeLinks: {[key: string]: string} = {
   'text-to-visual': '#dimensions',
   'edge-to-text': '#dimensions',
   'pill': '#dimensions',
-  'baseColors': '#colors'
+  'baseColors': '#colors',
+  'fontSize': '#text'
 }
 
 // a mapping of value to mdn links that should be replaced in place
@@ -435,14 +517,20 @@ const propertyDescriptions: {[key: string]: string} = {
   'rotate': 'Accepts a number (treated as degrees) or a string with units (deg, rad, grad, turn).',
   'scaleX': 'Accepts a number or percentage string.',
   'scaleY': 'Accepts a number or percentage string.',
-  'aspectRatio': 'Also accepts a ratio in the format number/number (e.g., 16/9, 4/3).'
+  'scaleShortHand': 'Accepts a number or percentage string.',
+  'aspectRatio': 'Also accepts a ratio in the format number/number (e.g., 16/9, 4/3).',
+  'transitionShorthand': 'This shorthand explicitly defines duration as 150 and the timing function as "default".',
+  'animationShortHand': 'This shorthand explicitly defines duration as 150 and the timing function as "default".',
+  'truncateShortHand': 'Applying this shorthand will enable text truncation.',
+  'fontShortHand': 'The "fontSize" provided defines the values this shorthand sets on the mapped values.'
 };
 
 interface StyleMacroPropertyDefinition {
   values: string[],
   additionalTypes?: string[],
   links?: {[value: string]: {href: string, isRelative?: boolean}},
-  description?: string
+  description?: string,
+  mapping?: string[]
 }
 
 export function getPropertyDefinitions(propertyCategory: string): {[key: string]: StyleMacroPropertyDefinition} {
@@ -481,3 +569,34 @@ export function getPropertyDefinitions(propertyCategory: string): {[key: string]
   }
   return result;
 }
+
+export function getShorthandDefinitions(): {[key: string]: StyleMacroPropertyDefinition} {
+  let result: {[key: string]: StyleMacroPropertyDefinition} = {};
+
+  for (let [shorthandName, shorthandDef] of Object.entries(shorthandMapping)) {
+    let values = shorthandDef.values;
+    let links: {[value: string]: {href: string, isRelative?: boolean}} = {};
+
+    for (let value of values) {
+      if (value === 'pill' && shorthandName.includes('border')) {
+        continue;
+      }
+
+      if (mdnTypeLinks[value]) {
+        links[value] = {href: mdnTypeLinks[value]};
+      } else if (relativeLinks[value]) {
+        links[value] = {href: relativeLinks[value], isRelative: true};
+      }
+    }
+
+    result[shorthandName] = {
+      values,
+      additionalTypes: getAdditionalTypes(shorthandDef.mapping[0]),
+      links: Object.keys(links).length > 0 ? links : undefined,
+      mapping: shorthandDef.mapping,
+      description: propertyDescriptions[`${shorthandName}ShortHand`]
+    };
+  }
+
+  return result;
+}
diff --git a/packages/dev/s2-docs/src/types.tsx b/packages/dev/s2-docs/src/types.tsx
index be59df53216..1bed98dfef2 100644
--- a/packages/dev/s2-docs/src/types.tsx
+++ b/packages/dev/s2-docs/src/types.tsx
@@ -755,15 +755,17 @@ interface StyleMacroPropertyDefinition {
   values: string[],
   additionalTypes?: string[],
   links?: {[value: string]: {href: string, isRelative?: boolean}},
-  description?: string
+  description?: string,
+  mapping?: string[]
 }
 
 interface StyleMacroPropertiesProps {
-  properties: {[propertyName: string]: StyleMacroPropertyDefinition}
+  properties: {[propertyName: string]: StyleMacroPropertyDefinition},
 }
 
 export function StyleMacroProperties({properties}: StyleMacroPropertiesProps) {
   let propertyNames = Object.keys(properties);
+  let hasMapping = Object.values(properties).some(p => p.mapping);
 
   return (
     <Table>
@@ -771,6 +773,7 @@ export function StyleMacroProperties({properties}: StyleMacroPropertiesProps) {
         <tr>
           <TableColumn>Property</TableColumn>
           <TableColumn>Values</TableColumn>
+          {hasMapping && <TableColumn>Mapping</TableColumn>}
         </tr>
       </TableHeader>
       <TableBody>
@@ -827,10 +830,22 @@ export function StyleMacroProperties({properties}: StyleMacroPropertiesProps) {
                     })}
                   </code>
                 </TableCell>
+                {hasMapping && (
+                  <TableCell hideBorder={!!propDef.description}>
+                    <code className={codeStyle}>
+                      {propDef.mapping?.map((mappedProp, i) => (
+                        <React.Fragment key={i}>
+                          {i > 0 && <Punctuation>{', '}</Punctuation>}
+                          <span className={codeStyles.attribute}>{mappedProp}</span>
+                        </React.Fragment>
+                      ))}
+                    </code>
+                  </TableCell>
+                )}
               </TableRow>
               {propDef.description && (
                 <TableRow>
-                  <TableCell colSpan={2}>{propDef.description}</TableCell>
+                  <TableCell colSpan={hasMapping ? 3 : 2}>{propDef.description}</TableCell>
                 </TableRow>
               )}
             </React.Fragment>

From 59e94008b71da3484eeaa0c3aeac1e84966c7698 Mon Sep 17 00:00:00 2001
From: Daniel Lu <dl1644@gmail.com>
Date: Thu, 30 Oct 2025 16:18:29 -0700
Subject: [PATCH 14/27] add subpage for reference and advanced style macro
 section

---
 packages/dev/s2-docs/pages/s2/styling.mdx     | 186 +---------------
 .../dev/s2-docs/pages/s2/styling/Advanced.mdx | 199 ++++++++++++++++++
 .../pages/s2/{ => styling}/Reference.mdx      |  11 +-
 packages/dev/s2-docs/src/styleProperties.ts   |  18 +-
 packages/dev/s2-docs/src/types.tsx            |  11 +-
 5 files changed, 220 insertions(+), 205 deletions(-)
 create mode 100644 packages/dev/s2-docs/pages/s2/styling/Advanced.mdx
 rename packages/dev/s2-docs/pages/s2/{ => styling}/Reference.mdx (91%)

diff --git a/packages/dev/s2-docs/pages/s2/styling.mdx b/packages/dev/s2-docs/pages/s2/styling.mdx
index 25ae0ec8ae1..69b57e691a2 100644
--- a/packages/dev/s2-docs/pages/s2/styling.mdx
+++ b/packages/dev/s2-docs/pages/s2/styling.mdx
@@ -119,7 +119,7 @@ function YourComponent() {
 
 ## 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
 
@@ -182,190 +182,6 @@ Define conditional values as objects to handle media queries, UI states (hover/p
 
 Conditions are mutually exclusive and ordered. The macro uses CSS cascade layers so the last matching condition wins without specificity issues.
 
-### Runtime conditions
-
-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` or `allows` can be used directly without nesting:
-
-```tsx
-const styles = style({
-  backgroundColor: {
-    default: 'gray-100',
-    isSelected: 'gray-900',
-    allowsRemoving: 'gray-400'
-  }
-});
-
-<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>
-```
-
-## 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:
diff --git a/packages/dev/s2-docs/pages/s2/styling/Advanced.mdx b/packages/dev/s2-docs/pages/s2/styling/Advanced.mdx
new file mode 100644
index 00000000000..a14204ec302
--- /dev/null
+++ b/packages/dev/s2-docs/pages/s2/styling/Advanced.mdx
@@ -0,0 +1,199 @@
+import {Layout} from '../../../src/Layout';
+export default Layout;
+
+export const tags = ['style', 'macro', 'spectrum', 'custom', 'advanced'];
+export const description = 'Style macro advanced usage guide';
+
+# Advanced style macro usage
+
+A guide to advanced use cases with the `style` macro.
+
+## Runtime conditions
+
+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` or `allows` can be used directly without nesting:
+
+```tsx
+const styles = style({
+  backgroundColor: {
+    default: 'gray-100',
+    isSelected: 'gray-900',
+    allowsRemoving: 'gray-400'
+  }
+});
+
+<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
+// 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',
+  columnGap: 8
+} as const;
+
+const styles = style({
+  ...horizontalStack,
+  backgroundColor: bannerBackground(),
+  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>
+```
+
+## 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.
diff --git a/packages/dev/s2-docs/pages/s2/Reference.mdx b/packages/dev/s2-docs/pages/s2/styling/Reference.mdx
similarity index 91%
rename from packages/dev/s2-docs/pages/s2/Reference.mdx
rename to packages/dev/s2-docs/pages/s2/styling/Reference.mdx
index 5d23ce5fbd6..ac252b82956 100644
--- a/packages/dev/s2-docs/pages/s2/Reference.mdx
+++ b/packages/dev/s2-docs/pages/s2/styling/Reference.mdx
@@ -1,12 +1,11 @@
-import {Layout} from '../../src/Layout';
+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';
+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 = 'Guides';
 export const tags = ['style', 'macro', 'spectrum', 'custom', 'values', 'reference'];
 export const description = 'Reference table for the `style` macro';
 
diff --git a/packages/dev/s2-docs/src/styleProperties.ts b/packages/dev/s2-docs/src/styleProperties.ts
index 98b94ba7fec..162af8aef8e 100644
--- a/packages/dev/s2-docs/src/styleProperties.ts
+++ b/packages/dev/s2-docs/src/styleProperties.ts
@@ -44,9 +44,9 @@ const negativeSpacingProperties = new Set([
 ]);
 
 // Spacing values used across multiple properties
-const baseSpacingValues = ['0', '2', '4', '8', '12', '16', '20', '24', '28', '32', '36', '40', '44', '48', '56', '64', '80', '96',];
+const baseSpacingValues = ['0', '2', '4', '8', '12', '16', '20', '24', '28', '32', '36', '40', '44', '48', '56', '64', '80', '96'];
 const negativeBaseSpacingValues = ['-2', '-4', '-8', '-12', '-16', '-20', '-24', '-28', '-32', '-36', '-40', '-44', '-48', '-56', '-64', '-80', '-96'];
-const relativeSpacingValues = [ 'text-to-control', 'text-to-visual', 'edge-to-text', 'pill'];
+const relativeSpacingValues = ['text-to-control', 'text-to-visual', 'edge-to-text', 'pill'];
 // const spacingValues = [...baseSpacingValues, ...relativeSpacingValues];
 // const marginValues = [...spacingValues, ...negativeBaseSpacingValues, 'auto'];
 // const insetValues = [...baseSpacingValues, ...negativeBaseSpacingValues, 'auto', 'full'];
@@ -218,9 +218,9 @@ const layoutPropertyValues: {[key: string]: string[]} = {
   gridRowStart: [],
   gridRowEnd: [],
   gridAutoFlow: ['row', 'column', 'dense', 'row dense', 'column dense'],
-  gridAutoRows:['auto', 'min-content', 'max-content', '${number}fr', 'minmax(${string}, ${string})', 'string'],
+  gridAutoRows: ['auto', 'min-content', 'max-content', '${number}fr', 'minmax(${string}, ${string})', 'string'],
   gridAutoColumns: ['auto', 'min-content', 'max-content', '${number}fr', 'minmax(${string}, ${string})', 'string'],
-  gridTemplateColumns: ['auto', 'min-content', 'max-content', '${number}fr', 'minmax(${string}, ${string})', 'none', 'subgrid', 'string',],
+  gridTemplateColumns: ['auto', 'min-content', 'max-content', '${number}fr', 'minmax(${string}, ${string})', 'none', 'subgrid', 'string'],
   gridTemplateRows: ['auto', 'min-content', 'max-content', '${number}fr', 'minmax(${string}, ${string})', 'none', 'subgrid', 'string'],
   gridTemplateAreas: ['string[]'],
   float: ['inline-start', 'inline-end', 'right', 'left', 'none'],
@@ -238,7 +238,7 @@ const layoutPropertyValues: {[key: string]: string[]} = {
   overscrollBehaviorX: ['auto', 'contain', 'none'],
   overscrollBehaviorY: ['auto', 'contain', 'none'],
   scrollBehavior: ['auto', 'smooth'],
-  order: ['number'],
+  order: ['number']
 };
 
 const miscPropertyValues: {[key: string]: string[]} = {
@@ -430,7 +430,7 @@ const conditionMapping: {[key: string]: string[]} = {
   lg: ['@media (min-width: ${pxToRem(1024)})'],
   xl: ['@media (min-width: ${pxToRem(1280)})'],
   '2xl': ['@media (min-width: ${pxToRem(1536)})']
-}
+};
 
 const properties: {[key: string]: {[key: string]: string[]}} = {
   color: colorPropertyValues,
@@ -483,7 +483,7 @@ const relativeLinks: {[key: string]: string} = {
   'pill': '#dimensions',
   'baseColors': '#colors',
   'fontSize': '#text'
-}
+};
 
 // a mapping of value to mdn links that should be replaced in place
 const mdnTypeLinks: {[key: string]: string} = {
@@ -494,7 +494,7 @@ const mdnTypeLinks: {[key: string]: string} = {
 // a mapping of value to links that should be replaced in place with the provided string
 const mdnPropertyLinks: {[key: string]: {[value: string]: string}} = {
   'flexShrink': {
-    'number':  'https://developer.mozilla.org/en-US/docs/Web/CSS/flex-shrink'
+    'number': 'https://developer.mozilla.org/en-US/docs/Web/CSS/flex-shrink'
   },
   'flexGrow': {
     'number': 'https://developer.mozilla.org/en-US/docs/Web/CSS/flex-grow'
@@ -548,7 +548,7 @@ export function getPropertyDefinitions(propertyCategory: string): {[key: string]
       // see if the property has any common types that should link to MDN instead
       for (let value of values) {
         // make sure not to overwrite number in sizing properties and pill in other sections aka effects
-        if ((value === 'number' && sizingProperties.has(name)) || (value === 'pill' && propertyCategory !== 'dimensions') ) {
+        if ((value === 'number' && sizingProperties.has(name)) || (value === 'pill' && propertyCategory !== 'dimensions')) {
           continue;
         }
 
diff --git a/packages/dev/s2-docs/src/types.tsx b/packages/dev/s2-docs/src/types.tsx
index 1bed98dfef2..fb6e43be18b 100644
--- a/packages/dev/s2-docs/src/types.tsx
+++ b/packages/dev/s2-docs/src/types.tsx
@@ -729,7 +729,7 @@ const styleMacroTypeLinks = {
   'number': {
     description: <>A numeric value in pixels e.g. <code className={codeStyle}>20</code>. Will be converted to rem and scaled on touch devices.</>
   }
-}
+};
 
 interface StyleMacroTypePopoverProps {
   typeName: string,
@@ -748,7 +748,7 @@ function StyleMacroTypePopover({typeName, description, body}: StyleMacroTypePopo
         {body}
       </>
     </TypePopover>
-  )
+  );
 }
 
 interface StyleMacroPropertyDefinition {
@@ -760,7 +760,7 @@ interface StyleMacroPropertyDefinition {
 }
 
 interface StyleMacroPropertiesProps {
-  properties: {[propertyName: string]: StyleMacroPropertyDefinition},
+  properties: {[propertyName: string]: StyleMacroPropertyDefinition}
 }
 
 export function StyleMacroProperties({properties}: StyleMacroPropertiesProps) {
@@ -799,8 +799,8 @@ export function StyleMacroProperties({properties}: StyleMacroPropertiesProps) {
                           <ColorLink
                             href={links[value].href}
                             type="variable"
-                            rel={links[value].isRelative ? undefined : "noreferrer"}
-                            target={links[value].isRelative ? undefined : "_blank"}>
+                            rel={links[value].isRelative ? undefined : 'noreferrer'}
+                            target={links[value].isRelative ? undefined : '_blank'}>
                             {value}
                           </ColorLink>
                         ) : (
@@ -813,6 +813,7 @@ export function StyleMacroProperties({properties}: StyleMacroPropertiesProps) {
                       return (
                         <React.Fragment key={`type-${i}`}>
                           {(values.length > 0 || i > 0) && <Punctuation>{' | '}</Punctuation>}
+                          {/* eslint-disable-next-line no-nested-ternary */}
                           {typeLink ? (
                             // only if the type link has a description and/or body do we want to render the type popover
                             // this is to make things like baseColor

From a414886f439fe072df7aa29e31d446adac423f87 Mon Sep 17 00:00:00 2001
From: Daniel Lu <dl1644@gmail.com>
Date: Thu, 30 Oct 2025 17:23:36 -0700
Subject: [PATCH 15/27] support subpage list under the ToC

---
 packages/dev/s2-docs/pages/s2/styling.mdx     | 21 ++++------------
 .../dev/s2-docs/pages/s2/styling/Advanced.mdx |  1 +
 .../s2-docs/pages/s2/styling/Reference.mdx    |  1 +
 packages/dev/s2-docs/src/Layout.tsx           | 24 +++++++++++++++++++
 packages/dev/s2-docs/src/Nav.tsx              |  4 ++--
 5 files changed, 32 insertions(+), 19 deletions(-)

diff --git a/packages/dev/s2-docs/pages/s2/styling.mdx b/packages/dev/s2-docs/pages/s2/styling.mdx
index 69b57e691a2..695e8abd91e 100644
--- a/packages/dev/s2-docs/pages/s2/styling.mdx
+++ b/packages/dev/s2-docs/pages/s2/styling.mdx
@@ -8,6 +8,10 @@ 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
 
@@ -165,23 +169,6 @@ Type scales include: UI, Body, Heading, Title, Detail, and Code. Each scale has
   </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.
-
 ## CSS optimization
 
 The `style` macro relies on CSS bundling and minification for optimal output. Follow these best practices:
diff --git a/packages/dev/s2-docs/pages/s2/styling/Advanced.mdx b/packages/dev/s2-docs/pages/s2/styling/Advanced.mdx
index a14204ec302..b729565799a 100644
--- a/packages/dev/s2-docs/pages/s2/styling/Advanced.mdx
+++ b/packages/dev/s2-docs/pages/s2/styling/Advanced.mdx
@@ -1,6 +1,7 @@
 import {Layout} from '../../../src/Layout';
 export default Layout;
 
+export const omitFromNav = true;
 export const tags = ['style', 'macro', 'spectrum', 'custom', 'advanced'];
 export const description = 'Style macro advanced usage guide';
 
diff --git a/packages/dev/s2-docs/pages/s2/styling/Reference.mdx b/packages/dev/s2-docs/pages/s2/styling/Reference.mdx
index ac252b82956..18331216a0a 100644
--- a/packages/dev/s2-docs/pages/s2/styling/Reference.mdx
+++ b/packages/dev/s2-docs/pages/s2/styling/Reference.mdx
@@ -6,6 +6,7 @@ import {StyleMacroProperties} from '../../../src/types';
 import {getPropertyDefinitions, getShorthandDefinitions} from '../../../src/styleProperties';
 export default Layout;
 
+export const omitFromNav = true;
 export const tags = ['style', 'macro', 'spectrum', 'custom', 'values', 'reference'];
 export const description = 'Reference table for the `style` macro';
 
diff --git a/packages/dev/s2-docs/src/Layout.tsx b/packages/dev/s2-docs/src/Layout.tsx
index 70c278a3589..5629442d422 100644
--- a/packages/dev/s2-docs/src/Layout.tsx
+++ b/packages/dev/s2-docs/src/Layout.tsx
@@ -262,6 +262,9 @@ export function Layout(props: PageProps & {children: ReactElement<any>}) {
                   <div className={style({font: 'title', minHeight: 32, paddingX: 12, display: 'flex', alignItems: 'center'})}>Contents</div>
                 )}
                 <Toc toc={currentPage.tableOfContents?.[0]?.children ?? []} />
+                {currentPage.exports?.relatedPages && (
+                  <RelatedPages pages={currentPage.exports.relatedPages} />
+                )}
               </aside>
             </main>
           </div>
@@ -286,10 +289,31 @@ function Toc({toc}) {
   );
 }
 
+function RelatedPages({pages}: {pages: Array<{title: string, url: string}>}) {
+  return (
+    <div className={style({paddingTop: 24})}>
+      <div className={style({font: 'title', minHeight: 32, paddingX: 12, display: 'flex', alignItems: 'center'})}>Related pages</div>
+      <OnPageNav>
+        <SideNav>
+          {pages.map((page, i) => (
+            <SideNavItem key={i}>
+              <SideNavLink href={page.url}>{page.title}</SideNavLink>
+            </SideNavItem>
+          ))}
+        </SideNav>
+      </OnPageNav>
+    </div>
+  );
+}
+
 function MobileToc({toc, currentPage}) {
+  let relatedPages = currentPage.exports?.relatedPages;
   return (
     <MobileOnPageNav currentPage={currentPage}>
       {renderMobileToc(toc)}
+      {relatedPages && relatedPages.map((page, i) => (
+        <PickerItem key={`related-${i}`} id={page.url} href={page.url}>{page.title}</PickerItem>
+      ))}
     </MobileOnPageNav>
   );
 }
diff --git a/packages/dev/s2-docs/src/Nav.tsx b/packages/dev/s2-docs/src/Nav.tsx
index 637d07d4812..3d89e36c47d 100644
--- a/packages/dev/s2-docs/src/Nav.tsx
+++ b/packages/dev/s2-docs/src/Nav.tsx
@@ -11,10 +11,10 @@ export function Nav({pages, currentPage}: PageProps) {
   let currentLibrary = getLibraryFromPage(currentPage);
   let sections = new Map();
   for (let page of pages) {
-    if (page.exports?.hideNav || page.exports?.hideFromSearch) {
+    if (page.exports?.hideNav || page.exports?.hideFromSearch || page.exports?.omitFromNav) {
       continue;
     }
-    
+
     let library = getLibraryFromPage(page);
     if (library !== currentLibrary) {
       continue;

From 0b2751dc78cc325f31cce5f0a866163edec4eb75 Mon Sep 17 00:00:00 2001
From: Daniel Lu <dl1644@gmail.com>
Date: Thu, 30 Oct 2025 17:33:39 -0700
Subject: [PATCH 16/27] forgot to move last bit of content

---
 .../dev/s2-docs/pages/s2/styling/Advanced.mdx   | 17 +++++++++++++++++
 1 file changed, 17 insertions(+)

diff --git a/packages/dev/s2-docs/pages/s2/styling/Advanced.mdx b/packages/dev/s2-docs/pages/s2/styling/Advanced.mdx
index b729565799a..ff6cbf83781 100644
--- a/packages/dev/s2-docs/pages/s2/styling/Advanced.mdx
+++ b/packages/dev/s2-docs/pages/s2/styling/Advanced.mdx
@@ -9,6 +9,23 @@ export const description = 'Style macro advanced usage guide';
 
 A guide to advanced use cases with the `style` macro.
 
+## 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
 
 When runtime conditions are detected (e.g., variants, UI states), the macro returns a function to resolve styles at runtime.

From 4ef49966a9179e5768652d88797a3dd74b033658 Mon Sep 17 00:00:00 2001
From: Daniel Lu <dl1644@gmail.com>
Date: Fri, 31 Oct 2025 11:22:50 -0700
Subject: [PATCH 17/27] update FAQ, add mobile related pages, link from RAC
 styling

---
 .../dev/s2-docs/pages/react-aria/styling.mdx  | 19 +++++++
 packages/dev/s2-docs/pages/s2/styling.mdx     | 20 +-------
 packages/dev/s2-docs/src/Layout.tsx           | 49 ++++++++++++-------
 packages/dev/s2-docs/src/S2FAQ.tsx            | 37 ++++++++++++++
 packages/dev/s2-docs/src/styleProperties.ts   |  8 ---
 packages/dev/s2-docs/src/types.tsx            |  2 -
 6 files changed, 90 insertions(+), 45 deletions(-)
 create mode 100644 packages/dev/s2-docs/src/S2FAQ.tsx

diff --git a/packages/dev/s2-docs/pages/react-aria/styling.mdx b/packages/dev/s2-docs/pages/react-aria/styling.mdx
index 1c11d96bf68..d2fd3f2e2e0 100644
--- a/packages/dev/s2-docs/pages/react-aria/styling.mdx
+++ b/packages/dev/s2-docs/pages/react-aria/styling.mdx
@@ -252,6 +252,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/).
diff --git a/packages/dev/s2-docs/pages/s2/styling.mdx b/packages/dev/s2-docs/pages/s2/styling.mdx
index 695e8abd91e..18c32540f8b 100644
--- a/packages/dev/s2-docs/pages/s2/styling.mdx
+++ b/packages/dev/s2-docs/pages/s2/styling.mdx
@@ -3,6 +3,7 @@ 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';
@@ -241,21 +242,4 @@ we have MCP servers for [React Aria](#TODO) and [React Spectrum](https://www.npm
 
 ## FAQ
 
-> I'm getting a "Could not statically evaluate macro argument" error.
-
-This indicates that your `style` macro has a condition that isn't evaluable at build time. This can happen for a variety of reasons such
-as if you've referenced non-constant variables within your `style` macro or if you've called non-macro functions within your `style` macro.
-If you are using Typescript, it can be as simple as forgetting to add `as const` to your own defined reusable macro.
-
-> I'm seeing a ton of duplicate rules being generated and/or my dev tools are very slow.
-
-Please make sure you've followed the [best practices listed above](#css-optimization).
-
-> I tried to pass my `style` macro to `UNSAFE_className` but it doesn't work.
-
-The `style` macro is not meant to be used with `UNSAFE_className`. Overrides to the Spectrum styles is highly discouraged,
-consider styling an equivalent React Aria Component instead.
-
-> I'm coming from S1, but where are Flex/Grid/etc?
-
-These no longer exist. Please style `<div>`, `<span>`, and other standard HTML elements with the `style` macro instead.
+<S2FAQ />
diff --git a/packages/dev/s2-docs/src/Layout.tsx b/packages/dev/s2-docs/src/Layout.tsx
index 5629442d422..dcf1910a597 100644
--- a/packages/dev/s2-docs/src/Layout.tsx
+++ b/packages/dev/s2-docs/src/Layout.tsx
@@ -31,23 +31,6 @@ const components = {
   p: ({children, ...props}) => <p {...props} className={style({font: {default: 'body', lg: 'body-lg'}, marginY: 24})}>{children}</p>,
   ul: (props) => <ul {...props} />,
   li: ({children, ...props}) => <li {...props} className={style({font: {default: 'body', lg: 'body-lg'}, marginY: 0})}>{children}</li>,
-  blockquote: ({children, ...props}) => (
-    <blockquote
-      {...props}
-      className={style({
-        borderStartWidth: 4,
-        borderEndWidth: 0,
-        borderTopWidth: 0,
-        borderBottomWidth: 0,
-        borderStyle: 'solid',
-        borderColor: 'gray-400',
-        paddingStart: 12,
-        font: {default: 'body', lg: 'body-lg'},
-        margin: 'unset'
-      })}>
-      {children}
-    </blockquote>
-  ),
   Figure: (props) => <figure {...props} className={style({display: 'flex', flexDirection: 'column', alignItems: 'center', marginY: 32, marginX: 0})} />,
   Caption: (props) => <figcaption {...props} className={style({font: 'body-sm'})} />,
   CodeBlock: CodeBlock,
@@ -243,6 +226,9 @@ export function Layout(props: PageProps & {children: ReactElement<any>}) {
               <article
                 className={articleStyles({isWithToC: hasToC})}>
                 {React.cloneElement(children, {components})}
+                {currentPage.exports?.relatedPages && (
+                  <MobileRelatedPages pages={currentPage.exports.relatedPages} />
+                )}
               </article>
               <aside
                 className={style({
@@ -306,6 +292,35 @@ function RelatedPages({pages}: {pages: Array<{title: string, url: string}>}) {
   );
 }
 
+function MobileRelatedPages({pages}: {pages: Array<{title: string, url: string}>}) {
+  const P = components.p;
+  const Li = components.li;
+  const Ul = components.ul;
+
+  return (
+    <div
+      className={style({
+        display: {
+          default: 'block',
+          lg: 'none'
+        }
+      })}>
+      <H2>Related pages</H2>
+      <Ul>
+        {pages.map((page, i) => (
+          <Li key={i}>
+            <P>
+              <Link href={page.url}>
+                {page.title}
+              </Link>
+            </P>
+          </Li>
+        ))}
+      </Ul>
+    </div>
+  );
+}
+
 function MobileToc({toc, currentPage}) {
   let relatedPages = currentPage.exports?.relatedPages;
   return (
diff --git a/packages/dev/s2-docs/src/S2FAQ.tsx b/packages/dev/s2-docs/src/S2FAQ.tsx
new file mode 100644
index 00000000000..4d08f1cdcec
--- /dev/null
+++ b/packages/dev/s2-docs/src/S2FAQ.tsx
@@ -0,0 +1,37 @@
+import {Disclosure, DisclosurePanel, DisclosureTitle} from '@react-spectrum/s2';
+import React from 'react';
+import {style} from '@react-spectrum/s2/style' with {type: 'macro'};
+
+export function S2FAQ() {
+  return (
+    <div className={style({display: 'flex', flexDirection: 'column', gap: 16})}>
+      <Disclosure isQuiet>
+        <DisclosureTitle>I'm getting a "Could not statically evaluate macro argument" error.</DisclosureTitle>
+        <DisclosurePanel>
+          This indicates that your <code>style</code> macro has a condition that isn't evaluable at build time. This can happen for a variety of reasons such
+          as if you've referenced non-constant variables within your <code>style</code> macro or if you've called non-macro functions within your <code>style</code> macro.
+          If you are using Typescript, it can be as simple as forgetting to add <code>as const</code> to your own defined reusable macro.
+        </DisclosurePanel>
+      </Disclosure>
+      <Disclosure isQuiet>
+        <DisclosureTitle>I'm seeing a ton of duplicate rules being generated and/or my dev tools are very slow.</DisclosureTitle>
+        <DisclosurePanel>
+          Please make sure you've followed the best practices listed above.
+        </DisclosurePanel>
+      </Disclosure>
+      <Disclosure isQuiet>
+        <DisclosureTitle>I tried to pass my <code>style</code> macro to <code>UNSAFE_className</code> but it doesn't work.</DisclosureTitle>
+        <DisclosurePanel>
+          The <code>style</code> macro is not meant to be used with <code>UNSAFE_className</code>. Overrides to the Spectrum styles is highly discouraged,
+          consider styling an equivalent React Aria Component instead.
+        </DisclosurePanel>
+      </Disclosure>
+      <Disclosure isQuiet>
+        <DisclosureTitle>I'm coming from S1, but where are Flex/Grid/etc?</DisclosureTitle>
+        <DisclosurePanel>
+          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>
+    </div>
+  );
+}
diff --git a/packages/dev/s2-docs/src/styleProperties.ts b/packages/dev/s2-docs/src/styleProperties.ts
index 162af8aef8e..7df98cc25ab 100644
--- a/packages/dev/s2-docs/src/styleProperties.ts
+++ b/packages/dev/s2-docs/src/styleProperties.ts
@@ -47,10 +47,6 @@ const negativeSpacingProperties = new Set([
 const baseSpacingValues = ['0', '2', '4', '8', '12', '16', '20', '24', '28', '32', '36', '40', '44', '48', '56', '64', '80', '96'];
 const negativeBaseSpacingValues = ['-2', '-4', '-8', '-12', '-16', '-20', '-24', '-28', '-32', '-36', '-40', '-44', '-48', '-56', '-64', '-80', '-96'];
 const relativeSpacingValues = ['text-to-control', 'text-to-visual', 'edge-to-text', 'pill'];
-// const spacingValues = [...baseSpacingValues, ...relativeSpacingValues];
-// const marginValues = [...spacingValues, ...negativeBaseSpacingValues, 'auto'];
-// const insetValues = [...baseSpacingValues, ...negativeBaseSpacingValues, 'auto', 'full'];
-// const translateValues = [...baseSpacingValues, ...negativeBaseSpacingValues, 'full'];
 const heightBaseValues = ['auto', 'full', 'min', 'max', 'fit', 'screen'];
 const fontSize = [
   'ui-xs', 'ui-sm', 'ui', 'ui-lg', 'ui-xl', 'ui-2xl', 'ui-3xl',
@@ -442,10 +438,6 @@ const properties: {[key: string]: {[key: string]: string[]}} = {
   conditions: conditionMapping
 };
 
-// TODO: will we need something specific for short hand?
-// TODO: see if there are any others that we will need to add additional shared types for
-// this is less additional types and more that we want to represent the below as a type link
-// special custom types that should be appended to the property but need special handling (render a type popover)
 export function getAdditionalTypes(propertyName: string): string[] {
   let types: string[] = [];
 
diff --git a/packages/dev/s2-docs/src/types.tsx b/packages/dev/s2-docs/src/types.tsx
index fb6e43be18b..015c5f53727 100644
--- a/packages/dev/s2-docs/src/types.tsx
+++ b/packages/dev/s2-docs/src/types.tsx
@@ -856,5 +856,3 @@ export function StyleMacroProperties({properties}: StyleMacroPropertiesProps) {
     </Table>
   );
 }
-
-// TODO: For the Shorthands, have a column for Name, value (what values it accepts), and mapping where mapping is what properties it maps to

From 807beb081d41dd2cde2f5f311c49521e3d95402d Mon Sep 17 00:00:00 2001
From: Daniel Lu <dl1644@gmail.com>
Date: Fri, 31 Oct 2025 11:30:05 -0700
Subject: [PATCH 18/27] fix mobile styling

---
 packages/dev/s2-docs/src/S2FAQ.tsx | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/packages/dev/s2-docs/src/S2FAQ.tsx b/packages/dev/s2-docs/src/S2FAQ.tsx
index 4d08f1cdcec..127cfb1fb7b 100644
--- a/packages/dev/s2-docs/src/S2FAQ.tsx
+++ b/packages/dev/s2-docs/src/S2FAQ.tsx
@@ -20,7 +20,7 @@ export function S2FAQ() {
         </DisclosurePanel>
       </Disclosure>
       <Disclosure isQuiet>
-        <DisclosureTitle>I tried to pass my <code>style</code> macro to <code>UNSAFE_className</code> but it doesn't work.</DisclosureTitle>
+        <DisclosureTitle>I tried to pass my style macro to "UNSAFE_className" but it doesn't work.</DisclosureTitle>
         <DisclosurePanel>
           The <code>style</code> macro is not meant to be used with <code>UNSAFE_className</code>. Overrides to the Spectrum styles is highly discouraged,
           consider styling an equivalent React Aria Component instead.

From 0c6ac3f4b2f13bd88f388c39d1c9554dd25bf97b Mon Sep 17 00:00:00 2001
From: Daniel Lu <dl1644@gmail.com>
Date: Mon, 3 Nov 2025 11:00:22 -0800
Subject: [PATCH 19/27] review comments

---
 packages/dev/s2-docs/pages/s2/styling.mdx     | 30 ++++-------------
 .../dev/s2-docs/pages/s2/styling/Advanced.mdx | 32 ++++++++++++++++---
 2 files changed, 34 insertions(+), 28 deletions(-)

diff --git a/packages/dev/s2-docs/pages/s2/styling.mdx b/packages/dev/s2-docs/pages/s2/styling.mdx
index 18c32540f8b..b0d3e13d2d7 100644
--- a/packages/dev/s2-docs/pages/s2/styling.mdx
+++ b/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
 
diff --git a/packages/dev/s2-docs/pages/s2/styling/Advanced.mdx b/packages/dev/s2-docs/pages/s2/styling/Advanced.mdx
index ff6cbf83781..50fc0baa377 100644
--- a/packages/dev/s2-docs/pages/s2/styling/Advanced.mdx
+++ b/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;
+}
+```

From a3d57a912dc0e9dc84c53b79e51c9fcf3451f5c2 Mon Sep 17 00:00:00 2001
From: Daniel Lu <dl1644@gmail.com>
Date: Mon, 3 Nov 2025 11:03:02 -0800
Subject: [PATCH 20/27] fix build links?

---
 packages/dev/s2-docs/pages/s2/styling.mdx | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/packages/dev/s2-docs/pages/s2/styling.mdx b/packages/dev/s2-docs/pages/s2/styling.mdx
index b0d3e13d2d7..e5928568abd 100644
--- a/packages/dev/s2-docs/pages/s2/styling.mdx
+++ b/packages/dev/s2-docs/pages/s2/styling.mdx
@@ -10,8 +10,8 @@ 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'}
+  {title: 'Advanced', url: './styling/Advanced.html'},
+  {title: 'Reference Table', url: './styling/Reference.html'}
 ];
 
 # Styling

From 30bab2283c4022fe8d4570468b80963ddbd4a741 Mon Sep 17 00:00:00 2001
From: Daniel Lu <dl1644@gmail.com>
Date: Mon, 3 Nov 2025 11:18:07 -0800
Subject: [PATCH 21/27] rename mdx file to fix all links

---
 packages/dev/s2-docs/pages/s2/styling.mdx                     | 4 ++--
 .../s2-docs/pages/s2/styling/{Advanced.mdx => advanced.mdx}   | 0
 .../s2-docs/pages/s2/styling/{Reference.mdx => reference.mdx} | 0
 3 files changed, 2 insertions(+), 2 deletions(-)
 rename packages/dev/s2-docs/pages/s2/styling/{Advanced.mdx => advanced.mdx} (100%)
 rename packages/dev/s2-docs/pages/s2/styling/{Reference.mdx => reference.mdx} (100%)

diff --git a/packages/dev/s2-docs/pages/s2/styling.mdx b/packages/dev/s2-docs/pages/s2/styling.mdx
index e5928568abd..b0d3e13d2d7 100644
--- a/packages/dev/s2-docs/pages/s2/styling.mdx
+++ b/packages/dev/s2-docs/pages/s2/styling.mdx
@@ -10,8 +10,8 @@ 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'}
+  {title: 'Advanced', url: './styling/advanced.html'},
+  {title: 'Reference Table', url: './styling/reference.html'}
 ];
 
 # Styling
diff --git a/packages/dev/s2-docs/pages/s2/styling/Advanced.mdx b/packages/dev/s2-docs/pages/s2/styling/advanced.mdx
similarity index 100%
rename from packages/dev/s2-docs/pages/s2/styling/Advanced.mdx
rename to packages/dev/s2-docs/pages/s2/styling/advanced.mdx
diff --git a/packages/dev/s2-docs/pages/s2/styling/Reference.mdx b/packages/dev/s2-docs/pages/s2/styling/reference.mdx
similarity index 100%
rename from packages/dev/s2-docs/pages/s2/styling/Reference.mdx
rename to packages/dev/s2-docs/pages/s2/styling/reference.mdx

From 5084b6bfa7066fbe90e520c9575422bf0df27dd0 Mon Sep 17 00:00:00 2001
From: Daniel Lu <dl1644@gmail.com>
Date: Mon, 3 Nov 2025 13:01:51 -0800
Subject: [PATCH 22/27] small fixes

---
 packages/dev/s2-docs/pages/s2/styling/advanced.mdx  | 2 +-
 packages/dev/s2-docs/pages/s2/styling/reference.mdx | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/packages/dev/s2-docs/pages/s2/styling/advanced.mdx b/packages/dev/s2-docs/pages/s2/styling/advanced.mdx
index 50fc0baa377..6a50851980b 100644
--- a/packages/dev/s2-docs/pages/s2/styling/advanced.mdx
+++ b/packages/dev/s2-docs/pages/s2/styling/advanced.mdx
@@ -215,7 +215,7 @@ function MyComponent({isQuiet, styles}: {isQuiet?: boolean, styles?: StyleString
 <MyComponent styles={userStyles} />
 ```
 
-The `iconStyle` macro should be used when styling Icons, see the [docs](../icons.html#iconstyle) for more information.
+The `iconStyle` macro should be used when styling Icons, see the [docs](../Icons.html#iconstyle) for more information.
 
 ## UNSAFE Style Overrides
 
diff --git a/packages/dev/s2-docs/pages/s2/styling/reference.mdx b/packages/dev/s2-docs/pages/s2/styling/reference.mdx
index 18331216a0a..aa7c3a5081d 100644
--- a/packages/dev/s2-docs/pages/s2/styling/reference.mdx
+++ b/packages/dev/s2-docs/pages/s2/styling/reference.mdx
@@ -8,7 +8,7 @@ export default Layout;
 
 export const omitFromNav = true;
 export const tags = ['style', 'macro', 'spectrum', 'custom', 'values', 'reference'];
-export const description = 'Reference table for the `style` macro';
+export const description = 'Reference table for the style macro';
 
 # Style Macro Reference
 

From 34ad8cc29ceeebdc405ea13ae171d33dfe610c8b Mon Sep 17 00:00:00 2001
From: Daniel Lu <dl1644@gmail.com>
Date: Mon, 3 Nov 2025 15:49:51 -0800
Subject: [PATCH 23/27] move reference out of subpage and merge styling page

---
 .../pages/s2/{styling => }/reference.mdx      |  16 +-
 packages/dev/s2-docs/pages/s2/styling.mdx     | 228 ++++++++++++++---
 .../dev/s2-docs/pages/s2/styling/advanced.mdx | 241 ------------------
 packages/dev/s2-docs/src/S2Colors.tsx         |   2 +-
 4 files changed, 198 insertions(+), 289 deletions(-)
 rename packages/dev/s2-docs/pages/s2/{styling => }/reference.mdx (87%)
 delete mode 100644 packages/dev/s2-docs/pages/s2/styling/advanced.mdx

diff --git a/packages/dev/s2-docs/pages/s2/styling/reference.mdx b/packages/dev/s2-docs/pages/s2/reference.mdx
similarity index 87%
rename from packages/dev/s2-docs/pages/s2/styling/reference.mdx
rename to packages/dev/s2-docs/pages/s2/reference.mdx
index aa7c3a5081d..6b2dd0fe46b 100644
--- a/packages/dev/s2-docs/pages/s2/styling/reference.mdx
+++ b/packages/dev/s2-docs/pages/s2/reference.mdx
@@ -1,18 +1,18 @@
-import {Layout} from '../../../src/Layout';
+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';
+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 omitFromNav = true;
+export const section = 'Components';
 export const tags = ['style', 'macro', 'spectrum', 'custom', 'values', 'reference'];
 export const description = 'Reference table for the style macro';
 
-# Style Macro Reference
+# Style Macro
 
-Reference for the properties and values supported by React Spectrum `style` macro.
+The `style` macro supports a constrained set of values per property that conform to Spectrum 2.
 
 ## Colors
 
diff --git a/packages/dev/s2-docs/pages/s2/styling.mdx b/packages/dev/s2-docs/pages/s2/styling.mdx
index b0d3e13d2d7..ca3232e390a 100644
--- a/packages/dev/s2-docs/pages/s2/styling.mdx
+++ b/packages/dev/s2-docs/pages/s2/styling.mdx
@@ -1,7 +1,5 @@
 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;
@@ -9,10 +7,6 @@ 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
 
@@ -99,58 +93,214 @@ import {Button} from '@react-spectrum/s2';
   'visibility'
 ]} />
 
-## Values
+## Conditional styles
 
-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.
+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.
 
-### Colors
+```tsx
+<div
+  className={style({
+    padding: {
+      default: 8,
+      lg: 32,
+      '@media (min-width: 2560px)': 64,
+    }
+  })}
+/>
+```
 
-All Spectrum 2 color tokens are available across color properties (e.g., `backgroundColor`, `color`, `borderColor`).
+Conditions are mutually exclusive and ordered. The macro uses CSS cascade layers so the last matching condition wins without specificity issues.
 
-<S2Colors />
+## Runtime conditions
 
-### Spacing
+When runtime conditions are detected (e.g., variants, UI states), the macro returns a function to resolve styles at runtime.
 
-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:
+```tsx
+import {style} from '@react-spectrum/s2/style' with {type: 'macro'};
 
-- `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.
+const styles = style({
+  backgroundColor: {
+    variant: {
+      primary: 'accent',
+      secondary: 'neutral'
+    }
+  }
+});
 
-### Sizing
+function MyComponent({variant}: {variant: 'primary' | 'secondary'}) {
+  return <div className={styles({variant})} />
+}
+```
 
-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.
+Boolean conditions starting with `is` or `allows` can be used directly without nesting:
 
-### Typography
+```tsx
+const styles = style({
+  backgroundColor: {
+    default: 'gray-100',
+    isSelected: 'gray-900',
+    allowsRemoving: 'gray-400'
+  }
+});
+
+<div className={styles({isSelected: true})} />
+```
 
-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.
+Runtime conditions work well with render props in React Aria Components. If you inline styles, you’ll get autocomplete for available conditions.
 
 ```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>
+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'
+    }
+  })}
+/>
 ```
 
-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`).
+### Nesting conditions
 
-<S2Typography />
+Nest conditions to apply styles when multiple conditions are true. Conditions at the same level are mutually exclusive; order determines precedence.
 
-<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>
+```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
+// 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',
+  columnGap: 8
+} as const;
+
+const styles = style({
+  ...horizontalStack,
+  backgroundColor: bannerBackground(),
+  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>
+```
 
-### Breakpoints
+## 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 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.
+The `iconStyle` macro should be used when styling Icons, see the [docs](./Icons.html#iconstyle) for more information.
 
 ## CSS optimization
 
diff --git a/packages/dev/s2-docs/pages/s2/styling/advanced.mdx b/packages/dev/s2-docs/pages/s2/styling/advanced.mdx
deleted file mode 100644
index 6a50851980b..00000000000
--- a/packages/dev/s2-docs/pages/s2/styling/advanced.mdx
+++ /dev/null
@@ -1,241 +0,0 @@
-import {Layout} from '../../../src/Layout';
-export default Layout;
-
-export const omitFromNav = true;
-export const tags = ['style', 'macro', 'spectrum', 'custom', 'advanced'];
-export const description = 'A guide to advanced styling use cases for React Spectrum';
-
-# Advanced styling guide
-
-A guide to advanced styling use cases for React Spectrum.
-
-## 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,
-      '@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
-
-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` or `allows` can be used directly without nesting:
-
-```tsx
-const styles = style({
-  backgroundColor: {
-    default: 'gray-100',
-    isSelected: 'gray-900',
-    allowsRemoving: 'gray-400'
-  }
-});
-
-<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
-// 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',
-  columnGap: 8
-} as const;
-
-const styles = style({
-  ...horizontalStack,
-  backgroundColor: bannerBackground(),
-  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>
-```
-
-## 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.
-
-## 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;
-}
-```
diff --git a/packages/dev/s2-docs/src/S2Colors.tsx b/packages/dev/s2-docs/src/S2Colors.tsx
index 8aab16355dc..946aa8eba13 100644
--- a/packages/dev/s2-docs/src/S2Colors.tsx
+++ b/packages/dev/s2-docs/src/S2Colors.tsx
@@ -102,7 +102,7 @@ export function S2Colors() {
           </div>
         </DisclosurePanel>
       </Disclosure>
-      <Disclosure isQuiet>
+      <Disclosure isQuiet styles={style({marginBottom: 16})}>
         <DisclosureTitle>Global colors</DisclosureTitle>
         <DisclosurePanel>
           <p>The following values are available across all color properties.</p>

From 6bf172454f6b8371c00d42720bb4f42e054e12a2 Mon Sep 17 00:00:00 2001
From: Daniel Lu <dl1644@gmail.com>
Date: Mon, 3 Nov 2025 16:04:11 -0800
Subject: [PATCH 24/27] make icons page lowercase and fix shorthands link

---
 packages/dev/s2-docs/pages/s2/index.mdx     | 2 +-
 packages/dev/s2-docs/pages/s2/reference.mdx | 2 +-
 packages/dev/s2-docs/pages/s2/styling.mdx   | 2 +-
 3 files changed, 3 insertions(+), 3 deletions(-)

diff --git a/packages/dev/s2-docs/pages/s2/index.mdx b/packages/dev/s2-docs/pages/s2/index.mdx
index 5856d0107d9..c6774e6e4ed 100644
--- a/packages/dev/s2-docs/pages/s2/index.mdx
+++ b/packages/dev/s2-docs/pages/s2/index.mdx
@@ -49,7 +49,7 @@ export const title = 'Home';
   {id: 'Divider', name: 'Divider', href: 'Divider.html'},
   {id: 'DropZone', name: 'DropZone', href: 'DropZone.html'},
   {id: 'Form', name: 'Form', href: 'Form.html'},
-  {id: 'Icons', name: 'Icons', href: 'Icons.html'},
+  {id: 'Icons', name: 'Icons', href: 'icons.html'},
   {id: 'IllustratedMessage', name: 'IllustratedMessage', href: 'IllustratedMessage.html'},
   {id: 'Illustrations', name: 'Illustrations', href: 'Illustrations.html'},
   {id: 'Image', name: 'Image', href: 'Image.html'},
diff --git a/packages/dev/s2-docs/pages/s2/reference.mdx b/packages/dev/s2-docs/pages/s2/reference.mdx
index 6b2dd0fe46b..2a5cf7013dd 100644
--- a/packages/dev/s2-docs/pages/s2/reference.mdx
+++ b/packages/dev/s2-docs/pages/s2/reference.mdx
@@ -37,7 +37,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](#shorthand), which sets `fontFamily`, `fontSize`, `fontWeight`, `lineHeight`, and `color`. You can override any of these individually.
+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.
 
 ```tsx
 <main>
diff --git a/packages/dev/s2-docs/pages/s2/styling.mdx b/packages/dev/s2-docs/pages/s2/styling.mdx
index ca3232e390a..603a083edcd 100644
--- a/packages/dev/s2-docs/pages/s2/styling.mdx
+++ b/packages/dev/s2-docs/pages/s2/styling.mdx
@@ -300,7 +300,7 @@ function MyComponent({isQuiet, styles}: {isQuiet?: boolean, styles?: StyleString
 <MyComponent styles={userStyles} />
 ```
 
-The `iconStyle` macro should be used when styling Icons, see the [docs](./Icons.html#iconstyle) for more information.
+The `iconStyle` macro should be used when styling Icons, see the [docs](./icons.html#iconstyle) for more information.
 
 ## CSS optimization
 

From 6e508f215b8ba6c10475771c089a9c5efd4d3253 Mon Sep 17 00:00:00 2001
From: Daniel Lu <dl1644@gmail.com>
Date: Mon, 3 Nov 2025 16:08:26 -0800
Subject: [PATCH 25/27] whoops forgot to make git track the capitalization
 rename

---
 packages/dev/s2-docs/pages/s2/{Icons.mdx => icons.mdx} | 0
 1 file changed, 0 insertions(+), 0 deletions(-)
 rename packages/dev/s2-docs/pages/s2/{Icons.mdx => icons.mdx} (100%)

diff --git a/packages/dev/s2-docs/pages/s2/Icons.mdx b/packages/dev/s2-docs/pages/s2/icons.mdx
similarity index 100%
rename from packages/dev/s2-docs/pages/s2/Icons.mdx
rename to packages/dev/s2-docs/pages/s2/icons.mdx

From 4b38f9802222ab35b935cbf1f8177ff7f9e5fd18 Mon Sep 17 00:00:00 2001
From: Daniel Lu <dl1644@gmail.com>
Date: Tue, 4 Nov 2025 15:15:28 -0800
Subject: [PATCH 26/27] addressing feedback from quarry team

---
 packages/dev/s2-docs/pages/s2/reference.mdx |  1 +
 packages/dev/s2-docs/pages/s2/styling.mdx   | 19 ++++++++++++++-----
 packages/dev/s2-docs/src/S2FAQ.tsx          |  8 +++++++-
 3 files changed, 22 insertions(+), 6 deletions(-)

diff --git a/packages/dev/s2-docs/pages/s2/reference.mdx b/packages/dev/s2-docs/pages/s2/reference.mdx
index 2a5cf7013dd..de8f4bab05e 100644
--- a/packages/dev/s2-docs/pages/s2/reference.mdx
+++ b/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 />
 
diff --git a/packages/dev/s2-docs/pages/s2/styling.mdx b/packages/dev/s2-docs/pages/s2/styling.mdx
index 603a083edcd..37aeb4eaf98 100644
--- a/packages/dev/s2-docs/pages/s2/styling.mdx
+++ b/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,7 +98,6 @@ 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
@@ -104,15 +105,21 @@ Note how the example below uses a predefined [breakpoint](./reference.html#condi
     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).
diff --git a/packages/dev/s2-docs/src/S2FAQ.tsx b/packages/dev/s2-docs/src/S2FAQ.tsx
index 127cfb1fb7b..a54db8e2388 100644
--- a/packages/dev/s2-docs/src/S2FAQ.tsx
+++ b/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>
   );
 }

From 61ba9db97cf5aa3ce1987eb67a204404328703d6 Mon Sep 17 00:00:00 2001
From: Daniel Lu <dl1644@gmail.com>
Date: Wed, 5 Nov 2025 12:03:28 -0800
Subject: [PATCH 27/27] review comments

---
 .../dev/s2-docs/pages/react-aria/styling.mdx  |  2 +-
 packages/dev/s2-docs/pages/s2/reference.mdx   |  1 +
 packages/dev/s2-docs/pages/s2/styling.mdx     | 36 ++-----------------
 3 files changed, 4 insertions(+), 35 deletions(-)

diff --git a/packages/dev/s2-docs/pages/react-aria/styling.mdx b/packages/dev/s2-docs/pages/react-aria/styling.mdx
index 4ca2eab3809..5ea84abab72 100644
--- a/packages/dev/s2-docs/pages/react-aria/styling.mdx
+++ b/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
 
diff --git a/packages/dev/s2-docs/pages/s2/reference.mdx b/packages/dev/s2-docs/pages/s2/reference.mdx
index de8f4bab05e..4d312d9a2ca 100644
--- a/packages/dev/s2-docs/pages/s2/reference.mdx
+++ b/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>
diff --git a/packages/dev/s2-docs/pages/s2/styling.mdx b/packages/dev/s2-docs/pages/s2/styling.mdx
index 37aeb4eaf98..1f244ade31e 100644
--- a/packages/dev/s2-docs/pages/s2/styling.mdx
+++ b/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).