[WIP] chore(S2): audit style macro utilities

[reidbarber]

This PR audits the style macro utilities we use throughout @react-spectrum/s2 to help decide which ones we should export. This will make it easier for users to build custom S2 components that are similar to existing S2 components.

We should:

• Decide which ones to export
• Finalize naming/APIs for those
• Add docs + JSDocs

We probably want to export most of these, so it might be better to focus on which ones we don't want to export and why.

Utilities

Utility	Usage Count	Description	Export + Document?	Comments
baseColor()	77	Returns a stateful base color token set (default/hover/focus/pressed) for component color styling.	Yes	Already exported.
getAllowedOverrides()	57	Returns the list of allowed style override properties for the styles prop.
lightDark()	65	Produces a light/dark conditional color value for themes.	Yes	Already exported.
focusRing()	29	Provides consistent focus ring outline styles.	Yes	Already exported.
fontRelative()	26	Converts pixel values to a font-relative length based on base font size.	Yes	Already exported.
mergeStyles()	16	Merges multiple style strings together, combining properties from each style. Used for composing styles dynamically.
space()	20	Converts pixel values to Spectrum spacing tokens.	Yes	Already exported.
field()	14	Grid layout styles for form fields. Handles label positioning (top/side) and subgrid integration.
controlFont()	14	Returns font size values for controls based on the size prop (XS, S, M, L, XL).
colorMix()	12	Mixes two Spectrum colors by percentage to generate a blended token value.	Yes	Already exported.
fieldInput()	10	Styles for field input containers, including default width and size containment.
control()	9	Composite utility for pill or rounded rectangle shaped containers with text and icon slots. Supports wrapping text and icon-only modes.
controlSize()	9	Returns height/width values for controls based on size prop. Has 'sm' and 'md' variants.
size()	8	Converts a numeric size into a CSS calc expression suitable for sizing tokens.	Yes	Already exported.
raw()	8	Injects raw CSS strings into the style system with optional layer specification.
color()	7	Resolves a Spectrum color token to a CSS color value.	Yes	Already exported.
staticColor()	6	Sets container background color variable for static color variants (black/white).
colorScheme()	6	Configures the CSS color-scheme property for light/dark mode.
centerPadding()	6	Calculates vertical padding to center single-line content within a minimum height container.
controlBorderRadius()	5	Generates border radius for t-shirt sizes using the Major Second logarithmic scale (power of 1.125).
edgeToText()	4	Calculates spacing from edge to text content based on Spectrum spacing tokens.
keyframes()	4	Defines CSS keyframe animations.
fieldLabel()	3	Styles for field labels including font, cursor, and color states.
iconStyle()	1	Icon styling utility with size and color options.	Yes	Already exported.
linearGradient()	1	Creates animated linear gradients with color stops.

Types

Type	Description	Export + Document?	Comments
StylesProp	Style prop type with width properties
StylesPropWithHeight	Style prop type with width and height properties
StylesPropWithoutWidth	Style prop type without width properties
UnsafeClassName	Type for UNSAFE_className prop
UnsafeStyles	Interface for UNSAFE_style prop
StyleProps	Interface for style props
StyleString	String representing the output of the style macro.	Yes	Already exported.

Constants

Constant	Description	Export + Document?	Comments
widthProperties	Array of allowed width-related properties. Only used by Popover.
heightProperties	Array of allowed height-related properties. Only used by Popover.

✅ 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:

🧢 Your Project:

[rspbot]

Build successful! 🎉

• View the storybook
• View the S2 storybook
• View the S2 docs
• View the React Aria docs

[rspbot]

Build successful! 🎉

• View the storybook
• View the S2 storybook
• View the S2 docs
• View the React Aria docs

[rspbot]

## API Changes

@react-spectrum/s2

/@react-spectrum/s2:getAllowedOverrides

+getAllowedOverrides {
+  undefined: any
+  returnVal: undefined
+}

/@react-spectrum/s2:field

+field {
+  returnVal: undefined
+}

/@react-spectrum/s2:fieldLabel

+fieldLabel {
+  returnVal: undefined
+}

/@react-spectrum/s2:fieldInput

+fieldInput {
+  returnVal: undefined
+}

/@react-spectrum/s2:control

+control {
+  options: ControlOptions
+  returnVal: undefined
+}

/@react-spectrum/s2:controlFont

+controlFont {
+  returnVal: undefined
+}

/@react-spectrum/s2:controlSize

+controlSize {
+  size: 'sm' | 'md'
+  returnVal: undefined
+}

/@react-spectrum/s2:controlBorderRadius

+controlBorderRadius {
+  size: 'default' | 'sm'
+  returnVal: undefined
+}

/@react-spectrum/s2:centerPadding

+centerPadding {
+  minHeight: string
+  returnVal: undefined
+}

/@react-spectrum/s2:colorScheme

+colorScheme {
+  returnVal: undefined
+}

/@react-spectrum/s2:staticColor

+staticColor {
+  returnVal: undefined
+}

/@react-spectrum/s2:widthProperties

+widthProperties {
+  UNTYPED
+}

/@react-spectrum/s2:heightProperties

+heightProperties {
+  UNTYPED
+}

/@react-spectrum/s2:focusRing

+focusRing {
+  returnVal: undefined
+}

/@react-spectrum/s2:iconStyle

+iconStyle {
+  this: MacroContext | void
+  options: IconStyle
+  returnVal: undefined
+}

/@react-spectrum/s2:linearGradient

+linearGradient {
+  this: MacroContext | void
+  angle: string
+  tokens: Array<[SpectrumColor, number]>
+  returnVal: undefined
+}

/@react-spectrum/s2:edgeToText

+edgeToText {
+  this: MacroContext | void
+  height: keyof any
+  returnVal: undefined
+}

/@react-spectrum/s2:raw

+raw {
+  this: MacroContext | void
+  css: string
+  layer: any
+  returnVal: undefined
+}

/@react-spectrum/s2:keyframes

+keyframes {
+  this: MacroContext | void
+  css: string
+  returnVal: undefined
+}

/@react-spectrum/s2:mergeStyles

+mergeStyles {
+  styles: Array<StyleString | null | undefined>
+  returnVal: undefined
+}

/@react-spectrum/s2:StylesProp

+StylesProp {
+  S: undefined
+}

/@react-spectrum/s2:StylesPropWithHeight

+StylesPropWithHeight {
+  S: undefined
+}

/@react-spectrum/s2:StylesPropWithoutWidth

+StylesPropWithoutWidth {
+  S: undefined
+}

/@react-spectrum/s2:UnsafeClassName

+UnsafeClassName {
+  U: undefined
+}

/@react-spectrum/s2:UnsafeStyles

+UnsafeStyles {
+  UNSAFE_className?: UnsafeClassName
+  UNSAFE_style?: CSSProperties
+}

/@react-spectrum/s2:StyleProps

+StyleProps {
+  UNSAFE_className?: UnsafeClassName
+  UNSAFE_style?: CSSProperties
+  styles?: StylesProp
+}

---