@primer/react-brand 0.0.0-20260630102653 → 0.0.0-20261013101252

package/docs/components/ActionMenu/index.md

@@ -29,6 +29,23 @@ import {ActionMenu} from '@primer/react-brand'
 </ActionMenu>
 ```
 
+### Icon button trigger-only
+
+Use `ActionMenu.IconButton` when a familiar icon clearly communicates that contextual actions are available. Always provide a concise, context-specific `aria-label`, which also supplies content for the visible tooltip.
+
+Prefer `ActionMenu.Button` when the icon would be ambiguous without a visible label.
+
+```jsx
+<ActionMenu>
+  <ActionMenu.IconButton icon={KebabHorizontalIcon} aria-label="File actions" />
+  <ActionMenu.Overlay aria-label="File actions">
+    <ActionMenu.Item value="Copy link">Copy link</ActionMenu.Item>
+    <ActionMenu.Item value="Rename file">Rename file</ActionMenu.Item>
+    <ActionMenu.Item value="Move to archive">Move to archive</ActionMenu.Item>
+  </ActionMenu.Overlay>
+</ActionMenu>
+```
+
 ### Single selection
 
 In single selection mode it is important to apply an `aria-label` to the
@@ -62,31 +79,43 @@ render(<App />)
 
 ### Split-button layout
 
-In this `mode`, the `ActionMenu` can be shown as a split button with an action (left) and dropdown button (right) with an additional list of actions.
+In this `mode`, the `ActionMenu` can be shown as a split button with an action on the left and a dropdown button with additional actions on the right.
 
-> In split-button mode, each action must be rendered as a link element using the as="a" prop, including the main button
-> and all menu items.
+The primary action may use a visible label or a familiar icon. For an icon-only primary action, ensure that its `aria-label` names the action, while the required `ActionMenu.Overlay` label names the generated menu trigger.
 
 ```jsx
-<ActionMenu mode="split-button">
-  <ActionMenu.Button variant="subtle" as="a" href="#location-for-link" leadingVisual={<StarIcon />}>
-    Action 1
-  </ActionMenu.Button>
-  <ActionMenu.Overlay aria-label="Alternative actions">
-    <ActionMenu.Item as="a" href="#location-for-link" leadingVisual={<StarIcon />}>
+<Stack direction="horizontal" alignItems="center" gap="condensed">
+  <ActionMenu mode="split-button">
+    <ActionMenu.Button variant="subtle" as="a" href="#location-for-link" leadingVisual={<StarIcon />}>
       Action 1
