Merge pull request #132 from Vinishbhaskar/main

refactor(docs): enhance component descriptions for clarity and access…

Author: johurul-pimjo

apps/docs/content/components/alert-dialog.mdx

@@ -1,6 +1,6 @@
 ---
 title: React Alert Dialog Components
-description: A modal dialog that interrupts the user with important content and expects a response.
+description: A React alert dialog component built with Tailwind CSS. Show confirmation modals for actions like delete or logout with accessible dialogs, focus control, and keyboard support.
 ---
 
 import AlertDialogCustomPreview from "@/components/preview/alert-dialog/alert-dialog-custom-preview";
@@ -11,9 +11,11 @@ import { Accordion, Accordions } from "fumadocs-ui/components/accordion";
 
 # Alert Dialog
 
-Alert Dialogs are used to display critical information that requires user confirmation or action before proceeding. They interrupt the user's workflow to ensure important messages are seen and acted upon.
+The React Alert Dialog component shows a modal that asks users to confirm an important action. It is used for actions like deleting data, logging out, or making permanent changes.
 
-This Alert Dialog component is built with React Aria Components and styled using Tailwind CSS, providing a highly accessible and customizable experience.
+It blocks the screen until the user takes action, such as confirming or canceling. For example, users must confirm before deleting an account or removing a file.
+
+Built with React Aria Components and styled using Tailwind CSS. It supports keyboard navigation, focus management, and accessible modal interactions.
 
 <ComponentPreview
   codeSnippet={getFileContent(
@@ -215,7 +217,9 @@ See [Modal](https://react-aria.adobe.com/Modal) reference for more information.
 
 ## Accessibility
 
-- **Role**: Uses `role="alertdialog"` to ensure screen readers treat it as an interruptive modal.
-- **Focus Management**: Automatically handles focus entrapment and returns focus to the trigger upon closing.
-- **Keyboard Navigation**: Supports `Escape` key to close the dialog and `Enter` to trigger actions.
-- **Aria Labels**: Titles and descriptions are automatically linked to the dialog container for context.
+- **Focus management:** The alert dialog keeps focus within it while open and returns focus to the trigger when it closes.
+- **Keyboard support:** Users can press the `Escape` key to close the dialog and press `Enter` to confirm the primary action.
+- **Trigger behavior:** Users can open the alert dialog using a trigger and interact with actions using the mouse or keyboard.
+- **Screen reader support:** Screen readers announce the dialog as an alert, so users understand that immediate action is required.
+- **ARIA labeling:** Use `AlertDialogTitle` and `AlertDialogDescription` to describe the purpose and impact of the action clearly.
+- **Action clarity:** Provide clear labels for actions like confirm and cancel so users understand the outcome before proceeding.

apps/docs/content/components/aspect-ratio.mdx

@@ -1,6 +1,6 @@
 ---
 title: React Aspect Ratio Components
-description: A React component for maintaining a desired aspect ratio for content like images, videos, and embeds. Supports responsive layouts with Tailwind CSS variants.
+description: A React aspect ratio component built with Tailwind CSS. Keep images, videos, and embeds in a fixed ratio with responsive scaling and no layout shift.
 ---
 
 import AspectRatioCustomPreview from "@/components/preview/aspect-ratio/aspect-ratio-custom-preview";
@@ -12,9 +12,11 @@ import { Accordion, Accordions } from "fumadocs-ui/components/accordion";
 
 # Aspect Ratio
 
-The Aspect Ratio component helps you maintain a consistent aspect ratio for content, particularly useful for responsive images, videos, and embedded content. It ensures that content maintains desired proportions across different screen sizes.
+The React Aspect Ratio component keeps an element’s width and height in a fixed ratio. It is useful for images, videos, and embeds that need to keep the same shape across different screen sizes.
 
-This component is built with React and styled using Tailwind CSS, offering predefined aspect ratio variants as well as support for custom ratios.
+It adjusts the height based on the container width. So, the content scales correctly, and the layout does not shift during loading or resizing.
+
+Built with React and styled using Tailwind CSS. It supports predefined aspect ratios and custom values for flexible layouts.
 
 <ComponentPreview
   codeSnippet={getFileContent(
@@ -123,7 +125,7 @@ The AspectRatio component works seamlessly with responsive images. Use `object-c
 
 ## Accessibility
 
-- **Semantic HTML**: The component uses a standard `<div>` element that can be enhanced with ARIA attributes as needed.
-- **Image Alt Text**: When using images, always provide descriptive `alt` text for screen readers.
-- **Focus Management**: The component forwards refs, allowing you to manage focus programmatically when needed.
-- **Responsive Design**: Aspect ratios are maintained across all screen sizes, ensuring consistent presentation for all users.
+- **Semantic structure:** The component uses a standard `<div>`. Add semantic elements inside it when needed, such as `<img>`, `<video>`, or `<iframe>`.
+- **Alt text for images:** Always provide a clear `alt` attribute when using images so screen readers can understand the content.
+- **Focus handling:** The component forwards refs, so you can manage focus if the content inside is interactive.
+- **Responsive behavior:** The aspect ratio stays consistent across screen sizes, so content does not shift or break layout.

apps/docs/content/components/card.mdx

@@ -1,6 +1,6 @@
 ---
 title: React Card Components
-description: A React Card component that lets users display content in a structured and visually appealing way. Used for grouping related information, such as articles, profiles, or product details.
+description: A React card component built with Tailwind CSS. Create UI cards for products, blogs, dashboards, and profiles with header, content, and footer sections.
 ---
 
 import CardArticlePreview from "@/components/preview/card/card-article-preview";
@@ -16,9 +16,11 @@ import { Accordion, Accordions } from "fumadocs-ui/components/accordion";
 
 # Card
 
-Cards are flexible containers used to group related content and actions. They are commonly used for displaying articles, user profiles, product details, and summary information in a dashboard.
+The React Card component is a container for grouping related content and actions. It helps you organize information in a clear and structured way.
 
-This Card component is built with React and styled using Tailwind CSS, offering a clean and modern design. It includes subcomponents for header, title, description, content, and footer sections to structure information effectively.
+You can use it to display content such as articles, user profiles, product details, or dashboard summaries. For example, a card can show a title, description, and buttons in one place.
+
+Built with React and styled with Tailwind CSS, it includes sections like header, content, and footer to help you easily structure your layout.
 
 <ComponentPreview
   codeSnippet={getFileContent("/src/components/preview/card/card-preview.tsx")}
@@ -246,6 +248,7 @@ The footer of the card.
 
 ## Accessibility
 
-- **Semantic Structure**: Use `CardTitle` (which renders a div by default, but can be customized) for headings to seek user attention.
-- **Grouping**: Cards naturally group related content. For complex cards, ensure the `CardTitle` properly describes the card's purpose.
-- **Keyboard Navigation**: Ensure any interactive elements within the card (buttons, links in `CardFooter` or `CardContent`) are keyboard accessible.
+- **Semantic structure:** Use `CardTitle` for headings and structure content clearly so users can understand what the card represents.
+- **Content grouping:** The card groups related content and actions together, making it easier to scan and understand.
+- **Keyboard support:** Ensure any interactive elements inside the card (such as buttons or links in `CardFooter` or `CardContent`) are accessible using the keyboard.
+- **Screen reader support:** Provide clear text for titles, descriptions, and actions so screen readers can describe the card content properly.

apps/docs/content/components/carousel.mdx

@@ -1,6 +1,6 @@
 ---
 title: React Carousel Components
-description: A powerful, flexible carousel component built with Embla Carousel. Supports horizontal/vertical orientation, custom plugins, and full API control.
+description: A React carousel component built with Tailwind CSS. Create image sliders, card carousels, and testimonial sliders with smooth scrolling, navigation controls, and responsive layouts.
 ---
 
 import CarouselApiPreview from "@/components/preview/carousel/carousel-api-preview";
@@ -13,7 +13,11 @@ import { Accordion, Accordions } from "fumadocs-ui/components/accordion";
 
 # Carousel
 
-A carousel component allows users to scroll through a collection of items, such as images, cards, or testimonials, in a space-efficient manner. Built on top of Embla Carousel, it provides a smooth, accessible, and highly customizable experience.
+The React Carousel component lets users scroll through a list of items, such as images, cards, or testimonials. It shows one or more items at a time and allows users to move between them.
+
+It helps save space while still displaying multiple pieces of content. For example, you can use a carousel for product images, customer reviews, or featured content.
+
+Built on top of Embla Carousel and styled with Tailwind CSS. It supports smooth scrolling and keyboard navigation, and it works well across different screen sizes.
 
 <ComponentPreview
   codeSnippet={getFileContent(
@@ -183,9 +187,9 @@ See the [Embla Cacrousel Guides](https://www.embla-carousel.com/guides/) for mor
 
 ## Accessibility
 
-- Use the [Embla Carousel Accessibility](https://www.embla-carousel.com/plugins/accessibility/) plugin for best accessibility support.
-- Built with keyboard navigation support (Arrow keys automatically scroll items).
-- Uses `role="region"` with `aria-roledescription="carousel"` for the outer container.
-- Each slide has `role="group"` and `aria-roledescription="slide"`.
-- Buttons include `sr-only` text for screen readers ("Previous slide", "Next slide").
-- Properly handles `disabled` states when the carousel cannot scroll further.
+- **Keyboard support:** Users can navigate between slides using `Arrow` keys.
+- **Screen reader support:** Navigation buttons include hidden text like “Previous slide” and “Next slide” so screen readers can announce them clearly.
+- **ARIA roles:** The carousel uses roles like `region` (carousel) and `group` (slide) to help screen readers understand the structure.
+- **Slide structure:** Each slide is treated as a separate group so users can identify slide boundaries.
+- **Navigation states:** Navigation buttons are `disabled` when there are no more slides to scroll.
+- **Accessibility plugins:** You can use the Embla accessibility plugin to enhance support for screen readers and interactions.

apps/docs/content/components/chart.mdx

@@ -1,6 +1,6 @@
 ---
 title: React Chart Components
-description: Beautiful and responsive chart components built on top of Recharts. Supports line, area, bar, and pie charts with custom tooltips and legends.
+description: A React chart component built with Tailwind CSS and Recharts. Create line, bar, area, and pie charts with responsive layouts, tooltips, and legends.
 ---
 
 import ChartBarPreview from "@/components/preview/chart/chart-bar-preview";
@@ -13,7 +13,11 @@ import { Accordion, Accordions } from "fumadocs-ui/components/accordion";
 
 # Chart
 
-React Chart components provide a beautiful, Tailwind-styled wrapper around the popular [Recharts](https://recharts.org/) library. They enable developers to build responsive and customizable data visualizations with ease, featuring custom styled tooltips, legends, and axis formatting.
+The React Chart component helps you build charts and data visualizations in your app. It works with the Recharts library and adds Tailwind CSS styling for a clean and consistent look.
+
+You can use it to display data as line, bar, area, or pie charts. For example, you can show sales data, user growth, or performance metrics in a visual format.
+
+Built with React and [Recharts](https://recharts.org/), it supports responsive charts, custom tooltips, legends, and flexible styling using Tailwind CSS.
 
 <ComponentPreview
   codeSnippet={getFileContent(
@@ -174,11 +178,12 @@ Extends Recharts `DefaultLegendContentProps`.
 | `hideIndicator` | `boolean` | `false` | Whether to hide the color indicator shape next to legend items. |
 | `className`     | `string`  | -       | Additional CSS classes for the legend container.                |
 
-## Accessibility
-
 The Chart components are designed with accessibility in mind, ensuring that data visualizations are perceivable and navigable.
 
-- **Focus Management**: The `ChartContainer` includes keyboard-accessible styles for the underlying Recharts wrapper, providing clear visual indicators when the component receives focus.
-- **Dynamic Indicators**: Customizable indicators (`dot`, `line`, `square`) help differentiate data series, making them easier to identify for users with visual impairments.
-- **ARIA Support**: Leverages Recharts' built-in ARIA support for SVG elements, providing semantic roles and labels to assistive technologies.
-- **Screen Readers**: Descriptive tooltips and legends ensure that data values are correctly announced when interacted with.
+## Accessibility
+
+- **Focus management:** The chart can receive focus and shows clear visual indicators when it is active.
+- **Screen reader support:** Tooltips and legends help screen readers describe data values.
+- **Data clarity:** Use clear labels, legends, and axis titles so users can easily understand the data.
+- **Visual distinction:** Different colors and indicator styles (dot, line, square) help users distinguish between data series.
+- **ARIA support:** The chart uses accessible SVG elements and roles provided by Recharts.

apps/docs/content/components/collapsible.mdx

@@ -1,6 +1,6 @@
 ---
 title: React Collapsible Components
-description: A React collapsible component for showing and hiding a single section of content. Built on React Aria Disclosure for full accessibility and keyboard support, with a composable API inspired by shadcn/ui.
+description: A React collapsible component built with Tailwind CSS. Show or hide content with expandable sections, toggle panels, with simple and accessible interactions.
 ---
 
 import CollapsibleControlledPreview from "@/components/preview/collapsible/collapsible-controlled-preview";
@@ -15,9 +15,11 @@ import { Accordion, Accordions } from "fumadocs-ui/components/accordion";
 
 # Collapsible
 
-A Collapsible is a single expandable section. Use it wherever content should be progressively revealed without a page transition — order summaries, stack traces, DNS settings, build logs, environment variables, and more.
+The React Collapsible component lets users show or hide content by clicking a trigger. It is used to expand and collapse sections without leaving the page.
 
-This component is built on top of **React Aria's `Disclosure`** primitive, giving you managed focus, correct ARIA attributes, and keyboard interaction for free.
+It helps keep the UI clean by hiding details until needed. For example, users can click to view order details, logs, or settings only when required.
+
+This component is built on top of **React Aria's `Disclosure`** primitive and styled using Tailwind CSS. It gives built-in focus management, proper ARIA attributes, and keyboard interaction out of the box.
 
 <ComponentPreview
   codeSnippet={getFileContent(
@@ -216,9 +218,9 @@ The panel is hidden from the accessibility tree when collapsed. React Aria handl
 
 ## Accessibility
 
-- **Semantics** — The trigger is a `<button>` inside a heading element (`h3` by default). This creates the correct heading hierarchy for screen readers.
-- **ARIA attributes** — `aria-expanded` and `aria-controls` are automatically managed by React Aria. No manual wiring required.
-- **Keyboard support** — Press `Space` or `Enter` on the focused trigger to expand or collapse the panel.
-- **Focus management** — Focus styles are visible when navigating by keyboard (`focus-visible`).
-- **Disabled state** — When `isDisabled` is set, the trigger receives `disabled` and is removed from the tab order.
-- **Heading level** — Use the `level` prop on `CollapsibleTrigger` to match the heading hierarchy of the surrounding page content.
+- **Keyboard support:** Users can press `Enter` or `Space` on the trigger to expand or collapse the content.
+- **Focus management:** The trigger can receive focus, and focus styles appear when navigating with the keyboard.
+- **ARIA behavior:** The component automatically manages expanded (`aria-expanded`) and collapsed states so screen readers know when content is visible.
+- **Semantic structure:** The trigger is rendered as a button within a heading, helping screen readers understand the content hierarchy.
+- **Content visibility:** When collapsed, the content is hidden from assistive technologies and becomes available when expanded.
+- **Disabled state:** When `disabled`, the trigger cannot be focused or activated.

apps/docs/content/components/combobox.mdx

@@ -1,6 +1,6 @@
 ---
 title: React Combobox Components
-description: A Combobox component that combines a text input with a listbox, allowing users to filter options and select a value. It supports sections, multi-selection, and accessibility features.
+description: A React combobox component built with Tailwind CSS. Create searchable dropdowns with input filtering, single or multi-select options, and accessible keyboard navigation.
 ---
 
 import ComboboxAvatarPreview from "@/components/preview/combobox/combobox-avatar-preview";
@@ -20,7 +20,11 @@ import { Tab, Tabs } from "fumadocs-ui/components/tabs";
 
 # Combobox
 
-React Combobox components combine a text input with a listbox, allowing users to filter options and select a value from a list. They are often used for search-driven selection, large sets of options, and other layouts where users need to filter through data to find their choice.
+The React Combobox component combines an input field with a dropdown list, allowing users to search and select an option. It lets users type to filter results and quickly find what they need.
+
+It is useful when you have a large list of options. For example, users can search for a country, user, or category instead of scrolling through a long list. It also supports selecting multiple options with MultiCombobox, with selected items displayed as tags.
+
+Built with React and styled using Tailwind CSS. It supports filtering, keyboard navigation, and accessible selection patterns.
 
 <ComponentPreview
   codeSnippet={getFileContent(
@@ -352,7 +356,8 @@ The `Key` type supports `string` and `number`. See [React Aria's Combobox](https
 
 ## Accessibility
 
-- **Keyboard Navigation**: Supports arrow keys to navigate options, Enter/Space to select, and Escape to close.
-- **Filtering**: Type to filter the list of options dynamically.
-- **Screen Readers**: Follows W3C ARIA ComboBox design pattern with proper descriptions and state announcements.
-- **Focus Management**: Maintains focus within the input while navigating the listbox.
+- **Keyboard support:** Users can navigate options using `Arrow` keys, select an option with `Enter`, and close the list with `Escape`.
+- **Search and filtering:** As users type in the input, the list updates to show matching results.
+- **Focus management:** Focus stays on the input while users navigate the list.
+- **Selection behavior:** Supports single and multiple selection depending on configuration.
+- **Label and description:** Provide a label and optional description so users understand the purpose of the input.