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

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

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

…_table

…ack to the visual

yihuiliao · 2025-10-30T22:30:57Z

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

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


could we make use of disclosures here? (but maybe a follow-up if it takes too long to style and what not)

thats a good suggestion, I was a bit torn on if the current style was better or now (inspired by our own FAQ in github) but I've definitely seen both styles on other sites like MUI and Untitled UI. I'll bring this up with the rest of the team and see what people like

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

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-03T19:12:03Z

Build successful! 🎉

rspbot · 2025-11-03T19:26:45Z

Build successful! 🎉

reidbarber

Approving for testing, just a few comments.

reidbarber · 2025-11-03T19:33:31Z

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

+
+export const omitFromNav = true;
+export const tags = ['style', 'macro', 'spectrum', 'custom', 'values', 'reference'];
+export const description = 'Reference table for the `style` macro';


Maybe better as:

Suggested change

export const description = 'Reference table for the `style` macro';

export const description = 'Reference table for the style macro';

reidbarber · 2025-11-03T19:35:08Z

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

+<S2Colors />
+
+<StyleMacroProperties properties={getPropertyDefinitions('color')} />


Nit, we should add some margin between these:

reidbarber · 2025-11-03T19:38:41Z

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

+<MyComponent styles={userStyles} />
+```
+
+The `iconStyle` macro should be used when styling Icons, see the [docs](../icons.html#iconstyle) for more information.


This link is currently broken on the build because it needs be capitalized (../Icons.html#iconstyle), but I actually think it's correct to lowercase this page since it isn't a component. We could update this in a follow-up (we'd probably need to update a bunch of links).

devongovett · 2025-11-03T20:08:25Z

I got a 404 when trying to click on the "related pages" links

LFDanLu · 2025-11-03T20:57:04Z

@devongovett the related pages links on https://reactspectrum.blob.core.windows.net/reactspectrum/30bab2283c4022fe8d4570468b80963ddbd4a741/s2-docs/s2/styling.html? Those seem to work for me

…ro_docs

rspbot · 2025-11-03T21:10:40Z

Build successful! 🎉

LFDanLu · 2025-11-03T23:56:27Z

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

For those reviewing this page, compare the current experience with the old: https://reactspectrum.blob.core.windows.net/reactspectrum/5084b6bfa7066fbe90e520c9575422bf0df27dd0/s2-docs/s2/styling.html

In particular the organization/existence of subpage/contents, open to opinions as to which is preferred

rspbot · 2025-11-03T23:59:03Z

Build successful! 🎉

rspbot · 2025-11-04T00:13:08Z

Build successful! 🎉

rspbot · 2025-11-04T00:18:29Z

Build successful! 🎉

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

snowystinger · 2025-11-04T05:17:54Z

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

  {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'},


why would this be the only one with a lowercase? seems like the file should be renamed if that's what it relies on, that way it's more predictable.

really i'd like to get rid of all the uppercases in the urls... but that's a different issue

the convention that seems to exist currently is that component pages are capitalized (e.g. DropZone/Menu/etc) and that non component pages aren't (e.g. dnd.mdx/migrating.mdx/etc) and icons fits into the latter. The file should be renamed to be lower case as well with my last commit, forgot to force git to recognize that change since it didn't automatically

snowystinger · 2025-11-04T05:24:45Z

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.


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

…ro_docs

rspbot · 2025-11-04T23:24:16Z

Build successful! 🎉

rspbot · 2025-11-04T23:27:35Z

Build successful! 🎉

snowystinger · 2025-11-05T02:50:23Z

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

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


reuse that inline alert you wrote?

snowystinger · 2025-11-05T03:10:03Z

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

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


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

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

LFDanLu added 2 commits November 3, 2025 11:00

review comments

0c6ac3f

fix build links?

a3d57a9

rename mdx file to fix all links

30bab22

reidbarber previously approved these changes Nov 3, 2025

View reviewed changes

snowystinger previously approved these changes Nov 3, 2025

View reviewed changes

LFDanLu added 2 commits November 3, 2025 13:00

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

44b0d8d

…ro_docs

small fixes

5084b6b

LFDanLu dismissed stale reviews from snowystinger and reidbarber via 5084b6b November 3, 2025 21:01

snowystinger previously approved these changes Nov 3, 2025

View reviewed changes

move reference out of subpage and merge styling page

34ad8cc

LFDanLu dismissed snowystinger’s stale review via 34ad8cc November 3, 2025 23:49

LFDanLu commented Nov 3, 2025

View reviewed changes

LFDanLu added 2 commits November 3, 2025 16:04

make icons page lowercase and fix shorthands link

6bf1724

whoops forgot to make git track the capitalization rename

6e508f2

snowystinger reviewed Nov 4, 2025

View reviewed changes

LFDanLu added 2 commits November 4, 2025 15:15

addressing feedback from quarry team

4b38f98

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

2e13868

…ro_docs

snowystinger approved these changes Nov 5, 2025

View reviewed changes

		- 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';

	export const description = 'Reference table for the `style` macro';
	export const description = 'Reference table for the style macro';

		<S2Colors />

		<StyleMacroProperties properties={getPropertyDefinitions('color')} />

docs: Style macro docs #9090

Are you sure you want to change the base?

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!

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!

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!

Choose a reason for hiding this comment

Uh oh!

LFDanLu commented Oct 23, 2025 •

edited

Loading

snowystinger Nov 3, 2025 •

edited

Loading