-    </ActionMenu.Item>
-    <ActionMenu.Item as="a" href="#location-for-link-2" leadingVisual={<StarIcon />}>
-      Action 2
-    </ActionMenu.Item>
-    <ActionMenu.Item as="a" href="#location-for-link-3" leadingVisual={<StarIcon />}>
-      Action 3
-    </ActionMenu.Item>
-    <ActionMenu.Item as="a" href="#location-for-link-4" leadingVisual={<StarIcon />}>
-      Action 4
-    </ActionMenu.Item>
-  </ActionMenu.Overlay>
-</ActionMenu>
+    </ActionMenu.Button>
+    <ActionMenu.Overlay aria-label="Alternative actions">
+      <ActionMenu.Item as="a" href="#location-for-link" leadingVisual={<StarIcon />}>
+        Action 1
+      </ActionMenu.Item>
+      <ActionMenu.Item as="a" href="#location-for-link-2" leadingVisual={<StarIcon />}>
+        Action 2
+      </ActionMenu.Item>
+      <ActionMenu.Item as="a" href="#location-for-link-3" leadingVisual={<StarIcon />}>
+        Action 3
+      </ActionMenu.Item>
+      <ActionMenu.Item as="a" href="#location-for-link-4" leadingVisual={<StarIcon />}>
+        Action 4
+      </ActionMenu.Item>
+    </ActionMenu.Overlay>
+  </ActionMenu>
+  <ActionMenu mode="split-button">
+    <ActionMenu.IconButton as="a" href="#new-document" icon={PlusIcon} aria-label="Create document" />
+    <ActionMenu.Overlay aria-label="Creation options">
+      <ActionMenu.Item as="a" href="#new-document">
+        New document
+      </ActionMenu.Item>
+      <ActionMenu.Item as="a" href="#upload-file">
+        Upload file
+      </ActionMenu.Item>
+    </ActionMenu.Overlay>
+  </ActionMenu>
+</Stack>
 ```
 
 ### Sizes
@@ -129,11 +158,28 @@ In this `mode`, the `ActionMenu` can be shown as a split button with an action (
 
 ### ActionMenu.Button `Required`
 
-| name        | type           | default | required | description                        |
-| ----------- | -------------- | ------- | -------- | ---------------------------------- |
-| `className` | `string`       |         |          | Sets a custom class on the element |
-| `children`  | `ReactElement` |         |          |                                    |
-| `id`        | `string`       |         |          | Sets a custom `id`                 |
+| name            | type                                   | default     | required | description                                      |
+| --------------- | -------------------------------------- | ----------- | -------- | ------------------------------------------------ |
+| `className`     | `string`                               |             |          | Sets a custom class on the element               |
+| `children`      | `ReactElement`                         |             |          |                                                  |
+| `id`            | `string`                               |             |          | Sets a custom `id`                               |
+| `variant`       | `'primary' \| 'secondary' \| 'subtle'` |             | `false`  | Sets the button styling variation                |
+| `onClick`       | `(event: MouseEvent) => void`          | `undefined` | `false`  | Handles activation of the button                 |
+| `leadingVisual` | `ReactElement`                         | `undefined` | `false`  | Renders a leading visual before the button label |
+
+### ActionMenu.IconButton
+
+| name               | type                          | default       | required | description                                                   |
+| ------------------ | ----------------------------- | ------------- | -------- | ------------------------------------------------------------- |
+| `icon`             | `Icon`                        |               | `true`   | Icon that represents the menu trigger                         |
+| `aria-label`       | `string`                      |               | `true`   | Action-oriented accessible label and visible tooltip text     |
+| `as`               | `ElementType`                 | `'button'`    | `false`  | Element rendered for the primary action                       |
+| `href`             | `string`                      | `undefined`   | `false`  | Link destination when the primary action renders as an anchor |
+| `variant`          | `IconButtonVariants`          | `'secondary'` | `false`  | Sets the icon button styling variation                        |
+| `description`      | `string`                      | `undefined`   | `false`  | Supplies supplementary tooltip text                           |
+| `tooltipDirection` | `TooltipDirection`            | `'s'`         | `false`  | Preferred direction for the automatic tooltip                 |
+| `rounded`          | `boolean`                     | `false`       | `false`  | Uses a fully rounded shape                                    |
+| `onClick`          | `(event: MouseEvent) => void` | `undefined`   | `false`  | Handles activation; toggles the menu only in default mode     |
 
 ### ActionMenu.Overlay `Required`
 

package/docs/components/ButtonGroup/index.md

@@ -8,10 +8,12 @@ keywords: ['buttons', 'control', 'action', 'group', 'paired']
 
 ## Usage
 
-Use button group to group a set of actions that are related between them or to a single application. E,g, "Log in" and "Sign up" or "Try it out" and "Learn more".
+Use a button group for actions that are related to each other or to a single task, such as “Log in” and “Sign up” or “Try it out” and “Learn more.”
 
 Use button group to display a pair of primary and a secondary actions. The primary button is used for the main call to action while the secondary button is a related, less important action.
 
+Join controls when they represent closely related peer actions with equal hierarchy. Icon-only actions must use a familiar symbol and have a concise, action-oriented accessible name.
+
 **✅ Do**
 
 ![](https://github.com/primer/brand/assets/6951037/c69ae38e-819b-4e03-9b92-665a479f188a)
@@ -52,11 +54,12 @@ _Don't stack the buttons horizontally when there's not enough space to avoid tex
 
 ### Size
 
-The button group component has two sizes: `medium` and `large`. The `medium` size should be used for most cases. The `large` size should be used when the button group is used in large headings that introduces a page, as in the [Hero](../Hero/index.md) component.
+Use the default size in most cases. Use the smallest size in compact toolbars and the largest size alongside prominent page introductions.
 
 ## Related components
 
-- [Button](../Button/index.md): To display a button that performs an action.
-- Link: To display a link that navigates to another page.
-- [Hero](../Hero/index.md): To display a large heading and a description with a button group.
-- [CTA banner](../CTABanner/index.md): To draw attention to or create urgency around a user action.
+- [Button](../Button/index.md): To display an action with a visible label.
+- [Icon button](../IconButton/index.md): To display a familiar icon-only action with an accessible name.
+- Link: To navigate to another page.
+- [Hero](../Hero/index.md): To introduce a page with a large heading, description, and actions.
+- [CTA banner](../CTABanner/index.md): To draw attention to or create urgency around an action.

package/docs/components/ButtonGroup/react.md

@@ -1,6 +1,6 @@
 ---
 title: Button group
-description: Use the button group component to group related buttons together.
+description: Use the button group component to group related buttons and action menus together.
 keywords: ['buttons', 'control', 'action', 'group', 'paired']
 ready: true
 source: https://github.com/primer/brand/blob/main/packages/react/src/ButtonGroup/ButtonGroup.tsx
@@ -8,14 +8,14 @@ storybook: '/brand/storybook/?path=/story/components-buttongroup--playground'
 ---
 
 ```js
