docs: Style macro docs #9090

LFDanLu · 2025-10-23T23:59:15Z

Closes

✅ Pull Request Checklist:

Included link to corresponding React Spectrum GitHub Issue.
Added/updated unit tests and storybook for this change (for new code or code which already has tests).
Filled out test instructions.
Updated documentation (if it already exists for this component).
Looked at the Accessibility Practices for this feature - Aria Practices

📝 Test Instructions:

Go to the S2 Styling page and check the content. Also make sure the "Advanced" and "Reference Table" pages show up in desktop and mobile and check the content there as well

🧢 Your Project:

RSP

rspbot · 2025-10-24T00:07:17Z

Build successful! 🎉

LFDanLu · 2025-10-24T00:00:27Z

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

+- 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.


todo: replace with the new devtool extension @snowystinger is making

LFDanLu · 2025-10-24T00:01:18Z

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

+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.


Maybe add an example of a macro that would cause this?

i feel like there's several ways you could encounter this error (based on vibes) so a single example wouldn't be enough and might cause confusion for some people if their code doesn't match the example.

maybe would be good to find the most common ways you can encounter this error and offer a couple of possible solutions

yeah, its just been kinda hard finding which ways are the common ways people encounter this. I tried to allude to those fixes above but didn't want to fully document each since it might take too much room

LFDanLu · 2025-10-24T00:02:17Z

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

+> 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.


Already mentioned in the UNSAFE style overrides section but felt it was worth adding here anyways

LFDanLu · 2025-10-24T00:03:25Z

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

+<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>


Maybe overkill, but it felt like it was important to mention this up front so people realize that this is important

hmm yeah it's a little strong. I think after we re-structure the getting started page to include this it'll be unnecessary here.

sounds good, for now I've updated the copy to be Without these optimizations, the generated CSS may contain duplicate rules that affect bundle size and debugging as mentioned in another comment.

LFDanLu · 2025-10-24T00:08:24Z

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

+## 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.


We discussed previously that for this first pass that we want to stick with just modifying this page and create examples of style macros with RAC after the release of the docs. I've opted to keep this section and the once above it for now just to let people know about the existence of mergeStyles/iconStyle/and setting CSS variables with macros, but ideally these would move into an "Advanced" page or something similar to cut down on length here. Will comment on the file as to what I'm thinking the final division should look like

do we export mergeStyles yet? I don't see it in our exports?

not yet, but there was mention of doing so a while back in the beta slack channel. I've put it in the S2 1.0 canvas so we can track that

we can't really talk about it in the docs until we do, so probably best to remove this section for now

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

…_table

…ack to the visual

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

yihuiliao · 2025-10-30T22:44:37Z

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

+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 feel like there's several ways you could encounter this error (based on vibes) so a single example wouldn't be enough and might cause confusion for some people if their code doesn't match the example.

maybe would be good to find the most common ways you can encounter this error and offer a couple of possible solutions

yihuiliao · 2025-10-30T22:53:39Z

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

+
+## 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.


doesn't this repeat the content under Typography for the most part?

thats right, the content here is the same. Open to opinions if it should stay like that, I felt like some people might jump to this page on its own since it is a reference and therefore it would be useful to have the additional context/explanation

rspbot · 2025-10-31T00:41:35Z

Build successful! 🎉

…ro_docs

rspbot · 2025-10-31T18:39:31Z

Build successful! 🎉

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

snowystinger · 2025-11-02T22:38:57Z

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

  <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.


The typography section should also explain that you're expected to specify the font everywhere, we do not set it at a global level any longer
people have gotten confused on this point
I'll send a link in slack for one of the discussions

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

snowystinger · 2025-11-02T22:55:30Z

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

