diff --git a/packages/@react-spectrum/s2/style/index.ts b/packages/@react-spectrum/s2/style/index.ts
index 33c4aa925b3..7ca5b24f0b4 100644
--- a/packages/@react-spectrum/s2/style/index.ts
+++ b/packages/@react-spectrum/s2/style/index.ts
@@ -77,7 +77,7 @@ const iconSizes = {
 
 export function iconStyle(this: MacroContext | void, options: IconStyle): StyleString<Exclude<keyof IconStyle, 'color' | 'size'>> {
   let {size = 'M', color, ...styles} = options;
-  
+
   if (color) {
     styles['--iconPrimary'] = {
       type: 'fill',
diff --git a/packages/dev/s2-docs/pages/react-aria/styling.mdx b/packages/dev/s2-docs/pages/react-aria/styling.mdx
index c1b480a52ae..5ea84abab72 100644
--- a/packages/dev/s2-docs/pages/react-aria/styling.mdx
+++ b/packages/dev/s2-docs/pages/react-aria/styling.mdx
@@ -242,9 +242,28 @@ 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/).
+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/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
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
new file mode 100644
index 00000000000..4d312d9a2ca
--- /dev/null
+++ b/packages/dev/s2-docs/pages/s2/reference.mdx
@@ -0,0 +1,82 @@
+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';
+export default Layout;
+
+export const section = 'Components';
+export const tags = ['style', 'macro', 'spectrum', 'custom', 'values', 'reference'];
+export const description = 'Reference table for the style macro';
+
+# Style Macro
+
+The `style` macro supports a constrained set of values per property that conform to Spectrum 2.
+
+## 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 />
+
+<StyleMacroProperties properties={getPropertyDefinitions('color')} />
+
+## 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.
+- `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.
+
+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')} />
+
+## 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>
+  <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 />
+
+
+<StyleMacroProperties properties={getPropertyDefinitions('text')} />
+
+
+## Effects
+
+<StyleMacroProperties properties={getPropertyDefinitions('effects')} />
+
+## Layout
+
+<StyleMacroProperties properties={getPropertyDefinitions('layout')} />
+
+## Misc
+
+<StyleMacroProperties properties={getPropertyDefinitions('misc')} />
+
+## 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/pages/s2/styling.mdx b/packages/dev/s2-docs/pages/s2/styling.mdx
index 3735835c868..1f244ade31e 100644
--- a/packages/dev/s2-docs/pages/s2/styling.mdx
+++ b/packages/dev/s2-docs/pages/s2/styling.mdx
@@ -1,8 +1,7 @@
 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;
 
 export const section = 'Guides';
@@ -11,11 +10,13 @@ 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
 
-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'};
@@ -37,6 +38,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 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>
+
 ## Spectrum components
 
 The `styles` prop accepts a limited set of CSS properties, including layout, spacing, sizing, and positioning. Other styles such as colors and internal padding cannot be customized within Spectrum components.
@@ -86,77 +95,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.
-
-### 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.
-
-### 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.
-
-```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 />
-
-<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>
-
 ## 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.
@@ -166,12 +104,19 @@ 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
     }
   })}
 />
 ```
 
+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
@@ -195,13 +140,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 +168,7 @@ import {style} from '@react-spectrum/s2/style' with {type: 'macro'};
       isSelected: 'gray-900'
     }
   })}
-/> 
+/>
 ```
 
 ### Nesting conditions
@@ -253,6 +199,11 @@ const styles = style({
 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',
@@ -261,6 +212,7 @@ const horizontalStack = {
 
 const styles = style({
   ...horizontalStack,
+  backgroundColor: bannerBackground(),
   columnGap: 4
 });
 ```
@@ -308,9 +260,28 @@ 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'
+});
+```
+
 ## 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).
@@ -362,4 +333,22 @@ 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](../react-aria/mcp.html) and [React Spectrum](./mcp.html) respectively that interface with the docs.
+
+## FAQ
+
+<S2FAQ />
diff --git a/packages/dev/s2-docs/src/Layout.tsx b/packages/dev/s2-docs/src/Layout.tsx
index 6f949230edd..4448c8b3463 100644
--- a/packages/dev/s2-docs/src/Layout.tsx
+++ b/packages/dev/s2-docs/src/Layout.tsx
@@ -267,6 +267,9 @@ export function Layout(props: PageProps & {children: ReactElement<any>}) {
                       components,
                     pages
                   })}