-import {ButtonGroup, Button} from '@primer/react-brand'
+import {ActionMenu, Button, ButtonGroup, IconButton} from '@primer/react-brand'
 ```
 
 ## Examples
 
 ### Default
 
-This is the default variant for the ButtonGroup component. The first button in the group is the primary button and the second button is the secondary button.
+This is the default variant for the ButtonGroup component. The first item in the group uses the primary button variant and the second uses the secondary button variant.
 
 ```jsx
 <ButtonGroup>
@@ -24,9 +24,49 @@ This is the default variant for the ButtonGroup component. The first button in t
 </ButtonGroup>
 ```
 
+### Joined buttons and icon buttons
+
+Set `variant="joined"` to connect any number of `Button` and `IconButton` children. Joined controls use the `secondary` variant by default so they share one visual hierarchy; explicit child variants override that default.
+
+```jsx
+<Stack direction="vertical" alignItems="flex-start" gap="condensed">
+  <ButtonGroup variant="joined">
+    <Button>Previous</Button>
+    <Button>Today</Button>
+    <Button>Next</Button>
+  </ButtonGroup>
+  <ButtonGroup variant="joined">
+    <IconButton icon={DownloadIcon} aria-label="Download" />
+    <IconButton icon={ShareIcon} aria-label="Share" />
+    <IconButton icon={KebabHorizontalIcon} aria-label="More actions" />
+  </ButtonGroup>
+</Stack>
+```
+
+### Action menus
+
+The default ButtonGroup variant supports up to two children and applies `primary` to the first action and `secondary` to the second. Joined groups support any number of `Button` and `IconButton` children. `ActionMenu` is supported only by the default variant.
+
+Explicit `variant` overrides to `Button` or `ActionMenu.Button` will override the default values.
+
+`buttonSize` applies to both child types. Because `ActionMenu` supports only `small` and `medium`, it remains `medium` when `buttonSize="large"`. Set `size` on `ActionMenu` to override the inherited size.
+
+```jsx
+<ButtonGroup>
+  <Button>Primary action</Button>
+  <ActionMenu>
+    <ActionMenu.Button>More actions</ActionMenu.Button>
+    <ActionMenu.Overlay aria-label="More actions">
+      <ActionMenu.Item value="contact-sales">Contact sales</ActionMenu.Item>
+      <ActionMenu.Item value="view-pricing">View pricing</ActionMenu.Item>
+    </ActionMenu.Overlay>
+  </ActionMenu>
+</ButtonGroup>
+```
+
 ### Sizes
 
-The ButtonGroup component can be rendered in different sizes in `medium` and `large` sizes. The default size is `medium`.
+The ButtonGroup component supports `small`, `medium`, and `large` buttons. The default size is `medium`. ActionMenu children support `small` and `medium`.
 
 ```jsx
 <ButtonGroup buttonSize="large">
