From b8b068822998c859a98d4ba94270eba8f57484c6 Mon Sep 17 00:00:00 2001
From: Robert Snow <rsnow@adobe.com>
Date: Thu, 18 Jun 2026 05:47:15 +1000
Subject: [PATCH 1/4] chore: Audit style props in AI package (#10218)

* chore: Audit style props in AI package

* more cleanup

* get rid of unsafe and simplify to just use styleString

also updated chat to be more consistent and other audit todos

* add missing style props jsdoc

* match toggleButtonGroup style prop type

---------

Co-authored-by: Daniel Lu <dl1644@gmail.com>
---
 .../@react-spectrum/ai/src/AttachmentList.tsx | 25 ++++++---
 packages/@react-spectrum/ai/src/Chat.tsx      | 52 ++++++++++++-------
 .../@react-spectrum/ai/src/HorizontalCard.tsx |  2 +-
 .../ai/src/MessageFeedback.tsx                | 12 ++---
 .../@react-spectrum/ai/src/MessageSource.tsx  | 36 +++----------
 .../ai/src/MessageSuggestion.tsx              | 12 +++--
 .../@react-spectrum/ai/src/PromptField.tsx    | 10 ++--
 .../@react-spectrum/ai/src/ResponseStatus.tsx | 11 ++--
 .../@react-spectrum/ai/src/UserMessage.tsx    |  2 +-
 packages/@react-spectrum/ai/src/types.ts      | 13 -----
 .../ai/stories/Chat.stories.tsx               | 38 ++++----------
 .../src/gridlist/useGridListItem.ts           |  2 -
 .../src/selection/ListKeyboardDelegate.ts     |  5 +-
 13 files changed, 91 insertions(+), 129 deletions(-)
 delete mode 100644 packages/@react-spectrum/ai/src/types.ts

diff --git a/packages/@react-spectrum/ai/src/AttachmentList.tsx b/packages/@react-spectrum/ai/src/AttachmentList.tsx
index 8881b4426b0..a56dcf1b323 100644
--- a/packages/@react-spectrum/ai/src/AttachmentList.tsx
+++ b/packages/@react-spectrum/ai/src/AttachmentList.tsx
@@ -10,7 +10,13 @@
  * governing permissions and limitations under the License.
  */
 
-import {AriaLabelingProps, DOMRef, forwardRefType, GlobalDOMAttributes} from '@react-types/shared';
+import {
+  AriaLabelingProps,
+  DOMProps,
+  DOMRef,
+  forwardRefType,
+  GlobalDOMAttributes
+} from '@react-types/shared';
 import {baseColor, focusRing, style} from '@react-spectrum/s2/style' with {type: 'macro'};
 import {BasicHorizontalCard} from './HorizontalCard';
 import {Button} from 'react-aria-components/Button';
@@ -22,7 +28,7 @@ import {ImageContext} from '@react-spectrum/s2/Image';
 import {mergeStyles} from '@react-spectrum/s2/mergeStyles';
 import {pressScale} from '@react-spectrum/s2/pressScale';
 import {ProgressCircle} from '@react-spectrum/s2/ProgressCircle';
-import {StyleString} from './types';
+import {StyleString} from '@react-spectrum/s2/style' with {type: 'macro'};
 import {
   Tag,
   TagGroup,
@@ -120,6 +126,7 @@ const CloseButton = function CloseButton(props) {
 
 export interface AttachmentListProps<T>
   extends
+    DOMProps,
     Omit<
       TagGroupProps,
       | 'children'
@@ -148,12 +155,13 @@ export const AttachmentList = (forwardRef as forwardRefType)(function Attachment
   props: AttachmentListProps<T>,
   ref: DOMRef<HTMLDivElement>
 ) {
+  let {styles, items, children, dependencies, ...otherProps} = props;
   let domRef = useDOMRef(ref);
   return (
-    <TagGroup {...props} className={props.styles} ref={domRef}>
+    <TagGroup {...otherProps} className={styles} ref={domRef}>
       <TagList
-        items={props.items}
-        dependencies={props.dependencies}
+        items={items}
+        dependencies={dependencies}
         className={style({
           display: 'flex',
           flexDirection: 'row',
@@ -162,7 +170,7 @@ export const AttachmentList = (forwardRef as forwardRefType)(function Attachment
           alignItems: 'center',
           width: 'full'
         })}>
-        {props.children}
+        {children}
       </TagList>
     </TagGroup>
   );
@@ -172,7 +180,7 @@ export interface AttachmentProps
   extends
     Omit<CardProps, 'styles' | 'UNSAFE_className' | 'UNSAFE_style'>,
     AriaLabelingProps,
-    Pick<TagProps, 'id' | 'textValue'> {
+    Pick<TagProps, 'id' | 'textValue' | 'render'> {
   /** The children of the Attachment. */
   children: ReactNode | ((renderProps: AttachmentRenderProps) => ReactNode);
   uploadProgress?: number;
@@ -200,6 +208,7 @@ export const Attachment = forwardRef(function Attachment(
     'aria-label': ariaLabel,
     'aria-labelledby': ariaLabelledby,
     'aria-describedby': ariaDescribedby,
+    styles,
     ...otherProps
   } = props;
   let domRef = useDOMRef(ref);
@@ -211,7 +220,7 @@ export const Attachment = forwardRef(function Attachment(
       aria-labelledby={ariaLabelledby}
       aria-describedby={ariaDescribedby}
       ref={domRef}
-      className={renderProps => mergeStyles(tagStyles({...renderProps}), props.styles)}>
+      className={renderProps => mergeStyles(tagStyles({...renderProps}), styles)}>
       <BasicHorizontalCard {...otherProps}>
         {props.uploadProgress != null && props.uploadProgress < 100 && (
           <div
diff --git a/packages/@react-spectrum/ai/src/Chat.tsx b/packages/@react-spectrum/ai/src/Chat.tsx
index 1052229605a..162837b1ba4 100644
--- a/packages/@react-spectrum/ai/src/Chat.tsx
+++ b/packages/@react-spectrum/ai/src/Chat.tsx
@@ -23,9 +23,9 @@ import {
   useRef,
   useState
 } from 'react';
-import type {CSSProperties} from 'react';
 import {DEFAULT_SLOT, Provider} from 'react-aria-components/slots';
 import {DOMRef, forwardRefType} from '@react-types/shared';
+import {focusRing, style, StyleString} from '@react-spectrum/s2/style' with {type: 'macro'};
 import {
   GridList,
   GridListItem,
@@ -34,7 +34,7 @@ import {
 } from 'react-aria-components/GridList';
 // @ts-ignore
 import intlMessages from '../intl/*.json';
-import {style} from '@react-spectrum/s2/style' with {type: 'macro'};
+import {mergeStyles} from '@react-spectrum/s2/mergeStyles';
 import {useDOMRef} from './useDOMRef';
 import {useEnterAnimation, useExitAnimation} from 'react-aria/private/utils/animation';
 import {useFocusWithin} from 'react-aria/useFocusWithin';
@@ -92,8 +92,13 @@ const ThreadScrollButtonContext = createContext<ThreadScrollButtonContextValue>(
 
 // TODO: make this more RAC like (aka default class name and other RAC prop)
 export interface ChatProps {
-  className?: string;
-  style?: CSSProperties;
+  /**
+   * Spectrum-defined styles, returned by the `style()` macro.
+   */
+  styles?: StyleString;
+  /**
+   * Children of the chat, such as Thread, PromptField, and ThreadScrollButton.
+   */
   children?: ReactNode;
 }
 
@@ -101,7 +106,7 @@ export const Chat = /*#__PURE__*/ (forwardRef as forwardRefType)(function Chat(
   props: ChatProps,
   ref: DOMRef<HTMLDivElement>
 ) {
-  let {children, className, style} = props;
+  let {children, styles} = props;
   let domRef = useDOMRef(ref);
   let isFieldFocusedRef = useRef(false);
   let isChatFocusWithinRef = useRef(false);
@@ -190,24 +195,28 @@ export const Chat = /*#__PURE__*/ (forwardRef as forwardRefType)(function Chat(
           }
         ]
       ]}>
-      <div ref={domRef} className={className} style={style} {...focusWithinProps}>
+      <div ref={domRef} className={styles} {...focusWithinProps}>
         {children}
       </div>
     </Provider>
   );
 });
 
-// TODO: update the items/className/children/etc type to reflect a thread specific classname once we finalize API
 export interface ThreadProps<T extends object> extends Pick<
   GridListProps<T>,
-  'items' | 'children' | 'UNSTABLE_focusOnEntry' | 'aria-label' | 'aria-labelledby' | 'className'
-> {}
+  'items' | 'children' | 'UNSTABLE_focusOnEntry' | 'aria-label' | 'aria-labelledby'
+> {
+  /**
+   * Spectrum-defined styles, returned by the `style()` macro.
+   */
+  styles?: StyleString;
+}
 
 export function Thread<T extends object>(props: ThreadProps<T>) {
   let {
     items,
     children,
-    className,
+    styles,
     UNSTABLE_focusOnEntry,
     'aria-label': ariaLabel,
     'aria-labelledby': ariaLabelledby
@@ -267,7 +276,7 @@ export function Thread<T extends object>(props: ThreadProps<T>) {
         boxSizing: 'border-box',
         minWidth: 0
       }}
-      className={className}>
+      className={styles}>
       {children}
     </GridList>
   );
@@ -314,11 +323,16 @@ function ThreadScrollButtonInner({domRef, isExiting, children}: ThreadScrollButt
   );
 }
 
-// TODO: update the className type to reflect a thread specific classname once we finalize API
-export interface ThreadItemProps extends Pick<
-  GridListItemProps,
-  'className' | 'children' | 'textValue'
-> {
+const threadItemBase = style({
+  ...focusRing(),
+  borderRadius: 'default'
+});
+
+export interface ThreadItemProps extends Pick<GridListItemProps, 'children' | 'textValue'> {
+  /**
+   * Spectrum-defined styles, returned by the `style()` macro.
+   */
+  styles?: StyleString;
   /** Whether or not the item's content is currently being streamed in. */
   isStreaming?: boolean;
   /** Announce textValue on mount even when isStreaming is provided. */
@@ -326,7 +340,7 @@ export interface ThreadItemProps extends Pick<
 }
 
 export function ThreadItem(props: ThreadItemProps) {
-  let {className, children, textValue = ' ', isStreaming, shouldAnnounceOnMount} = props;
+  let {styles, children, textValue = ' ', isStreaming, shouldAnnounceOnMount} = props;
   let {announceItem} = useContext(InternalChatContext);
 
   // TODO: using aria-live on the gridlist item was pretty chatty and the streaming causes the text announcement
@@ -354,7 +368,9 @@ export function ThreadItem(props: ThreadItemProps) {
   }, [isStreaming, isStreamingNow, textValue, announceItem]);
 
   return (
-    <GridListItem textValue={textValue} className={className}>
+    <GridListItem
+      textValue={textValue}
+      className={renderProps => mergeStyles(threadItemBase({...renderProps}), styles)}>
       {children}
     </GridListItem>
   );
diff --git a/packages/@react-spectrum/ai/src/HorizontalCard.tsx b/packages/@react-spectrum/ai/src/HorizontalCard.tsx
index 4135e44dbb3..df6d6ad7bcc 100644
--- a/packages/@react-spectrum/ai/src/HorizontalCard.tsx
+++ b/packages/@react-spectrum/ai/src/HorizontalCard.tsx
@@ -36,7 +36,7 @@ import {LinkButtonContext} from '@react-spectrum/s2/LinkButton';
 import {mergeStyles} from '@react-spectrum/s2/mergeStyles';
 import {pressScale} from '@react-spectrum/s2/pressScale';
 import {SkeletonContext, useIsSkeleton} from '@react-spectrum/s2/Skeleton';
-import {StyleString} from './types';
+import {StyleString} from '@react-spectrum/s2/style' with {type: 'macro'};
 import {TextContext} from '@react-spectrum/s2/Text';
 import {useDOMRef} from './useDOMRef';
 interface HorizontalCardRenderProps {
diff --git a/packages/@react-spectrum/ai/src/MessageFeedback.tsx b/packages/@react-spectrum/ai/src/MessageFeedback.tsx
index fb34798849f..2f692b858b8 100644
--- a/packages/@react-spectrum/ai/src/MessageFeedback.tsx
+++ b/packages/@react-spectrum/ai/src/MessageFeedback.tsx
@@ -16,7 +16,7 @@ import {forwardRef} from 'react';
 // @ts-ignore
 import intlMessages from '../intl/*.json';
 import {SlotProps} from 'react-aria-components/slots';
-import {StyleString} from './types';
+import {StylesPropWithHeight} from '@react-spectrum/s2';
 import ThumbDown from '@react-spectrum/s2/icons/ThumbDown';
 import ThumbUp from '@react-spectrum/s2/icons/ThumbUp';
 import {ToggleButton} from '@react-spectrum/s2/ToggleButton';
@@ -39,10 +39,8 @@ export interface MessageFeedbackProps extends DOMProps, AriaLabelingProps, SlotP
   thumbUpLabel?: string;
   /** Accessible label for the thumbs down button. */
   thumbDownLabel?: string;
-  /**
-   * Spectrum-defined styles, returned by the `style()` macro.
-   */
-  styles?: StyleString;
+  /** Spectrum-defined styles, returned by the `style()` macro. */
+  styles?: StylesPropWithHeight;
 }
 
 function selectionToValue(selection: Selection): MessageFeedbackValue {
@@ -83,9 +81,7 @@ export const MessageFeedback = forwardRef(function MessageFeedback(
       defaultSelectedKeys={defaultSelectedKeys}
       onSelectionChange={handleSelectionChange}
       isDisabled={isDisabled}
-      // Pass styles to UNSAFE because S2 ToggleButtonGroup styles have type StylesPropWithHeight which restrict what can be overridden
-      //@ts-ignore
-      UNSAFE_className={styles}>
+      styles={styles}>
       <ToggleButton
         id="up"
         isQuiet
diff --git a/packages/@react-spectrum/ai/src/MessageSource.tsx b/packages/@react-spectrum/ai/src/MessageSource.tsx
index e27648f6bd8..d8f888e9c38 100644
--- a/packages/@react-spectrum/ai/src/MessageSource.tsx
+++ b/packages/@react-spectrum/ai/src/MessageSource.tsx
@@ -31,19 +31,15 @@ import {mergeStyles} from '@react-spectrum/s2/mergeStyles';
 import {NumberFormatter} from '@internationalized/number';
 import React, {createContext, forwardRef, useContext} from 'react';
 import {SlotProps} from 'react-aria-components/slots';
-import {StyleString} from './types';
+import {StyleString} from '@react-spectrum/s2/style' with {type: 'macro'};
 import {useDOMRef} from './useDOMRef';
 import {useLocale} from 'react-aria/I18nProvider';
 
 export interface MessageSourceProps extends Omit<
   DisclosureProps,
-  'isQuiet' | 'styles' | 'UNSAFE_className' | 'UNSAFE_style'
+  'isQuiet' | 'UNSAFE_className' | 'UNSAFE_style'
 > {
   label: string;
-  /**
-   * Spectrum-defined styles, returned by the `style()` macro.
-   */
-  styles?: StyleString;
 }
 
 const MessageSourceInternalContext = createContext<{size: 'S' | 'M' | 'L' | 'XL'}>({size: 'M'});
@@ -62,13 +58,7 @@ export const MessageSource = (forwardRef as forwardRefType)(function MessageSour
   return (
     <MessageSourceInternalContext.Provider value={{size}}>
       <NumberBadgeContext.Provider value={{size}}>
-        <Disclosure
-          {...otherProps}
-          //@ts-ignore
-          UNSAFE_className={styles}
-          size={size}
-          ref={ref}
-          isQuiet>
+        <Disclosure {...otherProps} styles={styles} size={size} ref={ref} isQuiet>
           <DisclosureTitle>{label}</DisclosureTitle>
           {children}
         </Disclosure>
@@ -96,15 +86,7 @@ const itemStyles = style({
   gap: 8
 });
 
-export interface SourceListProps extends Omit<
-  DisclosurePanelProps,
-  'styles' | 'UNSAFE_className' | 'UNSAFE_style'
-> {
-  /**
-   * Spectrum-defined styles, returned by the `style()` macro.
-   */
-  styles?: StyleString;
-}
+export interface SourceListProps extends DisclosurePanelProps {}
 
 /**
  * A SourceList displays an ordered list of sources inside a MessageSource.
@@ -114,18 +96,14 @@ export const SourceList = (forwardRef as forwardRefType)(function SourceList(
   props: SourceListProps,
   ref: DOMRef<HTMLDivElement>
 ) {
-  let {children, styles, ...otherProps} = props;
+  let {children, ...otherProps} = props;
 
   let numberedChildren = React.Children.map(children, (child, i) => (
     <SourceListIndexContext.Provider value={i + 1}>{child}</SourceListIndexContext.Provider>
   ));
 
   return (
-    <DisclosurePanel
-      {...otherProps}
-      // @ts-ignore
-      UNSAFE_className={styles}
-      ref={ref}>
+    <DisclosurePanel {...otherProps} ref={ref}>
       <ol className={listStyles}>{numberedChildren}</ol>
     </DisclosurePanel>
   );
@@ -147,7 +125,7 @@ const linkStyles = style({
 });
 
 export interface SourceListItemProps
-  extends Omit<LinkProps, 'className' | 'style' | keyof GlobalDOMAttributes>, DOMProps {
+  extends Omit<LinkProps, 'className' | 'style' | 'render' | keyof GlobalDOMAttributes>, DOMProps {
   /** The content of the source list item. */
   children: React.ReactNode;
   /**
diff --git a/packages/@react-spectrum/ai/src/MessageSuggestion.tsx b/packages/@react-spectrum/ai/src/MessageSuggestion.tsx
index 88eef065af0..e7fa524286a 100644
--- a/packages/@react-spectrum/ai/src/MessageSuggestion.tsx
+++ b/packages/@react-spectrum/ai/src/MessageSuggestion.tsx
@@ -26,7 +26,7 @@ import {IconContext} from '@react-spectrum/s2/Icon';
 import {mergeStyles} from '@react-spectrum/s2/mergeStyles';
 import {pressScale} from '@react-spectrum/s2';
 import {Provider, SlotProps} from 'react-aria-components/slots';
-import {StyleString} from './types';
+import {StyleString} from '@react-spectrum/s2/style' with {type: 'macro'};
 import {useDOMRef} from './useDOMRef';
 import {useLocale} from 'react-aria/I18nProvider';
 
@@ -42,15 +42,17 @@ const controlSizeM = {
 
 export interface MessageSuggestionProps extends Omit<
   ButtonProps,
-  'style' | 'className' | 'isPending' | 'isDisabled' | keyof GlobalDOMAttributes
+  'style' | 'className' | 'isPending' | 'isDisabled' | 'render' | keyof GlobalDOMAttributes
 > {
   /** The text content of the suggestion. */
   children: ReactNode;
-  /** The size of the MessageSuggestion. */
-  size?: 'S' | 'M' | 'L' | 'XL';
   /**
-   * Spectrum-defined styles, returned by the `style()` macro.
+   * The size of the MessageSuggestion.
+   *
+   * @default 'M'
    */
+  size?: 'S' | 'M' | 'L' | 'XL';
+  /** Spectrum-defined styles, returned by the `style()` macro. */
   styles?: StyleString;
 }
 
diff --git a/packages/@react-spectrum/ai/src/PromptField.tsx b/packages/@react-spectrum/ai/src/PromptField.tsx
index 66851d662b0..7614bcae7d3 100644
--- a/packages/@react-spectrum/ai/src/PromptField.tsx
+++ b/packages/@react-spectrum/ai/src/PromptField.tsx
@@ -37,7 +37,7 @@ import {
 } from './TokenSegmentList';
 import {getEventTarget} from 'react-aria/private/utils/shadowdom/DOMFunctions';
 import {Group} from 'react-aria-components/Group';
-import {IconContext, mergeStyles, UnsafeStyles} from '@react-spectrum/s2';
+import {IconContext, mergeStyles} from '@react-spectrum/s2';
 import {Image, Text} from '@react-spectrum/s2/Card';
 import {isFileDropItem, useDrop} from 'react-aria-components/useDrop';
 import {isFocusable} from 'react-aria/private/utils/isFocusable';
@@ -58,7 +58,7 @@ export interface PromptFieldAttachment {
   image: string;
 }
 
-export interface PromptFieldProps extends UnsafeStyles {
+export interface PromptFieldProps {
   children: React.ReactNode;
   acceptedAttachmentTypes?: string[];
   onSubmit?: (prompt: TokenSegmentList, attachments: PromptFieldAttachment[]) => void;
@@ -139,8 +139,6 @@ export function PromptField(props: PromptFieldProps) {
     acceptedAttachmentTypes,
     isGenerating,
     onStop,
-    UNSAFE_className = '',
-    UNSAFE_style,
     styles,
     onAddAttachments,
     onRemoveAttachments
@@ -207,9 +205,7 @@ export function PromptField(props: PromptFieldProps) {
         <Group
           {...dropProps}
           role="group"
-          style={UNSAFE_style}
           className={renderProps =>
-            UNSAFE_className +
             mergeStyles(
               style({
                 display: 'flex',
@@ -457,7 +453,7 @@ function PromptTokenFieldPopover(props: PromptTokenFieldPopoverProps) {
   );
 }
 
-export interface PromptTokenProps extends Omit<TokenProps, 'children'> {
+export interface PromptTokenProps extends Omit<TokenProps, 'children' | 'render'> {
   children: React.ReactNode;
 }
 
diff --git a/packages/@react-spectrum/ai/src/ResponseStatus.tsx b/packages/@react-spectrum/ai/src/ResponseStatus.tsx
index 786f9120609..9e0a66cc424 100644
--- a/packages/@react-spectrum/ai/src/ResponseStatus.tsx
+++ b/packages/@react-spectrum/ai/src/ResponseStatus.tsx
@@ -39,7 +39,7 @@ import {mergeStyles} from '@react-spectrum/s2/mergeStyles';
 import {ProgressCircle} from '@react-spectrum/s2/ProgressCircle';
 import {Provider} from 'react-aria-components/slots';
 import React, {createContext, forwardRef, ReactNode, useContext} from 'react';
-import {StyleString} from './types';
+import {StyleString} from '@react-spectrum/s2/style' with {type: 'macro'};
 import {useDOMRef} from './useDOMRef';
 import {useLocale} from 'react-aria/I18nProvider';
 import {useLocalizedStringFormatter} from 'react-aria/useLocalizedStringFormatter';
@@ -321,6 +321,9 @@ export interface ResponseStatusPanelProps
     DOMProps,
     AriaLabelingProps {
   children: React.ReactNode;
+  /**
+   * Spectrum-defined styles, returned by the `style()` macro.
+   */
   styles?: StyleString;
 }
 
@@ -355,14 +358,12 @@ export const ResponseStatusPanel = forwardRef(function ResponseStatusPanel(
   props: ResponseStatusPanelProps,
   ref: DOMRef<HTMLDivElement>
 ) {
+  let {styles} = props;
   let {size = 'M'} = useContext(ResponseStatusContext)!;
   const domProps = filterDOMProps(props);
   let panelRef = useDOMRef(ref);
   return (
-    <RACDisclosurePanel
-      {...domProps}
-      ref={panelRef}
-      className={mergeStyles(panelStyles, props.styles)}>
+    <RACDisclosurePanel {...domProps} ref={panelRef} className={mergeStyles(panelStyles, styles)}>
       <div className={panelInner({size})}>{props.children}</div>
     </RACDisclosurePanel>
   );
diff --git a/packages/@react-spectrum/ai/src/UserMessage.tsx b/packages/@react-spectrum/ai/src/UserMessage.tsx
index 4415b3b687a..29b5d91677b 100644
--- a/packages/@react-spectrum/ai/src/UserMessage.tsx
+++ b/packages/@react-spectrum/ai/src/UserMessage.tsx
@@ -17,7 +17,7 @@ import {forwardRef, ReactNode} from 'react';
 import {ImageContext} from '@react-spectrum/s2/Image';
 import {mergeStyles} from '@react-spectrum/s2/mergeStyles';
 import {style} from '@react-spectrum/s2/style' with {type: 'macro'};
-import {StyleString} from './types';
+import {StyleString} from '@react-spectrum/s2/style' with {type: 'macro'};
 import {useDOMRef} from './useDOMRef';
 
 export interface UserMessageProps extends DOMProps, AriaLabelingProps, SlotProps {
diff --git a/packages/@react-spectrum/ai/src/types.ts b/packages/@react-spectrum/ai/src/types.ts
deleted file mode 100644
index 0d0f5866676..00000000000
--- a/packages/@react-spectrum/ai/src/types.ts
+++ /dev/null
@@ -1,13 +0,0 @@
-/*
- * Copyright 2024 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.
- */
-
-export type StyleString<P = string> = string & {properties: P};
diff --git a/packages/@react-spectrum/ai/stories/Chat.stories.tsx b/packages/@react-spectrum/ai/stories/Chat.stories.tsx
index aab79d76610..23d0794fc81 100644
--- a/packages/@react-spectrum/ai/stories/Chat.stories.tsx
+++ b/packages/@react-spectrum/ai/stories/Chat.stories.tsx
@@ -16,7 +16,6 @@ import {AssetCard, CardPreview} from '@react-spectrum/s2/Card';
 import {Chat} from '../src/Chat';
 import ChevronDown from '@react-spectrum/s2/icons/ChevronDown';
 import {Content} from '@react-spectrum/s2/Content';
-import {focusRing, style} from '@react-spectrum/s2/style' with {type: 'macro'};
 import {GridList} from 'react-aria-components';
 import {Image} from '@react-spectrum/s2/Image';
 import {ListLayout} from 'react-stately/useVirtualizerState';
@@ -42,6 +41,7 @@ import {
 } from '@react-spectrum/ai';
 import type {Meta} from '@storybook/react';
 import {ReactNode, useRef, useState} from 'react';
+import {style} from '@react-spectrum/s2/style' with {type: 'macro'};
 import {Text} from '@react-spectrum/s2/Text';
 import {Virtualizer} from 'react-aria-components/Virtualizer';
 
@@ -130,7 +130,7 @@ function CardMessage({
   imageUrl: string;
 }) {
   return (
-    <ThreadItem textValue={title} className={style({...focusRing(), borderRadius: 'default'})}>
+    <ThreadItem textValue={title}>
       <AssetCard>
         <CardPreview>
           <Image src={imageUrl} />
@@ -365,7 +365,7 @@ export function StreamingChat() {
         height: '100%'
       })}>
       <Chat
-        className={style({
+        styles={style({
           display: 'flex',
           flexDirection: 'column',
           overflow: 'hidden',
@@ -402,7 +402,7 @@ export function StreamingChat() {
             items={[...messages].reverse()}
             UNSTABLE_focusOnEntry="first"
             aria-label="Chat thread"
-            className={style({
+            styles={style({
               flexGrow: 1,
               overflowX: 'hidden',
               overflowY: 'auto',
@@ -416,12 +416,7 @@ export function StreamingChat() {
                 return (
                   <ThreadItem
                     textValue={msg.content}
-                    className={style({
-                      ...focusRing(),
-                      borderRadius: 'default',
-                      display: 'flex',
-                      justifyContent: 'end'
-                    })}>
+                    styles={style({display: 'flex', justifyContent: 'end'})}>
                     <UserMessage>{msg.content}</UserMessage>
                   </ThreadItem>
                 );
@@ -437,8 +432,7 @@ export function StreamingChat() {
                   <ThreadItem
                     textValue={announcement}
                     isStreaming={msg.isStreaming}
-                    shouldAnnounceOnMount
-                    className={style({...focusRing(), borderRadius: 'default'})}>
+                    shouldAnnounceOnMount>
                     <ResponseStatus isLoading={msg.isStreaming}>
                       <ResponseStatusTitle>{title}</ResponseStatusTitle>
                       <ResponseStatusPanel>
@@ -463,9 +457,7 @@ export function StreamingChat() {
                 // TODO: probably should have ThreadItem auto wrap MessageSuggestionList as well
                 // but this one I could see perhaps being a standalone component to be used outside of thread
                 return (
-                  <ThreadItem
-                    textValue={msg.title}
-                    className={style({...focusRing(), borderRadius: 'default'})}>
+                  <ThreadItem textValue={msg.title}>
                     <MessageSuggestionList title={msg.title}>
                       {msg.suggestions.map((s, i) => (
                         <MessageSuggestion key={i}>{s}</MessageSuggestion>
@@ -559,12 +551,7 @@ export function VirtualizedChat() {
               return (
                 <ThreadItem
                   textValue={msg.content}
-                  className={style({
-                    ...focusRing(),
-                    borderRadius: 'lg',
-                    display: 'flex',
-                    justifyContent: 'end'
-                  })}>
+                  styles={style({borderRadius: 'lg', display: 'flex', justifyContent: 'end'})}>
                   <UserMessage>{msg.content}</UserMessage>
                 </ThreadItem>
               );
@@ -574,9 +561,7 @@ export function VirtualizedChat() {
               let message = isPending ? 'Generating response' : 'Response generated';
 
               return (
-                <ThreadItem
-                  textValue={message}
-                  className={style({...focusRing(), borderRadius: 'default'})}>
+                <ThreadItem textValue={message}>
                   <ResponseStatus isLoading={isPending}>
                     <ResponseStatusTitle>{message}</ResponseStatusTitle>
                   </ResponseStatus>
@@ -616,10 +601,7 @@ function SystemMessage({
   sources?: string[];
 }) {
   return (
-    <ThreadItem
-      textValue={textValue}
-      isStreaming={isStreaming}
-      className={style({...focusRing(), borderRadius: 'default'})}>
+    <ThreadItem textValue={textValue} isStreaming={isStreaming}>
       {children}
       {sources && sources.length > 0 && (
         <MessageSource label="Sources">
diff --git a/packages/react-aria/src/gridlist/useGridListItem.ts b/packages/react-aria/src/gridlist/useGridListItem.ts
index f352fc824f4..511bf86fa8d 100644
--- a/packages/react-aria/src/gridlist/useGridListItem.ts
+++ b/packages/react-aria/src/gridlist/useGridListItem.ts
@@ -362,8 +362,6 @@ export function useGridListItem<T>(
     id: getRowId(state, node.key)
   });
 
-  // TODO: guarding against selection when firing space/enter/click on a element in a row is technically not only limited to textfields so I
-  // am not making it specific to keyboardNavigationBehavior = tab, but maybe we should still?
   // we need to guard against space/enter triggering selection/row link via usePress (from itemProps) so check if propagation
   // is stopped. this also fixes space not working in a textfield in a tree parent row
   let baseOnKeyDown = rowProps.onKeyDown;
diff --git a/packages/react-aria/src/selection/ListKeyboardDelegate.ts b/packages/react-aria/src/selection/ListKeyboardDelegate.ts
index ee89a2a7fa0..06e736447c6 100644
--- a/packages/react-aria/src/selection/ListKeyboardDelegate.ts
+++ b/packages/react-aria/src/selection/ListKeyboardDelegate.ts
@@ -312,8 +312,7 @@ export class ListKeyboardDelegate<T> implements KeyboardDelegate {
       }
     } else {
       let visibleRect = this.layoutDelegate.getVisibleRect();
-      // TODO: column reverse makes y negative for items so we need to instead do current pos - height instead
-      // will need to revist for virtualized reverse layouts?
+      // column reverse makes y negative for items so we need to instead do current pos - height instead
       let pageY = reversed
         ? itemRect.y - visibleRect.height
         : Math.max(0, itemRect.y + itemRect.height - visibleRect.height);
@@ -324,7 +323,6 @@ export class ListKeyboardDelegate<T> implements KeyboardDelegate {
       }
     }
 
-    // TODO: in column reverse, the top most key is the last key
     return nextKey ?? (reversed ? this.getLastKey() : this.getFirstKey());
   }
 
@@ -363,7 +361,6 @@ export class ListKeyboardDelegate<T> implements KeyboardDelegate {
       }
     }
 
-    // TODO: in column reverse, the bottom most key is the first key
     return nextKey ?? (reversed ? this.getFirstKey() : this.getLastKey());
   }
 

From 05949146c0e72a3f3fc0fa9ecb6c33b9b2efdfec Mon Sep 17 00:00:00 2001
From: Yihui Liao <44729383+yihuiliao@users.noreply.github.com>
Date: Wed, 17 Jun 2026 14:32:05 -0700
Subject: [PATCH 2/4] chore: update chat story prompts to be more realistic
 (#10223)

---
 .../ai/stories/Chat.stories.tsx               | 104 ++++++++++++++----
 1 file changed, 82 insertions(+), 22 deletions(-)

diff --git a/packages/@react-spectrum/ai/stories/Chat.stories.tsx b/packages/@react-spectrum/ai/stories/Chat.stories.tsx
index 23d0794fc81..ae2c03cd45a 100644
--- a/packages/@react-spectrum/ai/stories/Chat.stories.tsx
+++ b/packages/@react-spectrum/ai/stories/Chat.stories.tsx
@@ -74,18 +74,78 @@ type Message =
   | {id: number; type: 'status'; status: 'pending' | 'complete'};
 
 let initialResponses = [
-  {id: 0, type: 'user', content: 'prompt 1'},
-  {id: 1, type: 'system', content: dummyResponses[0]},
-  {id: 2, type: 'user', content: 'prompt 2'},
-  {id: 3, type: 'system', content: dummyResponses[1]},
-  {id: 4, type: 'user', content: 'prompt 3'},
-  {id: 5, type: 'system', content: dummyResponses[2]},
-  {id: 6, type: 'user', content: 'prompt 4'},
-  {id: 7, type: 'system', content: dummyResponses[0]},
-  {id: 8, type: 'user', content: 'prompt 5'},
-  {id: 9, type: 'system', content: dummyResponses[1]},
-  {id: 10, type: 'user', content: 'prompt 6'},
-  {id: 11, type: 'system', content: dummyResponses[2]}
+  {
+    id: 0,
+    type: 'user',
+    content:
+      "I'm launching a new product next month—a sustainable, affordable athletic wear line targeting Gen Z. We have a limited budget and need to figure out our go-to-market strategy. Where do we even start?"
+  },
+  {
+    id: 1,
+    type: 'system',
+    content:
+      "Exciting launch! A few things to clarify so I give you relevant guidance: (1) What's your total marketing budget for the launch month? (2) Do you already have an email list, social following, or any existing audience? (3) Who's your main competitor, and what are they doing? (4) Is this DTC (direct-to-consumer) or are you selling through retailers? These will shape whether we focus on paid ads, influencers, organic content, or a mix."
+  },
+  {
+    id: 2,
+    type: 'user',
+    content:
+      "We have about $15,000 for the first month. We're DTC only, launching on our own website. We have a small email list of about 2,000 people from a waitlist, and basically no social following yet. Our main competitor is Reformation, but they're way more established. We want to emphasize our sustainability angle and lower price point."
+  },
+  {
+    id: 3,
+    type: 'system',
+    content:
+      "Okay, $15K is modest but workable for DTC. Here's my initial take: Since you're starting from zero on social and have a small email list, I'd suggest a three-part approach: (1) Allocate ~$8K to highly targeted paid ads (TikTok and Instagram) reaching eco-conscious Gen Z with strong creative, (2) Use $3K for micro-influencer partnerships (people with 10K-100K followers in the sustainability space—cheaper but authentic), (3) Keep $4K for email and organic content. Before we dive deeper—what's your product's main hook? Is it the materials, the price, the designs, or the transparency of your supply chain?"
+  },
+  {
+    id: 4,
+    type: 'user',
+    content:
+      "The main hook is that we use recycled ocean plastic and sell at 40% lower prices than Reformation. Our supply chain is also fully transparent. We've got 15 styles launching across tops, shorts, and leggings."
+  },
+  {
+    id: 5,
+    type: 'system',
+    content:
+      "Perfect—that's a strong, differentiated message. Here's what I'd focus on: The ocean plastic angle is visually compelling and emotionally resonant with Gen Z; the price-to-quality ratio is your competitive advantage against Reformation. For your first month, I'd recommend this campaign narrative: 'High performance, zero guilt, actual prices.' Now, a strategic question: Do you want to go all-in on one or two channels, or spread across TikTok, Instagram, and YouTube? Gen Z is on TikTok and Instagram, but each requires different content styles. What does your creative team feel most confident producing?"
+  },
+  {
+    id: 6,
+    type: 'user',
+    content:
+      "We can handle both TikTok and Instagram, but honestly TikTok feels more authentic for our brand. We have some behind-the-scenes footage of our production process and some early customer testimonials. Instagram we'd probably do more polished product shots."
+  },
+  {
+    id: 7,
+    type: 'system',
+    content:
+      "Smart instinct—TikTok is perfect for you because behind-the-scenes and authenticity is the content style there, and sustainability messaging performs really well. That said, here's my suggestion: (1) Use TikTok primarily for awareness and virality—behind-the-scenes, sustainability stories, affordability messaging. Spend $5K there. (2) Use Instagram for conversion—polished product shots, customer testimonials, sustainability proof. Spend $3K there. (3) With your micro-influencers ($3K), focus on TikTok creators first since that's where your audience is. One question though: Do you have a clear conversion path ready? Like, when someone clicks your ad, what's the landing page experience? Are you doing a discount code to incentivize first purchase?"
+  },
+  {
+    id: 8,
+    type: 'user',
+    content:
+      "We have the website ready, but we haven't thought about a launch discount. Should we do one? Won't that hurt our perceived value?"
+  },
+  {
+    id: 9,
+    type: 'system',
+    content:
+      "Great question—common concern. For a DTC launch with limited awareness, I'd actually recommend a strategic discount, not a deep one. Something like 15-20% off for the first 48 hours, with messaging like 'Early founder pricing' or 'Launch week exclusive.' Why? It creates urgency, lowers the barrier for first-time buyers trying an unknown brand, and you get email addresses and reviews to leverage later. You're not training people to wait for sales—you're using urgency to convert. Pair it with clear value messaging (ocean plastic, transparent supply chain, high quality) so it doesn't feel cheap. Also, include a referral incentive—Gen Z shares—maybe $10 off for them and the referee. This turns customers into advocates. Does that strategy feel right for your brand?"
+  },
+  {
+    id: 10,
+    type: 'user',
+    content:
+      'That makes sense. Before we move forward, can you summarize the full plan and tell me what could go wrong?'
+  },
+  {
+    id: 11,
+    type: 'system',
+    content:
+      "Absolutely. Your Launch Plan: $8K paid ads (TikTok $5K, Instagram $3K) with behind-the-scenes and product content; $3K micro-influencer partnerships on TikTok; $4K allocated to email nurture and organic/referral growth. 15-20% launch discount for 48 hours. What could go wrong: (1) Creative underperforms—test multiple ad versions early and kill losers fast, (2) Website crashes or checkout breaks—stress test before launch, (3) Influencers don't deliver—vet their audiences carefully and look for engagement rates, not just follower count, (4) You don't have enough inventory—make sure supply matches demand projections, (5) Customer acquisition cost exceeds your margins—monitor CAC closely in week one and adjust spending. My advice: Launch on a Tuesday or Wednesday so you have time to optimize before the weekend. Track everything obsessively in the first 72 hours—CAC, conversion rate, email signup rate. Be ready to shift budget if one channel is outperforming. Want me to help you build a monitoring dashboard or refine your email launch sequence next?"
+  }
 ] as Message[];
 
 type StreamingMessage =
@@ -236,7 +296,7 @@ export function StreamingChat() {
     // faster and thus the announcements will get cut off even with polite...
     // first batch, does tool calls with text response
     let timestamp = 0;
-    let toolCallDuration = 4000;
+    let toolCallDuration = 1000;
     // Status added after short delay so user message announcement plays first
     addTimeout(
       () => {
@@ -251,9 +311,9 @@ export function StreamingChat() {
           }
         ]);
       },
-      (timestamp += 1000)
+      (timestamp += 500)
     );
-    addTimeout(() => addTool('Thinking', true), (timestamp += 1000));
+    addTimeout(() => addTool('Thinking', true), (timestamp += 500));
     addTimeout(
       () =>
         completeTool(
@@ -261,12 +321,12 @@ export function StreamingChat() {
         ),
       (timestamp += toolCallDuration)
     );
-    addTimeout(() => addTool('Loading tool'), (timestamp += 1000));
+    addTimeout(() => addTool('Loading tool'), (timestamp += 500));
     addTimeout(
       () => completeTool('Asset search tool loaded with access to the Hilton brand library.'),
       (timestamp += toolCallDuration)
     );
-    addTimeout(() => addTool('Searching'), (timestamp += 1000));
+    addTimeout(() => addTool('Searching'), (timestamp += 500));
     addTimeout(
       () => completeTool('Found 15 assets matching the brand criteria across 3 campaigns.'),
       (timestamp += toolCallDuration)
@@ -276,11 +336,11 @@ export function StreamingChat() {
         streamText(
           'I found some relevant assets that match your request. Let me pull up the details.'
         ),
-      (timestamp += 1000)
+      (timestamp += 500)
     );
 
     // then does searching, streaming more text, returning a card and sources
-    addTimeout(() => addTool('Searching'), (timestamp += 4000));
+    addTimeout(() => addTool('Searching'), (timestamp += 1000));
     addTimeout(
       () =>
         completeTool('Identified additional brand materials related to the presentation context.'),
@@ -321,7 +381,7 @@ export function StreamingChat() {
               'The user shared Hilton brand assets and is asking for a presentation outline. I analyzed the visual themes and brand guidelines to suggest a narrative structure that aligns with the hospitality brand identity.'
           }
         ]),
-      (timestamp += 2000)
+      (timestamp += 1000)
     );
     addTimeout(
       () =>
@@ -331,10 +391,10 @@ export function StreamingChat() {
             'revolve around brand consistency, audience engagement, and clear calls to action.',
           MOCK_SOURCES
         ),
-      (timestamp += 1000)
+      (timestamp += 500)
     );
 
-    let streamEndTimestamp = timestamp + 8000;
+    let streamEndTimestamp = timestamp + 500;
     addTimeout(() => {
       setMessages(prev => [...prev, {id: nextId.current++, type: 'card', ...MOCK_CARD}]);
     }, streamEndTimestamp);

From a064c190640ee83c1d266a95dc3fe45f6581e579 Mon Sep 17 00:00:00 2001
From: Reid Barber <reid@reidbarber.com>
Date: Wed, 17 Jun 2026 16:38:03 -0500
Subject: [PATCH 3/4] docs: add S2 audit skill (#10160)

* initialize spectrum-audit skill

* clean up skill

* add rule about Interactive components in ListView/TreeView
---
 .../s2-docs/scripts/generateAgentSkills.mjs   | 105 ++++++++++++++++++
 .../spectrum-audit/checks/01-setup-config.md  |  53 +++++++++
 .../checks/02-component-usage.md              |  42 +++++++
 .../spectrum-audit/checks/03-styling.md       |  47 ++++++++
 .../spectrum-audit/checks/04-accessibility.md |  30 +++++
 .../spectrum-audit/checks/05-versioning.md    |  18 +++
 .../spectrum-audit/checks/06-testing.md       |  12 ++
 .../skills/spectrum-audit/report-template.md  |  72 ++++++++++++
 .../skills/spectrum-audit/scoring-rubric.md   |  57 ++++++++++
 9 files changed, 436 insertions(+)
 create mode 100644 packages/dev/s2-docs/skills/spectrum-audit/checks/01-setup-config.md
 create mode 100644 packages/dev/s2-docs/skills/spectrum-audit/checks/02-component-usage.md
 create mode 100644 packages/dev/s2-docs/skills/spectrum-audit/checks/03-styling.md
 create mode 100644 packages/dev/s2-docs/skills/spectrum-audit/checks/04-accessibility.md
 create mode 100644 packages/dev/s2-docs/skills/spectrum-audit/checks/05-versioning.md
 create mode 100644 packages/dev/s2-docs/skills/spectrum-audit/checks/06-testing.md
 create mode 100644 packages/dev/s2-docs/skills/spectrum-audit/report-template.md
 create mode 100644 packages/dev/s2-docs/skills/spectrum-audit/scoring-rubric.md

diff --git a/packages/dev/s2-docs/scripts/generateAgentSkills.mjs b/packages/dev/s2-docs/scripts/generateAgentSkills.mjs
index 8815e2e12c2..ca793ea3b5f 100644
--- a/packages/dev/s2-docs/scripts/generateAgentSkills.mjs
+++ b/packages/dev/s2-docs/scripts/generateAgentSkills.mjs
@@ -28,6 +28,7 @@ const MARKDOWN_DOCS_DIST = path.join(REPO_ROOT, 'packages/dev/s2-docs/dist');
 const MDX_PAGES_DIR = path.join(REPO_ROOT, 'packages/dev/s2-docs/pages');
 const MARKDOWN_DOCS_SCRIPT = path.join(__dirname, 'generateMarkdownDocs.mjs');
 const MIGRATION_REFS_DIR = path.join(REPO_ROOT, 'packages/dev/s2-docs/migration-references');
+const AUDIT_SKILL_SOURCE_DIR = path.join(REPO_ROOT, 'packages/dev/s2-docs/skills/spectrum-audit');
 const WELL_KNOWN_DIR = '.well-known';
 const WELL_KNOWN_SKILLS_DIR = 'skills';
 
@@ -79,6 +80,19 @@ const SKILLS = {
       author: 'Adobe',
       website: 'https://react-aria.adobe.com/'
     }
+  },
+  'spectrum-audit': {
+    name: 'spectrum-audit',
+    description:
+      'Audit a codebase for adherence to the Spectrum design system and React Spectrum S2 best practices. Use when a developer asks to audit, review, lint, or check a project for Spectrum/S2 correctness, configuration, styling, accessibility, or component-usage issues.',
+    kind: 'audit',
+    license: 'Apache-2.0',
+    sourceDir: 's2',
+    compatibility: 'Requires a React project using @react-spectrum/s2.',
+    metadata: {
+      author: 'Adobe',
+      website: 'https://react-spectrum.adobe.com/'
+    }
   }
 };
 
@@ -665,6 +679,65 @@ Use these when you need more component-by-component or API-level detail:
   );
 }
 
+function generateAuditSkillMd(skillConfig) {
+  return (
+    `${generateFrontmatter(skillConfig)}# Spectrum Audit
+
+Audit a codebase for adherence to the Spectrum design system and React Spectrum S2 best practices, then produce a scored, prioritized report. This skill is **report-only** — it does not modify any files.
+
+## When to use
+
+Use when a developer asks to audit, review, lint, or check a project for Spectrum / S2 correctness, configuration, styling, accessibility, or component-usage issues.
+
+Requires a project with \`@react-spectrum/s2\` installed. If S2 is not a dependency, say so and stop.
+
+## How it works
+
+Run these phases in order.
+
+### Phase 0 — Scope
+
+- Identify the project — or, in a monorepo, the specific package — to audit. Audit the package, not the workspace root.
+- Detect the package manager from the lockfile, the bundler (Vite / webpack / Next.js / Parcel / Rollup / ESBuild), and read \`package.json\` dependencies.
+- Confirm \`@react-spectrum/s2\` is installed. Establish the source globs to scan (e.g. \`src/**/*.{tsx,jsx,ts,js}\`).
+- Check whether the \`react-spectrum-s2\` skill is available (listed among the agent's installed skills, or present under a local skills directory such as \`.cursor/skills/\` or \`.agents/skills/\`). Record whether it was found — the report template uses this.
+
+### Phase 1 — Run the checks
+
+Work through each check file in \`references/checks/\`, in order. For every violation, record a finding: \`{file:line, rule, severity, category, fix}\`. Cite only line numbers you actually read or grepped — never invent locations. Record **one finding per distinct root cause** at a \`file:line\` — if multiple check files cover the same issue (e.g. a missing collection \`aria-label\` or a third-party design system), assign it to the most specific check and do not duplicate it across categories.
+
+- [01 — Setup & configuration](references/checks/01-setup-config.md)
+- [02 — Component usage](references/checks/02-component-usage.md)
+- [03 — Styling](references/checks/03-styling.md)
+- [04 — Accessibility & correctness](references/checks/04-accessibility.md)
+- [05 — Versioning & maintenance](references/checks/05-versioning.md)
+- [06 — Testing](references/checks/06-testing.md)
+
+The canonical rules behind these checks live in the \`react-spectrum-s2\` skill — read its \`SKILL.md\` (implementation guidance) and \`references/guides/getting-started.md\`, \`references/guides/component-decision-tree.md\`, and \`references/components/\` as needed. If that skill is not installed, proceed using the check files alone, but note the limitation in the report (see Phase 3).
+
+### Phase 2 — Score
+
+Apply the [scoring rubric](references/scoring-rubric.md) to the recorded findings to compute per-category scores and the overall Spectrum Adherence Score. The score is arithmetic over counted findings — do not estimate it.
+
+### Phase 3 — Report
+
+Write \`SPECTRUM-AUDIT.md\` to the audited project following the [report template](references/report-template.md): headline score, grade, and severity counts; a summary; scores by category; findings grouped by severity (each with a clickable \`file:line\` and the check name that defines its rule); prioritized action items; what looks good; and — if \`react-spectrum-s2\` was not detected in Phase 0 — a recommendation to install it.
+
+### Phase 4 — Hand off
+
+This skill does not edit code. Recommend:
+
+- The \`react-spectrum-s2\` skill to implement the fixes. If it is not installed:
+
+  \`\`\`bash
+  npx skills add https://react-spectrum.adobe.com --skill react-spectrum-s2
+  \`\`\`
+
+- The \`migrate-react-spectrum-v3-to-s2\` skill if Spectrum 1 packages (\`@adobe/react-spectrum\`, \`@react-spectrum/*\`, \`@spectrum-icons/*\`) are present.
+`.trimEnd() + '\n'
+  );
+}
+
 /**
  * Copy documentation files to the skill's references directory.
  */
@@ -823,6 +896,26 @@ function writeMigrationReferences(skillDir, sourceDir) {
   ]);
 }
 
+function writeAuditReferences(skillDir) {
+  const refsDir = path.join(skillDir, 'references');
+  fs.mkdirSync(refsDir, {recursive: true});
+
+  // Copy authored audit check files.
+  const checksSourceDir = path.join(AUDIT_SKILL_SOURCE_DIR, 'checks');
+  const checksTargetDir = path.join(refsDir, 'checks');
+  fs.mkdirSync(checksTargetDir, {recursive: true});
+  for (const file of fs.readdirSync(checksSourceDir)) {
+    if (file.endsWith('.md')) {
+      fs.copyFileSync(path.join(checksSourceDir, file), path.join(checksTargetDir, file));
+    }
+  }
+
+  // Copy the authored scoring rubric and report template.
+  for (const file of ['scoring-rubric.md', 'report-template.md']) {
+    fs.copyFileSync(path.join(AUDIT_SKILL_SOURCE_DIR, file), path.join(refsDir, file));
+  }
+}
+
 function collectSkillFiles(skillDir) {
   const files = [];
 
@@ -918,6 +1011,18 @@ function generateSkill(skillConfig, wellKnownRoot) {
     return skillDir;
   }
 
+  if (skillConfig.kind === 'audit') {
+    fs.writeFileSync(path.join(skillDir, 'SKILL.md'), generateAuditSkillMd(skillConfig));
+    console.log(`Generated ${path.relative(REPO_ROOT, path.join(skillDir, 'SKILL.md'))}`);
+
+    writeAuditReferences(skillDir);
+    console.log(
+      `Copied audit references to ${path.relative(REPO_ROOT, path.join(skillDir, 'references'))}`
+    );
+
+    return skillDir;
+  }
+
   const isS2 = skillConfig.name === 'react-spectrum-s2';
 
   // Parse documentation entries
diff --git a/packages/dev/s2-docs/skills/spectrum-audit/checks/01-setup-config.md b/packages/dev/s2-docs/skills/spectrum-audit/checks/01-setup-config.md
new file mode 100644
index 00000000000..572c454695a
--- /dev/null
+++ b/packages/dev/s2-docs/skills/spectrum-audit/checks/01-setup-config.md
@@ -0,0 +1,53 @@
+# Check 01 — Setup & configuration
+
+Validates that the project is configured the way the `react-spectrum-s2` skill specifies.
+
+Read first: `react-spectrum-s2` skill → `references/guides/getting-started.md` (canonical setup), plus the project's `package.json` and bundler config file.
+
+## Detection inputs (gathered in Phase 0)
+
+- **Package manager:** lockfile — `yarn.lock`, `package-lock.json`, or `pnpm-lock.yaml`.
+- **Bundler:** `vite.config.*`, `webpack.config.*`, `next.config.*`, `.parcelrc` / a `parcel` dependency, `rollup.config.*`, or an esbuild build script.
+- **Installed deps:** `dependencies` / `devDependencies` in `package.json`.
+
+## Checks
+
+### `@react-spectrum/s2` is installed
+- **Detect:** `@react-spectrum/s2` present in `package.json`. If absent, the audit does not apply — stop and tell the user.
+- **Severity:** — (precondition)
+
+### Style macro plugin configured
+- **Rule:** Non-Parcel bundlers must wire `unplugin-parcel-macros` into the build; Parcel needs ≥ 2.12.0. Without it, `style({...})` calls are never evaluated at build time and components render unstyled.
+- **Detect:**
+  - Vite/Rollup/React Router/ESBuild/webpack/Next: `unplugin-parcel-macros` in deps **and** referenced in the bundler config (`macros.vite()`, `macros.webpack()`, `macros.rollup()`, `macros.esbuild()`).
+  - Parcel: `parcel` ≥ 2.12.0 (macros are built in) — no plugin needed.
+  - Next.js: also confirm the app starts with `--webpack` (not Turbopack) — check the `dev`/`build` scripts. `unplugin-parcel-macros` does not work with Turbopack.
+- **Severity:** Critical.
+
+### CSS bundle optimization
+- **Rule:** All S2 + macro-generated CSS should be combined into a single shared `s2-styles` bundle rather than code-split per route. Atomic CSS overlaps heavily between components, so loading it up front is smaller than duplicating it across chunks.
+- **Detect:**
+  - Parcel: `@parcel/bundler-default.manualSharedBundles` with an `s2-styles` entry in the root `package.json`.
+  - webpack/Next: `optimization.splitChunks.cacheGroups` with an `s2`/`s2-styles` group testing for `@react-spectrum/s2` and `macro-*.css`.
+  - Vite/Rollup/React Router: `build.rollupOptions.output.manualChunks` returning `'s2-styles'` for `macro-*.css` and `@react-spectrum/s2/*.css`.
+- **Severity:** High.
+
+### lightningcss minification
+- **Rule:** Compile/minify CSS with lightningcss — it produces a much smaller bundle and dedupes atomic rules.
+- **Detect:** `cssMinify: 'lightningcss'` (Vite/React Router) or `CssMinimizerPlugin.lightningCssMinify` (webpack/Next).
+- **Severity:** Medium.
+
+### Locale optimization
+- **Rule:** S2 ships localized strings for 30+ languages by default. Projects should install the locale optimization plugin and declare only the languages they support.
+- **Detect:** `@react-aria/optimize-locales-plugin` (webpack/Vite/Rollup/React Router/ESBuild) or `@react-aria/parcel-resolver-optimize-locales` (Parcel) installed **and** configured with a `locales` list.
+- **Severity:** Medium.
+
+### Single root Provider, wired to the router
+- **Rule:** Mount one `Provider` from `@react-spectrum/s2/Provider` at the app root, wired to the client router; SSR frameworks (Next.js, React Router) set `locale` from the server request and render `Provider` with `elementType="html"`.
+- **Detect:** exactly one root `Provider`; a `router={{navigate}}` prop; for Next/RR, a server-derived locale. Flag a missing `router`, or SSR setups that don't sync the locale.
+- **Severity:** High. (Provider *scope* misuse — stacking, hard-coded `colorScheme` — is in [04-accessibility](04-accessibility.md).)
+
+### React 19
+- **Rule:** React 19 is recommended for S2.
+- **Detect:** `react` version in `package.json`.
+- **Severity:** Low.
diff --git a/packages/dev/s2-docs/skills/spectrum-audit/checks/02-component-usage.md b/packages/dev/s2-docs/skills/spectrum-audit/checks/02-component-usage.md
new file mode 100644
index 00000000000..0c00b6fe407
--- /dev/null
+++ b/packages/dev/s2-docs/skills/spectrum-audit/checks/02-component-usage.md
@@ -0,0 +1,42 @@
+# Check 02 — Component usage
+
+Validates that the project uses S2 components where they exist, builds custom components on React Aria Components + the `style` macro, and follows S2 composition and collection conventions. This is the most judgment-heavy category — read the component's docs in the `react-spectrum-s2` skill (`references/components/`) before flagging.
+
+Canonical rules: `react-spectrum-s2` skill → `SKILL.md` (Component composition, Collections, Typography, Form fields). Reverse-lookup help ("is there an S2 component for this?"): `references/guides/component-decision-tree.md`.
+
+## Checks
+
+### Use an S2 component where one exists
+- **Rule:** Prefer S2 components over hand-rolled UI. S2 covers ~85 components — Button, Picker, ComboBox, Menu, Dialog/AlertDialog, Card/CardView, TableView, ListView, Tabs, and more.
+- **Detect:** hand-rolled equivalents — `<div role="button|dialog|menu|listbox|tablist">`, custom dropdown/modal/tooltip implementations, native `<button>`/`<select>` styled to look like Spectrum, native `<table>` for data grids. Cross-check candidates against the canonical component list (`@react-spectrum/s2` exports / the `react-spectrum-s2` skill).
+- **Severity:** High.
+
+### Custom components build on RAC + the style macro
+- **Rule:** When no S2 component fits, build the custom component on React Aria Components (for behavior + accessibility) and style it with the `style` macro — not raw divs with click handlers.
+- **Detect:** interactive custom components using bare `<div onClick>` / `<div onKeyDown>` / `<span onClick>` instead of an RAC primitive or an S2 component.
+- **Severity:** High (accessibility regressions).
+
+### Typed item components
+- **Rule:** Each collection has its own item export — `MenuItem`, `PickerItem`, `ComboBoxItem`, `ListViewItem`, `TreeViewItem`, `Row`/`Cell`/`Column`, `Tag`, `Breadcrumb`, `AccordionItem`, etc. There is no generic `Item`. Typed section exports (`MenuSection`, `PickerSection`, `ComboBoxSection`, …) are valid — only a **generic** `Section` import is wrong.
+- **Detect:** `import {Item}` or `import {Section}` (or `Item`/`Section` from `react-stately` / Spectrum 1 packages); a generic `<Item>` / `<Section>` element in S2 code (usually a Spectrum 1 leftover); or the wrong item type nested inside a collection. Do **not** flag typed `*Section` components such as `MenuSection`.
+- **Severity:** Medium.
+
+### Collection conventions
+- **Rule:** Collection items need an `id` (and React `key` when built with `.map`); items whose children aren't plain text need `textValue`; virtualized collections must not be wrapped in an `overflow` container; empty/loading/bulk-action UI uses the built-in `renderEmptyState` / `loadingState` / `renderActionBar`. Accessible names on collections are covered in [04-accessibility](04-accessibility.md) — record those findings there, not here.
+- **Detect:** items lacking `id`; non-text item children without `textValue`; an `overflow*` wrapper around `TableView`/`ListView`/`CardView`/`TreeView`/`Menu`/`ListBox`; hand-rolled empty/spinner/bulk-action UI replacing the built-ins.
+- **Severity:** High for missing `id` / `textValue` (breaks selection, keyboard nav, screen readers); Medium for the rest.
+
+### Interactive components in ListView / TreeView
+- **Rule:** When a `ListView` or `TreeView` row contains interactive children whose keyboard handling conflicts with arrow-key row navigation (e.g. `TextField`, `ComboBox`, `Picker`), set `keyboardNavigationBehavior="tab"` on the collection so Tab moves focus in and out of rows. See `react-spectrum-s2` skill → `references/components/ListView.md` and `references/components/TreeView.md`.
+- **Detect:** `TextField`, `ComboBox`, `Picker`, or other keyboard-interactive components rendered inside a `ListViewItem` / `TreeViewItem` while the parent `ListView` / `TreeView` does not have `keyboardNavigationBehavior="tab"`.
+- **Severity:** High.
+
+### Don't reinvent Card / CardView
+- **Rule:** For grids of objects/files/products/people, use `CardView` with a variant (`AssetCard`, `UserCard`, `ProductCard`) or `Card` composed from `CardPreview`/`Content`/`Text`/`Footer`.
+- **Detect:** hand-rolled card `<div>` / `<article>` grids reproducing card layout.
+- **Severity:** Medium.
+
+### Slot discipline
+- **Rule:** Only pass `slot` values the parent documents, and don't inject wrapper elements where a component expects specific slot children.
+- **Detect:** `<div>`/`<span>` wrapping collection-item children; `slot=` values the parent component doesn't define (e.g. `slot="close"` on an arbitrary button).
+- **Severity:** Medium.
diff --git a/packages/dev/s2-docs/skills/spectrum-audit/checks/03-styling.md b/packages/dev/s2-docs/skills/spectrum-audit/checks/03-styling.md
new file mode 100644
index 00000000000..4ac86abe2a9
--- /dev/null
+++ b/packages/dev/s2-docs/skills/spectrum-audit/checks/03-styling.md
@@ -0,0 +1,47 @@
+# Check 03 — Styling
+
+Validates that styling goes through S2 components and the `style` macro with tokens — not escape hatches, raw CSS, or third-party styling systems. Canonical rules: `react-spectrum-s2` skill → `SKILL.md` (Styling and Icons sections).
+
+Search the source globs (e.g. `**/*.{tsx,jsx,ts,js}`) for the patterns below.
+
+## Checks
+
+### No `UNSAFE_style` / `UNSAFE_className`
+- **Rule:** Avoid `UNSAFE_style` and `UNSAFE_className`; they bypass tokens and the style layer ordering.
+- **Detect:** grep `UNSAFE_style|UNSAFE_className`.
+- **Severity:** High.
+
+### No concatenation of macro output
+- **Rule:** `style()` results encode style precedence; concatenating them with template literals, `clsx`, `classnames`, or string spaces breaks ordering. Express variation in one `style({...})` call with runtime conditions, or use `mergeStyles`.
+- **Detect:** macro results combined via `` `${style(...)} ...` ``, `clsx(`/`classNames(` wrapping `style(`, or Tailwind utility classes alongside S2 components. grep `clsx|classnames`, `tailwind`, and template-literal `className`s containing `style(`.
+- **Severity:** High.
+
+### No inline `style` alongside the macro
+- **Rule:** Don't combine `className={style({...})}` (or the `styles` prop) with an inline `style={{...}}` on the same element — inline styles bypass tokens and break layer ordering. Inline `style` is only for values genuinely unknowable at build time (e.g. a drag position).
+- **Detect:** elements carrying both `style={{` and `style(` / `styles=`.
+- **Severity:** Medium.
+
+### Tokens, not raw CSS values
+- **Rule:** Macro values are typed tokens, not raw CSS. No hex / `rgb()` / `var()` colors; no string units like `'1rem'` / `'100%'` (use numbers on the 4px grid, or `'full'`); no `'flex-start'` / `'flex-end'` (use `'start'` / `'end'`); no physical sides (use logical `paddingStart`/`marginEnd`/`insetStart`/`borderStartStartRadius` so they flip under RTL).
+- **Detect:** inside `style(` / `styles=`: `#` hex colors, `rgb(`, `var(--`, quoted units (`'…rem'`, `'…px'`, `'…%'`), `'flex-start'`/`'flex-end'`, and physical props `paddingLeft|paddingRight|marginLeft|marginRight|borderTopLeftRadius|borderTopRightRadius`.
+- **Severity:** Medium. Prefer **semantic** color tokens (`accent`, `neutral`, `negative`, `positive`, `informative`, `notice`) where color carries meaning, over raw hue tokens (`red-…`, `blue-…`).
+
+### The `styles` prop is layout-only
+- **Rule:** The `styles` prop on S2 components is restricted to layout properties (margin, width, flex, grid placement, position, z-index, visibility). Non-layout properties belong on a native element's `className={style(...)}`.
+- **Detect:** `styles={style({` on an S2 component containing `backgroundColor`, `color`, `font`, `borderWidth`, or `padding`.
+- **Severity:** Medium.
+
+### Subpath imports, not the barrel
+- **Rule:** Import components from their subpath (`@react-spectrum/s2/Button`), not the package barrel (`@react-spectrum/s2`). Shared types and list-data hooks (`useListData`, `Key`, `Selection`, …) are the exception — they're re-exported from the barrel.
+- **Detect:** a named **component** import from the root: `import {Button|Picker|…} from '@react-spectrum/s2'`.
+- **Severity:** Low.
+
+### No third-party icon or design-system libraries
+- **Rule:** Use S2 icons/illustrations and components. Don't introduce `lucide-react`, `heroicons`, `phosphor-icons`, `react-icons`, or whole design systems (MUI, Chakra, Radix UI kits, shadcn/ui, Ant Design) in S2 code. `react-aria-components` is fine for custom components — this check targets pre-styled UI kits, not RAC primitives.
+- **Detect:** imports from those packages.
+- **Severity:** Medium for icon libraries; High for a competing design system. If the same import also triggers [02-component-usage](02-component-usage.md), record **one** finding here (Styling) only.
+
+### Don't restate default prop values
+- **Rule:** Setting a prop to its default — `variant="primary"`, `size="M"`, `density="regular"` — is noise.
+- **Detect:** those literal default props on S2 components.
+- **Severity:** Low.
diff --git a/packages/dev/s2-docs/skills/spectrum-audit/checks/04-accessibility.md b/packages/dev/s2-docs/skills/spectrum-audit/checks/04-accessibility.md
new file mode 100644
index 00000000000..5c75d8a7c8b
--- /dev/null
+++ b/packages/dev/s2-docs/skills/spectrum-audit/checks/04-accessibility.md
@@ -0,0 +1,30 @@
+# Check 04 — Accessibility & correctness
+
+Catches accessibility regressions and slot / Provider misuse that S2 otherwise handles for you. Canonical rules: `react-spectrum-s2` skill → `SKILL.md` (Buttons with text and icon, Typography, Form fields, Provider scope).
+
+## Checks
+
+### Accessible names
+- **Rule:** Icon-only buttons and every collection container need an accessible name.
+- **Detect:** `Button` / `ActionButton` with only an icon child and no `aria-label`; collections (`ListView`, `TableView`, `CardView`, `TreeView`, `Menu`, `ListBox`, `GridList`, `TagGroup`, `Breadcrumbs`) without `aria-label` / `aria-labelledby`.
+- **Severity:** High.
+
+### Icon + text buttons wrap the label in `Text`
+- **Rule:** A button with **both** an icon and a label must wrap the label in `<Text>`; a bare string sibling next to an icon renders incorrectly.
+- **Detect:** `Button` / `ActionButton` / `LinkButton` with an icon child and a bare string sibling (no `<Text>`).
+- **Severity:** Medium.
+
+### Slot components only inside their slot context
+- **Rule:** `Text`, `Heading`, and `Content` are slot components — standalone (outside a card, dialog, list, picker, menu, tab, etc.) they don't produce correct typography. Use a native element + the `style` macro instead.
+- **Detect:** `<Heading>` / `<Text>` / `<Content>` rendered outside a component that provides their slot.
+- **Severity:** Medium.
+
+### Form fields use props, not wrappers
+- **Rule:** S2 fields render their own label, description, error message, and required indicator. Pass these as props (`label`, `description`, `errorMessage`, `isRequired`, `contextualHelp`) — don't wrap a field in a `<label>` / `<p>` / `<div>` to attach them.
+- **Detect:** an S2 field wrapped in `<label>`, or a sibling `<p>`/`<span>` used as its label or help text.
+- **Severity:** Medium.
+
+### Provider scope and color scheme
+- **Rule:** One root Provider; don't stack Providers (nesting is only for scoping a different `locale`/`router`/`colorScheme` to a subtree); let the Provider manage `colorScheme` — use `lightDark()` for one-off color differences rather than hard-coding `colorScheme="light"|"dark"`.
+- **Detect:** more than one `Provider`; a hard-coded `colorScheme` prop on `Provider`. (Root-Provider setup is in [01-setup-config](01-setup-config.md).)
+- **Severity:** Medium.
diff --git a/packages/dev/s2-docs/skills/spectrum-audit/checks/05-versioning.md b/packages/dev/s2-docs/skills/spectrum-audit/checks/05-versioning.md
new file mode 100644
index 00000000000..b169ed29396
--- /dev/null
+++ b/packages/dev/s2-docs/skills/spectrum-audit/checks/05-versioning.md
@@ -0,0 +1,18 @@
+# Check 05 — Versioning & maintenance
+
+## Checks
+
+### On the latest `@react-spectrum/s2`
+- **Rule:** Use the latest S2 release.
+- **Detect:** read the installed `@react-spectrum/s2` version (from the lockfile or `package.json`) and compare against the latest published version (`npm view @react-spectrum/s2 version`, if network access is available; otherwise note that it couldn't be checked).
+- **Severity:** Medium if behind by a minor/patch; High if a major version behind.
+
+### No Spectrum 1 + Spectrum 2 mixing
+- **Rule:** A codebase shouldn't straddle Spectrum 1 and Spectrum 2 long-term.
+- **Detect:** `@react-spectrum/s2` present **and** any Spectrum 1 packages — `@adobe/react-spectrum`, `@react-spectrum/*` (other than `/s2`), or `@spectrum-icons/*` — in `package.json` or imported in source.
+- **Severity:** High. **Hand off:** recommend the `migrate-react-spectrum-v3-to-s2` skill.
+
+### No deprecated props
+- **Rule:** Avoid props marked deprecated in the current S2 docs.
+- **Detect:** cross-check the props in use against the component docs in the `react-spectrum-s2` skill (`references/components/`).
+- **Severity:** Medium.
diff --git a/packages/dev/s2-docs/skills/spectrum-audit/checks/06-testing.md b/packages/dev/s2-docs/skills/spectrum-audit/checks/06-testing.md
new file mode 100644
index 00000000000..8519f8bd540
--- /dev/null
+++ b/packages/dev/s2-docs/skills/spectrum-audit/checks/06-testing.md
@@ -0,0 +1,12 @@
+# Check 06 — Testing
+
+Lowest-weight category. Only applies if the project has tests that exercise S2 components.
+
+## Checks
+
+### Use the ARIA pattern testers
+- **Rule:** Test S2 components with the ARIA pattern testers from `@react-spectrum/test-utils` rather than hand-rolled role/selector queries. The testers model real user interaction (open a menu, select a row, toggle a checkbox) and stay correct as internal DOM changes.
+- **Detect:** tests that render S2 collections or overlays and query them with raw `getByRole` / `container.querySelector` chains instead of the `@react-spectrum/test-utils` testers.
+- **Severity:** Low.
+
+If the project has no tests touching S2 components, score this category **100** and label it "not applicable" in the report.
diff --git a/packages/dev/s2-docs/skills/spectrum-audit/report-template.md b/packages/dev/s2-docs/skills/spectrum-audit/report-template.md
new file mode 100644
index 00000000000..9ca13066f5e
--- /dev/null
+++ b/packages/dev/s2-docs/skills/spectrum-audit/report-template.md
@@ -0,0 +1,72 @@
+# Spectrum Audit report format
+
+Write the report to `SPECTRUM-AUDIT.md` in the audited project (or the audited package's root in a monorepo). Use this structure exactly.
+
+## Template
+
+```markdown
+# Spectrum Audit: <project name>
+
+**Spectrum Adherence Score: <score>/100 (<grade>)**
+<n> Critical · <n> High · <n> Medium · <n> Low
+
+## Summary
+
+<2–3 sentences: the overall state of Spectrum/S2 adherence, the single most important thing to fix, and one thing the project does well.>
+
+## Recommended skill
+
+<Include this section only if the `react-spectrum-s2` skill was not detected in Phase 0. Omit it entirely when the skill is installed.>
+
+> The `react-spectrum-s2` skill was not detected. Install it for full component docs, implementation guidance, and help fixing findings:
+>
+> ```bash
+> npx skills add https://react-spectrum.adobe.com --skill react-spectrum-s2
+> ```
+
+## Scores by category
+
+| Category | Grade | Findings |
+|----------|-------|----------|
+| Setup & configuration | <A–F> | <count> |
+| Component usage | <A–F> | <count> |
+| Styling | <A–F> | <count> |
+| Accessibility | <A–F> | <count> |
+| Versioning & maintenance | <A–F> | <count> |
+| Testing | <A–F> | <count> |
+
+## Findings
+
+Group by severity, highest first; omit empty groups. One bullet per finding:
+
+### Critical
+- `path/to/file.tsx:42` — **<rule>**. <Why it matters, one line.> _Fix:_ <remediation>. _Check:_ 03 — Styling
+
+### High
+…
+
+### Medium
+…
+
+### Low
+…
+
+## Action items
+
+- **Fix now** (Critical + High) — most impactful first.
+- **Improve** (Medium).
+- **Polish** (Low).
+- **Follow-ups** — e.g. upgrade to the latest `@react-spectrum/s2`; run the migration skill for remaining Spectrum 1 packages; move to React 19.
+
+## What looks good
+
+- <Genuine positives: correct build setup, good token usage, proper component composition.>
+```
+
+## Rules
+
+- Every finding cites a real `file:line` you actually read or grepped. Never invent locations.
+- Render `file:line` as a clickable link so the user can jump straight to it.
+- Cite the check that defines each rule as plain text (e.g. `_Check:_ 03 — Styling`).
+- Include the **Recommended skill** section when `react-spectrum-s2` was not detected in Phase 0; omit it when the skill is installed.
+- The audit is **report-only** — do not edit any files. Hand fixes to the `react-spectrum-s2` skill.
diff --git a/packages/dev/s2-docs/skills/spectrum-audit/scoring-rubric.md b/packages/dev/s2-docs/skills/spectrum-audit/scoring-rubric.md
new file mode 100644
index 00000000000..1197e687c9d
--- /dev/null
+++ b/packages/dev/s2-docs/skills/spectrum-audit/scoring-rubric.md
@@ -0,0 +1,57 @@
+# Spectrum Adherence Scoring
+
+The Spectrum Adherence Score is computed **deterministically** from the findings you recorded — never from a subjective sense of overall quality. The same set of findings must always produce the same score. Do not round, fudge, or "feel out" a number; run the arithmetic below.
+
+## Severity weights
+
+Each finding contributes points equal to its severity:
+
+| Severity | Weight | Meaning |
+|----------|--------|---------|
+| Critical | 10 | Breaks the build, breaks accessibility, or ships visibly broken styling to users. |
+| High | 5 | Wrong approach that will cause real problems — `UNSAFE_*`, bypassing the design system, missing CSS-bundle optimization. |
+| Medium | 2 | Missed reuse or a convention violation that degrades quality but still works. |
+| Low | 1 | Polish: redundant default props, minor token choices, naming. |
+
+## Per-category score
+
+For each of the six categories:
+
+```
+categoryScore = 100 − min(100, Σ severityWeight for findings in that category)
+```
+
+A category with no findings scores 100. A category with one Critical + two Medium findings scores `100 − (10 + 2 + 2) = 86`. The `min(…, 100)` caps deductions so one very-noncompliant category can't push a score below 0.
+
+## Overall score
+
+The overall score is the weighted average of the six category scores:
+
+| Category | Weight |
+|----------|--------|
+| Setup & configuration | 25% |
+| Component usage | 20% |
+| Styling | 20% |
+| Accessibility | 20% |
+| Versioning & maintenance | 10% |
+| Testing | 5% |
+
+```
+overall = round( Σ (categoryScore × categoryWeight) )
+```
+
+## Grade bands
+
+| Score | Grade |
+|-------|-------|
+| 90–100 | A |
+| 80–89 | B |
+| 70–79 | C |
+| 60–69 | D |
+| < 60 | F |
+
+## Notes
+
+- If a category does not apply (e.g. the project has no tests), score it **100** and label it "not applicable" rather than penalizing the project.
+- Always show the raw finding counts next to the score. The number is a summary, not a substitute for reading the findings.
+- **Deduplicate findings:** count each distinct root cause at a `file:line` once. If multiple checks could apply (e.g. a missing collection `aria-label`, or a third-party design system import), assign it to the most specific check and category only.

From 208099b23661a5157a197774be14dc9a9ef44cab Mon Sep 17 00:00:00 2001
From: Daniel Lu <dl1644@gmail.com>
Date: Wed, 17 Jun 2026 15:25:03 -0700
Subject: [PATCH 4/4] chore: omit isNonModal from ContextualHelpPopover
 (#10224)

---
 packages/@react-spectrum/s2/src/ContextualHelp.tsx | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/packages/@react-spectrum/s2/src/ContextualHelp.tsx b/packages/@react-spectrum/s2/src/ContextualHelp.tsx
index 714ef17d051..12da8a4c411 100644
--- a/packages/@react-spectrum/s2/src/ContextualHelp.tsx
+++ b/packages/@react-spectrum/s2/src/ContextualHelp.tsx
@@ -26,7 +26,7 @@ import {useLabels} from 'react-aria/private/utils/useLabels';
 import {useLocalizedStringFormatter} from 'react-aria/useLocalizedStringFormatter';
 import {useSpectrumContextProps} from './useSpectrumContextProps';
 
-export interface ContextualHelpPopoverProps extends PopoverDialogProps {
+export interface ContextualHelpPopoverProps extends Omit<PopoverDialogProps, 'isNonModal'> {
   /**
    * The children of the contextual help popover. Supports Heading, Content, and Footer elements.
    */