From 1403064a86160f0a09e49ce6182925313c613a6e Mon Sep 17 00:00:00 2001
From: Devon Govett <devongovett@gmail.com>
Date: Mon, 27 Oct 2025 18:11:21 -0700
Subject: [PATCH 1/3] docs: Add concepts page

---
 .../dev/s2-docs/pages/react-aria/concepts.mdx | 156 ++++++++++++++++++
 .../dev/s2-docs/pages/react-aria/index.mdx    |   6 +-
 .../dev/s2-docs/pages/react-aria/styling.mdx  |   2 +-
 3 files changed, 160 insertions(+), 4 deletions(-)
 create mode 100644 packages/dev/s2-docs/pages/react-aria/concepts.mdx

diff --git a/packages/dev/s2-docs/pages/react-aria/concepts.mdx b/packages/dev/s2-docs/pages/react-aria/concepts.mdx
new file mode 100644
index 00000000000..5dd5c6f6f8e
--- /dev/null
+++ b/packages/dev/s2-docs/pages/react-aria/concepts.mdx
@@ -0,0 +1,156 @@
+import {Layout} from '../../src/Layout';
+export default Layout;
+
+export const section = 'Guides';
+export const description = 'Implementing drag and drop in React Aria';
+
+# Concepts
+
+<PageDescription>React Aria is built around three core principles: **Accessibility**, **Internationalization**, and **Interactions**. Together, these ensure that every component you build works for everyone, everywhere, and on every device.</PageDescription>
+
+## Accessibility
+
+Accessible applications are usable by everyone, including people with disabilities. Accessibility benefits all users — not just those using assistive technologies — by improving efficiency, consistency, and usability.
+
+React Aria provides built-in support for screen readers and keyboard navigation, following the [WAI-ARIA](https://www.w3.org/TR/wai-aria-1.2/) and [ARIA Authoring Practices](https://www.w3.org/WAI/ARIA/apg/) guidelines. It supplies the correct semantics via ARIA roles and attributes, handles keyboard and pointer events, manages focus, and provides screen reader announcements. React Aria components are tested across a wide variety of devices, browsers, and screen readers.
+
+You’re responsible for providing meaningful labels and ensuring your visual design supports all users. This includes designing with sufficient [color contrast](https://www.w3.org/WAI/WCAG22/Understanding/non-text-contrast) and [hit target sizes](https://www.w3.org/WAI/WCAG22/Understanding/target-size-enhanced), including visible [focus rings](https://www.w3.org/WAI/WCAG22/Understanding/focus-appearance), respecting [motion preferences](https://www.w3.org/WAI/WCAG21/Understanding/animation-from-interactions), and more. The [WCAG guidelines](https://www.w3.org/WAI/WCAG22/Understanding/) are a good resource to reference when designing and building components with React Aria.
+
+### Labeling
+
+Most components should have a visible label, which is usually provided by rendering a `<Label>` element within it. This is associated with the component automatically.
+
+```tsx
+import {TextField, Label, Input} from 'react-aria-components';
+
+<TextField>
+  {/*- begin highlight -*/}
+  <Label>First name</Label>
+  {/*- end highlight -*/}
+  <Input />
+</TextField>
+```
+
+When a component doesn't have a visible label, it must have an [aria-label](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-label) or [aria-labelledby](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-labelledby) prop to provide an accessible name.
+
+```tsx
+import {ProgressBar} from 'react-aria-components';
+
+<ProgressBar
+  /*- begin highlight -*/
+  aria-label="Processing" />
+  /*- end highlight -*/
+```
+
+### Supported screen readers
+
+React Aria is tested across a variety of devices, browsers, and screen readers.
+
+* [VoiceOver on macOS](https://www.apple.com/accessibility/mac/vision/) in Safari and Chrome
+* [JAWS](https://www.freedomscientific.com/products/software/jaws/) on Windows in Firefox and Chrome
+* [NVDA](https://www.nvaccess.org) on Windows in Firefox and Chrome
+* [VoiceOver on iOS](https://www.apple.com/accessibility/iphone/vision/)
+* [TalkBack](https://www.android.com/accessibility/) on Android in Chrome
+
+### Automated testing
+
+Automated accessibility testing tools sometimes catch false positives in React Aria. These are documented in our [wiki](https://github.com/adobe/react-spectrum/wiki/Known-accessibility-false-positives). Use the rules below to ignore these issues in your own testing tools, such as in the [Storybook test runner](https://storybook.js.org/docs/7.1/react/writing-tests/accessibility-testing#a11y-config-with-the-test-runner) or [Storybook a11y addon](https://storybook.js.org/docs/7.1/react/writing-tests/accessibility-testing#global-a11y-configuration).
+
+```tsx
+{
+  rules: [
+    {
+      id: 'aria-hidden-focus',
+      selector: 'body *:not([data-a11y-ignore="aria-hidden-focus"])'
+    }
+  ]
+}
+```
+
+## Internationalization
+
+Localization is an important way to make your application usable by the widest number of people. React Aria includes localized strings for 30+ languages, handles dates and numbers in many calendar and numbering systems, and supports right-to-left interactions (e.g. keyboard navigation).
+
+You’re responsible for ensuring your design supports right-to-left layout, and adapts to different languages (e.g. using appropriate fonts). Modern CSS grid and flex layouts are automatically mirrored depending on the direction, and [logical properties](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_logical_properties_and_values) can be used to adapt margins, paddings, borders, etc.
+
+### Setting the locale
+
+React Aria automatically detects the user's current language by default. Use the `I18nProvider` component to set the locale to a specific value. You should also set the `lang` and `dir` attributes on the root-most element of your application.
+
+```tsx
+import {I18nProvider, useLocale} from 'react-aria-components';
+
+<I18nProvider locale="fr-FR">
+  <App />
+</I18nProvider>
+
+function App() {
+  let {locale, direction} = useLocale();
+
+  return (
+    <html lang={locale} dir={direction}>
+      {/* your app here */}
+    </html>
+  );
+}
+```
+
+### Supported locales
+
+<ul style={{columnWidth: 200, paddingLeft: 16, fontFamily: 'adobe-clean-spectrum-vf'}}>
+  <li>Arabic (United Arab Emirates)</li>
+  <li>Bulgarian (Bulgaria)</li>
+  <li>Chinese (Simplified)</li>
+  <li>Chinese (Traditional)</li>
+  <li>Croatian (Croatia)</li>
+  <li>Czech (Czech Republic)</li>
+  <li>Danish (Denmark)</li>
+  <li>Dutch (Netherlands)</li>
+  <li>English (Great Britain)</li>
+  <li>English (United States)</li>
+  <li>Estonian (Estonia)</li>
+  <li>Finnish (Finland)</li>
+  <li>French (Canada)</li>
+  <li>French (France)</li>
+  <li>German (Germany)</li>
+  <li>Greek (Greece)</li>
+  <li>Hebrew (Israel)</li>
+  <li>Hungarian (Hungary)</li>
+  <li>Italian (Italy)</li>
+  <li>Japanese (Japan)</li>
+  <li>Korean (Korea)</li>
+  <li>Latvian (Latvia)</li>
+  <li>Lithuanian (Lithuania)</li>
+  <li>Norwegian (Norway)</li>
+  <li>Polish (Poland)</li>
+  <li>Portuguese (Brazil)</li>
+  <li>Romanian (Romania)</li>
+  <li>Russian (Russia)</li>
+  <li>Serbian (Serbia)</li>
+  <li>Slovakian (Slovakia)</li>
+  <li>Slovenian (Slovenia)</li>
+  <li>Spanish (Spain)</li>
+  <li>Swedish (Sweden)</li>
+  <li>Turkish (Turkey)</li>
+  <li>Ukrainian (Ukraine)</li>
+</ul>
+
+## Interactions
+
+Modern web apps run on everything from desktops to mobile devices to TVs, with users interacting through mouse, touch, keyboard, and assistive technologies. React Aria normalizes these differences, delivering consistent “press”, “hover”, and “focus” behaviors across all browsers and input types.
+
+React Aria components provide data attributes and render props to style these states:
+
+* `data-pressed` – like the `:active` pseudo class, but removed when dragging off the element.
+* `data-hovered` – like `:hover`, but does not apply on touch devices to avoid sticky hover states.
+* `data-focus-visible` – like `:focus-visible`, but avoids false positives from programmatic focus.
+
+These states also come with corresponding events such as `onPress` and `onHoverStart`. To use these events in your own custom components, see hooks such as [usePress](usePress.html), [useHover](useHover.html), [useMove](useMove.html), and [useFocusRing](useFocusRing.html).
+
+Read our blog post series to learn more about the intricacies behind these interactions.
+
+* [Building a Button Part 1: Press Events](https://react-spectrum.adobe.com/blog/building-a-button-part-1.html)
+* [Building a Button Part 2: Hover Interactions](https://react-spectrum.adobe.com/blog/building-a-button-part-2.html)
+* [Building a Button Part 3: Keyboard Focus Behavior](https://react-spectrum.adobe.com/blog/building-a-button-part-3.html)
+
+Higher level interaction patterns such as [selection](selection.html) and [drag and drop](dnd.html) are also built on top of these low level primitives.
diff --git a/packages/dev/s2-docs/pages/react-aria/index.mdx b/packages/dev/s2-docs/pages/react-aria/index.mdx
index a6de187240b..75c1ba2558b 100644
--- a/packages/dev/s2-docs/pages/react-aria/index.mdx
+++ b/packages/dev/s2-docs/pages/react-aria/index.mdx
@@ -305,7 +305,7 @@ export const hideFromSearch = true;
     <Section className="cyan-gradient-background">
       <h2><GradientText>High quality</GradientText> <span className="bg-clip-text bg-linear-to-t from-cyan-600 to-green-600">interactions</span> <GradientText>on all devices.</GradientText></h2>
       <p className="m-0">React Aria ensures a great experience for users, no matter their device. All components are optimized for mouse, touch, keyboard, and screen reader interactions, with a meticulous attention to detail that makes your app feel responsive and natural on every platform.</p>
-      <LearnMoreLink href="interactions.html" className="text-cyan-700 dark:text-cyan-600 hover:bg-cyan-400/[15%]" />
+      <LearnMoreLink href="concepts.html#interactions" className="text-cyan-700 dark:text-cyan-600 hover:bg-cyan-400/[15%]" />
 
       <PaginatedCarousel className="grid gap-4 md:gap-6 grid-cols-[repeat(4,100%)] md:grid-cols-2 md:grid-rows-2 -mx-8 md:mx-0 px-8 md:px-0 py-4 md:py-0 overflow-auto md:overflow-visible snap-x snap-mandatory no-scrollbar" paginationClassName="md:hidden">
         <Card>
@@ -347,7 +347,7 @@ export const hideFromSearch = true;
     <Section className="blue-gradient-background">
       <h2><span className="bg-clip-text bg-linear-to-b from-sky-500 to-indigo-600">Accessibility</span> <GradientText>that's truly first-class.</GradientText></h2>
       <p className="m-0">React Aria is designed with accessibility as a top priority, and battle tested in production applications. All components are built to work across a wide variety of devices and assistive technologies to ensure the best experience possible for all users.</p>
-      <LearnMoreLink href="accessibility.html" className="text-blue-600 dark:text-blue-500 hover:bg-blue-400/[15%]" />
+      <LearnMoreLink href="concepts.html#accessibility" className="text-blue-600 dark:text-blue-500 hover:bg-blue-400/[15%]" />
 
       <div className="grid gap-y-6 gap-x-20 md:grid-cols-[min-content_auto] md:grid-flow-col place-items-center">
         <div className="w-full max-w-xs md:w-auto md:max-w-none md:row-span-3 md:h-full aspect-1/2 iphone-frame md:order-4">
@@ -376,7 +376,7 @@ export const hideFromSearch = true;
     <Section className="orange-gradient-background">
       <h2><GradientText>Ready for an</GradientText> <span className="bg-clip-text bg-linear-to-b from-yellow-500 to-orange-600">international</span> <GradientText>audience.</GradientText></h2>
       <p className="m-0">React Aria is engineered for internationalization out of the box, including translations in over 30 languages, localized date and number formatting and parsing, support for 13 calendar systems, 5 numbering systems, right-to-left layout, and more.</p>
-      <LearnMoreLink href="internationalization.html" className="text-orange-700 dark:text-orange-600 hover:bg-orange-400/[15%]" />
+      <LearnMoreLink href="concepts.html#internationalization" className="text-orange-700 dark:text-orange-600 hover:bg-orange-400/[15%]" />
       <I18n />
     </Section>
 
diff --git a/packages/dev/s2-docs/pages/react-aria/styling.mdx b/packages/dev/s2-docs/pages/react-aria/styling.mdx
index 1c11d96bf68..323135d1dd2 100644
--- a/packages/dev/s2-docs/pages/react-aria/styling.mdx
+++ b/packages/dev/s2-docs/pages/react-aria/styling.mdx
@@ -47,7 +47,7 @@ Components often support multiple UI states (e.g. pressed, hovered, selected, et
 }
 ```
 
-In order to ensure high quality interactions across browsers and devices, React Aria Components includes states such as `data-hovered` and `data-pressed` which are similar to CSS pseudo classes such as `:hover` and `:active`, but work consistently between mouse, touch, and keyboard modalities. You can read more about this in our [blog post series](https://react-spectrum.adobe.com/blog/building-a-button-part-1.html) and our [Interactions](https://react-spectrum.adobe.com/react-aria/interactions.html) overview.
+React Aria includes states such as `data-hovered` and `data-pressed` which are similar to CSS pseudo classes such as `:hover` and `:active`, but work consistently between mouse, touch, and keyboard modalities. You can read more about this in our [blog post series](https://react-spectrum.adobe.com/blog/building-a-button-part-1.html) and our [Interactions](concepts.html#interactions) overview.
 
 All states supported by each component are listed in the Styling section of their documentation.
 

From dfb9f994fb7800efb0d4902f6e899b4948fd3eae Mon Sep 17 00:00:00 2001
From: Devon Govett <devongovett@gmail.com>
Date: Mon, 27 Oct 2025 18:17:10 -0700
Subject: [PATCH 2/3] Fix description

---
 packages/dev/s2-docs/pages/react-aria/concepts.mdx | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/packages/dev/s2-docs/pages/react-aria/concepts.mdx b/packages/dev/s2-docs/pages/react-aria/concepts.mdx
index 5dd5c6f6f8e..37cf4845cc5 100644
--- a/packages/dev/s2-docs/pages/react-aria/concepts.mdx
+++ b/packages/dev/s2-docs/pages/react-aria/concepts.mdx
@@ -2,7 +2,7 @@ import {Layout} from '../../src/Layout';
 export default Layout;
 
 export const section = 'Guides';
-export const description = 'Implementing drag and drop in React Aria';
+export const description = 'Learn about Accessibility, Internationalization, and Interactions in React Aria';
 
 # Concepts
 

From 08de791c82de77c16213ea52e8ccbcc4b14512dc Mon Sep 17 00:00:00 2001
From: Devon Govett <devongovett@gmail.com>
Date: Tue, 4 Nov 2025 15:44:28 -0800
Subject: [PATCH 3/3] updates

---
 .../dev/s2-docs/pages/react-aria/concepts.mdx | 23 +++++--------------
 1 file changed, 6 insertions(+), 17 deletions(-)

diff --git a/packages/dev/s2-docs/pages/react-aria/concepts.mdx b/packages/dev/s2-docs/pages/react-aria/concepts.mdx
index 37cf4845cc5..5097a103b0e 100644
--- a/packages/dev/s2-docs/pages/react-aria/concepts.mdx
+++ b/packages/dev/s2-docs/pages/react-aria/concepts.mdx
@@ -14,7 +14,7 @@ Accessible applications are usable by everyone, including people with disabiliti
 
 React Aria provides built-in support for screen readers and keyboard navigation, following the [WAI-ARIA](https://www.w3.org/TR/wai-aria-1.2/) and [ARIA Authoring Practices](https://www.w3.org/WAI/ARIA/apg/) guidelines. It supplies the correct semantics via ARIA roles and attributes, handles keyboard and pointer events, manages focus, and provides screen reader announcements. React Aria components are tested across a wide variety of devices, browsers, and screen readers.
 
-You’re responsible for providing meaningful labels and ensuring your visual design supports all users. This includes designing with sufficient [color contrast](https://www.w3.org/WAI/WCAG22/Understanding/non-text-contrast) and [hit target sizes](https://www.w3.org/WAI/WCAG22/Understanding/target-size-enhanced), including visible [focus rings](https://www.w3.org/WAI/WCAG22/Understanding/focus-appearance), respecting [motion preferences](https://www.w3.org/WAI/WCAG21/Understanding/animation-from-interactions), and more. The [WCAG guidelines](https://www.w3.org/WAI/WCAG22/Understanding/) are a good resource to reference when designing and building components with React Aria.
+Be sure to create an accessible visual design with meaningful labels, sufficient [color contrast](https://www.w3.org/WAI/WCAG22/Understanding/non-text-contrast) and [hit target sizes](https://www.w3.org/WAI/WCAG22/Understanding/target-size-enhanced), visible [focus rings](https://www.w3.org/WAI/WCAG22/Understanding/focus-appearance), and respect [motion preferences](https://www.w3.org/WAI/WCAG21/Understanding/animation-from-interactions). The [WCAG guidelines](https://www.w3.org/WAI/WCAG22/Understanding/) are a good resource to reference when designing and building components with React Aria.
 
 ### Labeling
 
@@ -54,24 +54,13 @@ React Aria is tested across a variety of devices, browsers, and screen readers.
 
 ### Automated testing
 
-Automated accessibility testing tools sometimes catch false positives in React Aria. These are documented in our [wiki](https://github.com/adobe/react-spectrum/wiki/Known-accessibility-false-positives). Use the rules below to ignore these issues in your own testing tools, such as in the [Storybook test runner](https://storybook.js.org/docs/7.1/react/writing-tests/accessibility-testing#a11y-config-with-the-test-runner) or [Storybook a11y addon](https://storybook.js.org/docs/7.1/react/writing-tests/accessibility-testing#global-a11y-configuration).
-
-```tsx
-{
-  rules: [
-    {
-      id: 'aria-hidden-focus',
-      selector: 'body *:not([data-a11y-ignore="aria-hidden-focus"])'
-    }
-  ]
-}
-```
+Automated accessibility testing tools sometimes catch false positives in React Aria. These are documented in our [wiki](https://github.com/adobe/react-spectrum/wiki/Known-accessibility-false-positives).
 
 ## Internationalization
 
 Localization is an important way to make your application usable by the widest number of people. React Aria includes localized strings for 30+ languages, handles dates and numbers in many calendar and numbering systems, and supports right-to-left interactions (e.g. keyboard navigation).
 
-You’re responsible for ensuring your design supports right-to-left layout, and adapts to different languages (e.g. using appropriate fonts). Modern CSS grid and flex layouts are automatically mirrored depending on the direction, and [logical properties](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_logical_properties_and_values) can be used to adapt margins, paddings, borders, etc.
+Make sure your design supports right-to-left layout, and adapts to different languages (e.g. using appropriate fonts). Modern CSS grid and flex layouts are automatically mirrored depending on the direction, and [logical properties](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_logical_properties_and_values) can be used to adapt margins, paddings, borders, etc.
 
 ### Setting the locale
 
@@ -141,9 +130,9 @@ Modern web apps run on everything from desktops to mobile devices to TVs, with u
 
 React Aria components provide data attributes and render props to style these states:
 
-* `data-pressed` – like the `:active` pseudo class, but removed when dragging off the element.
-* `data-hovered` – like `:hover`, but does not apply on touch devices to avoid sticky hover states.
-* `data-focus-visible` – like `:focus-visible`, but avoids false positives from programmatic focus.
+* `data-pressed` – like the `:active` pseudo class, but removed when the pointer is dragged off.
+* `data-hovered` – like `:hover`, but not applied on touch devices, preventing sticky hover states.
+* `data-focus-visible` – like `:focus-visible`, but not on input click or programmatic focus.
 
 These states also come with corresponding events such as `onPress` and `onHoverStart`. To use these events in your own custom components, see hooks such as [usePress](usePress.html), [useHover](useHover.html), [useMove](useMove.html), and [useFocusRing](useFocusRing.html).