@@ -54,7 +94,8 @@ The `Button` component can render as a `button` or `a` HTML element. By default,
 
 ### ButtonGroup
 
-| Name         | Type                  |   Default  | Description                             |
-| :----------- | :-------------------- | :--------: | :-------------------------------------- |
-| `buttonSize` | `'medium' \| 'large'` | `'medium'` | The size variations available in Button |
-| `buttonsAs`  | `'button' \| 'a'`     | `'button'` | The HTML variations available in Button |
+| Name         | Type                             |   Default   | Description                             |
+| :----------- | :------------------------------- | :---------: | :-------------------------------------- |
+| `buttonSize` | `'small' \| 'medium' \| 'large'` |  `'medium'` | The size variations available in Button |
+| `buttonsAs`  | `'button' \| 'a'`                |  `'button'` | The HTML variations available in Button |
+| `variant`    | `ButtonGroupVariants`            | `'default'` | The visual presentation of the group    |

package/docs/components/Card/index.md

@@ -96,9 +96,9 @@ _Don't use both icon and image as the visual asset._
 
 ### Label
 
-The label can be used to indicate the type of content or its status. For example, use it to indicate that the content is `new` or that it is a `beta` feature. The label is optional and can be used along with a visual asset.
+Use `Card.Label` for displaying one short label above the heading. It renders a [Token](../Token/index.md) by default.
 