+                  {currentPage.exports?.relatedPages && (
+                    <MobileRelatedPages pages={currentPage.exports.relatedPages} />
+                  )}
                 </article>
               </CodePlatterProvider>
               {hasToC && <aside
@@ -285,6 +288,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>
@@ -309,10 +315,60 @@ 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 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 (
     <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 e77f6553e37..6bfdc39b5c9 100644
--- a/packages/dev/s2-docs/src/Nav.tsx
+++ b/packages/dev/s2-docs/src/Nav.tsx
@@ -11,7 +11,7 @@ export function Nav({pages, currentPage}: PageProps) {
   let currentLibrary = getLibraryFromPage(currentPage);
   let sections = new Map();
   for (let page of pages) {
-    if (page.exports?.hideNav) {
+    if (page.exports?.hideNav || page.exports?.omitFromNav) {
       continue;
     }
 
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>
diff --git a/packages/dev/s2-docs/src/S2FAQ.tsx b/packages/dev/s2-docs/src/S2FAQ.tsx
new file mode 100644
index 00000000000..a54db8e2388
--- /dev/null
+++ b/packages/dev/s2-docs/src/S2FAQ.tsx
@@ -0,0 +1,43 @@
+import {Disclosure, DisclosurePanel, DisclosureTitle, Link} 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 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.
+        </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>
+      <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>
+  );
+}
diff --git a/packages/dev/s2-docs/src/styleProperties.ts b/packages/dev/s2-docs/src/styleProperties.ts
new file mode 100644
index 00000000000..7df98cc25ab
--- /dev/null
+++ b/packages/dev/s2-docs/src/styleProperties.ts
@@ -0,0 +1,594 @@
+/*
+ * 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.
+ */
+
+// 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'
+]);
+
+// 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
+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 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[]} = {
+  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',
+    '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', 'baseColors'
+  ],
+  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', 'baseColors'
+  ],
+  stroke: ['none', 'currentColor', 'baseColors']
+};
+
+const dimensionsPropertyValues: {[key: string]: string[]} = {
+  borderSpacing: [],
+  flexBasis: ['auto', 'full'],
+  rowGap: relativeSpacingValues,
+  columnGap: relativeSpacingValues,
+  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: ['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'],
+  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'],
+  insetEnd: ['auto', 'full'],
+  top: ['auto', 'full'],
+  left: ['auto', 'full'],
+  bottom: ['auto', 'full'],
+  right: ['auto', 'full'],
+  aspectRatio: ['auto', 'square', 'video', 'number / number']
+};
+
+const textPropertyValues: {[key: string]: string[]} = {
+  fontFamily: ['sans', 'serif', 'code'],
+  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'],
+  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']
+};
+
+const effectsPropertyValues: {[key: string]: string[]} = {
+  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 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'],
+  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'],
+  opacity: ['number'],
+  outlineStyle: ['none', 'solid', 'dashed', 'dotted', 'double', 'inset'],
+  outlineOffset: ['number'],
+  outlineWidth: ['0', '1', '2', '4'],
+  transition: ['default', 'colors', 'opacity', 'shadow', 'transform', 'all', 'none'],
+  transitionDelay: ['string', 'number'],
+  transitionDuration: ['string', 'number'],
+  transitionTimingFunction: ['default', 'linear', 'in', 'out', 'in-out'],
+  animation: ['string'],
+  animationDuration: ['string', 'number'],
+  animationDelay: ['string', 'number'],
+  animationDirection: ['normal', 'reverse', 'alternate', 'alternate-reverse'],
+  animationFillMode: ['none', 'forwards', 'backwards', 'both'],
+  animationIterationCount: ['string', 'number'],
+  animationTimingFunction: ['default', 'linear', 'in', 'out', 'in-out'],
+  animationPlayState: ['paused', 'running']
+};
+
+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'],
+  // these will be handled via specific links
+  flexShrink: [],
+  flexGrow: [],
+  gridColumnStart: [],
+  gridColumnEnd: [],
+  gridRowStart: [],
+  gridRowEnd: [],
+  gridAutoFlow: ['row', 'column', 'dense', 'row dense', 'column dense'],
+  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'],
+  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'],
+  order: ['number']
+};
+
+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'],
+  zIndex: ['number'],
+  disableTapHighlight: ['true'],
+  unicodeBidi: ['normal', 'embed', 'bidi-override', 'isolate', 'isolate-override', 'plaintext'],
+  caretColor: ['auto', 'transparent']
+};
+
+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[]} = {
+  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,
+  dimensions: dimensionsPropertyValues,
+  text: textPropertyValues,
+  effects: effectsPropertyValues,
+  layout: layoutPropertyValues,
+  misc: miscPropertyValues,
+  conditions: conditionMapping
+};
+
+export function getAdditionalTypes(propertyName: string): string[] {
+  let types: string[] = [];
+
+  if (baseSpacingProperties.has(propertyName)) {
+    types.push('baseSpacing');
+  }
+
+  if (negativeSpacingProperties.has(propertyName)) {
+    types.push('negativeSpacing');
+  }
+
+  if (sizingProperties.has(propertyName)) {
+    types.push('number', 'LengthPercentage');
+  }
+
+  if (percentageProperties.has(propertyName)) {
+    types.push('LengthPercentage');
+  }
+
+  return types;
+}
+
+export const spacingTypeValues = {
+  baseSpacing: baseSpacingValues,
+  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} = {
+  'text-to-control': '#dimensions',
+  'text-to-visual': '#dimensions',
+  'edge-to-text': '#dimensions',
+  'pill': '#dimensions',
+  'baseColors': '#colors',
+  'fontSize': '#text'
+};
+
+// 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'
+};
+
+// 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'
+  },
+  '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'
+  }
+};
+
+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.',
+  '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,
+  mapping?: string[]
+}
+
+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)) {
+    let links: {[value: string]: {href: string, isRelative?: boolean}} = {};
+
+    if (mdnPropertyLinks[name]) {
+      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) {
+        // 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]) {
+          links[value] = {href: mdnTypeLinks[value]};
+        } else if (relativeLinks[value]) {
+          links[value] = {href: relativeLinks[value], isRelative: true};
+        }
+      }
+    }
+
+    result[name] = {
+      values,
+      additionalTypes: getAdditionalTypes(name),
+      links: Object.keys(links).length > 0 ? links : undefined,
+      description: propertyDescriptions[name]
+    };
+  }
+  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 edd33c02c94..015c5f53727 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';
@@ -47,7 +48,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 +695,164 @@ function TemplateLiteral({elements}: TTemplate) {
     </>
   );
 }
+
+const styleMacroTypeLinks = {
+  '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,
+  link?: string
+}
+
+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[],
+  links?: {[value: string]: {href: string, isRelative?: boolean}},
+  description?: string,
+  mapping?: string[]
+}
+
+interface StyleMacroPropertiesProps {
+  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>
+      <TableHeader>
+        <tr>
+          <TableColumn>Property</TableColumn>
+          <TableColumn>Values</TableColumn>
+          {hasMapping && <TableColumn>Mapping</TableColumn>}
+        </tr>
+      </TableHeader>
+      <TableBody>
+        {propertyNames.map((propertyName, index) => {
+          let propDef = properties[propertyName];
+          let values = propDef.values;
+          let links = propDef.links || {};
+
+          return (
+            <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>
+                    ))}
+                    {propDef.additionalTypes && propDef.additionalTypes.map((typeName, i) => {
+                      let typeLink = styleMacroTypeLinks[typeName];
+                      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
+                            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>
+                {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={hasMapping ? 3 : 2}>{propDef.description}</TableCell>
+                </TableRow>
+              )}
+            </React.Fragment>
+          );
+        })}
+      </TableBody>
+    </Table>
+  );
+}