updated carousel docs.

apps/website/src/pages/docs/carousel.mdx

@@ -2,76 +2,102 @@
 title: Carousel
 description: A slideshow component for cycling through elements.
 layout: ./_layout.astro
-propsPath: '@itwin/itwinui-react/esm/core/Carousel/Carousel.d.ts'
 thumbnail: Carousel
 group: core
 ---
 
 import PropsTable from '~/components/PropsTable.astro';
 import LiveExample from '~/components/LiveExample.astro';
-import Placeholder from '~/components/Placeholder.astro';
 import * as AllExamples from 'examples';
 
 <p>{frontmatter.description}</p>
 
-<Placeholder componentPageName='carousel' />
-
 <LiveExample src='Carousel.main.tsx'>
   <AllExamples.CarouselMainExample client:load />
 </LiveExample>
 
-The Carousel component consists of a set of slides, normally displayed one at a time. A navigation section is
-located below the slides, consisting of "dots" and "previous"/"next" buttons, used for changing slides.
-
-The currently shown slide can also be changed using the left/right arrow keys or by dragging on a touch device.
+The Carousel component consists of a set of slides, normally displayed one at a time. A navigation section is located below the slides, consisting of ["dots"](#carouseldotslist) and ["previous"/"next"](#carouselnavigation) buttons, used for changing slides.
 
 ## Usage
 
-Carousels can be controlled externally by using the properties `activeSlideIndex` and `onSlideChange`.
+The Carousel component is made up of [customizable subcomponents](#component-api). Here's what the basic usage looks like:
+
+```tsx
+<Carousel>
+  <Carousel.Navigation />
+  <Carousel.Slider>
+    <Carousel.Slide>…</Carousel.Slide>
+    <Carousel.Slide>…</Carousel.Slide>
+    <Carousel.Slide>…</Carousel.Slide>
+  </Carousel.Slider>
+</Carousel>
+```
+
+### Controlled State
+
+By default, the carousel maintains its own state. But it can also be controlled externally using `activeSlideIndex` and `onSlideChange`.
 
 <LiveExample src='Carousel.controlled.tsx'>
   <AllExamples.CarouselControlledExample client:load />
 </LiveExample>
 
-The subcomponents can be used outside of Carousel. The following example shows how `Carousel.DotsList` can be used without the `Carousel` component. Clicking on the right half of the slide will advance the carousel to the next slide, whereas clicking on the left half will go to the previous slide.
+## Accessibility
 
-<LiveExample src='Carousel.onlyDots.tsx'>
-  <AllExamples.CarouselOnlyDotsExample client:load />
-</LiveExample>
+The `Carousel` component is built with accessibility in mind and tested to work well with different input modalities. It includes support for keyboard users and touch-screen users.
+
+The component is loosely based on the [APG Tabs pattern](https://www.w3.org/WAI/ARIA/apg/patterns/tabs/), where the dots are considered to be "tabs" and the slides are considered to be "panels". For this reason, it is important that the dots (navigation section) is present before the slides in DOM order.
+
+When a slide is changed, all inactive slides will become ["inert"](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/inert) so that they cannot be interacted with by users of assistive technology.
 
-## Props
+Lastly, the carousel does not support auto-rotating slides, because that can lead to many different [accessibility](https://www.boia.org/blog/carousels-and-accessibility-7-tips) and [usability](https://www.nngroup.com/articles/auto-forwarding/) issues. We do _not_ recommend implementing your own auto-rotating carousel unless you have done extensive research and testing with users (including users with disabilities).
 
-Properties table is to be defined.
+## Component API
 
-<PropsTable path={frontmatter.propsPath} />
+Carousel exposes the following subcomponents. The usage of all subcomponents is not mandatory; some of them (e.g. `Carousel.Navigation`) will automatically include recommended children and props by default.
 
-## Subcomponents
+### Carousel
 
-This component uses a composition approach so it should be used with the provided subcomponents.
+`Carousel` is the main component that orchestrates all other sub-components and maintains the overall state.
 
-### Slider
+<PropsTable path={'@itwin/itwinui-react/esm/core/Carousel/Carousel.d.ts'} />
+
+### Carousel.Slider
 
 `Carousel.Slider` is the scrollable list that should consist of `Carousel.Slide` components.
 
-### Slide
+### Carousel.Slide
 
 `Carousel.Slide` is used for the actual slide content. The content can be specified through `children`. It is recommended that the slide content bring its own dimensions (esp. height) and that the dimensions should be the same for all slides.
 
 <PropsTable path={'@itwin/itwinui-react/esm/core/Carousel/CarouselSlide.d.ts'} />
 
-### Navigation
+### Carousel.Navigation
+
+The `Carousel.Navigation` component by default consists of the `PreviousButton` and `NextButton` shown on the left and right and the `Carousel.DotsList` component shown in the middle. `children` can be specified to override what is shown in this navigation section.
 
-The `Carousel.Navigation` component by default consists of the `PreviousButton` and `NextButton` shown on the left and right, and the `Carousel.DotsList` component shown in the middle. `children` can be specified to override what is shown in this navigation section.
+**Important**: The navigation section must always be present before the slides in DOM order.
 
 <PropsTable path={'@itwin/itwinui-react/esm/core/Carousel/CarouselNavigation.d.ts'} />
 
-### Dots List
+### Carousel.Navigation.PreviousButton
+
+The `Carousel.Navigation.PreviousButton` component facilitates navigation to the previous slide in the carousel.
+
+### Carousel.Navigation.NextButton
+
+The `Carousel.Navigation.NextButton` component enables navigation to the next slide in the carousel.
+
+### Carousel.DotsList
+
+The `Carousel.DotsList` component shows a list of `Carousel.Dot` components which can be used to choose a specific slide.
+
+If used as a descendant of `Carousel`, then this component does not need any props or `children`. `children` can be specified to override the individual dots that are shown. The props can be specified if this component is being used standalone (outside `Carousel`).
 
-The `Carousel.DotsList` component shows a list of `Carousel.Dot` components which can be used to choose a specific slide. If used as a descendant of `Carousel`, then this component does not need any props or `children`. The props can be specified if this component is being used outside `Carousel`. `children` can be specified to override the individual dots that are shown.
+When used standalone, it is important to pay close attention to [accessibility](#accessibility), since you may be missing some parts that make the carousel pattern complete. For this reason, we do not recommend diverging from the standard usage unless you have a very strong need and are confident that you can implement it accessibly.
 
 <PropsTable path={'@itwin/itwinui-react/esm/core/Carousel/CarouselDotsList.d.ts'} />
 
-### Dot
+### Carousel.Dot
 
 `Carousel.Dot` is the actual "dot" component used to activate a slide on clicking. It should be used as a child of `Carousel.Dots`.
 

examples/index.tsx

@@ -224,10 +224,6 @@ const CarouselControlledExample = withThemeProvider(
 );
 export { CarouselControlledExample };
 
-import { default as CarouselOnlyDotsExampleRaw } from './Carousel.onlyDots';
-const CarouselOnlyDotsExample = withThemeProvider(CarouselOnlyDotsExampleRaw);
-export { CarouselOnlyDotsExample };
-
 // ----------------------------------------------------------------------------
 
 import { default as CheckboxMainExampleRaw } from './Checkbox.main';