-![An image showing two cards, one with a Label and another one with Label and Icon.](https://github.com/primer/brand/assets/6951037/3e16bb51-9e19-4a98-a9c2-e289d4bf540c)
+Prefer `Card.Tokens` for showing groups of metadata. Both are optional. Never place the standalone [Label](../Label/index.md) component inside or alongside a Card.
 
 ### Heading
 

package/docs/components/Card/react.md

@@ -58,7 +58,11 @@ Use `ctaVariant="none"` when the card should remain fully clickable without visi
 
 ### Arrow CTA
 
-Use `ctaVariant="arrow"` when the card should present an icon-only call to action instead of the default text-plus-arrow treatment.
+Use `ctaVariant="arrow"` for a compact call to action. On devices that support hover, the label is visually
+hidden until the Card is hovered or focused. On devices without hover, the label remains visible so the call
+to action does not rely on an unavailable interaction.
+
+Set `disableAnimation` to `true` when CTA state changes should occur without animated transitions.
 
 ```jsx
 <Card href="https://github.com" ctaVariant="arrow">
@@ -97,8 +101,7 @@ Use `Card.Tokens` to display one or more [Token](../Token/index.md) components b
 
 ### Label
 
-Use `Card.Label` to display a short label above the heading. It renders a `Token` by default. Use
-`variant="accent-text"` for eyebrow-style copy.
+Use `Card.Label` for displaying one short label above the heading.
 
 ```jsx
 <Card href="https://github.com" ctaVariant="arrow">
@@ -143,9 +146,57 @@ Use the `Image` component to add an image to the `Card`. The `Image` component i
 </>
 ```
 
+### Full-bleed images
+
+When an image should stretch to fill the card width, set `padding="none"` on `Card.Image` and add `hasBorder` to the `Card` for visual containment. Display full-bleed cards in a regular `Grid` with clear gaps between them rather than in a shared gridline frame. Keep the image position and aspect ratio consistent across the group.
+
+```jsx
+<Grid>
+  <Grid.Column span={{xsmall: 12, large: 4}}>
+    <Card href="https://github.com" fullWidth hasBorder ctaVariant="arrow">
+      <Card.Heading>Build with GitHub Copilot</Card.Heading>
+      <Card.Description>Write, review, and understand code with AI-powered assistance.</Card.Description>
+      <Card.Image
+        position="block-end"
+        padding="none"
+        src="/images/placeholder-1.png"
+        alt="Abstract gradient illustration"
+        aspectRatio="4:3"
+      />
+    </Card>
+  </Grid.Column>
+  <Grid.Column span={{xsmall: 12, large: 4}}>
+    <Card href="https://github.com" fullWidth hasBorder ctaVariant="arrow">
+      <Card.Heading>Automate your workflow</Card.Heading>
+      <Card.Description>Keep projects moving with tools that fit the way your team works.</Card.Description>
+      <Card.Image
+        position="block-end"
+        padding="none"
+        src="/images/placeholder-2.png"
+        alt="Abstract gradient illustration"
+        aspectRatio="4:3"
+      />
+    </Card>
+  </Grid.Column>
+  <Grid.Column span={{xsmall: 12, large: 4}}>
+    <Card href="https://github.com" fullWidth hasBorder ctaVariant="arrow">
+      <Card.Heading>Ship secure software</Card.Heading>
+      <Card.Description>Find and fix vulnerabilities throughout the development lifecycle.</Card.Description>
+      <Card.Image
+        position="block-end"
+        padding="none"
+        src="/images/placeholder-3.png"
+        alt="Abstract gradient illustration"
+        aspectRatio="4:3"
+      />
+    </Card>
+  </Grid.Column>
+</Grid>
+```
+
 ### Tokens
 
-Use `Card.Tokens` to display more than one [Token](../Token/index.md).
+Use `Card.Tokens` to display one or more [Token](../Token/index.md) components.
 
 ```jsx
 <>
@@ -178,23 +229,28 @@ Use `Card.Tokens` to display more than one [Token](../Token/index.md).
 
 ### Card `Required`
 
-| name               | type                              | default      | required | description                                                      |
-| ------------------ | --------------------------------- | ------------ | -------- | ---------------------------------------------------------------- |
-| `align`            |                                   | `'start'`    | `false`  | Aligns the card content                                          |
-| `backgroundColor`  | `'default' \| 'subtle' \| 'none'` | `'default'`  | `false`  | Optional background color override for the card                  |
-| `ctaText`          | `string`                          | `Learn more` | `false`  | Label of the link at the bottom of the card                      |
-| `ctaVariant`       | `'text' \| 'arrow' \| 'none'`     | `'text'`     | `false`  | Presentation of the call-to-action area                          |
-| `disableAnimation` | `boolean`                         | `false`      | `false`  | A flag to disable the default hover animation effect of the card |
-| `fullWidth`        | `boolean`                         | `false`      | `false`  | A flag to optionally fill the width of the parent container      |
-| `hasBorder`        | `boolean`                         | `false`      | `false`  | A flag used to provide a border to the card                      |
-| `href`             | `string`                          |              | `true`   | URL to the card content                                          |
-| `leadingVisual`    | `ReactElement`                    |              | `false`  | Logo or brand mark shown above the card content                  |
-| `variant`          | `'default' \| 'minimal'`          | `'default'`  | `false`  | The variant of the card                                          |
+| name               | type                              | default      | required | description                                                 |
+| ------------------ | --------------------------------- | ------------ | -------- | ----------------------------------------------------------- |
+| `align`            |                                   | `'start'`    | `false`  | Aligns the card content                                     |
+| `backgroundColor`  | `'default' \| 'subtle' \| 'none'` | `'default'`  | `false`  | Optional background color override for the card             |
+| `ctaText`          | `string`                          | `Learn more` | `false`  | Label of the link at the bottom of the card                 |
+| `ctaVariant`       | `'text' \| 'arrow' \| 'none'`     | `'text'`     | `false`  | Presentation of the call-to-action area                     |
+| `disableAnimation` | `boolean`                         | `false`      | `false`  | Disables transitions and animations within the Card         |
+| `fullWidth`        | `boolean`                         | `false`      | `false`  | A flag to optionally fill the width of the parent container |
+| `hasBorder`        | `boolean`                         | `false`      | `false`  | A flag used to provide a border to the card                 |
+| `href`             | `string`                          |              | `true`   | URL to the card content                                     |
+| `leadingVisual`    | `ReactElement`                    |              | `false`  | Logo or brand mark shown above the card content             |
+| `variant`          | `'default' \| 'minimal'`          | `'default'`  | `false`  | The variant of the card                                     |
 
 ### Card.Image
 
 Forwards all the props from the [Image component](../Image/index.md), including `src`, `alt`, and `aspectRatio`.
 
+| name       | type                           | default       | required | description                                                       |
+| ---------- | ------------------------------ | ------------- | -------- | ----------------------------------------------------------------- |
+| `padding`  | `'default' \| 'none'`          | `'default'`   | `false`  | Controls spacing around the image within the card                 |
+| `position` | `'block-start' \| 'block-end'` | `block-start` | `false`  | Places the image at the block-start or block-end edge of the card |
+
 ### Card.Icon
 
 | name            | type                                                                                                                                                                                                                                                         | default   | required | description                                  |

package/docs/components/FeatureComparisonTable/index.md

@@ -0,0 +1,186 @@
+---
+title: Feature comparison table
+description: Use the feature comparison table to compare features across pricing plans.
+keywords: ['pricing', 'plans', 'comparison', 'features']
+ready: true
+source: https://github.com/primer/brand/blob/main/packages/react/src/FeatureComparisonTable/FeatureComparisonTable.tsx
+storybook: '/brand/storybook/?path=/story/components-featurecomparisontable--playground'
+---
+
+```js
+import {FeatureComparisonTable} from '@primer/react-brand'
+```
+
+## Examples
+
+### Default
+
+Compare two to four plans. Use an `Item` for each plan and a `Group` for related features.
+
+On smaller screens, features appear in collapsible groups. Plan descriptions, prices, labels, and actions are shown only at `80rem` and above.
+
+Only the active responsive layout is mounted. Switching across `80rem` remounts custom content, so keep any state that must survive layout changes outside the projected children.
+
+Plan names repeat in each feature row on smaller screens. Avoid fixed IDs in `Item` heading descendants; custom components that need IDs should generate a unique ID per instance with React's `useId`.
+
+```jsx
+<FeatureComparisonTable>
+  <FeatureComparisonTable.Heading>Compare features</FeatureComparisonTable.Heading>
+  <FeatureComparisonTable.Item>
+    <FeatureComparisonTable.Heading>Free</FeatureComparisonTable.Heading>
+    <FeatureComparisonTable.Description>For individuals.</FeatureComparisonTable.Description>
+    <FeatureComparisonTable.Price>$0 per month</FeatureComparisonTable.Price>
+    <FeatureComparisonTable.PrimaryAction as="a" href="#">
+      Get started
+    </FeatureComparisonTable.PrimaryAction>
+  </FeatureComparisonTable.Item>
+  <FeatureComparisonTable.Item>
+    <FeatureComparisonTable.Label>Recommended</FeatureComparisonTable.Label>
+    <FeatureComparisonTable.Heading>Team</FeatureComparisonTable.Heading>
+    <FeatureComparisonTable.Description>For teams.</FeatureComparisonTable.Description>
+    <FeatureComparisonTable.Price>$4 per user / month</FeatureComparisonTable.Price>
+    <FeatureComparisonTable.PrimaryAction as="a" href="#">
+      Start a free trial
+    </FeatureComparisonTable.PrimaryAction>
+  </FeatureComparisonTable.Item>
+
+  <FeatureComparisonTable.Group>
+    <FeatureComparisonTable.GroupHeading id="core-features">Core features</FeatureComparisonTable.GroupHeading>
+    <FeatureComparisonTable.Row>
+      <FeatureComparisonTable.RowHeading>Private repositories</FeatureComparisonTable.RowHeading>
+      <FeatureComparisonTable.Cell variant="included" />
+      <FeatureComparisonTable.Cell variant="included" />
+    </FeatureComparisonTable.Row>
+    <FeatureComparisonTable.Row>
+      <FeatureComparisonTable.RowHeading>Support</FeatureComparisonTable.RowHeading>
+      <FeatureComparisonTable.Cell>Community</FeatureComparisonTable.Cell>
+      <FeatureComparisonTable.Cell>Standard</FeatureComparisonTable.Cell>
+    </FeatureComparisonTable.Row>
+  </FeatureComparisonTable.Group>
+</FeatureComparisonTable>
+```
+
+### Row descriptions
+
+Add an optional `RowDescription` alongside `RowHeading` inside a `Row`. It renders beneath the feature name in small, muted body text in all layouts and supports inline rich text, including links and emphasis.
+
+```jsx
+<FeatureComparisonTable>
+  <FeatureComparisonTable.Heading>Compare features</FeatureComparisonTable.Heading>
+  <FeatureComparisonTable.Item>
+    <FeatureComparisonTable.Heading>Free</FeatureComparisonTable.Heading>
+  </FeatureComparisonTable.Item>
+  <FeatureComparisonTable.Item>
+    <FeatureComparisonTable.Heading>Team</FeatureComparisonTable.Heading>
+  </FeatureComparisonTable.Item>
+  <FeatureComparisonTable.Group>
+    <FeatureComparisonTable.GroupHeading id="codespaces">Codespaces</FeatureComparisonTable.GroupHeading>
+    <FeatureComparisonTable.Row>
+      <FeatureComparisonTable.RowHeading>Codespaces</FeatureComparisonTable.RowHeading>
+      <FeatureComparisonTable.RowDescription>
+        Develop in <strong>the cloud</strong>. <InlineLink href="#codespaces">Learn more</InlineLink>
+      </FeatureComparisonTable.RowDescription>
+      <FeatureComparisonTable.Cell variant="included" />
+      <FeatureComparisonTable.Cell variant="included" />
+    </FeatureComparisonTable.Row>
+  </FeatureComparisonTable.Group>
+</FeatureComparisonTable>
+```
+
+## Component props
+
+### FeatureComparisonTable `Required`
+
+| Name               | Type                   | Default | required | Description                                                           |
+| :----------------- | :--------------------- | :-----: | :------: | :-------------------------------------------------------------------- |
+| `children`         | `Heading, Item, Group` |         |  `true`  | Table title, plans, and feature groups                                |
+| `rowHighlighting`  | `boolean`              |  `true` |  `false` | Highlights rows on hover or keyboard focus; set to `false` to disable |
+| `hasStickyHeaders` | `boolean`              | `false` |  `false` | Keeps headers visible while scrolling at `80rem` and above            |
+
+### FeatureComparisonTable.Item `Required`
+
+| Name       | Type                                                                 | Default | required | Description  |
+| :--------- | :------------------------------------------------------------------- | :-----: | :------: | :----------- |
+| `children` | `Label, Heading, Description, Price, PrimaryAction, SecondaryAction` |         |  `true`  | Plan content |
+
+### FeatureComparisonTable.Label
+
+| Name       | Type        | Default | required | Description                                                  |
+| :--------- | :---------- | :-----: | :------: | :----------------------------------------------------------- |
+| `children` | `ReactNode` |         |  `true`  | Short label, such as "Recommended", that highlights the plan |
+
+### FeatureComparisonTable.Heading `Required`
+
+Add a `Heading` to the table and each `Item`.
+
+| Name       | Type          |          Default          | required | Description                                       |
+| :--------- | :------------ | :-----------------------: | :------: | :------------------------------------------------ |
+| `as`       | `HeadingTags` | `h2` (table), `h3` (plan) |  `false` | Heading level for the table title or plan summary |
+| `children` | `ReactNode`   |                           |  `true`  | Table title or plan name                          |
+
+### FeatureComparisonTable.Description
+
+| Name       | Type        | Default | required | Description      |
+| :--------- | :---------- | :-----: | :------: | :--------------- |
+| `children` | `ReactNode` |         |  `true`  | Plan description |
+
+### FeatureComparisonTable.Price
+
+| Name       | Type        | Default | required | Description                        |
+| :--------- | :---------- | :-----: | :------: | :--------------------------------- |
+| `children` | `ReactNode` |         |  `true`  | Price text, such as "$4 per month" |
+
+### FeatureComparisonTable.PrimaryAction and FeatureComparisonTable.SecondaryAction
+
+| Name       | Type              | Default | required | Description                              |
+| :--------- | :---------------- | :-----: | :------: | :--------------------------------------- |
+| `as`       | `'a' \| 'button'` |         |  `true`  | Link or button element                   |
+| `children` | `ReactNode`       |         |  `true`  | Action label                             |
+| `href`     | `string`          |         |  `false` | Link destination. Required when `as="a"` |
+
+### FeatureComparisonTable.Group `Required`
+
+Groups start collapsed below `48rem` and expanded on larger screens.
+
+| Name       | Type                                                                    |   Default  | required | Description                                                      |
+| :--------- | :---------------------------------------------------------------------- | :--------: | :------: | :--------------------------------------------------------------- |
+| `children` | `GroupHeading, Row`                                                     |            |  `true`  | Group title and feature rows                                     |
+| `expanded` | `'boolean' \| '{narrow: boolean \| regular: boolean \| wide: boolean}'` | Responsive |  `false` | Initial open state. Resets when the screen-size category changes |
+
+### FeatureComparisonTable.GroupHeading `Required`
+
+Set `id` to link directly to a group heading, for example with `href="#core-features"`. The ID is assigned only to the heading in the active responsive layout.
+
+| Name       | Type          | Default | required | Description                         |
+| :--------- | :------------ | :-----: | :------: | :---------------------------------- |
+| `as`       | `HeadingTags` |   `h3`  |  `false` | Heading level                       |
+| `id`       | `string`      |         |  `false` | Anchor target for the group heading |
+| `children` | `ReactNode`   |         |  `true`  | Group title                         |
+
+### FeatureComparisonTable.Row `Required`
+
+| Name       | Type                               | Default | required | Description                                         |
+| :--------- | :--------------------------------- | :-----: | :------: | :-------------------------------------------------- |
+| `children` | `RowHeading, RowDescription, Cell` |         |  `true`  | Feature name, optional description, and plan values |
+
+### FeatureComparisonTable.RowHeading `Required`
+
+| Name       | Type        | Default | required | Description  |
+| :--------- | :---------- | :-----: | :------: | :----------- |
+| `children` | `ReactNode` |         |  `true`  | Feature name |
+
+### FeatureComparisonTable.RowDescription
+
+| Name       | Type        | Default | required | Description         |
+| :--------- | :---------- | :-----: | :------: | :------------------ |
+| `children` | `ReactNode` |         |  `true`  | Feature description |
+
+### FeatureComparisonTable.Cell `Required`
+
+Add one cell per plan, in the same order as the items.
+
+| Name               | Type                                                      | Default | required | Description                                                                                  |
+| :----------------- | :-------------------------------------------------------- | :-----: | :------: | :------------------------------------------------------------------------------------------- |
+| `children`         | `ReactNode`                                               |         |  `false` | Feature value                                                                                |
+| `variant`          | `'included' \| 'unavailable' \| 'unlimited' \| 'refresh'` |         |  `false` | Included, unavailable, unlimited, or periodically renewed                                    |
+| `variantAriaLabel` | `string`                                                  |         |  `false` | Accessible icon label. Use to translate "Included", "Unavailable", "Unlimited", or "Refresh" |