docs: unify writing style and polish component intros (Badge, Card)

docs/data/material/components/badges/badges.md

@@ -8,29 +8,37 @@
 
 # Badge
 
-<p class="description">Badge generates a small badge to the top-right of its child(ren).</p>
+<p class="description">Badge displays small status or count information aligned to its wrapped element.</p>
 
 {{"component": "@mui/docs/ComponentLinkHeader"}}
 
+> For full API and props, see [Badge API](/material-ui/api/badge/).
+
 ## Basic badge
 
 Examples of badges containing text, using primary and secondary colors. The badge is applied to its children.
 
 {{"demo": "SimpleBadge.js"}}
 
+Use badges for lightweight status or counts. Avoid relying on the badge text alone to convey meaning.
+
 ## Color
 
 Use `color` prop to apply theme palette to component.
 
 {{"demo": "ColorBadge.js"}}
 
+Pick colors that reflect semantic meaning (e.g., success/error/info) and ensure sufficient contrast.
+
 ## Customization
 
 Here is an example of customizing the component.
 You can learn more about this in the [overrides documentation page](/material-ui/customization/how-to-customize/).
 
 {{"demo": "CustomizedBadges.js"}}
 
+Target the badge element via `& .MuiBadge-badge` in `sx` or theme overrides to fine-tune size, color, and offsets.
+
 ## Badge visibility
 
 The visibility of badges can be controlled using the `invisible` prop.
@@ -39,6 +47,8 @@
 
 The badge hides automatically when `badgeContent` is zero. You can override this with the `showZero` prop.
 
+If “0” is meaningful in your UI (e.g., explicit emptiness), enable `showZero` so users aren’t confused.
+
 {{"demo": "ShowZeroBadge.js"}}
 
 ## Maximum value
@@ -47,27 +57,51 @@
 
 {{"demo": "BadgeMax.js"}}
 
+Cap large counts with `max` (e.g., 99+) to reduce cognitive load and avoid layout shifts.
+
 ## Dot badge
 
 The `dot` prop changes a badge into a small dot. This can be used as a notification that something has changed without giving a count.
 
 {{"demo": "DotBadge.js"}}
 
+The `dot` variant signals attention without a number; pair it with descriptive text for assistive technologies.
+
 ## Badge overlap
 
 You can use the `overlap` prop to place the badge relative to the corner of the wrapped element.
 
 {{"demo": "BadgeOverlap.js"}}
 
+Use `overlap="circular"` for round children (e.g., `Avatar`) and `overlap="rectangular"` for square/rectangular ones.
+
 ## Badge alignment
 
 You can use the `anchorOrigin` prop to move the badge to any corner of the wrapped element.
 
 {{"demo": "BadgeAlignment.js", "hideToolbar": true}}
 
+Verify alignment visually when using non-standard child sizes (icons 20/24/28px may need different `anchorOrigin`).
+
+## Best practices
+
+- showZero: Enable when zero carries meaning (e.g., empty state clarity).
+- max: Prefer compact display (e.g., 99+) to reduce cognitive load.
+- Semantics: Badge supplements content; don’t rely on it as the only indicator.
+
+## Composition tips
+
+- With `IconButton` and `Avatar`, pick `overlap` that matches the child shape.
+- Space multiple badges using `Stack` and `gap` to prevent visual crowding.
+
+## Theming and customization
+
+Customize the badge appearance via `sx` or theme overrides:
+- Target the badge element with `& .MuiBadge-badge` for size, color, and offset tweaks.
+- Align offsets to the child’s actual size (icons 20/24/28px may need different `anchorOrigin`).
+
 ## Accessibility
 
-You can't rely on the content of the badge to be announced correctly.
-You should provide a full description, for instance, with `aria-label`:
+Screen readers may not announce `badgeContent` reliably. Provide a full description on the focusable parent, for instance with `aria-label` (e.g., `aria-label="3 unread notifications"`). For `variant="dot"`, always include a complementary text description.
 
 {{"demo": "AccessibleBadges.js"}}

docs/data/material/components/cards/cards.md

@@ -12,18 +12,19 @@
 <p class="description">Cards contain content and actions about a single subject.</p>
 
 {{"component": "@mui/docs/ComponentLinkHeader"}}
+> For full API and props, see [Card API](/material-ui/api/card/).
 
 ## Introduction
 
 Cards are surfaces that display content and actions on a single topic.
-The Material UI Card component includes several complementary utility components to handle various use cases:
+The MUI Card component includes several complementary utility components to handle various use cases:
 
-- Card: a surface-level container for grouping related components.
-- Card Content: the wrapper for the Card content.
-- Card Header: an optional wrapper for the Card header.
-- Card Media: an optional container for displaying images, videos, etc.
-- Card Actions: an optional wrapper that groups a set of buttons.
-- Card Action Area: an optional wrapper that allows users to interact with the specified area of the Card.
+- Card: a container for grouping related content and actions.
+- CardContent: the wrapper for the card’s main content.
+- CardHeader: an optional wrapper for the card’s header area.
+- CardMedia: an optional container for images, videos, and other media.
+- CardActions: an optional wrapper that groups action buttons.
+- CardActionArea: an optional wrapper that makes a defined area of the card interactive.
 
 {{"demo": "BasicCard.js", "bg": true}}
 
@@ -58,15 +59,17 @@
 
 By default, we use the combination of a `<div>` element and a _background image_ to display the media. It can be problematic in some situations, for example, you might want to display a video or a responsive image. Use the `component` prop for these use cases:
 
+> When using `component="img"`, provide an appropriate `alt` text for accessibility.
+
 {{"demo": "ImgMediaCard.js", "bg": true}}
 
 ## Primary action
 
-Often a card allow users to interact with the entirety of its surface to trigger its main action, be it an expansion, a link to another screen or some other behavior. The action area of the card can be specified by wrapping its contents in a `CardActionArea` component.
+Often a card allows users to interact with the entirety of its surface to trigger its main action, be it an expansion, a link to another screen, or another behavior. The action area of the card can be specified by wrapping its contents in a `CardActionArea` component.
 
 {{"demo": "ActionAreaCard.js", "bg": true}}
 
-A card can also offer supplemental actions which should stand detached from the main action area in order to avoid event overlap.
+A card can also offer supplemental actions that should be separate from the main action area to avoid event overlap.
 
 {{"demo": "MultiActionAreaCard.js", "bg": true}}
 

docs/next-env.d.ts

@@ -1,6 +1,6 @@
 /// <reference types="next" />
 /// <reference types="next/image-types/global" />
-/// <reference path="./.next/types/routes.d.ts" />
+/// <reference path="./export/types/routes.d.ts" />
 
 // NOTE: This file should not be edited
 // see https://nextjs.org/docs/pages/api-reference/config/typescript for more information.