diff --git a/packages/components/src/box-control/README.md b/packages/components/src/box-control/README.md
index 80cfce6689642..77543aa0fba68 100644
--- a/packages/components/src/box-control/README.md
+++ b/packages/components/src/box-control/README.md
@@ -1,5 +1,9 @@
# BoxControl
+
+This feature is still experimental. “Experimental” means this is an early implementation subject to drastic and breaking changes.
+
+
BoxControl components let users set values for Top, Right, Bottom, and Left. This can be used as an input control for values like `padding` or `margin`.
## Usage
diff --git a/packages/components/src/dimension-control/README.md b/packages/components/src/dimension-control/README.md
index 6eda6430a488c..7c627b7fbe266 100644
--- a/packages/components/src/dimension-control/README.md
+++ b/packages/components/src/dimension-control/README.md
@@ -1,5 +1,9 @@
# DimensionControl
+
+This feature is still experimental. “Experimental” means this is an early implementation subject to drastic and breaking changes.
+
+
`DimensionControl` is a component designed to provide a UI to control spacing and/or dimensions.
## Usage
diff --git a/packages/components/src/divider/README.md b/packages/components/src/divider/README.md
index a793646650ee1..ae9b961dad5e5 100644
--- a/packages/components/src/divider/README.md
+++ b/packages/components/src/divider/README.md
@@ -1,5 +1,9 @@
# Divider
+
+This feature is still experimental. “Experimental” means this is an early implementation subject to drastic and breaking changes.
+
+
`Divider` is a layout component that separates groups of related content.
## Usage
diff --git a/packages/components/src/elevation/README.md b/packages/components/src/elevation/README.md
index 134948c4e801d..0e61fe7db0a75 100644
--- a/packages/components/src/elevation/README.md
+++ b/packages/components/src/elevation/README.md
@@ -1,5 +1,9 @@
# Elevation
+
+This feature is still experimental. “Experimental” means this is an early implementation subject to drastic and breaking changes.
+
+
`Elevation` is a core component that renders shadow, using the component system's shadow system.
## Usage
@@ -10,7 +14,7 @@ The shadow effect is generated using the `value` prop.
import {
__experimentalElevation as Elevation,
__experimentalSurface as Surface,
- __experimentalText as Text
+ __experimentalText as Text,
} from '@wordpress/components';
function Example() {
diff --git a/packages/components/src/flex/flex-block/README.md b/packages/components/src/flex/flex-block/README.md
index b5cbe861f6d66..691f1b0ad33c0 100644
--- a/packages/components/src/flex/flex-block/README.md
+++ b/packages/components/src/flex/flex-block/README.md
@@ -1,6 +1,8 @@
# FlexBlock
-> **Experimental!**
+
+This feature is still experimental. “Experimental” means this is an early implementation subject to drastic and breaking changes.
+
A layout component to contain items of a fixed width within `Flex`.
diff --git a/packages/components/src/flex/flex-item/README.md b/packages/components/src/flex/flex-item/README.md
index 6a6fc03826327..2aec78afe35c2 100644
--- a/packages/components/src/flex/flex-item/README.md
+++ b/packages/components/src/flex/flex-item/README.md
@@ -1,6 +1,8 @@
# FlexItem
-> **Experimental!**
+
+This feature is still experimental. “Experimental” means this is an early implementation subject to drastic and breaking changes.
+
A layout component to contain items of a fixed width within `Flex`.
diff --git a/packages/components/src/flex/flex/README.md b/packages/components/src/flex/flex/README.md
index 2ca42bb44baa5..55a7b8b15ecc5 100644
--- a/packages/components/src/flex/flex/README.md
+++ b/packages/components/src/flex/flex/README.md
@@ -1,6 +1,8 @@
# Flex
-> **Experimental!**
+
+This feature is still experimental. “Experimental” means this is an early implementation subject to drastic and breaking changes.
+
`Flex` is a primitive layout component that adaptively aligns child content horizontally or vertically. `Flex` powers components like `HStack` and `VStack`.
diff --git a/packages/components/src/grid/README.md b/packages/components/src/grid/README.md
index 6765ff856b3d0..27695353d54c2 100644
--- a/packages/components/src/grid/README.md
+++ b/packages/components/src/grid/README.md
@@ -1,6 +1,8 @@
# Grid
-> **Experimental!**
+
+This feature is still experimental. “Experimental” means this is an early implementation subject to drastic and breaking changes.
+
`Grid` is a primitive layout component that can arrange content in a grid configuration.
@@ -9,7 +11,7 @@
```jsx
import {
__experimentalGrid as Grid,
- __experimentalText as Text
+ __experimentalText as Text,
} from '@wordpress/components';
function Example() {
diff --git a/packages/components/src/h-stack/README.md b/packages/components/src/h-stack/README.md
index 99182bb3e7b9a..a0b63c7521fcb 100644
--- a/packages/components/src/h-stack/README.md
+++ b/packages/components/src/h-stack/README.md
@@ -1,6 +1,8 @@
# HStack
-> **Experimental!**
+
+This feature is still experimental. “Experimental” means this is an early implementation subject to drastic and breaking changes.
+
`HStack` (Horizontal Stack) arranges child elements in a horizontal line.
@@ -93,7 +95,7 @@ function Example() {
Code
- is
+ is
Poetry
diff --git a/packages/components/src/heading/README.md b/packages/components/src/heading/README.md
index c686ccf49b971..f96fe871add75 100644
--- a/packages/components/src/heading/README.md
+++ b/packages/components/src/heading/README.md
@@ -1,6 +1,8 @@
# Heading
-> **Experimental!**
+
+This feature is still experimental. “Experimental” means this is an early implementation subject to drastic and breaking changes.
+
`Heading` renders headings and titles using the library's typography system.
diff --git a/packages/components/src/input-control/README.md b/packages/components/src/input-control/README.md
index fef516a7a3f18..63a0c50901014 100644
--- a/packages/components/src/input-control/README.md
+++ b/packages/components/src/input-control/README.md
@@ -1,5 +1,9 @@
# InputControl
+
+This feature is still experimental. “Experimental” means this is an early implementation subject to drastic and breaking changes.
+
+
InputControl components let users enter and edit text. This is an experimental component intended to (in time) merge with or replace [TextControl](../text-control).
## Usage
diff --git a/packages/components/src/navigation/README.md b/packages/components/src/navigation/README.md
index b793489d5a000..1128874463d57 100644
--- a/packages/components/src/navigation/README.md
+++ b/packages/components/src/navigation/README.md
@@ -1,5 +1,9 @@
# Navigation
+
+This feature is still experimental. “Experimental” means this is an early implementation subject to drastic and breaking changes.
+
+
Render a navigation list with optional groupings and hierarchy.
## Usage
diff --git a/packages/components/src/number-control/README.md b/packages/components/src/number-control/README.md
index efb77dd18a40a..b233502f92f6a 100644
--- a/packages/components/src/number-control/README.md
+++ b/packages/components/src/number-control/README.md
@@ -1,5 +1,9 @@
# NumberControl
+
+This feature is still experimental. “Experimental” means this is an early implementation subject to drastic and breaking changes.
+
+
NumberControl is an enhanced HTML [`input[type="number]`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input/number) element.
## Usage
diff --git a/packages/components/src/radio-group/README.md b/packages/components/src/radio-group/README.md
index 6c3b0d84633a2..721ff07d33a9f 100644
--- a/packages/components/src/radio-group/README.md
+++ b/packages/components/src/radio-group/README.md
@@ -1,5 +1,9 @@
# RadioGroup
+
+This feature is still experimental. “Experimental” means this is an early implementation subject to drastic and breaking changes.
+
+
Use a RadioGroup component when you want users to select one option from a small set of options.
diff --git a/packages/components/src/spacer/README.md b/packages/components/src/spacer/README.md
index 1aad9670c082f..7bc5b01abf42d 100644
--- a/packages/components/src/spacer/README.md
+++ b/packages/components/src/spacer/README.md
@@ -1,6 +1,8 @@
# Spacer
-> **Experimental!**
+
+This feature is still experimental. “Experimental” means this is an early implementation subject to drastic and breaking changes.
+
`Spacer` is a primitive layout component that providers inner (`padding`) or outer (`margin`) space in-between components. It can also be used to adaptively provide space within an `HStack` or `VStack`.
@@ -14,7 +16,7 @@
import {
__experimentalSpacer as Spacer,
__experimentalHeading as Heading,
- __experimentalView as View
+ __experimentalView as View,
} from '@wordpress/components';
function Example() {
@@ -23,9 +25,7 @@ function Example() {
WordPress.org
-
- Code is Poetry
-
+ Code is Poetry
);
}
diff --git a/packages/components/src/text/README.md b/packages/components/src/text/README.md
index 72a1831a25191..7747ec9cbc727 100644
--- a/packages/components/src/text/README.md
+++ b/packages/components/src/text/README.md
@@ -1,6 +1,8 @@
# Text
-> **Experimental!**
+
+This feature is still experimental. “Experimental” means this is an early implementation subject to drastic and breaking changes.
+
`Text` is a core component that renders text in the library, using the library's typography system.
diff --git a/packages/components/src/tree-grid/README.md b/packages/components/src/tree-grid/README.md
index eaedacdfe6f55..3806d7cc66fd3 100644
--- a/packages/components/src/tree-grid/README.md
+++ b/packages/components/src/tree-grid/README.md
@@ -1,5 +1,8 @@
-# TreeGrid (experimental)
+# TreeGrid
+
+This feature is still experimental. “Experimental” means this is an early implementation subject to drastic and breaking changes.
+
## Table of contents
1. [Development guidelines](#development-guidelines)
diff --git a/packages/components/src/truncate/README.md b/packages/components/src/truncate/README.md
index 494c99dd9720c..f7c72f53f884a 100644
--- a/packages/components/src/truncate/README.md
+++ b/packages/components/src/truncate/README.md
@@ -1,6 +1,8 @@
# Truncate
-> **Experimental!**
+
+This feature is still experimental. “Experimental” means this is an early implementation subject to drastic and breaking changes.
+
`Truncate` is a typography primitive that trims text content. For almost all cases, it is recommended that `Text`, `Heading`, or `Subheading` is used to render text content. However, `Truncate` is available for custom implementations.
diff --git a/packages/components/src/ui/card/README.md b/packages/components/src/ui/card/README.md
index 447a2b10bfcc4..56c2bef2af5ce 100644
--- a/packages/components/src/ui/card/README.md
+++ b/packages/components/src/ui/card/README.md
@@ -1,5 +1,9 @@
# Card
+
+This feature is still experimental. “Experimental” means this is an early implementation subject to drastic and breaking changes.
+
+
`Card` groups similar concepts and tasks together. `Card`'s background is rendered with a `Surface`.
## Usage
diff --git a/packages/components/src/ui/control-group/README.md b/packages/components/src/ui/control-group/README.md
index 3e7f9760fb9c9..122a6a612a32c 100644
--- a/packages/components/src/ui/control-group/README.md
+++ b/packages/components/src/ui/control-group/README.md
@@ -1,5 +1,9 @@
# ControlGroup
+
+This feature is still experimental. “Experimental” means this is an early implementation subject to drastic and breaking changes.
+
+
`ControlGroup` is a layout-based component for rendering a group of control-based components, such as `Button`, `Select` or `TextInput`. Control components that render within `ControlGroup` automatically have their borders offset and border-radii rounded.
## Usage
diff --git a/packages/components/src/ui/control-label/README.md b/packages/components/src/ui/control-label/README.md
index ee6dd9a31329d..d4e31e034dfd8 100644
--- a/packages/components/src/ui/control-label/README.md
+++ b/packages/components/src/ui/control-label/README.md
@@ -1,5 +1,9 @@
# ControlLabel
+
+This feature is still experimental. “Experimental” means this is an early implementation subject to drastic and breaking changes.
+
+
`ControlLabel` is a form component that works with `FormGroup` to provide a label for form elements (e.g. `Switch` or `TextInput`).
## Usage
diff --git a/packages/components/src/ui/form-group/README.md b/packages/components/src/ui/form-group/README.md
index 69b65aabc638c..fec4316caf355 100644
--- a/packages/components/src/ui/form-group/README.md
+++ b/packages/components/src/ui/form-group/README.md
@@ -1,5 +1,9 @@
# FormGroup
+
+This feature is still experimental. “Experimental” means this is an early implementation subject to drastic and breaking changes.
+
+
`FormGroup` is a form component that groups a label with a form element (e.g. `Switch` or `TextInput`).
## Usage
diff --git a/packages/components/src/ui/popover/README.md b/packages/components/src/ui/popover/README.md
index 294d43a0380d1..028d093818749 100644
--- a/packages/components/src/ui/popover/README.md
+++ b/packages/components/src/ui/popover/README.md
@@ -1,5 +1,9 @@
# Popover
+
+This feature is still experimental. “Experimental” means this is an early implementation subject to drastic and breaking changes.
+
+
`Popover` is a component to render a floating content modal. It is similar in purpose to a tooltip, but renders content of any sort, not only simple text.
## Usage
diff --git a/packages/components/src/ui/scrollable/README.md b/packages/components/src/ui/scrollable/README.md
index a3996eab2dcc0..e098a2683d7c4 100644
--- a/packages/components/src/ui/scrollable/README.md
+++ b/packages/components/src/ui/scrollable/README.md
@@ -1,5 +1,9 @@
# Scrollable
+
+This feature is still experimental. “Experimental” means this is an early implementation subject to drastic and breaking changes.
+
+
`Scrollable` is a layout component that content in a scrollable container.
## Usage
diff --git a/packages/components/src/ui/spinner/README.md b/packages/components/src/ui/spinner/README.md
index 7f611ea6c8832..5e25f9992d0c3 100644
--- a/packages/components/src/ui/spinner/README.md
+++ b/packages/components/src/ui/spinner/README.md
@@ -1,5 +1,9 @@
# Spinner
+
+This feature is still experimental. “Experimental” means this is an early implementation subject to drastic and breaking changes.
+
+
`Spinner` is a component that notify users that their action is being processed.
## Usage
diff --git a/packages/components/src/ui/surface/README.md b/packages/components/src/ui/surface/README.md
index c3481f0ffa942..3e82138864cf4 100644
--- a/packages/components/src/ui/surface/README.md
+++ b/packages/components/src/ui/surface/README.md
@@ -1,5 +1,9 @@
# Surface
+
+This feature is still experimental. “Experimental” means this is an early implementation subject to drastic and breaking changes.
+
+
`Surface` is a core component that renders a primary background color.
## Usage
diff --git a/packages/components/src/ui/tooltip/README.md b/packages/components/src/ui/tooltip/README.md
index ac9e3789c8452..424da79828a48 100644
--- a/packages/components/src/ui/tooltip/README.md
+++ b/packages/components/src/ui/tooltip/README.md
@@ -1,5 +1,9 @@
# Tooltip
+
+This feature is still experimental. “Experimental” means this is an early implementation subject to drastic and breaking changes.
+
+
`Tooltip` is a component to render floating help text relative to a node when it receives focus or when the user places the mouse cursor atop it.
## Usage
diff --git a/packages/components/src/ui/visually-hidden/README.md b/packages/components/src/ui/visually-hidden/README.md
index 6200eed80dacb..756311c8043ca 100644
--- a/packages/components/src/ui/visually-hidden/README.md
+++ b/packages/components/src/ui/visually-hidden/README.md
@@ -1,5 +1,9 @@
# VisuallyHidden
+
+This feature is still experimental. “Experimental” means this is an early implementation subject to drastic and breaking changes.
+
+
`VisuallyHidden` is a component used to render text intended to be visually hidden, but will show for alternate devices, for example a screen reader.
## Usage
diff --git a/packages/components/src/unit-control/README.md b/packages/components/src/unit-control/README.md
index b024e6aaf5e5e..5c681ff2ca40a 100644
--- a/packages/components/src/unit-control/README.md
+++ b/packages/components/src/unit-control/README.md
@@ -1,5 +1,9 @@
# UnitControl
+
+This feature is still experimental. “Experimental” means this is an early implementation subject to drastic and breaking changes.
+
+
UnitControl allows the user to set a value as well as a unit (e.g. `px`).
## Usage
diff --git a/packages/components/src/v-stack/README.md b/packages/components/src/v-stack/README.md
index ba2132804f78f..e1fbba7f90d16 100644
--- a/packages/components/src/v-stack/README.md
+++ b/packages/components/src/v-stack/README.md
@@ -1,6 +1,8 @@
# VStack
-> **Experimental!**
+
+This feature is still experimental. “Experimental” means this is an early implementation subject to drastic and breaking changes.
+
`VStack` (or Vertical Stack) is a layout component that arranges child elements in a vertical line.
@@ -93,7 +95,7 @@ function Example() {
Code
- is
+ is
Poetry
diff --git a/packages/components/src/view/README.md b/packages/components/src/view/README.md
index f991f2d95c733..794d7b49a0d38 100644
--- a/packages/components/src/view/README.md
+++ b/packages/components/src/view/README.md
@@ -1,6 +1,8 @@
# View
-> **Experimental!**
+
+This feature is still experimental. “Experimental” means this is an early implementation subject to drastic and breaking changes.
+
`View` is a core component that renders everything in the library. It is the principle component in the entire library.
@@ -11,7 +13,7 @@
```jsx
import {
__experimentalText as Text,
- __experimentalView as View
+ __experimentalView as View,
} from '@wordpress/components';
function Example() {
diff --git a/packages/components/src/z-stack/README.md b/packages/components/src/z-stack/README.md
index 6a4a31fb38b9f..7f07104b0654f 100644
--- a/packages/components/src/z-stack/README.md
+++ b/packages/components/src/z-stack/README.md
@@ -1,6 +1,8 @@
# ZStack
-> **Experimental!**
+
+This feature is still experimental. “Experimental” means this is an early implementation subject to drastic and breaking changes.
+
## Usage