Skip to content

An open source design system that's fully customizable and agent ready

TypeScript

fix(docs): resolve all 55 README validation issues across 25 components (#351)

Cindy Zhangab3ff612b181
diff --git a/packages/core/src/AspectRatio/README.md b/packages/core/src/AspectRatio/README.md
index bc9ea18b0d..c9ecd7c7ae 100644
--- a/packages/core/src/AspectRatio/README.md
+++ b/packages/core/src/AspectRatio/README.md
@@ -47,3 +47,11 @@ const theme: Theme = {
| Surface | Description |
| ------- | --------------------- |
| `root` | Root container styles |
+
+## Props
+
+| Prop | Type | Default | Description |
+| ---------- | -------------- | ------- | ------------------------------------------------- |
+| `ratio` | `number` | — | Aspect ratio as width/height (e.g., 16/9, 1) |
+| `children` | `ReactNode` | — | Content positioned absolutely to fill container |
+| `xstyle` | `StyleXStyles` | — | StyleX overrides for the container |
diff --git a/packages/core/src/Avatar/README.md b/packages/core/src/Avatar/README.md
index 363716e836..4beb7aff82 100644
--- a/packages/core/src/Avatar/README.md
+++ b/packages/core/src/Avatar/README.md
@@ -46,6 +46,10 @@ import { XDSAvatar, XDSAvatarStatusDot } from '@xds/core/Avatar';
### XDSAvatar
+```tsx
+<XDSAvatar src="/user.jpg" name="John Doe" size="medium" />
+```
+
| Prop | Type | Default | Description |
| ------------- | --------------- | --------- | ------------------------------------ |
| `src` | `string` | — | Primary image source URL |
@@ -58,6 +62,10 @@ import { XDSAvatar, XDSAvatarStatusDot } from '@xds/core/Avatar';
### XDSAvatarStatusDot
+```tsx
+<XDSAvatarStatusDot variant="positive" label="Online" />
+```
+
| Prop | Type | Default | Description |
| --------- | --------------------------------------- | ------------ | --------------------------------------------------- |
| `variant` | `'positive' \| 'neutral' \| 'negative'` | `'positive'` | Semantic color variant of the dot |
diff --git a/packages/core/src/Breadcrumbs/README.md b/packages/core/src/Breadcrumbs/README.md
index ebbc99d20b..9784719ec0 100644
--- a/packages/core/src/Breadcrumbs/README.md
+++ b/packages/core/src/Breadcrumbs/README.md
@@ -12,7 +12,17 @@ A navigation breadcrumb trail with semantic HTML.
| `XDSBreadcrumbItem` | Component | Individual breadcrumb item |
| `XDSBreadcrumbItemProps` | Type | Item props interface |
-## Props — XDSBreadcrumbs
+### XDSBreadcrumbs
+
+Navigation container that renders a `<nav>` with an ordered list of breadcrumb items.
+
+```tsx
+<XDSBreadcrumbs>
+ <XDSBreadcrumbItem href="/">Home</XDSBreadcrumbItem>
+ <XDSBreadcrumbItem href="/projects">Projects</XDSBreadcrumbItem>
+ <XDSBreadcrumbItem isCurrent>My Project</XDSBreadcrumbItem>
+</XDSBreadcrumbs>
+```
| Prop | Type | Default | Description |
| ------------- | --------------------------- | -------------- | --------------------------------- |
@@ -23,7 +33,15 @@ A navigation breadcrumb trail with semantic HTML.
| `label` | `string` | `'Breadcrumb'` | Accessible label for nav landmark |
| `data-testid` | `string` | — | Test ID |
-## Props — XDSBreadcrumbItem
+### XDSBreadcrumbItem
+
+Individual breadcrumb item that renders as a link or plain text.
+
+```tsx
+<XDSBreadcrumbItem href="/settings" startIcon={<XDSIcon icon={CogIcon} size="sm" />}>
+ Settings
+</XDSBreadcrumbItem>
+```
| Prop | Type | Default | Description |
| ------------- | ------------------------- | ------- | ------------------------------------ |
diff --git a/packages/core/src/Calendar/README.md b/packages/core/src/Calendar/README.md
index ab8da5fd70..b1ad07069d 100644
--- a/packages/core/src/Calendar/README.md
+++ b/packages/core/src/Calendar/README.md
@@ -40,22 +40,22 @@ import { XDSCalendar } from '@xds/core/Calendar';
## Props
-| Prop | Type | Default | Description |
-| ------------------- | ------------------------------------ | ---------- | ------------------------------ |
-| mode | `'single' \| 'range'` | `'single'` | Selection mode |
-| value | `ISODateString \| DateRange` | — | Controlled selected value |
-| defaultValue | `ISODateString \| DateRange` | — | Uncontrolled default value |
-| onChange | `Function` | — | Selection callback |
-| numberOfMonths | `1 \| 2` | `1` | Number of months to display |
-| min | `ISODateString` | — | Minimum selectable date |
-| max | `ISODateString` | — | Maximum selectable date |
-| dateConstraints | `Array<(date: Date) => boolean>` | — | Custom constraint functions |
-| focusDate | `ISODateString` | — | Controlled visible month |
-| onFocusDateChange | `(focusDate: ISODateString) => void` | — | Navigation callback |
-| hasOutsideDays | `boolean` | `true` | Show days from adjacent months |
-| hasWeekNumbers | `boolean` | `false` | Show ISO week numbers |
-| hasVariableRowCount | `boolean` | `false` | Variable vs fixed 6-row grid |
-| weekStartsOn | `0-6` | `0` | First day of week (0=Sunday) |
+| Prop | Type | Default | Description |
+| --------------------- | ------------------------------------ | ---------- | ------------------------------ |
+| `mode` | `'single' \| 'range'` | `'single'` | Selection mode |
+| `value` | `ISODateString \| DateRange` | — | Controlled selected value |
+| `defaultValue` | `ISODateString \| DateRange` | — | Uncontrolled default value |
+| `onChange` | `Function` | — | Selection callback |
+| `numberOfMonths` | `1 \| 2` | `1` | Number of months to display |
+| `min` | `ISODateString` | — | Minimum selectable date |
+| `max` | `ISODateString` | — | Maximum selectable date |
+| `dateConstraints` | `Array<(date: Date) => boolean>` | — | Custom constraint functions |
+| `focusDate` | `ISODateString` | — | Controlled visible month |
+| `onFocusDateChange` | `(focusDate: ISODateString) => void` | — | Navigation callback |
+| `hasOutsideDays` | `boolean` | `true` | Show days from adjacent months |
+| `hasWeekNumbers` | `boolean` | `false` | Show ISO week numbers |
+| `hasVariableRowCount` | `boolean` | `false` | Variable vs fixed 6-row grid |
+| `weekStartsOn` | `0-6` | `0` | First day of week (0=Sunday) |
## Types
diff --git a/packages/core/src/Center/README.md b/packages/core/src/Center/README.md
index 1309dd0fbe..3bf10a969f 100644
--- a/packages/core/src/Center/README.md
+++ b/packages/core/src/Center/README.md
@@ -48,3 +48,14 @@ const theme: Theme = {
| Surface | Description |
| ------- | --------------------- |
| `root` | Root container styles |
+
+## Props
+
+| Prop | Type | Default | Description |
+| ---------- | -------------------------------------------- | -------- | -------------------------------------------------- |
+| `axis` | `'both' \| 'horizontal' \| 'vertical'` | `'both'` | Which direction(s) to center |
+| `width` | `number \| string` | — | Container width (px or CSS value) |
+| `height` | `number \| string` | — | Container height (px or CSS value) |
+| `isInline` | `boolean` | `false` | Use inline-flex (useful for text/icons) |
+| `children` | `ReactNode` | — | Content to center |
+| `xstyle` | `StyleXStyles` | — | StyleX overrides |
diff --git a/packages/core/src/Collapsible/README.md b/packages/core/src/Collapsible/README.md
index ff82c15d28..cc2728600f 100644
--- a/packages/core/src/Collapsible/README.md
+++ b/packages/core/src/Collapsible/README.md
@@ -97,6 +97,12 @@ import {XDSCollapsible, XDSCollapsibleGroup} from '@xds/core/Collapsible';
### XDSCollapsible
+```tsx
+<XDSCollapsible trigger="Details">
+ <p>This content can be collapsed</p>
+</XDSCollapsible>
+```
+
| Prop | Type | Default | Description |
| --------------- | --------------------------- | ------- | -------------------------------------------------- |
| `trigger` | `ReactNode` | — | Content shown in the trigger area (always visible) |
@@ -108,6 +114,17 @@ import {XDSCollapsible, XDSCollapsibleGroup} from '@xds/core/Collapsible';
### XDSCollapsibleGroup
+```tsx
+<XDSCollapsibleGroup type="single" defaultValue="general">
+ <XDSCollapsible trigger="General" value="general">
+ <p>General settings</p>
+ </XDSCollapsible>
+ <XDSCollapsible trigger="Advanced" value="advanced">
+ <p>Advanced settings</p>
+ </XDSCollapsible>
+</XDSCollapsibleGroup>
+```
+
| Prop | Type | Default | Description |
| --------------- | ------------------------------------- | ---------- | -------------------------------------- |
| `type` | `"single" \| "multiple"` | `"single"` | Whether one or many items can be open |
diff --git a/packages/core/src/DateInput/README.md b/packages/core/src/DateInput/README.md
index 2d9c003e80..9d78d2198c 100644
--- a/packages/core/src/DateInput/README.md
+++ b/packages/core/src/DateInput/README.md
@@ -64,23 +64,23 @@ import { XDSDateInput } from '@xds/core/DateInput';
## Props
-| Prop | Type | Default | Description |
-| --------------- | --------------------------------------------- | ----------------- | ---------------------------------------- |
-| label | `string` | — | Label text (required) |
-| isLabelHidden | `boolean` | `false` | Visually hide label |
-| description | `string` | — | Helper text below label |
-| isOptional | `boolean` | `false` | Show "(optional)" indicator |
-| isRequired | `boolean` | `false` | Mark field as required |
-| isDisabled | `boolean` | `false` | Disable input and calendar |
-| value | `ISODateString` | — | Selected date (YYYY-MM-DD) |
-| onChange | `(value: ISODateString \| undefined) => void` | — | Selection callback |
-| min | `ISODateString` | — | Minimum selectable date |
-| max | `ISODateString` | — | Maximum selectable date |
-| dateConstraints | `Array<(date: Date) => boolean>` | — | Custom constraint functions |
-| placeholder | `string` | `"Select a date"` | Input placeholder text |
-| size | `'sm' \| 'md' \| 'lg'` | `'md'` | Input size |
-| status | `XDSInputStatus` | — | Status indicator (error/warning/success) |
-| numberOfMonths | `1 \| 2` | `1` | Months shown in calendar popover |
+| Prop | Type | Default | Description |
+| ----------------- | --------------------------------------------- | ----------------- | ---------------------------------------- |
+| `label` | `string` | — | Label text (required) |
+| `isLabelHidden` | `boolean` | `false` | Visually hide label |
+| `description` | `string` | — | Helper text below label |
+| `isOptional` | `boolean` | `false` | Show "(optional)" indicator |
+| `isRequired` | `boolean` | `false` | Mark field as required |
+| `isDisabled` | `boolean` | `false` | Disable input and calendar |
+| `value` | `ISODateString` | — | Selected date (YYYY-MM-DD) |
+| `onChange` | `(value: ISODateString \| undefined) => void` | — | Selection callback |
+| `min` | `ISODateString` | — | Minimum selectable date |
+| `max` | `ISODateString` | — | Maximum selectable date |
+| `dateConstraints` | `Array<(date: Date) => boolean>` | — | Custom constraint functions |
+| `placeholder` | `string` | `"Select a date"` | Input placeholder text |
+| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | Input size |
+| `status` | `XDSInputStatus` | — | Status indicator (error/warning/success) |
+| `numberOfMonths` | `1 \| 2` | `1` | Months shown in calendar popover |
## Keyboard Navigation
diff --git a/packages/core/src/Dialog/README.md b/packages/core/src/Dialog/README.md
index 777fc052bb..fc737836c6 100644
--- a/packages/core/src/Dialog/README.md
+++ b/packages/core/src/Dialog/README.md
@@ -61,6 +61,58 @@ function Example() {
}
```
+## Components
+
+### XDSDialog
+
+Modal dialog using the native `<dialog>` element.
+
+```tsx
+<XDSDialog isShown={isShown} onHide={() => setIsShown(false)}>
+ <XDSLayout
+ header={<XDSLayoutHeader hasDivider>Title</XDSLayoutHeader>}
+ content={<XDSLayoutContent>Content goes here</XDSLayoutContent>}
+ footer={
+ <XDSLayoutFooter hasDivider>
+ <XDSButton label="Confirm" variant="primary" onClick={() => setIsShown(false)} />
+ </XDSLayoutFooter>
+ }
+ />
+</XDSDialog>
+```
+
+| Prop | Type | Default | Description |
+| ----------- | -------------------------------- | ------------ | ------------------------------------------------ |
+| `isShown` | `boolean` | — | Whether the dialog is shown (required) |
+| `onHide` | `() => unknown` | — | Callback when dialog requests to hide (required) |
+| `width` | `number \| string` | `400` | Width of the dialog (px or CSS value) |
+| `maxHeight` | `number \| string` | `'75vh'` | Maximum height of the dialog |
+| `position` | `XDSDialogPosition` | — | Static position (centered by default) |
+| `variant` | `'standard' \| 'fullscreen'` | `'standard'` | Dialog variant |
+| `purpose` | `'required' \| 'form' \| 'info'` | `'info'` | Dismissal behavior |
+| `children` | `ReactNode` | — | Dialog content (required) |
+
+### XDSDialogHeader
+
+Header for dialogs with title, optional subtitle, close button, and start/end content slots.
+
+```tsx
+<XDSDialogHeader
+ title="Confirm Action"
+ subtitle="This cannot be undone"
+ onHide={() => setIsShown(false)}
+/>
+```
+
+| Prop | Type | Default | Description |
+| -------------- | ---------------- | ------- | ---------------------------------------------------- |
+| `title` | `string` | — | Dialog title (receives focus on open) |
+| `subtitle` | `string` | — | Subtitle below the title |
+| `onHide` | `() => unknown` | — | Close button callback (no button if omitted) |
+| `startContent` | `ReactNode` | — | Content before the title (e.g., back button) |
+| `endContent` | `ReactNode` | — | Content after the title, before close button |
+| `hasDivider` | `boolean` | `true` | Adds border at the bottom edge |
+
## Props
| Prop | Type | Default | Description |
diff --git a/packages/core/src/Divider/README.md b/packages/core/src/Divider/README.md
index 098f36b42c..27e7e90143 100644
--- a/packages/core/src/Divider/README.md
+++ b/packages/core/src/Divider/README.md
@@ -52,3 +52,13 @@ const theme: Theme = {
| `root` | Root container styles |
| `line` | Divider line styles |
| `label` | Label text styles |
+
+## Props
+
+| Prop | Type | Default | Description |
+| ------------- | ------------------------------ | -------------- | ----------------------------------------------- |
+| `orientation` | `'horizontal' \| 'vertical'` | `'horizontal'` | Orientation of the divider |
+| `label` | `ReactNode` | — | Optional label centered on the divider |
+| `variant` | `'subtle' \| 'strong'` | `'subtle'` | Visual weight of the divider line |
+| `isFullBleed` | `boolean` | `false` | Extend to container edges with negative margins |
+| `xstyle` | `StyleXStyles` | — | StyleX overrides |
diff --git a/packages/core/src/DropdownMenu/README.md b/packages/core/src/DropdownMenu/README.md
index 1546742d9d..94f4f86306 100644
--- a/packages/core/src/DropdownMenu/README.md
+++ b/packages/core/src/DropdownMenu/README.md
@@ -99,6 +99,16 @@ const [isOpen, setIsOpen] = useState(false);
### XDSDropdownMenu
+```tsx
+<XDSDropdownMenu
+ button={{ label: 'Actions' }}
+ items={[
+ { label: 'Edit', icon: PencilIcon, onClick: () => handleEdit() },
+ { label: 'Delete', icon: TrashIcon, onClick: () => handleDelete() },
+ ]}
+/>
+```
+
| Prop | Type | Default | Description |
| -------------- | ---------------------------------------------- | ------------------- | ------------------------------------------------------------- |
| `button` | `XDSDropdownMenuButtonProps` | `{ label: 'Menu' }` | Props for the trigger button (XDSButton props except onClick) |
@@ -113,6 +123,14 @@ const [isOpen, setIsOpen] = useState(false);
Helper component for custom item rendering with consistent styling.
+```tsx
+<XDSDropdownMenuItem
+ icon={UserIcon}
+ label="Alice Johnson"
+ description="[email protected]"
+/>
+```
+
| Prop | Type | Default | Description |
| ------------- | -------------- | ------- | ---------------------------------------------- |
| `icon` | `XDSIconType` | — | Icon to display before the label |
diff --git a/packages/core/src/Field/README.md b/packages/core/src/Field/README.md
index 8b52b267e8..d6a3cc28b2 100644
--- a/packages/core/src/Field/README.md
+++ b/packages/core/src/Field/README.md
@@ -13,6 +13,65 @@ A form field wrapper component that provides label and description.
- **Accessible**: Label properly associated with input via htmlFor/id
- **Styled with StyleX**: Uses XDS design tokens for consistent styling
+## Components
+
+### XDSField
+
+Form field wrapper that provides label, description, and optional/required indicators.
+
+```tsx
+<XDSField label="Email" inputID={id}>
+ <input id={id} />
+</XDSField>
+```
+
+| Prop | Type | Default | Description |
+| ---------------- | ------------- | ------- | ----------------------------------------------------- |
+| `label` | `string` | — | Label text (required for accessibility) |
+| `isLabelHidden` | `boolean` | `false` | Visually hide the label |
+| `description` | `string` | — | Description text between label and input |
+| `inputID` | `string` | — | ID for the input (used for label's htmlFor) |
+| `descriptionID` | `string` | — | ID for the description (for aria-describedby) |
+| `isOptional` | `boolean` | `false` | Show "Optional" indicator |
+| `isRequired` | `boolean` | `false` | Show "Required" indicator |
+| `labelStartIcon` | `XDSIconType` | — | Icon before the label text |
+| `labelTooltip` | `string` | — | Tooltip text for info icon at end of label |
+| `children` | `ReactNode` | — | The input or control to render |
+
+### XDSFieldLabel
+
+Standalone label component with optional/required indicators and tooltip support.
+
+```tsx
+<XDSFieldLabel label="Username" inputID={id} isRequired />
+```
+
+| Prop | Type | Default | Description |
+| ---------------- | ------------- | ------- | ------------------------------------------- |
+| `label` | `string` | — | Label text (required) |
+| `inputID` | `string` | — | ID of the input this label is for |
+| `isLabelHidden` | `boolean` | `false` | Visually hide the label |
+| `isDisabled` | `boolean` | `false` | Whether the associated input is disabled |
+| `isOptional` | `boolean` | `false` | Show "Optional" indicator |
+| `isRequired` | `boolean` | `false` | Show "Required" indicator |
+| `startIcon` | `XDSIconType` | — | Icon before the label text |
+| `tooltip` | `string` | — | Tooltip text for info icon at end of label |
+
+### XDSFieldStatus
+
+Status message component for form field validation feedback.
+
+```tsx
+<XDSFieldStatus type="error" message="This field is required" />
+```
+
+| Prop | Type | Default | Description |
+| --------- | ------------------------------------------ | ------------ | ----------------------------------------------- |
+| `type` | `'error' \| 'warning' \| 'success'` | — | Status type |
+| `message` | `string` | — | Status message text |
+| `id` | `string` | — | ID for aria-describedby association |
+| `variant` | `'attached' \| 'detached'` | `'attached'` | Visual variant (overlaps vs floats below input) |
+
## Usage
```tsx
diff --git a/packages/core/src/Grid/README.md b/packages/core/src/Grid/README.md
index 392075b37d..6e4d72f862 100644
--- a/packages/core/src/Grid/README.md
+++ b/packages/core/src/Grid/README.md
@@ -8,6 +8,50 @@ CSS Grid-based layout with responsive auto-fit support.
import {XDSGrid, XDSGridSpan} from '@xds/core/Grid';
```
+### XDSGrid
+
+Grid container with fixed or responsive auto-fit columns.
+
+```tsx
+<XDSGrid columns={3} gap="space4">
+ <Item />
+ <Item />
+ <Item />
+</XDSGrid>
+```
+
+| Prop | Type | Default | Description |
+| --------------- | ---------------- | ----------- | ---------------------------------------------- |
+| `columns` | `number` | — | Maximum number of columns |
+| `minChildWidth` | `number` | — | Min item width in px (enables auto-fit) |
+| `width` | `number \| string` | — | Container width |
+| `height` | `number \| string` | — | Container height |
+| `gap` | `SpacingScale` | — | Spacing between all items |
+| `rowGap` | `SpacingScale` | — | Row spacing (overrides gap) |
+| `columnGap` | `SpacingScale` | — | Column spacing (overrides gap) |
+| `align` | `GridAlignment` | `'stretch'` | Vertical alignment of items |
+| `justify` | `GridAlignment` | `'stretch'` | Horizontal alignment of items |
+| `xstyle` | `StyleXStyles` | — | StyleX overrides |
+| `children` | `ReactNode` | — | Grid content |
+
+### XDSGridSpan
+
+Grid item that spans multiple columns or rows.
+
+```tsx
+<XDSGrid columns={3} gap="space4">
+ <XDSGridSpan columns={2}>Wide item</XDSGridSpan>
+ <div>Normal item</div>
+</XDSGrid>
+```
+
+| Prop | Type | Default | Description |
+| ---------- | -------------------- | ------- | ---------------------------------------- |
+| `columns` | `number \| 'full'` | — | Columns to span ('full' = entire row) |
+| `rows` | `number` | — | Rows to span |
+| `xstyle` | `StyleXStyles` | — | StyleX overrides |
+| `children` | `ReactNode` | — | Content |
+
## Usage
```tsx
diff --git a/packages/core/src/Layer/README.md b/packages/core/src/Layer/README.md
index 4e11873a05..af178278e3 100644
--- a/packages/core/src/Layer/README.md
+++ b/packages/core/src/Layer/README.md
@@ -87,6 +87,29 @@ const hoverCard = useXDSHoverCard({placement: 'above'});
## Components
+### XDSTooltip
+
+Component wrapper for tooltip display on hover/focus.
+
+```tsx
+<XDSTooltip content="Save your changes" placement="above">
+ <XDSButton label="Save" variant="primary" />
+</XDSTooltip>
+```
+
+| Prop | Type | Default | Description |
+| -------------------- | ------------------------------- | --------- | -------------------------------------------------- |
+| `children` | `ReactNode` | — | Trigger element(s) |
+| `anchorRef` | `RefObject<HTMLElement>` | — | External anchor ref (sibling mode) |
+| `content` | `ReactNode` | — | Tooltip content (typically short text) |
+| `placement` | `LayerPlacement` | `'above'` | Position relative to anchor |
+| `alignment` | `LayerAlignment` | `'center'`| Alignment on placement axis |
+| `delay` | `number` | `200` | Show delay in ms |
+| `hideDelay` | `number` | `0` | Hide delay in ms |
+| `focusTrigger` | `'auto' \| 'always' \| 'never'` | `'auto'` | When to trigger on focus |
+| `isEnabled` | `boolean` | `true` | Enable/disable triggers |
+| `hasHoverIndication` | `'auto' \| boolean` | `'auto'` | Show dashed underline on trigger |
+
### XDSHoverCard
Component wrapper for simpler hover card usage.
diff --git a/packages/core/src/Layout/README.md b/packages/core/src/Layout/README.md
index c708666828..1d689fe6ca 100644
--- a/packages/core/src/Layout/README.md
+++ b/packages/core/src/Layout/README.md
@@ -71,6 +71,105 @@ Layout/
## Quick Start
+### XDSLayout
+
+Page shell with header, sidebar(s), content, and footer slots.
+
+```tsx
+<XDSLayout
+ header={<XDSLayoutHeader hasDivider>App Name</XDSLayoutHeader>}
+ content={<XDSLayoutContent>Body content</XDSLayoutContent>}
+ footer={<XDSLayoutFooter hasDivider>Footer</XDSLayoutFooter>}
+/>
+```
+
+| Prop | Type | Default | Description |
+| ------------- | --------------- | -------- | ----------------------------------------------- |
+| `content` | `ReactNode` | — | Main content area (center) |
+| `header` | `ReactNode` | — | Header slot |
+| `footer` | `ReactNode` | — | Footer slot |
+| `start` | `ReactNode` | — | Start panel (left in LTR) |
+| `end` | `ReactNode` | — | End panel (right in LTR) |
+| `height` | `'fill' \| 'auto'` | `'fill'` | Height behavior (fill container vs grow) |
+| `isFullBleed` | `boolean` | `false` | Remove padding at outer edges |
+
+### XDSLayoutHeader
+
+Top bar for page titles, app bars, and toolbars.
+
+```tsx
+<XDSLayoutHeader hasDivider role="banner">
+ Page Title
+</XDSLayoutHeader>
+```
+
+| Prop | Type | Default | Description |
+| ------------- | ------------------ | ------- | ------------------------------------- |
+| `children` | `ReactNode` | — | Header content |
+| `hasDivider` | `boolean` | `false` | Border at bottom edge |
+| `height` | `number \| string` | — | Header height |
+| `isFullBleed` | `boolean` | `false` | Remove internal padding |
+| `label` | `string` | — | Accessible label for landmark |
+| `role` | `AriaRole` | — | ARIA landmark role |
+
+### XDSLayoutContent
+
+Scrollable main content area.
+
+```tsx
+<XDSLayoutContent role="main">
+ <MainContent />
+</XDSLayoutContent>
+```
+
+| Prop | Type | Default | Description |
+| -------------- | ---------- | ------- | ------------------------------------- |
+| `children` | `ReactNode`| — | Content |
+| `isFullBleed` | `boolean` | `false` | Remove internal padding |
+| `isScrollable` | `boolean` | `true` | Enable scrollable overflow |
+| `label` | `string` | — | Accessible label for landmark |
+| `role` | `AriaRole` | — | ARIA landmark role |
+
+### XDSLayoutFooter
+
+Bottom bar for action bars, pagination, and status bars.
+
+```tsx
+<XDSLayoutFooter hasDivider>
+ <XDSButton label="Save" variant="primary" />
+</XDSLayoutFooter>
+```
+
+| Prop | Type | Default | Description |
+| ------------- | ------------------ | ------- | ------------------------------------- |
+| `children` | `ReactNode` | — | Footer content |
+| `hasDivider` | `boolean` | `false` | Border at top edge |
+| `height` | `number \| string` | — | Footer height |
+| `isFullBleed` | `boolean` | `false` | Remove internal padding |
+| `label` | `string` | — | Accessible label for landmark |
+| `role` | `AriaRole` | — | ARIA landmark role |
+
+### XDSLayoutPanel
+
+Sidebar for navigation, settings, or inspector panels.
+
+```tsx
+<XDSLayoutPanel hasDivider width={240} role="navigation">
+ <Navigation />
+</XDSLayoutPanel>
+```
+
+| Prop | Type | Default | Description |
+| -------------- | ------------------ | ------- | ------------------------------------- |
+| `children` | `ReactNode` | — | Panel content |
+| `hasDivider` | `boolean` | `false` | Border on appropriate edge |
+| `isFullBleed` | `boolean` | `false` | Remove internal padding |
+| `isScrollable` | `boolean` | `true` | Enable scrollable overflow |
+| `label` | `string` | — | Accessible label for landmark |
+| `role` | `AriaRole` | — | ARIA landmark role |
+
+## Usage Examples
+
### Card Layout
```tsx
diff --git a/packages/core/src/Link/README.md b/packages/core/src/Link/README.md
index bbd964b0a6..60b32eef7b 100644
--- a/packages/core/src/Link/README.md
+++ b/packages/core/src/Link/README.md
@@ -16,6 +16,46 @@ XDSLink component for styled anchor links with multiple variants and features, p
- **Focus visible**: Accessible focus outline
- **Polymorphic link**: Render as a custom component via `as` prop or `XDSLinkProvider`
+## Components
+
+### XDSLink
+
+Styled anchor link with variants, external link support, and polymorphic rendering.
+
+```tsx
+<XDSLink label="Documentation" href="/docs">Documentation</XDSLink>
+```
+
+| Prop | Type | Default | Description |
+| ---------------- | ------------------------------------ | ----------- | ------------------------------------------- |
+| `as` | `XDSLinkComponentType` | — | Custom component to render instead of `<a>` |
+| `label` | `string` | — | Accessible label (required) |
+| `href` | `string` | — | Link destination URL |
+| `variant` | `'default' \| 'subtle' \| 'inherit'` | `'default'` | Visual style variant |
+| `hasUnderline` | `boolean` | `false` | Always show underline |
+| `isDisabled` | `boolean` | `false` | Disables the link |
+| `isExternalLink` | `boolean` | `false` | Opens in new tab with external icon |
+| `target` | `string` | — | Where to open linked document |
+| `onClick` | `MouseEventHandler` | — | Click event handler |
+| `tooltip` | `string` | — | Tooltip text displayed on hover |
+| `isStandalone` | `boolean` | `false` | Applies base font sizing |
+| `children` | `ReactNode` | — | Link content (required) |
+
+### XDSLinkProvider
+
+Provider that sets the default link component for all XDS link components in the subtree.
+
+```tsx
+<XDSLinkProvider component={Link}>
+ <App />
+</XDSLinkProvider>
+```
+
+| Prop | Type | Default | Description |
+| ----------- | ---------------------- | ------- | ------------------------------------------------ |
+| `component` | `XDSLinkComponentType` | — | Component to use for all link elements (required)|
+| `children` | `ReactNode` | — | Subtree |
+
## Usage
```tsx
diff --git a/packages/core/src/List/README.md b/packages/core/src/List/README.md
index 1f98173c46..87705af11d 100644
--- a/packages/core/src/List/README.md
+++ b/packages/core/src/List/README.md
@@ -53,7 +53,16 @@ import {XDSList, XDSListItem} from '@xds/core';
</XDSList>
```
-## XDSList Props
+### XDSList
+
+List container with density, dividers, and header support.
+
+```tsx
+<XDSList hasDividers header={<strong>Team Members</strong>}>
+ <XDSListItem label="Alice" description="Engineering" />
+ <XDSListItem label="Bob" description="Design" />
+</XDSList>
+```
| Prop | Type | Default | Description |
| ------------- | ------------------------------------------- | ------------ | ------------------------------------------------ |
@@ -65,7 +74,18 @@ import {XDSList, XDSListItem} from '@xds/core';
| `xstyle` | `StyleXStyles` | — | Style overrides |
| `data-testid` | `string` | — | Test ID |
-## XDSListItem Props
+### XDSListItem
+
+List item with label, description, start/end content slots, and interactive patterns.
+
+```tsx
+<XDSListItem
+ label="Settings"
+ description="Manage your preferences"
+ startContent={<XDSIcon icon={CogIcon} />}
+ onClick={() => navigate('/settings')}
+/>
+```
| Prop | Type | Default | Description |
| -------------- | ------------------------- | ------- | ------------------------------------------------ |
diff --git a/packages/core/src/RadioList/README.md b/packages/core/src/RadioList/README.md
index 063396dc6d..33d421a38a 100644
--- a/packages/core/src/RadioList/README.md
+++ b/packages/core/src/RadioList/README.md
@@ -84,7 +84,16 @@ import { XDSRadioList, XDSRadioListItem } from '@xds/core/RadioList';
</XDSRadioList>
```
-## XDSRadioList Props
+### XDSRadioList
+
+Radio group container with field integration for label, description, and status.
+
+```tsx
+<XDSRadioList label="Notification preference" value={selected} onChange={setSelected}>
+ <XDSRadioListItem label="Email" value="email" />
+ <XDSRadioListItem label="SMS" value="sms" />
+</XDSRadioList>
+```
| Prop | Type | Default | Description |
| --------------- | ---------------------------- | ------------ | -------------------------------------------------------------------- |
@@ -104,7 +113,17 @@ import { XDSRadioList, XDSRadioListItem } from '@xds/core/RadioList';
| `data-testid` | `string` | — | Test ID for the outer container |
| `children` | `ReactNode` | — | `XDSRadioListItem` elements |
-## XDSRadioListItem Props
+### XDSRadioListItem
+
+Individual radio item with label, description, and content slots.
+
+```tsx
+<XDSRadioListItem
+ label="Pro"
+ value="pro"
+ description="All features, unlimited usage"
+/>
+```
| Prop | Type | Default | Description |
| -------------- | ----------- | ------- | ---------------------------------------------- |
diff --git a/packages/core/src/Selector/README.md b/packages/core/src/Selector/README.md
index d1ddce5a5b..6926b29348 100644
--- a/packages/core/src/Selector/README.md
+++ b/packages/core/src/Selector/README.md
@@ -61,7 +61,18 @@ import {XDSSelector, XDSSelectorItem} from '@xds/core/Selector';
/>
```
-## Props
+### XDSSelector
+
+Dropdown selector for choosing from a list of options.
+
+```tsx
+<XDSSelector
+ label="Fruit"
+ items={['Apple', 'Banana', 'Orange']}
+ value={value}
+ onChange={setValue}
+/>
+```
| Prop | Type | Description |
| --------------------------- | --------------------------------------------------------- | ------------------------------------------------------------------- |
@@ -94,18 +105,24 @@ import {XDSSelector, XDSSelectorItem} from '@xds/core/Selector';
{type: 'section', title: 'Group Name', items: [...]}
```
-## XDSSelectorItem
+### XDSSelectorItem
Helper for custom item rendering:
```tsx
<XDSSelectorItem
- icon={UserIcon} // Optional XDSIconType
- label="Primary text" // Required ReactNode
- description="Secondary" // Optional ReactNode
+ icon={UserIcon}
+ label="Primary text"
+ description="Secondary"
/>
```
+| Prop | Type | Default | Description |
+| ------------- | ------------- | ------- | --------------------------------- |
+| `icon` | `XDSIconType` | — | Icon before the label |
+| `label` | `ReactNode` | — | Primary label text (required) |
+| `description` | `ReactNode` | — | Secondary description text |
+
## Keyboard
↑↓ navigate, Enter/Space select, Escape close, Home/End jump, A-Z typeahead.
diff --git a/packages/core/src/SideNav/README.md b/packages/core/src/SideNav/README.md
index acbd3e5b91..ed5926d915 100644
--- a/packages/core/src/SideNav/README.md
+++ b/packages/core/src/SideNav/README.md
@@ -4,23 +4,100 @@ Sidebar navigation component for application pages. Supports sections, nested it
## Components
-| Component | Description |
-| ------------------- | ----------------------------------------------------------------------------------------- |
-| `XDSSideNav` | Container with five zones: header, topContent, children (scrollable), footer, footerIcons |
-| `XDSSideNavHeader` | Product/suite/account header with smart interaction boundary logic |
-| `XDSSideNavItem` | Navigation item with icon, selected state, and nesting |
-| `XDSSideNavSection` | Section grouping with optional title and end content |
-
-## Files
-
-| File | Purpose |
-| ----------------------- | ------------------------------------------ |
-| `XDSSideNav.tsx` | Container component |
-| `XDSSideNavHeader.tsx` | Header component with popover menu support |
-| `XDSSideNavItem.tsx` | Navigation item component |
-| `XDSSideNavSection.tsx` | Section grouping component |
-| `XDSSideNav.test.tsx` | Unit tests |
-| `index.ts` | Public exports |
+### XDSSideNav
+
+Container with five zones: header, topContent, children (scrollable), footer, footerIcons.
+
+```tsx
+<XDSSideNav
+ header={<XDSSideNavHeader icon={<AppIcon />} title="My App" titleHref="/" />}
+ topContent={<XDSButton label="Create new" variant="primary" />}>
+ <XDSSideNavSection title="Main">
+ <XDSSideNavItem label="Dashboard" icon={HomeIcon} isSelected href="/dashboard" />
+ <XDSSideNavItem label="Projects" icon={FolderIcon} href="/projects" />
+ </XDSSideNavSection>
+</XDSSideNav>
+```
+
+| Prop | Type | Default | Description |
+| ------------- | -------------- | ------- | -------------------------------------------- |
+| `header` | `ReactNode` | — | Header area (XDSSideNavHeader). Sticky |
+| `topContent` | `ReactNode` | — | Content below header (e.g., create button) |
+| `children` | `ReactNode` | — | Navigation sections and items. Scrollable |
+| `footer` | `ReactNode` | — | Footer area above icon bar |
+| `footerIcons` | `ReactNode` | — | Footer icon bar |
+| `xstyle` | `StyleXStyles` | — | StyleX overrides |
+| `data-testid` | `string` | — | Test ID |
+
+### XDSSideNavHeader
+
+Product/suite/account header with smart interaction boundary logic.
+
+```tsx
+<XDSSideNavHeader icon={<AppIcon />} title="My App" titleHref="/" />
+```
+
+| Prop | Type | Default | Description |
+| ---------------- | -------------- | ------- | --------------------------------- |
+| `icon` | `ReactNode` | — | Product/app icon |
+| `title` | `string` | — | Product/app name (required) |
+| `titleHref` | `string` | — | Link for the title |
+| `supertitle` | `string` | — | Text above the title |
+| `supertitleHref` | `string` | — | Link for the supertitle |
+| `subtitle` | `string` | — | Text below the title |
+| `subtitleHref` | `string` | — | Link for the subtitle |
+| `menu` | `ReactNode` | — | Menu content in a popover |
+| `xstyle` | `StyleXStyles` | — | StyleX overrides |
+| `data-testid` | `string` | — | Test ID |
+
+### XDSSideNavItem
+
+Navigation item with icon, selected state, and nesting support.
+
+```tsx
+<XDSSideNavItem
+ label="Dashboard"
+ icon={HomeIcon}
+ selectedIcon={HomeIconSolid}
+ isSelected
+ href="/dashboard"
+ endContent={<XDSBadge>3</XDSBadge>}
+/>
+```
+
+| Prop | Type | Default | Description |
+| -------------- | ---------------------- | ------- | ------------------------------------ |
+| `as` | `XDSLinkComponentType` | — | Custom link component |
+| `label` | `string` | — | Item label (required) |
+| `icon` | `XDSIconType` | — | Icon (outline variant) |
+| `selectedIcon` | `XDSIconType` | — | Icon when selected (filled variant) |
+| `isSelected` | `boolean` | `false` | Current page indicator |
+| `isDisabled` | `boolean` | `false` | Disabled state |
+| `href` | `string` | — | Navigation URL |
+| `onClick` | `(e: MouseEvent) => void` | — | Click handler |
+| `endContent` | `ReactNode` | — | Right-side content (badges, counts) |
+| `children` | `ReactNode` | — | Sub-items for nesting |
+| `data-testid` | `string` | — | Test ID |
+
+### XDSSideNavSection
+
+Section grouping with optional title and end content.
+
+```tsx
+<XDSSideNavSection title="Settings" endContent={<XDSBadge>New</XDSBadge>}>
+ <XDSSideNavItem label="General" href="/settings/general" />
+ <XDSSideNavItem label="Security" href="/settings/security" />
+</XDSSideNavSection>
+```
+
+| Prop | Type | Default | Description |
+| ---------------- | ----------- | ------- | ------------------------------------------- |
+| `title` | `string` | — | Section title (required) |
+| `subtitle` | `string` | — | Section subtitle |
+| `children` | `ReactNode` | — | Section items |
+| `endContent` | `ReactNode` | — | Right-side content in section header |
+| `isHeaderHidden` | `boolean` | `false` | Visually hide header (still accessible) |
+| `data-testid` | `string` | — | Test ID |
## Usage
diff --git a/packages/core/src/Slider/README.md b/packages/core/src/Slider/README.md
index ae05add1df..3e6d44cb21 100644
--- a/packages/core/src/Slider/README.md
+++ b/packages/core/src/Slider/README.md
@@ -98,7 +98,7 @@ import { XDSSlider } from '@xds/core/Slider';
/>
```
-## XDSSlider Props (Base)
+## Props
| Prop | Type | Default | Description |
| --------------- | ------------------------------------------ | -------------- | -------------------------------------------------------- |
diff --git a/packages/core/src/TabList/README.md b/packages/core/src/TabList/README.md
index f4dca080dd..51ad962550 100644
--- a/packages/core/src/TabList/README.md
+++ b/packages/core/src/TabList/README.md
@@ -63,6 +63,13 @@ import { XDSTabList, XDSTab, XDSTabMenu } from '@xds/core/TabList';
### XDSTabList
+```tsx
+<XDSTabList value={activeTab} onChange={setActiveTab} hasDivider>
+ <XDSTab value="home" label="Home" />
+ <XDSTab value="settings" label="Settings" />
+</XDSTabList>
+```
+
| Prop | Type | Default | Description |
| ------------ | ---------------------- | ------- | ---------------------------------- |
| `value` | `string` | — | Active tab value |
@@ -73,6 +80,10 @@ import { XDSTabList, XDSTab, XDSTabMenu } from '@xds/core/TabList';
### XDSTab
+```tsx
+<XDSTab value="home" label="Home" href="/home" icon={<HomeIcon />} />
+```
+
| Prop | Type | Default | Description |
| -------------- | ----------- | ----------- | ----------------------------------------- |
| `value` | `string` | — | Unique tab value |
@@ -83,6 +94,16 @@ import { XDSTabList, XDSTab, XDSTabMenu } from '@xds/core/TabList';
### XDSTabMenu
+```tsx
+<XDSTabMenu
+ label="More"
+ options={[
+ {value: 'analytics', label: 'Analytics', icon: ChartBarIcon},
+ {value: 'reports', label: 'Reports', icon: DocumentTextIcon},
+ ]}
+/>
+```
+
| Prop | Type | Default | Description |
| --------- | -------------------- | ------- | --------------------------------------------------------- |
| `label` | `string` | — | Trigger label (shown when no option selected) and heading |
diff --git a/packages/core/src/Table/README.md b/packages/core/src/Table/README.md
index e06099582c..3cbb3f931d 100644
--- a/packages/core/src/Table/README.md
+++ b/packages/core/src/Table/README.md
@@ -43,6 +43,102 @@ Table components for the XDS design system.
| `types.ts` | `TableHeaderCellComponentProps` | Props interface for HeaderCell components |
| `useXDSTableSelection.tsx` | `UseXDSTableSelectionConfig` | Config type for the selection hook |
+## Components
+
+### XDSTable
+
+Styled, data-driven table with density, dividers, hover, and plugin support.
+
+```tsx
+<XDSTable
+ data={users}
+ columns={[
+ {key: 'name', header: 'Name'},
+ {key: 'email', header: 'Email', width: proportional(2)},
+ ]}
+ density="balanced"
+ dividers="rows"
+ hasHover
+/>
+```
+
+| Prop | Type | Default | Description |
+| ----------- | --------------------------------- | ------------ | ------------------------------------ |
+| `data` | `T[]` | — | Array of data items |
+| `columns` | `XDSTableColumn<T>[]` | — | Column definitions (auto-generated if omitted) |
+| `idKey` | `string \| (item: T) => string` | — | Row key for React reconciliation |
+| `density` | `'compact' \| 'balanced' \| 'spacious'` | `'balanced'` | Row density |
+| `dividers` | `XDSTableDividers` | `'rows'` | Divider style |
+| `isStriped` | `boolean` | `false` | Striped even rows |
+| `hasHover` | `boolean` | `false` | Hover highlight on rows |
+| `plugins` | `Record<string, TablePlugin<T>>` | — | Named plugins to extend behavior |
+| `children` | `ReactNode` | — | Children mode (manual rows) |
+
+### XDSBaseTable
+
+Unstyled table with colgroup, plugin pipeline, and components prop for custom rendering.
+
+```tsx
+<XDSBaseTable
+ data={items}
+ columns={columns}
+ plugins={[myPlugin]}
+ components={{ Row: XDSTableRow, Cell: XDSTableCell }}
+/>
+```
+
+| Prop | Type | Default | Description |
+| ------------ | -------------------------- | ------- | ----------------------------------------- |
+| `data` | `T[]` | — | Array of data items |
+| `columns` | `XDSTableColumn<T>[]` | — | Column definitions |
+| `idKey` | `string \| (item: T) => string` | — | Row key for React reconciliation |
+| `plugins` | `TablePlugin<T>[]` | — | Ordered plugins for transform pipeline |
+| `components` | `{Row?, Cell?, HeaderCell?}` | — | Component overrides for table elements |
+| `children` | `ReactNode` | — | Children mode |
+| `tableProps` | `HTMLAttributes` | — | Additional attrs for `<table>` element |
+
+### XDSTableRow
+
+`<tr>` wrapper with context-aware styling and xstyle support.
+
+```tsx
+<XDSTableRow>
+ <XDSTableCell>Alice</XDSTableCell>
+ <XDSTableCell>30</XDSTableCell>
+</XDSTableRow>
+```
+
+| Prop | Type | Default | Description |
+| ---------- | ---------------- | ------- | --------------- |
+| `children` | `ReactNode` | — | Row cells |
+| `xstyle` | `StyleXStyles[]` | — | Style overrides |
+
+### XDSTableCell
+
+`<td>` wrapper with context-aware styling and xstyle support.
+
+```tsx
+<XDSTableCell>Cell content</XDSTableCell>
+```
+
+| Prop | Type | Default | Description |
+| ---------- | -------------------------------- | ------- | --------------- |
+| `children` | `ReactNode` | — | Cell content |
+| `xstyle` | `StyleXStyles \| StyleXStyles` | — | Style overrides |
+
+### XDSTableHeaderCell
+
+`<th>` wrapper with context-aware header styling and xstyle support.
+
+```tsx
+<XDSTableHeaderCell>Name</XDSTableHeaderCell>
+```
+
+| Prop | Type | Default | Description |
+| ---------- | -------------------------------- | ------- | --------------- |
+| `children` | `ReactNode` | — | Header content |
+| `xstyle` | `StyleXStyles \| StyleXStyles[]` | — | Style overrides |
+
## Usage Patterns
### Data-driven table
diff --git a/packages/core/src/Text/README.md b/packages/core/src/Text/README.md
index ac92229c3e..43783411ee 100644
--- a/packages/core/src/Text/README.md
+++ b/packages/core/src/Text/README.md
@@ -22,19 +22,59 @@ Typography components for the XDS design system.
## Usage Patterns
-### XDSText / XDSHeading
+### XDSText
-Use for explicit typography control with full type safety:
+Body text with semantic variants and truncation support.
```tsx
-<XDSHeading level={1} size="2xl">Page Title</XDSHeading>
<XDSText type="body" color="primary">Body text content.</XDSText>
-<XDSText type="supporting" color="secondary">Helper text.</XDSText>
```
+| Prop | Type | Default | Description |
+| -------------------- | --------------------------------------- | ---------- | --------------------------------------------- |
+| `type` | `XDSTextType` | — | Semantic text type (body, supporting, label) |
+| `size` | `XDSTextSize` | — | Explicit font size override |
+| `color` | `XDSTextColor` | — | Text color (defaults vary by type) |
+| `weight` | `XDSTextWeight` | — | Font weight override |
+| `display` | `XDSTextDisplay` | `'inline'` | Display type |
+| `maxLines` | `number` | `0` | Max lines before truncation |
+| `hasTruncateTooltip` | `boolean \| LayerPlacement` | `true` | Tooltip for truncated text |
+| `wordBreak` | `XDSWordBreak` | — | Word break behavior |
+| `textWrap` | `XDSTextWrap` | — | Text wrapping behavior |
+| `hasCapsize` | `boolean` | `false` | Enable optical alignment (text-box-trim) |
+| `hasStrikethrough` | `boolean` | `false` | Strikethrough decoration |
+| `hasTabularNumbers` | `boolean` | `false` | Use tabular (monospace) numbers |
+| `as` | `'span' \| 'p' \| 'div' \| 'label'` | `'span'` | HTML element to render |
+| `xstyle` | `StyleXStyles` | — | Constrained styles for layout integration |
+| `children` | `ReactNode` | — | Text content |
+
+### XDSHeading
+
+Headings with level-based styling and optional accessibility level override.
+
+```tsx
+<XDSHeading level={1} size="2xl">Page Title</XDSHeading>
+```
+
+| Prop | Type | Default | Description |
+| -------------------- | --------------------------- | ----------- | ---------------------------------------------- |
+| `level` | `1 \| 2 \| 3 \| 4 \| 5 \| 6` | — | Visual heading level (required) |
+| `accessibilityLevel` | `1 \| 2 \| 3 \| 4 \| 5 \| 6` | same as `level` | ARIA level override |
+| `variant` | `'default' \| 'editorial'` | `'default'` | Visual variant (dense vs editorial scale) |
+| `color` | `XDSTextColor` | `'primary'` | Text color |
+| `display` | `XDSTextDisplay` | `'block'` | Display type |
+| `maxLines` | `number` | `0` | Max lines before truncation |
+| `hasTruncateTooltip` | `boolean \| LayerPlacement` | `true` | Tooltip for truncated text |
+| `wordBreak` | `XDSWordBreak` | — | Word break behavior |
+| `textWrap` | `XDSTextWrap` | — | Text wrapping behavior |
+| `hasCapsize` | `boolean` | `false` | Enable optical alignment |
+| `hasStrikethrough` | `boolean` | `false` | Strikethrough decoration |
+| `xstyle` | `StyleXStyles` | — | Constrained styles for layout integration |
+| `children` | `ReactNode` | — | Heading content |
+
### XDSFontWrapper
-Use when rendering user content or markdown where you can't control the elements:
+Wrapper that applies typography styles to native HTML (for user content/markdown).
```tsx
<XDSFontWrapper variant="editorial">
@@ -42,6 +82,12 @@ Use when rendering user content or markdown where you can't control the elements
</XDSFontWrapper>
```
+| Prop | Type | Default | Description |
+| ------------- | ---------------------------- | ----------- | ------------------------------- |
+| `variant` | `'default' \| 'editorial'` | `'default'` | Heading scale variant |
+| `children` | `ReactNode` | — | Content to style |
+| `data-testid` | `string` | — | Test ID |
+
### useXDSFontWrapperStyles
Use when you want StyleX-based styling with theme tokens:
diff --git a/packages/core/src/TimeInput/README.md b/packages/core/src/TimeInput/README.md
index a921a4187a..0c1dea3240 100644
--- a/packages/core/src/TimeInput/README.md
+++ b/packages/core/src/TimeInput/README.md
@@ -46,6 +46,28 @@ import {XDSTimeInput} from '@xds/core/TimeInput';
/>
```
+## Props
+
+| Prop | Type | Default | Description |
+| --------------- | ------------------------------------------------- | ----------------- | ---------------------------------------------- |
+| `label` | `string` | — | Label text (required for accessibility) |
+| `isLabelHidden` | `boolean` | `false` | Visually hide label |
+| `description` | `string` | — | Description text below label |
+| `isOptional` | `boolean` | `false` | Show "(optional)" indicator |
+| `isRequired` | `boolean` | `false` | Mark field as required |
+| `isDisabled` | `boolean` | `false` | Disable the input |
+| `value` | `ISOTimeString` | — | Selected time (HH:MM or HH:MM:SS) |
+| `onChange` | `(value: ISOTimeString \| undefined) => void` | — | Callback fired when time changes |
+| `min` | `ISOTimeString` | — | Minimum selectable time |
+| `max` | `ISOTimeString` | — | Maximum selectable time |
+| `hasSeconds` | `boolean` | `false` | Include seconds in the time input |
+| `hasClear` | `boolean` | `false` | Show clear button when value is set |
+| `hourFormat` | `'12h' \| '24h'` | `'12h'` | Hour display format |
+| `increment` | `number` | `1` | Increment in minutes for arrow keys |
+| `placeholder` | `string` | `"Select a time"` | Placeholder text |
+| `size` | `'sm' \| 'md'` | `'md'` | Input size |
+| `status` | `XDSInputStatus` | — | Status indicator (error/warning/success) |
+
## Theming
Themes can override `TimeInput` styles via `ComponentStyles`:
diff --git a/packages/core/src/TopNav/README.md b/packages/core/src/TopNav/README.md
index 8ac9fef149..28035c07de 100644
--- a/packages/core/src/TopNav/README.md
+++ b/packages/core/src/TopNav/README.md
@@ -65,6 +65,15 @@ For the circular icon container, use `XDSNavIcon` from `@xds/core/NavIcon`.
### XDSTopNav
+```tsx
+<XDSTopNav
+ label="Main navigation"
+ title={<XDSTopNavTitle title="My App" href="/" />}
+ startContent={<XDSTopNavItem label="Dashboard" href="/dashboard" isSelected />}
+ endContent={<XDSButton label="Profile" variant="ghost" />}
+/>
+```
+
| Prop | Type | Default | Description |
| -------------- | ----------- | ------- | ----------------------------------------------------- |
| `title` | `ReactNode` | — | Title slot (logo, brand) - left aligned |
@@ -74,6 +83,10 @@ For the circular icon container, use `XDSNavIcon` from `@xds/core/NavIcon`.
### XDSTopNavTitle
+```tsx
+<XDSTopNavTitle title="My App" logo={<XDSNavIcon icon={<HomeIcon />} />} href="/" />
+```
+
| Prop | Type | Default | Description |
| ------- | ----------- | ------- | -------------------------------- |
| `title` | `string` | — | Title text to display |
@@ -82,6 +95,10 @@ For the circular icon container, use `XDSNavIcon` from `@xds/core/NavIcon`.
### XDSTopNavItem
+```tsx
+<XDSTopNavItem label="Dashboard" href="/dashboard" isSelected icon={<HomeIcon />} />
+```
+
| Prop | Type | Default | Description |
| ------------ | ----------- | ------- | ------------------------------- |
| `label` | `string` | — | Accessible label (required) |
@@ -93,6 +110,16 @@ For the circular icon container, use `XDSNavIcon` from `@xds/core/NavIcon`.
### XDSTopNavMenu
+```tsx
+<XDSTopNavMenu
+ label="Products"
+ items={[
+ {title: 'Analytics', description: 'View metrics', href: '/analytics'},
+ {title: 'Reports', description: 'Generate reports', href: '/reports'},
+ ]}
+/>
+```
+
| Prop | Type | Default | Description |
| ----------- | ------------------------- | ------- | ------------------------------------------- |
| `label` | `string` | — | Visible label for the trigger (required) |