-<Button styles={buttonStyle}>Press me</Button>
-```
-
 ## CSS optimization


optimization sounds so optional

maybe it'd be better to structure all bundler setups into their own page which includes how the optimization setup works, but then it all sounds much more mandatory

happy for the team to weigh in here then, especially since it would fall within the changes made in #9126

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

snowystinger · 2025-11-02T23:04:37Z

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

@@ -0,0 +1,217 @@
+import {Layout} from '../../../src/Layout';


can't seem to visit this page in the build yet?

this page being advanced.html

does clicking on the "Advanced" in the ToC work for you here? https://reactspectrum.blob.core.windows.net/reactspectrum/30bab2283c4022fe8d4570468b80963ddbd4a741/s2-docs/s2/styling.html
Brings me here: https://reactspectrum.blob.core.windows.net/reactspectrum/30bab2283c4022fe8d4570468b80963ddbd4a741/s2-docs/s2/styling/advanced.html which seems to work

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

snowystinger · 2025-11-02T23:10:33Z

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

+import React from 'react';
+import {style} from '@react-spectrum/s2/style' with {type: 'macro'};
+
+export function S2FAQ() {


could probably pass Disclosure and DisclosurePanel to components for summary/details so we don't have to create separate components for each accordion we want

Otherwise, i suggest creating a single component that accepts the title and panel contents so we can keep the content inside the pages and have a reusable accordion outside in the components

could probably pass Disclosure and DisclosurePanel to components for summary/details so we don't have to create separate components for each accordion we want

not quite sure what you mean here, mind expanding a bit on components here?

components is a map that's passed to the mdx renderer in Layout, it matches tags as the document is rendered and applies whatever rendering is in the map for that tag, so we should be able to match summary/description in that map and render our own Disclosure for it

might need to chat to you directly, still not quite envisioning what the change here would be, but I think you are suggesting that in the mdx we'd put <Disclosure> and DisclosurePanel> directly and that Layout could then handle rendering that?
i.e.

styling.mdx <Disclosure> ...FAQ content </Disclosure>

happy to do that, but honestly I almost prefer the separate component if only for type checking in the IDE haha

yeah, i guess our component is a little too complicated to just represent with details/summary

but i vote for putting it into the MDX because this is all content, and content really shouldn't be in src

I'll see about putting this into a follow up after some of the other docs work.

snowystinger · 2025-11-02T23:11:27Z

packages/dev/s2-docs/src/styleProperties.ts

+ */
+
+// Properties that use PercentageProperty (accept LengthPercentage in addition to mapped values)
+const percentageProperties = new Set([


move this file inside the s2 pages area, it's a ts file, so won't be picked up as a new page

Just want to note that it is used by types.tsx in the same folder hence why I kept it here. Didn't really feel like it fit in the pages area since that is where the mdx pages were and we already had things like S2Colors/etc here

we should make a bit of a push to move content out of the components, but fine if there's others for now

reidbarber · 2025-11-03T18:27:57Z

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

+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.


These can link to the respective /mcp docs pages instead.

rspbot · 2025-11-05T20:12:54Z

Build successful! 🎉

rspbot · 2025-11-10T19:42:07Z

Build successful! 🎉

rspbot · 2025-11-10T19:43:22Z

Build successful! 🎉

snowystinger · 2025-11-10T19:57:18Z

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

+  'aria-label'?: string
+}
+
+export function GoUpOneLink(props: GoUpOneLinkProps = {}) {


thought i deleted this in favour of the more breadcrumb looking thing?

rspbot · 2025-11-10T20:33:00Z

Build successful! 🎉

…ro_docs

rspbot · 2025-11-11T00:05:01Z

Build successful! 🎉

devongovett

Good for now, but I still think we might want to refactor the order of the sections a bit. I'll think about it.

devongovett · 2025-11-11T00:26:23Z

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

+export const bannerBackground = () => 'blue-1000' as const;
+
+// component.tsx
+import {bannerBackground} from './style-utils' with {type: 'macro'};


Kinda confusing IMO. You also showed custom utilities in a separate code block below. Do we need this one too?

haha, this was the one that came up in slack, happy to get rid of it though, we can re-add if people run into it again

devongovett · 2025-11-11T00:26:57Z

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


 ## 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.


Suggested change

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.

Extract common styles into constants and spread them into `style` calls within the same file.

devongovett · 2025-11-11T00:27:26Z

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

 });
 ```

 Create custom utilities by defining your own macros.


Suggested change

Create custom utilities by defining your own macros as functions in a separate file.

devongovett · 2025-11-11T00:32:12Z

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

 </ListBoxItem>
 ```

+## Style macro


Seems a little out of place here. External folks might be confused to see this here especially since we aren't really pushing style macros externally yet. Do you think this should be under RAC or should we have a section on the RSP side that shows how to use style macros with RAC?

thats a fair point, I'm fine moving this section to the S2 styling docs side

devongovett · 2025-11-11T00:35:11Z

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

+<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>


hmm yeah it's a little strong. I think after we re-structure the getting started page to include this it'll be unnecessary here.

devongovett · 2025-11-11T00:45:51Z

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

 ## 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.


It's a bit strong. I wouldn't say obtuse styling bugs – not sure which bugs you mean. Maybe "Without these optimizations, the generated CSS may contain duplicate rules that affect bundle size and debugging."

I was mainly thinking along the lines of the issues that micro frontends ran into but I guess that was resolved with the "versioning" we added to the generated css. I'll update the copy here

devongovett · 2025-11-11T00:47:44Z

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

-```
+```
+
+## Developing with style macros


Maybe just "Developer tools"?

devongovett · 2025-11-11T00:48:17Z

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

+## 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:


I don't think we need to say this. We don't want to scare people.

"These tools improve the developer experience when using style macros:"

devongovett · 2025-11-11T00:53:53Z

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

+- 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`.


Suggested change

