Update React Aria docs to introduce components by default (#5436)

Author: devongovett

packages/@react-aria/i18n/docs/internationalization.mdx

@@ -27,7 +27,7 @@ right-to-left mirroring and interactions.
 
 Internationalization is the process of structuring your code and user interface to support localization. React Aria supports
 many aspects of localization for many components out of the box, including translations for builtin strings, localized
-date and number formatting, right-to-left interactions, and more. By using React Aria for your design system,
+date and number formatting, right-to-left interactions, and more. By using React Aria to build your components,
 these aspects of internationalization are handled for you. You can also use our hooks in your own custom components.
 
 ## Localization
@@ -46,7 +46,7 @@ also use our internationalization hooks in your own components. These are implem
 [Intl](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl) APIs under the hood, so there's no
 large libraries or locale data for users to download.
 
-See [useMessageFormatter](useMessageFormatter.html), [useDateFormatter](useDateFormatter.html), [useNumberFormatter](useNumberFormatter.html),
+See [useDateFormatter](useDateFormatter.html), [useNumberFormatter](useNumberFormatter.html),
 and [useCollator](useCollator.html) for more information about using our internationalization hooks. The
 [Internationalized](../../internationalized/index.html) collection of libraries provides framework-agnostic utilities for representing
 and manipulating [dates and times](../../internationalized/date/index.html), and parsing and formatting
@@ -63,10 +63,9 @@ opposite side of the interface. For example, a button that would be displayed on
 would appear on the left side of the screen in a right-to-left language. In addition, elements within a component are also expected to
 mirror. For example, in a checkbox component, the label would be placed on the left side of the checkmark rather than the right.
 
-Since React Aria provides no rendering, it is up to you to implement RTL support in your design. The documentation for individual react-aria hooks
-calls out when you need to be aware of this, so you can account for it in your CSS using
-[logical properties](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Logical_Properties) or other means. For example, flexbox and CSS grid
-both automatically flip their layouts depending on the direction.
+Since React Aria provides no styling, it is up to you to implement RTL support in your design. CSS flex and grid layouts automatically flip depending
+on the direction, and [logical properties](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Logical_Properties) are a great way to handle
+margins, paddings, borders, and more.
 
 Even though it is not responsible for rendering or layout, React Aria is aware of the current directionality, and adjusts interactions
 accordingly. For example, when navigating using the left and right arrow keys, React Aria automatically flips the direction so that
@@ -76,10 +75,10 @@ the left arrow always navigates to the item physically to the left, and the righ
 
 The root most element of your application should define the [lang](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/lang)
 and [dir](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/dir) attributes so that the browser knows which language
-and direction the user interface should be rendered in. This can be done with the [useLocale](useLocale.html) hook from `@react-aria/i18n`.
+and direction the user interface should be rendered in. This can be done with the [useLocale](useLocale.html) hook.
 
 ```tsx
-import {useLocale} from '@react-aria/i18n';
+import {useLocale} from 'react-aria-components';
 
 function YourApp() {
   let {locale, direction} = useLocale();
@@ -94,10 +93,10 @@ function YourApp() {
 
 React Aria automatically detects the user's current language by default, and even updates this if the browser or system language changes.
 However, if you would like to override this with an application specific setting, you can do so using the [I18nProvider](I18nProvider.html)
-exposed by `@react-aria/i18n`.
+component.
 
 ```tsx
-import {I18nProvider} from '@react-aria/i18n';
+import {I18nProvider} from 'react-aria-components';
 
 <I18nProvider locale="fr-FR">
   <YourApp />

packages/@react-aria/interactions/docs/interactions.mdx

@@ -34,7 +34,7 @@ high level gesture events, or even the concept of a “press” event that works
 We just have low level events like mouse, touch, keyboard, and focus events, and it's up to developers to put them
 together properly. This leads to many web apps not working consistently across various types of devices and interaction models.
 
-React Aria includes a collection of [Hooks](https://reactjs.org/docs/hooks-intro.html) that provide higher level abstractions
+React Aria includes a collection of [Hooks](https://react.dev/reference/react/hooks) that provide higher level abstractions
 over the low level events exposed by the web platform, and helps normalize the behavior across browsers and devices. This includes
 support for high level events like “press”, “hover”, and “focus”. Some of these seem simple at first, but you’d be surprised how
 complicated it is to handle these events in a cross-browser, cross-device way. There are many tiny behavioral
@@ -78,7 +78,7 @@ At a high level, keyboard navigation is broken up into **tab stops**, which may
 move to the next tab stop, and <Keyboard>Shift</Keyboard> + <Keyboard>Tab</Keyboard> to move to the previous tab stop. A tab stop may be an atomic
 component like a text field or button, or a composite component like a listbox, radio group, grid, or toolbar. Composite components
 behave as a single tab stop. Elements within a composite component are typically navigated with the arrow keys, while the <Keyboard>Tab</Keyboard>
-key continues to navigate to the next/previous tab stop. React Aria implements hooks for many of these composite components and handles
+key continues to navigate to the next/previous tab stop. React Aria implements many of these composite components and handles
 all of the keyboard navigation behavior for elements inside them.
 
 Overlay elements like dialogs, popovers, and menus have additional focus behavior to ensure that focus stays within them while they
@@ -109,9 +109,7 @@ so that components receive a consistent stream of events regardless of the inter
 All React Aria components are tested across a wide variety of browsers and devices. We test across devices with
 mouse input, touchscreens, and also hybrid devices.
 
-* Chrome 88+ on macOS and Windows
-* Firefox 85+ on macOS and Windows
-* Safari 13+ on macOS
-* Edge 88+ on Windows
-* Safari 13+ on iOS and iPadOS
-* Chrome 88+ on Android
+* Chrome on macOS, Windows, and Android
+* Firefox on macOS and Windows
+* Safari on macOS, iOS, and iPadOS
+* Edge on Windows

packages/dev/docs/pages/architecture.mdx

@@ -61,17 +61,17 @@ and time, and reducing duplicated effort across the industry.
 
 <figure className={style.float}>
   <Flex direction="column" gap="size-125">
-    <View backgroundColor="magenta-600" height="size-900">
+    <View backgroundColor="static-magenta-600" height="size-900">
       <Flex alignItems="center" justifyContent="center" height="100%">
         <span style={{color: 'white', fontSize: 18}}>Component</span>
       </Flex>
     </View>
-    <View backgroundColor="green-600" height="size-900">
+    <View backgroundColor="static-green-600" height="size-900">
       <Flex alignItems="center" justifyContent="center" height="100%">
         <span style={{color: 'white', fontSize: 18}}>Behavior Hook</span>
       </Flex>
     </View>
-    <View backgroundColor="blue-500" height="size-900">
+    <View backgroundColor="static-blue-600" height="size-900">
       <Flex alignItems="center" justifyContent="center" height="100%">
         <span style={{color: 'white', fontSize: 18}}>State Hook</span>
       </Flex>
@@ -89,7 +89,7 @@ other components, so each component has the pieces of this architecture
 that make sense for their purpose.
 
 This architecture is made possible by
-[React Hooks](https://reactjs.org/docs/hooks-intro.html), which enable
+[React Hooks](https://react.dev/reference/react/hooks), which enable
 the ability to reuse behavior between multiple components. Hooks allow
 accessing React features like state and effects from functions which
 can be called from any component. If you're unfamiliar with hooks,
@@ -147,25 +147,30 @@ the state from the state hook to adjust its visual appearance.
 This allows complete control over the rendering of the component, including
 things like adding extra elements as needed for styling or layout control.
 
+The component itself may be split into unstyled and styled parts. Unstyled components
+compose together hooks and abstract away the glue code necessary to connect them together
+by providing reusable contexts, DOM structure, and styling APIs. This simplifies design system
+components while retaining the flexibility to drop down to lower-level APIs when needed.
+
 <div style={{clear: 'both'}} />
 
 ## Implementation
 
 <figure className={style.float}>
   <Flex direction="column" gap="size-125">
-    <View backgroundColor="magenta-600" height="size-900">
+    <View backgroundColor="static-magenta-600" height="size-900">
       <Flex alignItems="center" justifyContent="center" height="100%">
-        <span style={{color: 'white', fontSize: 18}}>@react-spectrum</span>
+        <span style={{color: 'white', fontSize: 18}}>React Spectrum</span>
       </Flex>
     </View>
-    <View backgroundColor="green-600" height="size-900">
+    <View backgroundColor="static-green-600" height="size-900">
       <Flex alignItems="center" justifyContent="center" height="100%">
-        <span style={{color: 'white', fontSize: 18}}>@react-aria</span>
+        <span style={{color: 'white', fontSize: 18}}>React Aria</span>
       </Flex>
     </View>
-    <View backgroundColor="blue-500" height="size-900">
+    <View backgroundColor="static-blue-600" height="size-900">
       <Flex alignItems="center" justifyContent="center" height="100%">
-        <span style={{color: 'white', fontSize: 18}}>@react-stately</span>
+        <span style={{color: 'white', fontSize: 18}}>React Stately</span>
       </Flex>
     </View>
   </Flex>
@@ -208,20 +213,21 @@ by reading the docs.
 ### React Aria
 
 [React Aria](react-aria/index.html) implements behavior and [accessibility](react-aria/accessibility.html)
-for the web according to [WAI-ARIA Authoring Practices](https://www.w3.org/TR/wai-aria-practices-1.2/).
+for the web according to the W3C's [ARIA Authoring Practices Guide](https://www.w3.org/WAI/ARIA/apg/).
 It includes full screen reader and keyboard navigation support, along with
 mouse and touch [interactions](react-aria/interactions.html) that have been
 tested across a wide variety of devices and browsers. It also implements
 [internationalization](react-aria/internationalization.html) for over 30
 languages, including right-to-left specific behavior, localized date and
 number formatting, and more.
 
-Most importantly, React Aria is **fully customizable**, since it doesn't
-implement any rendering or impose a DOM structure or styling methodology.
-You just need to spread the props returned by each React Aria hook onto
-the appropriate DOM elements, and you get high quality interactions,
-behavior, and accessibility pretty much for free. All you need to do is
-provide the styling.
+Most importantly, React Aria is **fully customizable**. It offers both high-level
+unstyled components and low-level hooks depending on the level of customization you need.
+The components provide a default DOM structure and styling API, and handle all
+of the glue code necessary to connect the hooks together on your behalf.
+If you need even more control, you can drop down to the lower-level hook-based API,
+which enables [advanced customization](react-aria/advanced.html) use cases such
+as overriding DOM elements, intercepting events, customizing behavior, and more.
 
 [Read more](react-aria/why.html) about React Aria and
 the problems it solves, and check out the docs to [get started](react-aria/getting-started.html)

packages/dev/docs/pages/react-aria/accessibility.mdx

@@ -46,15 +46,15 @@ with built-in semantics (e.g. `<button>` or `<select>`) for styling reasons, or
 ARIA is required to make presentational elements (e.g. `<div>`) have semantic meaning. This allows screen readers and
 other assistive technology to understand these elements and announce them properly to the user.
 
-However, ARIA is a contract: it only specifies semantics, and it's up to the developer to implement the
-**behavior** and interactions for each control with JavaScript. There is an additional document published by the W3C
-called the [WAI-ARIA Authoring Practices](https://www.w3.org/TR/wai-aria-practices-1.2/), which provides patterns
+However, ARIA only specifies semantics, and it's up to the developer to implement the
+**behavior** and interactions for each control with JavaScript. The W3C also publishes
+the [ARIA Authoring Practices Guide](https://www.w3.org/WAI/ARIA/apg/), which provides patterns
 and examples of implementing this behavior on top of ARIA. It specifies keyboard interactions that are expected
 by users of these controls, along with the required roles and states to make them accessible to assistive technology.
 
-React Aria provides hooks for many ARIA patterns, which provide the semantics and behavior together. This makes building
-accessible components with custom styling much easier: just spread the props returned by the hooks onto the appropriate
-elements and you get accessibility and behavior pretty much for free. All you need to do is provide the styling.
+React Aria provides implementations of ARIA patterns as unstyled React components and hooks, which include both the
+semantics and behavior out of the box. This makes building accessible components with custom styling much easier, because
+you only need to implement your custom styles and get the accessibility and behavior for free.
 
 ## Labeling
 
@@ -66,13 +66,13 @@ will automatically associate the visible label with the control so that assistiv
 
 In case a visible label is not desired for some reason, or you're using a control that doesn't have a built-in label,
 you must use the `aria-label` or `aria-labelledby` props to identify it to assistive technology. Most React Aria
-hooks will display a console warning if you are missing both a visible label and an ARIA label.
+components will display a console warning if you are missing both a visible label and an ARIA label.
 
 ## Keyboard navigation
 
 React Aria implements keyboard support for all components, which allows users who cannot use a mouse or touch screen
 to navigate your app. It also allows power users to navigate your application more quickly, without lifting their hands
-from the keyboard. All keyboard behavior is implemented according to the [WAI-ARIA Authoring Practices](https://www.w3.org/TR/wai-aria-practices-1.2/) guidelines,
+from the keyboard. All keyboard behavior is implemented according to the W3C's [ARIA Authoring Practices Guide](https://www.w3.org/WAI/ARIA/apg/),
 and is designed to feel familiar to users of most commonly used desktop operating systems.
 
 For more information about keyboard navigation and focus interactions, see the [interactions](interactions.html) overview.

packages/dev/docs/pages/react-aria/forms.mdx

@@ -14,14 +14,15 @@ import {Layout} from '@react-spectrum/docs';
 export default Layout;
 
 ```css hidden
+@import '@react-aria/example-theme';
 @import 'react-aria-components/docs/TextField.mdx';
 @import 'react-aria-components/docs/Button.mdx';
 ```
 
 ---
-category: Concepts
+category: Guides
 keywords: [forms, validation, frameworks, aria, next.js, remix, react server actions]
-order: 6
+order: 1
 ---
 
 # Forms