- 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`.

- If the viewport is larger than `2560px`, the padding is `64px`.

- Else if the viewport matches the `lg` [breakpoint](./reference.html#conditions) (`1024px`), the padding is `32px`.

- Otherwise, the padding is `8px`.

devongovett · 2025-11-11T00:56:50Z

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

-
 ## 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.


Suggested change

Define conditional values as objects to handle media queries, UI states (hover/press), and variants. This keeps all values for a property together.

Define conditional values such as media queries, UI states (e.g. hover, press), and style variants as objects. Conditional values are mutually exclusive: the last matching condition always wins.

LFDanLu added 2 commits October 23, 2025 11:48

add FAQ and other sections

edeaa2f

add section for creating custom components

8a1f97e

LFDanLu commented Oct 24, 2025

View reviewed changes

LFDanLu added 12 commits October 24, 2025 14:36

initial stab at extracting types from style macro

28eb788

testing sizing properties

457c59a

Merge branch 'main' of github.com:adobe/react-spectrum into reference…

a15c24f

…_table

revert export of theme object since it was breaking inference

819c076

adding more values

3b991ea

reorg

42b0406

add the rest of the properties and double check them

36f1a6f

add more type links

e2b29c9

add mdn links for common types and specific css properties

4c94cd0

add relative links so basecolors and various dimension strings link b…

83262ef

…ack to the visual

add descriptions to table and get rid of unessasary isRelative

5d2b172

add short hand and condition tables

980d3d6

yihuiliao reviewed Oct 30, 2025

View reviewed changes

LFDanLu added 3 commits October 30, 2025 16:18

add subpage for reference and advanced style macro section

59e9400

support subpage list under the ToC

a414886

forgot to move last bit of content

0b2751d

LFDanLu added 3 commits October 31, 2025 11:22

update FAQ, add mobile related pages, link from RAC styling

4ef4996

Merge branch 'main' of github.com:adobe/react-spectrum into style_mac…

b04b7af

…ro_docs

fix mobile styling

807beb0

LFDanLu changed the title ~~docs: (WIP) Style macro docs~~ docs: Style macro docs Oct 31, 2025

LFDanLu marked this pull request as ready for review October 31, 2025 18:30

LFDanLu added the ready for review label Oct 31, 2025

snowystinger reviewed Nov 2, 2025

View reviewed changes

reidbarber requested changes Nov 3, 2025

View reviewed changes

review comments

61ba9db

LFDanLu dismissed stale reviews from reidbarber and snowystinger via 61ba9db November 5, 2025 20:03

snowystinger previously approved these changes Nov 5, 2025

View reviewed changes

yihuiliao previously approved these changes Nov 5, 2025

View reviewed changes

LFDanLu dismissed stale reviews from yihuiliao and snowystinger via a9913cc November 10, 2025 19:32

snowystinger reviewed Nov 10, 2025

View reviewed changes

snowystinger previously approved these changes Nov 10, 2025

View reviewed changes

LFDanLu dismissed snowystinger’s stale review via 59a0fef November 10, 2025 20:24

reidbarber previously approved these changes Nov 10, 2025

View reviewed changes

snowystinger previously approved these changes Nov 10, 2025

View reviewed changes

LFDanLu added the release label Nov 10, 2025

LFDanLu added this pull request to the merge queue Nov 10, 2025

LFDanLu removed this pull request from the merge queue due to a manual request Nov 10, 2025

Merge branch 'main' of github.com:adobe/react-spectrum into style_mac…

cf728e8

…ro_docs

LFDanLu dismissed stale reviews from snowystinger and reidbarber via cf728e8 November 10, 2025 23:56

LFDanLu force-pushed the style_macro_docs branch from 59a0fef to cf728e8 Compare November 10, 2025 23:56

snowystinger approved these changes Nov 11, 2025

View reviewed changes

devongovett approved these changes Nov 11, 2025

View reviewed changes

LFDanLu added this pull request to the merge queue Nov 11, 2025

Merged via the queue into main with commit 2485ffa Nov 11, 2025
32 checks passed

LFDanLu deleted the style_macro_docs branch November 11, 2025 01:27

		- 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.


		## 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.

		@@ -0,0 +1,217 @@
		import {Layout} from '../../../src/Layout';


		## 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.


	Create custom utilities by defining your own macros as functions in a separate file.


		## 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.

	Define conditional values as objects to handle media queries, UI states (hover/press), and variants. This keeps all values for a property together.
	Define conditional values such as media queries, UI states (e.g. hover, press), and style variants as objects. Conditional values are mutually exclusive: the last matching condition always wins.

docs: Style macro docs #9090

docs: Style macro docs #9090

Conversation

LFDanLu commented Oct 23, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

✅ Pull Request Checklist:

📝 Test Instructions:

🧢 Your Project:

Uh oh!

rspbot commented Oct 24, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

rspbot commented Oct 31, 2025

Uh oh!

rspbot commented Oct 31, 2025

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

snowystinger Nov 3, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

LFDanLu commented Oct 23, 2025 •

edited

Loading

snowystinger Nov 3, 2025 •

edited

Loading