From fc54ccdf9a87d5c8806f91e706304efdc78da03c Mon Sep 17 00:00:00 2001
From: Haz <hazdiego@gmail.com>
Date: Fri, 19 Jun 2020 12:38:17 -0300
Subject: [PATCH 01/22] Deprecate legacy toolbar usage

---
 .../src/components/navigable-toolbar/index.js            | 9 ++++++++-
 1 file changed, 8 insertions(+), 1 deletion(-)

diff --git a/packages/block-editor/src/components/navigable-toolbar/index.js b/packages/block-editor/src/components/navigable-toolbar/index.js
index fa63839248267..29b0c8a8c7cb0 100644
--- a/packages/block-editor/src/components/navigable-toolbar/index.js
+++ b/packages/block-editor/src/components/navigable-toolbar/index.js
@@ -9,6 +9,7 @@ import {
 	useEffect,
 	useCallback,
 } from '@wordpress/element';
+import deprecated from '@wordpress/deprecated';
 import { focus } from '@wordpress/dom';
 import { useShortcut } from '@wordpress/keyboard-shortcuts';
 
@@ -43,7 +44,13 @@ function useIsAccessibleToolbar( ref ) {
 
 	const determineIsAccessibleToolbar = useCallback( () => {
 		const tabbables = focus.tabbable.find( ref.current );
-		setIsAccessibleToolbar( hasOnlyToolbarItem( tabbables ) );
+		const onlyToolbarItem = hasOnlyToolbarItem( tabbables );
+		if ( ! onlyToolbarItem ) {
+			deprecated( 'Using custom components as toolbar controls', {
+				alternative: 'ToolbarItem or ToolbarButton components',
+			} );
+		}
+		setIsAccessibleToolbar( onlyToolbarItem );
 	}, [] );
 
 	useLayoutEffect( determineIsAccessibleToolbar, [] );

From e29ae9636de0da871ffa04704c546292ed585e05 Mon Sep 17 00:00:00 2001
From: Haz <hazdiego@gmail.com>
Date: Fri, 19 Jun 2020 15:31:00 -0300
Subject: [PATCH 02/22] Update e2e tests

---
 packages/e2e-tests/specs/editor/various/is-typing.test.js | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/packages/e2e-tests/specs/editor/various/is-typing.test.js b/packages/e2e-tests/specs/editor/various/is-typing.test.js
index 8161118d65944..50a44d831f434 100644
--- a/packages/e2e-tests/specs/editor/various/is-typing.test.js
+++ b/packages/e2e-tests/specs/editor/various/is-typing.test.js
@@ -39,7 +39,7 @@ describe( 'isTyping', () => {
 	it( 'should not close the dropdown when typing in it', async () => {
 		// Adds a Dropdown with an input to all blocks
 		await page.evaluate( () => {
-			const { Dropdown, Button, Fill } = wp.components;
+			const { Dropdown, ToolbarButton, Fill } = wp.components;
 			const { createElement: el, Fragment } = wp.element;
 			function AddDropdown( BlockListBlock ) {
 				return ( props ) => {
@@ -52,7 +52,7 @@ describe( 'isTyping', () => {
 							el( Dropdown, {
 								renderToggle: ( { onToggle } ) =>
 									el(
-										Button,
+										ToolbarButton,
 										{
 											onClick: onToggle,
 											className: 'dropdown-open',

From d5201eb9be19c159ca8aa026ea21d842c1c5af2a Mon Sep 17 00:00:00 2001
From: Haz <hazdiego@gmail.com>
Date: Thu, 16 Jul 2020 11:45:24 -0300
Subject: [PATCH 03/22] Remove __experimental flag from Toolbar
 accessibilityLabel prop

---
 .../src/components/navigable-toolbar/index.js   |  2 +-
 .../src/heading/heading-level-dropdown.js       |  4 +---
 packages/components/src/toolbar-button/index.js |  3 ++-
 .../src/toolbar-button/stories/index.js         |  2 +-
 .../toolbar-group/toolbar-group-collapsed.js    |  2 +-
 packages/components/src/toolbar/index.js        | 17 +++++++----------
 .../components/src/toolbar/stories/index.js     |  7 ++-----
 packages/components/src/toolbar/test/index.js   |  2 +-
 8 files changed, 16 insertions(+), 23 deletions(-)

diff --git a/packages/block-editor/src/components/navigable-toolbar/index.js b/packages/block-editor/src/components/navigable-toolbar/index.js
index 29b0c8a8c7cb0..47d2fcb03ebb6 100644
--- a/packages/block-editor/src/components/navigable-toolbar/index.js
+++ b/packages/block-editor/src/components/navigable-toolbar/index.js
@@ -97,7 +97,7 @@ function NavigableToolbar( { children, focusOnMount, ...props } ) {
 	if ( isAccessibleToolbar ) {
 		return (
 			<Toolbar
-				__experimentalAccessibilityLabel={ props[ 'aria-label' ] }
+				accessibilityLabel={ props[ 'aria-label' ] }
 				ref={ wrapper }
 				{ ...props }
 			>
diff --git a/packages/block-library/src/heading/heading-level-dropdown.js b/packages/block-library/src/heading/heading-level-dropdown.js
index 263d0a8ba650c..dbdc3eaf05109 100644
--- a/packages/block-library/src/heading/heading-level-dropdown.js
+++ b/packages/block-library/src/heading/heading-level-dropdown.js
@@ -69,9 +69,7 @@ export default function HeadingLevelDropdown( { selectedLevel, onChange } ) {
 			renderContent={ () => (
 				<Toolbar
 					className="block-library-heading-level-toolbar"
-					__experimentalAccessibilityLabel={ __(
-						'Change heading level'
-					) }
+					accessibilityLabel={ __( 'Change heading level' ) }
 				>
 					<ToolbarGroup
 						isCollapsed={ false }
diff --git a/packages/components/src/toolbar-button/index.js b/packages/components/src/toolbar-button/index.js
index f449ecdd2d523..f27eade16d96d 100644
--- a/packages/components/src/toolbar-button/index.js
+++ b/packages/components/src/toolbar-button/index.js
@@ -30,7 +30,8 @@ function ToolbarButton(
 	const accessibleToolbarState = useContext( ToolbarContext );
 
 	if ( ! accessibleToolbarState ) {
-		// This should be deprecated when <Toolbar __experimentalAccessibilityLabel="label">
+		// TODO
+		// This should be deprecated when <Toolbar accessibilityLabel="label">
 		// becomes stable.
 		return (
 			<ToolbarButtonContainer className={ containerClassName }>
diff --git a/packages/components/src/toolbar-button/stories/index.js b/packages/components/src/toolbar-button/stories/index.js
index 1bb0475003e16..6171b8483a908 100644
--- a/packages/components/src/toolbar-button/stories/index.js
+++ b/packages/components/src/toolbar-button/stories/index.js
@@ -16,7 +16,7 @@ export const _default = () => {
 	const icon = text( 'Icon', 'wordpress' );
 
 	return (
-		<Toolbar __experimentalAccessibilityLabel="Example Toolbar">
+		<Toolbar accessibilityLabel="Example Toolbar">
 			<ToolbarButton icon={ icon } label={ label } />
 		</Toolbar>
 	);
diff --git a/packages/components/src/toolbar-group/toolbar-group-collapsed.js b/packages/components/src/toolbar-group/toolbar-group-collapsed.js
index 1c020ad84d5c4..a8897debb937b 100644
--- a/packages/components/src/toolbar-group/toolbar-group-collapsed.js
+++ b/packages/components/src/toolbar-group/toolbar-group-collapsed.js
@@ -12,7 +12,7 @@ import ToolbarItem from '../toolbar-item';
 
 function ToolbarGroupCollapsed( { controls = [], ...props } ) {
 	// It'll contain state if `ToolbarGroup` is being used within
-	// `<Toolbar __experimentalAccessibilityLabel="label" />`
+	// `<Toolbar accessibilityLabel="label" />`
 	const accessibleToolbarState = useContext( ToolbarContext );
 
 	const renderDropdownMenu = ( toggleProps ) => (
diff --git a/packages/components/src/toolbar/index.js b/packages/components/src/toolbar/index.js
index ebf8e3482bf63..45715423a3d3f 100644
--- a/packages/components/src/toolbar/index.js
+++ b/packages/components/src/toolbar/index.js
@@ -21,14 +21,11 @@ import ToolbarContainer from './toolbar-container';
  *
  * @param {Object} props                                    Component props.
  * @param {string} [props.className]                        Class to set on the container div.
- * @param {string} [props.__experimentalAccessibilityLabel] ARIA label for toolbar container.
+ * @param {string} [props.accessibilityLabel] ARIA label for toolbar container.
  * @param {Object} ref                                      React Element ref.
  */
-function Toolbar(
-	{ className, __experimentalAccessibilityLabel, ...props },
-	ref
-) {
-	if ( __experimentalAccessibilityLabel ) {
+function Toolbar( { className, accessibilityLabel, ...props }, ref ) {
+	if ( accessibilityLabel ) {
 		return (
 			<ToolbarContainer
 				// `ToolbarGroup` already uses components-toolbar for compatibility reasons
@@ -36,15 +33,15 @@ function Toolbar(
 					'components-accessible-toolbar',
 					className
 				) }
-				accessibilityLabel={ __experimentalAccessibilityLabel }
+				accessibilityLabel={ accessibilityLabel }
 				ref={ ref }
 				{ ...props }
 			/>
 		);
 	}
-	// When the __experimentalAccessibilityLabel prop is not passed, Toolbar will
-	// fallback to ToolbarGroup. This should be deprecated as soon as the new API
-	// gets stable.
+	// TODO
+	// When the accessibilityLabel prop is not passed, Toolbar will fallback to
+	// ToolbarGroup. This should be deprecated as soon as the new API gets stable.
 	// See https://github.com/WordPress/gutenberg/pull/20008#issuecomment-624503410
 	return <ToolbarGroup { ...props } className={ className } />;
 }
diff --git a/packages/components/src/toolbar/stories/index.js b/packages/components/src/toolbar/stories/index.js
index 2749329089b77..237a618ce1071 100644
--- a/packages/components/src/toolbar/stories/index.js
+++ b/packages/components/src/toolbar/stories/index.js
@@ -41,10 +41,7 @@ function InlineImageIcon() {
 export const _default = () => {
 	return (
 		// id is required for server side rendering
-		<Toolbar
-			__experimentalAccessibilityLabel="Options"
-			id="options-toolbar"
-		>
+		<Toolbar accessibilityLabel="Options" id="options-toolbar">
 			<ToolbarGroup>
 				<ToolbarButton icon={ paragraph } label="Paragraph" />
 			</ToolbarGroup>
@@ -116,7 +113,7 @@ export const withoutGroup = () => {
 	return (
 		// id is required for server side rendering
 		<Toolbar
-			__experimentalAccessibilityLabel="Options"
+			accessibilityLabel="Options"
 			id="options-toolbar-without-group"
 		>
 			<ToolbarButton icon={ formatBold } label="Bold" isPressed />
diff --git a/packages/components/src/toolbar/test/index.js b/packages/components/src/toolbar/test/index.js
index d5de14b4a86c5..ade3b8ff4a6d9 100644
--- a/packages/components/src/toolbar/test/index.js
+++ b/packages/components/src/toolbar/test/index.js
@@ -13,7 +13,7 @@ describe( 'Toolbar', () => {
 	describe( 'basic rendering', () => {
 		it( 'should render a toolbar with toolbar buttons', () => {
 			const { getByLabelText } = render(
-				<Toolbar __experimentalAccessibilityLabel="blocks">
+				<Toolbar accessibilityLabel="blocks">
 					<ToolbarButton label="control1" />
 					<ToolbarButton label="control2" />
 				</Toolbar>

From 7aecd5ec1b55a1d0a424051aeb2ef95b177d1cc7 Mon Sep 17 00:00:00 2001
From: Haz <hazdiego@gmail.com>
Date: Thu, 23 Jul 2020 05:02:34 -0300
Subject: [PATCH 04/22] Use label instead of accessibilityLabel

---
 .../src/components/navigable-toolbar/index.js    |  2 +-
 .../src/heading/heading-level-dropdown.js        |  2 +-
 .../src/toolbar-button/stories/index.js          |  2 +-
 packages/components/src/toolbar-group/index.js   |  2 +-
 .../src/toolbar-group/toolbar-group-collapsed.js |  2 +-
 packages/components/src/toolbar/index.js         | 16 ++++++++--------
 packages/components/src/toolbar/stories/index.js |  7 ++-----
 packages/components/src/toolbar/test/index.js    |  2 +-
 .../components/src/toolbar/toolbar-container.js  |  4 ++--
 9 files changed, 18 insertions(+), 21 deletions(-)

diff --git a/packages/block-editor/src/components/navigable-toolbar/index.js b/packages/block-editor/src/components/navigable-toolbar/index.js
index 099f9523f2ae1..c4dd450dac2ac 100644
--- a/packages/block-editor/src/components/navigable-toolbar/index.js
+++ b/packages/block-editor/src/components/navigable-toolbar/index.js
@@ -113,7 +113,7 @@ function NavigableToolbar( { children, focusOnMount, ...props } ) {
 	if ( isAccessibleToolbar ) {
 		return (
 			<Toolbar
-				accessibilityLabel={ props[ 'aria-label' ] }
+				label={ props[ 'aria-label' ] }
 				ref={ wrapper }
 				{ ...props }
 			>
diff --git a/packages/block-library/src/heading/heading-level-dropdown.js b/packages/block-library/src/heading/heading-level-dropdown.js
index dbdc3eaf05109..c936c9383ba83 100644
--- a/packages/block-library/src/heading/heading-level-dropdown.js
+++ b/packages/block-library/src/heading/heading-level-dropdown.js
@@ -69,7 +69,7 @@ export default function HeadingLevelDropdown( { selectedLevel, onChange } ) {
 			renderContent={ () => (
 				<Toolbar
 					className="block-library-heading-level-toolbar"
-					accessibilityLabel={ __( 'Change heading level' ) }
+					label={ __( 'Change heading level' ) }
 				>
 					<ToolbarGroup
 						isCollapsed={ false }
diff --git a/packages/components/src/toolbar-button/stories/index.js b/packages/components/src/toolbar-button/stories/index.js
index 6171b8483a908..cd13dbb3274d9 100644
--- a/packages/components/src/toolbar-button/stories/index.js
+++ b/packages/components/src/toolbar-button/stories/index.js
@@ -16,7 +16,7 @@ export const _default = () => {
 	const icon = text( 'Icon', 'wordpress' );
 
 	return (
-		<Toolbar accessibilityLabel="Example Toolbar">
+		<Toolbar label="Example Toolbar">
 			<ToolbarButton icon={ icon } label={ label } />
 		</Toolbar>
 	);
diff --git a/packages/components/src/toolbar-group/index.js b/packages/components/src/toolbar-group/index.js
index 86639e9e62823..595035fc59ee8 100644
--- a/packages/components/src/toolbar-group/index.js
+++ b/packages/components/src/toolbar-group/index.js
@@ -56,7 +56,7 @@ function ToolbarGroup( {
 	...props
 } ) {
 	// It'll contain state if `ToolbarGroup` is being used within
-	// `<Toolbar accessibilityLabel="label" />`
+	// `<Toolbar label="label" />`
 	const accessibleToolbarState = useContext( ToolbarContext );
 
 	if ( ( ! controls || ! controls.length ) && ! children ) {
diff --git a/packages/components/src/toolbar-group/toolbar-group-collapsed.js b/packages/components/src/toolbar-group/toolbar-group-collapsed.js
index a8897debb937b..e112309890cce 100644
--- a/packages/components/src/toolbar-group/toolbar-group-collapsed.js
+++ b/packages/components/src/toolbar-group/toolbar-group-collapsed.js
@@ -12,7 +12,7 @@ import ToolbarItem from '../toolbar-item';
 
 function ToolbarGroupCollapsed( { controls = [], ...props } ) {
 	// It'll contain state if `ToolbarGroup` is being used within
-	// `<Toolbar accessibilityLabel="label" />`
+	// `<Toolbar label="label" />`
 	const accessibleToolbarState = useContext( ToolbarContext );
 
 	const renderDropdownMenu = ( toggleProps ) => (
diff --git a/packages/components/src/toolbar/index.js b/packages/components/src/toolbar/index.js
index 45715423a3d3f..6aa1bc4290d21 100644
--- a/packages/components/src/toolbar/index.js
+++ b/packages/components/src/toolbar/index.js
@@ -19,13 +19,13 @@ import ToolbarContainer from './toolbar-container';
  *
  * To add controls, simply pass `ToolbarButton` components as children.
  *
- * @param {Object} props                                    Component props.
- * @param {string} [props.className]                        Class to set on the container div.
- * @param {string} [props.accessibilityLabel] ARIA label for toolbar container.
- * @param {Object} ref                                      React Element ref.
+ * @param {Object} props							Component props.
+ * @param {string} [props.className]	Class to set on the container div.
+ * @param {string} [props.label] 			ARIA label for toolbar container.
+ * @param {Object} ref								React Element ref.
  */
-function Toolbar( { className, accessibilityLabel, ...props }, ref ) {
-	if ( accessibilityLabel ) {
+function Toolbar( { className, label, ...props }, ref ) {
+	if ( label ) {
 		return (
 			<ToolbarContainer
 				// `ToolbarGroup` already uses components-toolbar for compatibility reasons
@@ -33,14 +33,14 @@ function Toolbar( { className, accessibilityLabel, ...props }, ref ) {
 					'components-accessible-toolbar',
 					className
 				) }
-				accessibilityLabel={ accessibilityLabel }
+				label={ label }
 				ref={ ref }
 				{ ...props }
 			/>
 		);
 	}
 	// TODO
-	// When the accessibilityLabel prop is not passed, Toolbar will fallback to
+	// When the label prop is not passed, Toolbar will fallback to
 	// ToolbarGroup. This should be deprecated as soon as the new API gets stable.
 	// See https://github.com/WordPress/gutenberg/pull/20008#issuecomment-624503410
 	return <ToolbarGroup { ...props } className={ className } />;
diff --git a/packages/components/src/toolbar/stories/index.js b/packages/components/src/toolbar/stories/index.js
index 237a618ce1071..79915eb11035a 100644
--- a/packages/components/src/toolbar/stories/index.js
+++ b/packages/components/src/toolbar/stories/index.js
@@ -41,7 +41,7 @@ function InlineImageIcon() {
 export const _default = () => {
 	return (
 		// id is required for server side rendering
-		<Toolbar accessibilityLabel="Options" id="options-toolbar">
+		<Toolbar label="Options" id="options-toolbar">
 			<ToolbarGroup>
 				<ToolbarButton icon={ paragraph } label="Paragraph" />
 			</ToolbarGroup>
@@ -112,10 +112,7 @@ export const _default = () => {
 export const withoutGroup = () => {
 	return (
 		// id is required for server side rendering
-		<Toolbar
-			accessibilityLabel="Options"
-			id="options-toolbar-without-group"
-		>
+		<Toolbar label="Options" id="options-toolbar-without-group">
 			<ToolbarButton icon={ formatBold } label="Bold" isPressed />
 			<ToolbarButton icon={ formatItalic } label="Italic" />
 			<ToolbarButton icon={ link } label="Link" />
diff --git a/packages/components/src/toolbar/test/index.js b/packages/components/src/toolbar/test/index.js
index ade3b8ff4a6d9..86777a8455424 100644
--- a/packages/components/src/toolbar/test/index.js
+++ b/packages/components/src/toolbar/test/index.js
@@ -13,7 +13,7 @@ describe( 'Toolbar', () => {
 	describe( 'basic rendering', () => {
 		it( 'should render a toolbar with toolbar buttons', () => {
 			const { getByLabelText } = render(
-				<Toolbar accessibilityLabel="blocks">
+				<Toolbar label="blocks">
 					<ToolbarButton label="control1" />
 					<ToolbarButton label="control2" />
 				</Toolbar>
diff --git a/packages/components/src/toolbar/toolbar-container.js b/packages/components/src/toolbar/toolbar-container.js
index 5141e6fe69f95..df4f29c5afc79 100644
--- a/packages/components/src/toolbar/toolbar-container.js
+++ b/packages/components/src/toolbar/toolbar-container.js
@@ -14,7 +14,7 @@ import { forwardRef } from '@wordpress/element';
 import ToolbarContext from '../toolbar-context';
 import { getRTL } from '../utils/rtl';
 
-function ToolbarContainer( { accessibilityLabel, ...props }, ref ) {
+function ToolbarContainer( { label, ...props }, ref ) {
 	// https://reakit.io/docs/basic-concepts/#state-hooks
 	// Passing baseId for server side rendering (which includes snapshots)
 	// If an id prop is passed to Toolbar, toolbar items will use it as a base for their ids
@@ -29,7 +29,7 @@ function ToolbarContainer( { accessibilityLabel, ...props }, ref ) {
 		<ToolbarContext.Provider value={ toolbarState }>
 			<Toolbar
 				ref={ ref }
-				aria-label={ accessibilityLabel }
+				aria-label={ label }
 				{ ...toolbarState }
 				{ ...props }
 			/>

From 94d5ca266ff92fcd6ef1636d486ae6100d2cf375 Mon Sep 17 00:00:00 2001
From: Haz <hazdiego@gmail.com>
Date: Thu, 23 Jul 2020 05:08:21 -0300
Subject: [PATCH 05/22] Deprecate <Toolbar> without label prop

---
 packages/components/src/toolbar/index.js | 37 ++++++++++++------------
 1 file changed, 19 insertions(+), 18 deletions(-)

diff --git a/packages/components/src/toolbar/index.js b/packages/components/src/toolbar/index.js
index 6aa1bc4290d21..ce8ca17e9d4be 100644
--- a/packages/components/src/toolbar/index.js
+++ b/packages/components/src/toolbar/index.js
@@ -7,6 +7,7 @@ import classnames from 'classnames';
  * WordPress dependencies
  */
 import { forwardRef } from '@wordpress/element';
+import deprecated from '@wordpress/deprecated';
 
 /**
  * Internal dependencies
@@ -25,25 +26,25 @@ import ToolbarContainer from './toolbar-container';
  * @param {Object} ref								React Element ref.
  */
 function Toolbar( { className, label, ...props }, ref ) {
-	if ( label ) {
-		return (
-			<ToolbarContainer
-				// `ToolbarGroup` already uses components-toolbar for compatibility reasons
-				className={ classnames(
-					'components-accessible-toolbar',
-					className
-				) }
-				label={ label }
-				ref={ ref }
-				{ ...props }
-			/>
-		);
+	if ( ! label ) {
+		deprecated( 'Using Toolbar without label prop', {
+			alternative: 'ToolbarGroup component',
+		} );
+		return <ToolbarGroup { ...props } className={ className } />;
 	}
-	// TODO
-	// When the label prop is not passed, Toolbar will fallback to
-	// ToolbarGroup. This should be deprecated as soon as the new API gets stable.
-	// See https://github.com/WordPress/gutenberg/pull/20008#issuecomment-624503410
-	return <ToolbarGroup { ...props } className={ className } />;
+	// `ToolbarGroup` already uses components-toolbar for compatibility reasons
+	const finalClassName = classnames(
+		'components-accessible-toolbar',
+		className
+	);
+	return (
+		<ToolbarContainer
+			className={ finalClassName }
+			label={ label }
+			ref={ ref }
+			{ ...props }
+		/>
+	);
 }
 
 export default forwardRef( Toolbar );

From 26dda7e46eccc275b0aca8ebe4cddf03013d4ade Mon Sep 17 00:00:00 2001
From: Haz <hazdiego@gmail.com>
Date: Thu, 23 Jul 2020 05:11:19 -0300
Subject: [PATCH 06/22] Make ToolbarItem component stable

---
 packages/block-editor/src/components/block-mover/index.js    | 5 +----
 .../block-editor/src/components/block-settings-menu/index.js | 5 +----
 packages/block-editor/src/components/block-switcher/index.js | 2 +-
 .../src/components/rich-text/format-toolbar/index.js         | 2 +-
 packages/block-library/src/image/image-editor.js             | 2 +-
 packages/block-library/src/table/edit.js                     | 2 +-
 packages/components/src/index.js                             | 2 +-
 packages/components/src/toolbar/stories/index.js             | 2 +-
 .../edit-post/src/components/header/header-toolbar/index.js  | 5 +----
 9 files changed, 9 insertions(+), 18 deletions(-)

diff --git a/packages/block-editor/src/components/block-mover/index.js b/packages/block-editor/src/components/block-mover/index.js
index 0b45496222043..d4b9cc66ead73 100644
--- a/packages/block-editor/src/components/block-mover/index.js
+++ b/packages/block-editor/src/components/block-mover/index.js
@@ -7,10 +7,7 @@ import classnames from 'classnames';
 /**
  * WordPress dependencies
  */
-import {
-	ToolbarGroup,
-	__experimentalToolbarItem as ToolbarItem,
-} from '@wordpress/components';
+import { ToolbarGroup, ToolbarItem } from '@wordpress/components';
 import { getBlockType } from '@wordpress/blocks';
 import { Component } from '@wordpress/element';
 import { withSelect } from '@wordpress/data';
diff --git a/packages/block-editor/src/components/block-settings-menu/index.js b/packages/block-editor/src/components/block-settings-menu/index.js
index 7014f29f0e336..0b0b1a775e736 100644
--- a/packages/block-editor/src/components/block-settings-menu/index.js
+++ b/packages/block-editor/src/components/block-settings-menu/index.js
@@ -1,10 +1,7 @@
 /**
  * WordPress dependencies
  */
-import {
-	ToolbarGroup,
-	__experimentalToolbarItem as ToolbarItem,
-} from '@wordpress/components';
+import { ToolbarGroup, ToolbarItem } from '@wordpress/components';
 
 /**
  * Internal dependencies
diff --git a/packages/block-editor/src/components/block-switcher/index.js b/packages/block-editor/src/components/block-switcher/index.js
index 1326e7c76cff7..6f77c5ccf8be3 100644
--- a/packages/block-editor/src/components/block-switcher/index.js
+++ b/packages/block-editor/src/components/block-switcher/index.js
@@ -11,7 +11,7 @@ import {
 	DropdownMenu,
 	ToolbarButton,
 	ToolbarGroup,
-	__experimentalToolbarItem as ToolbarItem,
+	ToolbarItem,
 	MenuGroup,
 	Popover,
 } from '@wordpress/components';
diff --git a/packages/block-editor/src/components/rich-text/format-toolbar/index.js b/packages/block-editor/src/components/rich-text/format-toolbar/index.js
index e0c35b11cdae5..4e98ce8d064ba 100644
--- a/packages/block-editor/src/components/rich-text/format-toolbar/index.js
+++ b/packages/block-editor/src/components/rich-text/format-toolbar/index.js
@@ -10,7 +10,7 @@ import { orderBy } from 'lodash';
 
 import { __ } from '@wordpress/i18n';
 import {
-	__experimentalToolbarItem as ToolbarItem,
+	ToolbarItem,
 	ToolbarGroup,
 	DropdownMenu,
 	Slot,
diff --git a/packages/block-library/src/image/image-editor.js b/packages/block-library/src/image/image-editor.js
index 361355ee8d9a5..895d337c2699d 100644
--- a/packages/block-library/src/image/image-editor.js
+++ b/packages/block-library/src/image/image-editor.js
@@ -20,7 +20,7 @@ import {
 import {
 	ToolbarGroup,
 	ToolbarButton,
-	__experimentalToolbarItem as ToolbarItem,
+	ToolbarItem,
 	Spinner,
 	RangeControl,
 	DropdownMenu,
diff --git a/packages/block-library/src/table/edit.js b/packages/block-library/src/table/edit.js
index 4bc6ca81bbdb3..515ef0a03f8f8 100644
--- a/packages/block-library/src/table/edit.js
+++ b/packages/block-library/src/table/edit.js
@@ -25,7 +25,7 @@ import {
 	TextControl,
 	ToggleControl,
 	ToolbarGroup,
-	__experimentalToolbarItem as ToolbarItem,
+	ToolbarItem,
 } from '@wordpress/components';
 import {
 	alignLeft,
diff --git a/packages/components/src/index.js b/packages/components/src/index.js
index 7c1ec414adbae..cc2bc1deb3ace 100644
--- a/packages/components/src/index.js
+++ b/packages/components/src/index.js
@@ -99,7 +99,7 @@ export { default as Toolbar } from './toolbar';
 export { default as ToolbarButton } from './toolbar-button';
 export { default as __experimentalToolbarContext } from './toolbar-context';
 export { default as ToolbarGroup } from './toolbar-group';
-export { default as __experimentalToolbarItem } from './toolbar-item';
+export { default as ToolbarItem } from './toolbar-item';
 export { default as Tooltip } from './tooltip';
 export {
 	default as __experimentalTreeGrid,
diff --git a/packages/components/src/toolbar/stories/index.js b/packages/components/src/toolbar/stories/index.js
index 79915eb11035a..ae07d52535c9c 100644
--- a/packages/components/src/toolbar/stories/index.js
+++ b/packages/components/src/toolbar/stories/index.js
@@ -23,7 +23,7 @@ import {
 	Path,
 	ToolbarButton,
 	ToolbarGroup,
-	__experimentalToolbarItem as ToolbarItem,
+	ToolbarItem,
 	DropdownMenu,
 } from '../../';
 
diff --git a/packages/edit-post/src/components/header/header-toolbar/index.js b/packages/edit-post/src/components/header/header-toolbar/index.js
index 6c178f193ba16..32ef40ea2a581 100644
--- a/packages/edit-post/src/components/header/header-toolbar/index.js
+++ b/packages/edit-post/src/components/header/header-toolbar/index.js
@@ -15,10 +15,7 @@ import {
 	EditorHistoryRedo,
 	EditorHistoryUndo,
 } from '@wordpress/editor';
-import {
-	Button,
-	__experimentalToolbarItem as ToolbarItem,
-} from '@wordpress/components';
+import { Button, ToolbarItem } from '@wordpress/components';
 import { plus } from '@wordpress/icons';
 
 function HeaderToolbar() {

From 5efe0db36a1fd175982b376488aee5c1c9d8c984 Mon Sep 17 00:00:00 2001
From: Haz <hazdiego@gmail.com>
Date: Thu, 23 Jul 2020 05:15:56 -0300
Subject: [PATCH 07/22] Deprecate ToolbarButton usage without a parent Toolbar

---
 packages/components/src/toolbar-button/index.js | 7 ++++---
 1 file changed, 4 insertions(+), 3 deletions(-)

diff --git a/packages/components/src/toolbar-button/index.js b/packages/components/src/toolbar-button/index.js
index f27eade16d96d..3a8b400fe82b7 100644
--- a/packages/components/src/toolbar-button/index.js
+++ b/packages/components/src/toolbar-button/index.js
@@ -6,6 +6,7 @@ import classnames from 'classnames';
  * WordPress dependencies
  */
 import { useContext, forwardRef } from '@wordpress/element';
+import deprecated from '@wordpress/deprecated';
 /**
  * Internal dependencies
  */
@@ -30,9 +31,9 @@ function ToolbarButton(
 	const accessibleToolbarState = useContext( ToolbarContext );
 
 	if ( ! accessibleToolbarState ) {
-		// TODO
-		// This should be deprecated when <Toolbar accessibilityLabel="label">
-		// becomes stable.
+		deprecated( 'Rendering ToolbarButton without a parent Toolbar', {
+			alternative: 'Button',
+		} );
 		return (
 			<ToolbarButtonContainer className={ containerClassName }>
 				<Button

From f48467e0476f518142feff5c0505c83d959d73e4 Mon Sep 17 00:00:00 2001
From: Haz <hazdiego@gmail.com>
Date: Thu, 23 Jul 2020 05:23:08 -0300
Subject: [PATCH 08/22] Simplify jsdocs

---
 packages/components/src/toolbar/index.js | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/packages/components/src/toolbar/index.js b/packages/components/src/toolbar/index.js
index ce8ca17e9d4be..30830b9b152d8 100644
--- a/packages/components/src/toolbar/index.js
+++ b/packages/components/src/toolbar/index.js
@@ -20,10 +20,10 @@ import ToolbarContainer from './toolbar-container';
  *
  * To add controls, simply pass `ToolbarButton` components as children.
  *
- * @param {Object} props							Component props.
- * @param {string} [props.className]	Class to set on the container div.
- * @param {string} [props.label] 			ARIA label for toolbar container.
- * @param {Object} ref								React Element ref.
+ * @param {Object} props Component props.
+ * @param {string} [props.className] Class to set on the container div.
+ * @param {string} [props.label] ARIA label for toolbar container.
+ * @param {Object} ref React Element ref.
  */
 function Toolbar( { className, label, ...props }, ref ) {
 	if ( ! label ) {

From b46495071246af70c3c5be40b9cd0b2556156b48 Mon Sep 17 00:00:00 2001
From: Haz <hazdiego@gmail.com>
Date: Thu, 23 Jul 2020 05:23:37 -0300
Subject: [PATCH 09/22] data-experimental-toolbar-item to data-toolbar-item

---
 packages/block-editor/src/components/navigable-toolbar/index.js | 2 +-
 packages/components/src/index.native.js                         | 2 +-
 packages/components/src/toolbar-button/index.js                 | 2 +-
 .../components/src/toolbar-group/toolbar-group-collapsed.js     | 2 +-
 packages/components/src/toolbar-item/index.js                   | 2 +-
 5 files changed, 5 insertions(+), 5 deletions(-)

diff --git a/packages/block-editor/src/components/navigable-toolbar/index.js b/packages/block-editor/src/components/navigable-toolbar/index.js
index c4dd450dac2ac..c051f6fe65f79 100644
--- a/packages/block-editor/src/components/navigable-toolbar/index.js
+++ b/packages/block-editor/src/components/navigable-toolbar/index.js
@@ -24,7 +24,7 @@ function useUpdateLayoutEffect( effect, deps ) {
 }
 
 function hasOnlyToolbarItem( elements ) {
-	const dataProp = 'experimentalToolbarItem';
+	const dataProp = 'toolbarItem';
 	return ! elements.some( ( element ) => ! ( dataProp in element.dataset ) );
 }
 
diff --git a/packages/components/src/index.native.js b/packages/components/src/index.native.js
index 2e74337bbf8fb..81a18d865ffee 100644
--- a/packages/components/src/index.native.js
+++ b/packages/components/src/index.native.js
@@ -17,7 +17,7 @@ export { default as Toolbar } from './toolbar';
 export { default as ToolbarButton } from './toolbar-button';
 export { default as __experimentalToolbarContext } from './toolbar-context';
 export { default as ToolbarGroup } from './toolbar-group';
-export { default as __experimentalToolbarItem } from './toolbar-item';
+export { default as ToolbarItem } from './toolbar-item';
 export { default as Icon } from './icon';
 export { default as IconButton } from './button/deprecated';
 export { default as Spinner } from './spinner';
diff --git a/packages/components/src/toolbar-button/index.js b/packages/components/src/toolbar-button/index.js
index 3a8b400fe82b7..712f6f9315f5a 100644
--- a/packages/components/src/toolbar-button/index.js
+++ b/packages/components/src/toolbar-button/index.js
@@ -54,7 +54,7 @@ function ToolbarButton(
 					) }
 					isPressed={ isActive }
 					disabled={ isDisabled }
-					data-experimental-toolbar-item
+					data-toolbar-item
 					{ ...extraProps }
 					{ ...props }
 				>
diff --git a/packages/components/src/toolbar-group/toolbar-group-collapsed.js b/packages/components/src/toolbar-group/toolbar-group-collapsed.js
index e112309890cce..05b30b17fc251 100644
--- a/packages/components/src/toolbar-group/toolbar-group-collapsed.js
+++ b/packages/components/src/toolbar-group/toolbar-group-collapsed.js
@@ -20,7 +20,7 @@ function ToolbarGroupCollapsed( { controls = [], ...props } ) {
 			controls={ controls }
 			toggleProps={ {
 				...toggleProps,
-				'data-experimental-toolbar-item': true,
+				'data-toolbar-item': true,
 			} }
 			{ ...props }
 		/>
diff --git a/packages/components/src/toolbar-item/index.js b/packages/components/src/toolbar-item/index.js
index 127f8e51d4b48..72a7a3b1687ef 100644
--- a/packages/components/src/toolbar-item/index.js
+++ b/packages/components/src/toolbar-item/index.js
@@ -24,7 +24,7 @@ function ToolbarItem( { children, as: Component, ...props }, ref ) {
 		return null;
 	}
 
-	const allProps = { ...props, ref, 'data-experimental-toolbar-item': true };
+	const allProps = { ...props, ref, 'data-toolbar-item': true };
 
 	if ( ! accessibleToolbarState ) {
 		if ( Component ) {

From 1813a7d9ba03b4a542c66e6163f3e08caabda578 Mon Sep 17 00:00:00 2001
From: Haz <hazdiego@gmail.com>
Date: Thu, 23 Jul 2020 05:45:13 -0300
Subject: [PATCH 10/22] Remove deprecation warning from ToolbarButton

This is actually an invalid warning as it may still be rendered inside <ToolbarGroup />
---
 packages/components/src/toolbar-button/index.js | 4 ----
 1 file changed, 4 deletions(-)

diff --git a/packages/components/src/toolbar-button/index.js b/packages/components/src/toolbar-button/index.js
index 712f6f9315f5a..d053ea2b52cf6 100644
--- a/packages/components/src/toolbar-button/index.js
+++ b/packages/components/src/toolbar-button/index.js
@@ -6,7 +6,6 @@ import classnames from 'classnames';
  * WordPress dependencies
  */
 import { useContext, forwardRef } from '@wordpress/element';
-import deprecated from '@wordpress/deprecated';
 /**
  * Internal dependencies
  */
@@ -31,9 +30,6 @@ function ToolbarButton(
 	const accessibleToolbarState = useContext( ToolbarContext );
 
 	if ( ! accessibleToolbarState ) {
-		deprecated( 'Rendering ToolbarButton without a parent Toolbar', {
-			alternative: 'Button',
-		} );
 		return (
 			<ToolbarButtonContainer className={ containerClassName }>
 				<Button

From e16144afb856ae8debe3c3955f7a16115cece6f1 Mon Sep 17 00:00:00 2001
From: Haz <hazdiego@gmail.com>
Date: Thu, 23 Jul 2020 05:52:23 -0300
Subject: [PATCH 11/22] Update unit test

---
 packages/components/src/toolbar/test/index.js | 1 +
 1 file changed, 1 insertion(+)

diff --git a/packages/components/src/toolbar/test/index.js b/packages/components/src/toolbar/test/index.js
index 86777a8455424..ba1b221a19212 100644
--- a/packages/components/src/toolbar/test/index.js
+++ b/packages/components/src/toolbar/test/index.js
@@ -33,6 +33,7 @@ describe( 'Toolbar', () => {
 			const { container } = render( <Toolbar /> );
 
 			expect( container.innerHTML ).toBe( '' );
+			expect( console ).toHaveWarned();
 		} );
 
 		it( 'should render an empty node, when controls are empty', () => {

From e3872390ac336183e0b5c1afb329af3536fa4c42 Mon Sep 17 00:00:00 2001
From: Haz <hazdiego@gmail.com>
Date: Thu, 23 Jul 2020 05:52:39 -0300
Subject: [PATCH 12/22] Update Toolbar README

---
 packages/components/src/toolbar/README.md | 4 ----
 1 file changed, 4 deletions(-)

diff --git a/packages/components/src/toolbar/README.md b/packages/components/src/toolbar/README.md
index 7458cb2e00936..b38427f480e85 100644
--- a/packages/components/src/toolbar/README.md
+++ b/packages/components/src/toolbar/README.md
@@ -13,10 +13,6 @@ Toolbar can be used to group related options. To emphasize groups of related ico
 
 ### Usage
 
-#### Selected action
-
-Only one option in a toolbar can be selected and active at a time. Selecting one option deselects any other.
-
 ### Best practices
 
 Toolbars should:

From 696279d453a998a2990a35e9ab92949412eb5008 Mon Sep 17 00:00:00 2001
From: Haz <hazdiego@gmail.com>
Date: Thu, 23 Jul 2020 06:00:27 -0300
Subject: [PATCH 13/22] Update tests

---
 packages/components/src/toolbar/test/index.js | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/packages/components/src/toolbar/test/index.js b/packages/components/src/toolbar/test/index.js
index ba1b221a19212..4d732e0d488db 100644
--- a/packages/components/src/toolbar/test/index.js
+++ b/packages/components/src/toolbar/test/index.js
@@ -40,6 +40,7 @@ describe( 'Toolbar', () => {
 			const { container } = render( <Toolbar controls={ [] } /> );
 
 			expect( container.innerHTML ).toBe( '' );
+			expect( console ).toHaveWarned();
 		} );
 
 		it( 'should render a list of controls with buttons', () => {
@@ -67,6 +68,7 @@ describe( 'Toolbar', () => {
 				'wp'
 			);
 			expect( toolbarButton.getAttribute( 'type' ) ).toBe( 'button' );
+			expect( console ).toHaveWarned();
 		} );
 	} );
 } );

From cf740b41825b26cf24ac26234ff293585f65cefa Mon Sep 17 00:00:00 2001
From: Haz <hazdiego@gmail.com>
Date: Thu, 23 Jul 2020 06:08:45 -0300
Subject: [PATCH 14/22] Remove ToolbarGroup test from Toolbar

---
 packages/components/src/toolbar/test/index.js | 44 -------------------
 1 file changed, 44 deletions(-)

diff --git a/packages/components/src/toolbar/test/index.js b/packages/components/src/toolbar/test/index.js
index 4d732e0d488db..11fc7d7e4e084 100644
--- a/packages/components/src/toolbar/test/index.js
+++ b/packages/components/src/toolbar/test/index.js
@@ -27,48 +27,4 @@ describe( 'Toolbar', () => {
 			).toBeTruthy();
 		} );
 	} );
-
-	describe( 'ToolbarGroup', () => {
-		it( 'should render an empty node, when controls are not passed', () => {
-			const { container } = render( <Toolbar /> );
-
-			expect( container.innerHTML ).toBe( '' );
-			expect( console ).toHaveWarned();
-		} );
-
-		it( 'should render an empty node, when controls are empty', () => {
-			const { container } = render( <Toolbar controls={ [] } /> );
-
-			expect( container.innerHTML ).toBe( '' );
-			expect( console ).toHaveWarned();
-		} );
-
-		it( 'should render a list of controls with buttons', () => {
-			const controls = [
-				{
-					icon: 'wordpress',
-					title: 'WordPress',
-					subscript: 'wp',
-					onClick: () => {},
-					isActive: false,
-				},
-			];
-			const { getByLabelText } = render(
-				<Toolbar controls={ controls } />
-			);
-
-			const toolbarButton = getByLabelText( 'WordPress' );
-			expect( toolbarButton.getAttribute( 'aria-label' ) ).toBe(
-				'WordPress'
-			);
-			expect( toolbarButton.getAttribute( 'aria-pressed' ) ).toBe(
-				'false'
-			);
-			expect( toolbarButton.getAttribute( 'data-subscript' ) ).toBe(
-				'wp'
-			);
-			expect( toolbarButton.getAttribute( 'type' ) ).toBe( 'button' );
-			expect( console ).toHaveWarned();
-		} );
-	} );
 } );

From dff16604c4a12ecc43cd472e677d7e9f8f89efa5 Mon Sep 17 00:00:00 2001
From: Haz <hazdiego@gmail.com>
Date: Tue, 28 Jul 2020 17:35:35 -0300
Subject: [PATCH 15/22] Replace Toolbar by ToolbarGroup on the Classic Editor

---
 packages/block-library/src/classic/edit.js | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/packages/block-library/src/classic/edit.js b/packages/block-library/src/classic/edit.js
index 238afa052a15b..8195e51006af4 100644
--- a/packages/block-library/src/classic/edit.js
+++ b/packages/block-library/src/classic/edit.js
@@ -7,7 +7,7 @@ import { debounce } from 'lodash';
  * WordPress dependencies
  */
 import { BlockControls } from '@wordpress/block-editor';
-import { Toolbar } from '@wordpress/components';
+import { ToolbarGroup } from '@wordpress/components';
 import { Component } from '@wordpress/element';
 import { __, _x } from '@wordpress/i18n';
 import { BACKSPACE, DELETE, F10, isKeyboardEvent } from '@wordpress/keycodes';
@@ -248,9 +248,9 @@ export default class ClassicEdit extends Component {
 		return (
 			<>
 				<BlockControls>
-					<Toolbar>
+					<ToolbarGroup>
 						<ConvertToBlocksButton clientId={ clientId } />
-					</Toolbar>
+					</ToolbarGroup>
 				</BlockControls>
 				<div
 					key="toolbar"

From 2b5d2323d62c32afee3ccd7e0922bc62f1797655 Mon Sep 17 00:00:00 2001
From: Haz <hazdiego@gmail.com>
Date: Thu, 6 Aug 2020 17:38:18 -0300
Subject: [PATCH 16/22] Add Toolbar, ToolbarButton, ToolbarGroup and
 ToolbarItem docs

---
 docs/manifest.json                            | 12 +++++
 .../components/src/toolbar-button/README.md   | 27 ++++++----
 .../components/src/toolbar-group/README.md    | 33 ++++++++++++
 .../components/src/toolbar-item/README.md     | 53 +++++++++++++++++++
 packages/components/src/toolbar/README.md     | 45 ++++++++++------
 5 files changed, 143 insertions(+), 27 deletions(-)
 create mode 100644 packages/components/src/toolbar-group/README.md
 create mode 100644 packages/components/src/toolbar-item/README.md

diff --git a/docs/manifest.json b/docs/manifest.json
index b9b8a239a36ba..abcc27569c88e 100644
--- a/docs/manifest.json
+++ b/docs/manifest.json
@@ -1199,6 +1199,18 @@
 		"markdown_source": "../packages/components/src/toolbar-button/README.md",
 		"parent": "components"
 	},
+	{
+		"title": "ToolbarGroup",
+		"slug": "toolbar-group",
+		"markdown_source": "../packages/components/src/toolbar-group/README.md",
+		"parent": "components"
+	},
+	{
+		"title": "ToolbarItem",
+		"slug": "toolbar-item",
+		"markdown_source": "../packages/components/src/toolbar-item/README.md",
+		"parent": "components"
+	},
 	{
 		"title": "Toolbar",
 		"slug": "toolbar",
diff --git a/packages/components/src/toolbar-button/README.md b/packages/components/src/toolbar-button/README.md
index 6c276b0e08c54..842982936accd 100644
--- a/packages/components/src/toolbar-button/README.md
+++ b/packages/components/src/toolbar-button/README.md
@@ -1,19 +1,26 @@
 # ToolbarButton
 
-A ToolbarButton can be used to add actions to your block control, usually inside a ToolbarGroup. It has similar features to the [Button](/packages/components/src/button/README.md) component. Using `ToolbarButton` will ensure the correct styling for a button in a toolbar, and also that keyboard interactions in a toolbar are consistent with the [WAI ARIA toolbar pattern](https://www.w3.org/TR/wai-aria-practices/#toolbar).
+A ToolbarButton can be used to add actions to your block control, usually inside a [Toolbar](/packages/components/src/toolbar/README.md) or [ToolbarGroup](/packages/components/src/toolbar-group/README.md).
+
+It has similar features to the [Button](/packages/components/src/button/README.md) component. Using `ToolbarButton` will ensure the correct styling for a button in a toolbar, and also that keyboard interactions in a toolbar are consistent with the [WAI-ARIA toolbar pattern](https://www.w3.org/TR/wai-aria-practices/#toolbar).
 
 ## Usage
 
 ```jsx
-import { ToolbarButton } from "@wordpress/components";
-import { edit } from "@wordpress/icons";
- 
-const MyToolbarButton = () => (
-    <MyToolbarButton
-        title="Edit"
-        icon={ edit }
-        onClick={ onEdit } />
-);
+import { Toolbar, ToolbarButton } from '@wordpress/components';
+import { edit } from '@wordpress/icons';
+
+function MyToolbar() {
+	return (
+		<Toolbar label="Options">
+			<ToolbarButton
+				icon={ edit }
+				label="Edit"
+				onClick={ () => alert( 'Editing' ) }
+			/>
+		</Toolbar>
+	);
+}
 ```
 
 ## Props
diff --git a/packages/components/src/toolbar-group/README.md b/packages/components/src/toolbar-group/README.md
new file mode 100644
index 0000000000000..0a757f5b40032
--- /dev/null
+++ b/packages/components/src/toolbar-group/README.md
@@ -0,0 +1,33 @@
+# ToolbarGroup
+
+A ToolbarGroup can be used to create subgroups of controls inside a [Toolbar](/packages/components/src/toolbar/README.md).
+
+## Usage
+
+```jsx
+import { Toolbar, ToolbarGroup, ToolbarButton } from '@wordpress/components';
+import { paragraph, formatBold, formatItalic, link } from '@wordpress/icons';
+
+function MyToolbar() {
+	return (
+		<Toolbar label="Options">
+			<ToolbarGroup>
+				<ToolbarButton icon={ paragraph } label="Paragraph" />
+			</ToolbarGroup>
+			<ToolbarGroup>
+				<ToolbarButton icon={ formatBold } label="Bold" />
+				<ToolbarButton icon={ formatItalic } label="Italic" />
+				<ToolbarButton icon={ link } label="Link" />
+			</ToolbarGroup>
+		</Toolbar>
+	);
+}
+```
+
+### Props
+
+ToolbarGroup will pass all HTML props to the underlying element.
+
+## Related components
+
+* ToolbarGroup may contain [ToolbarButton](/packages/components/src/toolbar-button/README.md) and [ToolbarItem](/packages/components/src/toolbar-Item/README.md) as children.
diff --git a/packages/components/src/toolbar-item/README.md b/packages/components/src/toolbar-item/README.md
new file mode 100644
index 0000000000000..ec7ff0fe4a4ca
--- /dev/null
+++ b/packages/components/src/toolbar-item/README.md
@@ -0,0 +1,53 @@
+# ToolbarItem
+
+A ToolbarItem is a generic headless component that can be used to make any custom component a [Toolbar](/packages/components/src/toolbar/README.md) item.
+
+## Usage
+
+### `as` prop
+
+You can use the `as` prop with a custom component or any HTML element.
+
+```jsx
+import { Toolbar, ToolbarItem, Button } from '@wordpress/components';
+
+function MyToolbar() {
+	return (
+		<Toolbar label="Options">
+			<ToolbarItem as={ Button }>I am a toolbar button</ToolbarItem>
+			<ToolbarItem as="button">I am another toolbar button</ToolbarItem>
+		</Toolbar>
+	);
+}
+```
+
+### render prop
+
+You can pass children as function to get the ToolbarItem props and pass them to another component.
+
+```jsx
+import { Toolbar, ToolbarItem, DropdownMenu } from '@wordpress/components';
+import { table } from '@wordpress/icons';
+
+function MyToolbar() {
+	return (
+		<Toolbar label="Options">
+			<ToolbarItem>
+				{ ( toolbarItemHTMLProps ) => (
+					<DropdownMenu
+						icon={ table }
+						toggleProps={ toolbarItemHTMLProps }
+						label={ 'Edit table' }
+						controls={ [] }
+					/>
+				) }
+			</ToolbarItem>
+		</Toolbar>
+	);
+}
+```
+
+## Related components
+
+* ToolbarItem should be used inside [Toolbar](/packages/components/src/toolbar/README.md) or [ToolbarGroup](/packages/components/src/toolbar-group/README.md).
+* If you want a simple toolbar button, consider using [ToolbarButton](/packages/components/src/toolbar-button/README.md) instead.
diff --git a/packages/components/src/toolbar/README.md b/packages/components/src/toolbar/README.md
index b38427f480e85..65e523766feb3 100644
--- a/packages/components/src/toolbar/README.md
+++ b/packages/components/src/toolbar/README.md
@@ -8,6 +8,7 @@ Toolbar can be used to group related options. To emphasize groups of related ico
 
 1. [Design guidelines](#design-guidelines)
 2. [Development guidelines](#development-guidelines)
+3. [Related components](#related-components)
 
 ## Design guidelines
 
@@ -26,11 +27,13 @@ Toolbars should:
 ### States
 
 #### Active and available toolbars
+
 A toolbar’s state makes it clear which icon button is active. Hover and focus states express the available selection options for icon buttons in a toolbar.
 
 ![Toolbar component](https://wordpress.org/gutenberg/files/2019/01/s_96EC471FE9C9D91A996770229947AAB54A03351BDE98F444FD3C1BF0CED365EA_1541784539545_ButtonGroup.png)
 
 #### Disabled toolbars
+
 Toolbars that cannot be selected can either be given a disabled state, or be hidden.
 
 ## Development guidelines
@@ -38,23 +41,31 @@ Toolbars that cannot be selected can either be given a disabled state, or be hid
 ### Usage
 
 ```jsx
-import { Toolbar } from '@wordpress/components';
-import { withState } from '@wordpress/compose';
-
-const MyToolbar = withState( {
-	activeControl: 'up',
-} )( ( { activeControl, setState } ) => { 
-	function createThumbsControl( thumbs ) {
-		return {
-			icon: `thumbs-${ thumbs }`,
-			title: `Thumbs ${ thumbs }`,
-			isActive: activeControl === thumbs,
-			onClick: () => setState( { activeControl: thumbs } ),
-		};
-	}
-	
+import { Toolbar, ToolbarButton } from '@wordpress/components';
+import { formatBold, formatItalic, link } from '@wordpress/icons';
+
+function MyToolbar() {
 	return (
-		<Toolbar controls={ [ 'up', 'down' ].map( createThumbsControl ) } />
+		<Toolbar label="Options">
+			<ToolbarButton icon={ formatBold } label="Bold" />
+			<ToolbarButton icon={ formatItalic } label="Italic" />
+			<ToolbarButton icon={ link } label="Link" />
+		</Toolbar>
 	);
-} );
+}
 ```
+
+### Props
+
+Toolbar will pass all HTML props to the underlying element. Additionally, you can pass the custom props specified below.
+
+#### label
+
+An accessible label for the toolbar.
+
+- Type: `String`
+- Required: Yes
+
+## Related components
+
+* Toolbar may contain [ToolbarGroup](/packages/components/src/toolbar-group/README.md), [ToolbarButton](/packages/components/src/toolbar-button/README.md) and [ToolbarItem](/packages/components/src/toolbar-Item/README.md) as children.
\ No newline at end of file

From 5931985e4616d152177d057bcbc3066726f1937d Mon Sep 17 00:00:00 2001
From: Haz <hazdiego@gmail.com>
Date: Thu, 6 Aug 2020 17:53:34 -0300
Subject: [PATCH 17/22] Add links to depreaction notices and warnings

---
 packages/components/src/toolbar-item/index.js | 3 ++-
 packages/components/src/toolbar/index.js      | 2 ++
 2 files changed, 4 insertions(+), 1 deletion(-)

diff --git a/packages/components/src/toolbar-item/index.js b/packages/components/src/toolbar-item/index.js
index 72a7a3b1687ef..7f938d55f8558 100644
--- a/packages/components/src/toolbar-item/index.js
+++ b/packages/components/src/toolbar-item/index.js
@@ -19,7 +19,8 @@ function ToolbarItem( { children, as: Component, ...props }, ref ) {
 
 	if ( typeof children !== 'function' && ! Component ) {
 		warning(
-			'`ToolbarItem` is a generic headless component. You must pass either a `children` prop as a function or an `as` prop as a component.'
+			'`ToolbarItem` is a generic headless component. You must pass either a `children` prop as a function or an `as` prop as a component. ' +
+				'See https://developer.wordpress.org/block-editor/components/toolbar-item/'
 		);
 		return null;
 	}
diff --git a/packages/components/src/toolbar/index.js b/packages/components/src/toolbar/index.js
index 30830b9b152d8..b94886bd9ce74 100644
--- a/packages/components/src/toolbar/index.js
+++ b/packages/components/src/toolbar/index.js
@@ -29,6 +29,8 @@ function Toolbar( { className, label, ...props }, ref ) {
 	if ( ! label ) {
 		deprecated( 'Using Toolbar without label prop', {
 			alternative: 'ToolbarGroup component',
+			link:
+				'https://developer.wordpress.org/block-editor/components/toolbar/',
 		} );
 		return <ToolbarGroup { ...props } className={ className } />;
 	}

From cf8483d00860890668b68f0661fda169bc61ac02 Mon Sep 17 00:00:00 2001
From: Haz <hazdiego@gmail.com>
Date: Thu, 6 Aug 2020 18:14:16 -0300
Subject: [PATCH 18/22] Update ToolbarButton docs

---
 .../components/src/toolbar-button/README.md   | 26 ++++++++++++++++++-
 1 file changed, 25 insertions(+), 1 deletion(-)

diff --git a/packages/components/src/toolbar-button/README.md b/packages/components/src/toolbar-button/README.md
index 842982936accd..e1816852b85e2 100644
--- a/packages/components/src/toolbar-button/README.md
+++ b/packages/components/src/toolbar-button/README.md
@@ -1,11 +1,13 @@
 # ToolbarButton
 
-A ToolbarButton can be used to add actions to your block control, usually inside a [Toolbar](/packages/components/src/toolbar/README.md) or [ToolbarGroup](/packages/components/src/toolbar-group/README.md).
+ToolbarButton can be used to add actions to a toolbar, usually inside a [Toolbar](/packages/components/src/toolbar/README.md) or [ToolbarGroup](/packages/components/src/toolbar-group/README.md) when used to create general interfaces. If you're using it to add controls to your custom block, you should consider using [BlockControls](/docs/designers-developers/developers/tutorials/block-tutorial/block-controls-toolbar-and-sidebar.md).
 
 It has similar features to the [Button](/packages/components/src/button/README.md) component. Using `ToolbarButton` will ensure the correct styling for a button in a toolbar, and also that keyboard interactions in a toolbar are consistent with the [WAI-ARIA toolbar pattern](https://www.w3.org/TR/wai-aria-practices/#toolbar).
 
 ## Usage
 
+To create general interfaces, you'll want to render ToolbarButton in a [Toolbar](/packages/components/src/toolbar/README.md) component.
+
 ```jsx
 import { Toolbar, ToolbarButton } from '@wordpress/components';
 import { edit } from '@wordpress/icons';
@@ -23,6 +25,28 @@ function MyToolbar() {
 }
 ```
 
+If you're working on a custom block and you want to add controls to the block toolbar, you should use [BlockControls](/docs/designers-developers/developers/tutorials/block-tutorial/block-controls-toolbar-and-sidebar.md) instead. Optinally wrapping it with [ToolbarGroup](/packages/components/src/toolbar-group/README.md).
+
+```jsx
+import { BlockControls } from '@wordpress/block-editor';
+import { ToolbarGroup, ToolbarButton } from '@wordpress/components';
+import { edit } from '@wordpress/icons';
+
+function Edit() {
+	return (
+		<BlockControls>
+			<ToolbarGroup>
+				<ToolbarButton
+					icon={ edit }
+					label="Edit"
+					onClick={ () => alert( 'Editing' ) }
+				/>
+			</ToolbarGroup>
+		</BlockControls>
+	);
+}
+```
+
 ## Props
 
 This component accepts [the same API of the Button](/packages/components/src/button/README.md#props) component.

From df663c69b03ac6fac07a1318299a3046d78bcd7a Mon Sep 17 00:00:00 2001
From: Haz <hazdiego@gmail.com>
Date: Mon, 10 Aug 2020 14:58:57 -0300
Subject: [PATCH 19/22] Improve documentation around BlockControls usage

---
 .../src/components/navigable-toolbar/index.js |  2 ++
 .../components/src/toolbar-button/README.md   |  2 ++
 .../components/src/toolbar-item/README.md     | 22 ++++++++++++++++++-
 3 files changed, 25 insertions(+), 1 deletion(-)

diff --git a/packages/block-editor/src/components/navigable-toolbar/index.js b/packages/block-editor/src/components/navigable-toolbar/index.js
index c051f6fe65f79..83e89f355587c 100644
--- a/packages/block-editor/src/components/navigable-toolbar/index.js
+++ b/packages/block-editor/src/components/navigable-toolbar/index.js
@@ -64,6 +64,8 @@ function useIsAccessibleToolbar( ref ) {
 		if ( ! onlyToolbarItem ) {
 			deprecated( 'Using custom components as toolbar controls', {
 				alternative: 'ToolbarItem or ToolbarButton components',
+				link:
+					'https://developer.wordpress.org/block-editor/components/toolbar-button/',
 			} );
 		}
 		setIsAccessibleToolbar( onlyToolbarItem );
diff --git a/packages/components/src/toolbar-button/README.md b/packages/components/src/toolbar-button/README.md
index e1816852b85e2..5d7f8f1fb1955 100644
--- a/packages/components/src/toolbar-button/README.md
+++ b/packages/components/src/toolbar-button/README.md
@@ -25,6 +25,8 @@ function MyToolbar() {
 }
 ```
 
+### Inside BlockControls
+
 If you're working on a custom block and you want to add controls to the block toolbar, you should use [BlockControls](/docs/designers-developers/developers/tutorials/block-tutorial/block-controls-toolbar-and-sidebar.md) instead. Optinally wrapping it with [ToolbarGroup](/packages/components/src/toolbar-group/README.md).
 
 ```jsx
diff --git a/packages/components/src/toolbar-item/README.md b/packages/components/src/toolbar-item/README.md
index ec7ff0fe4a4ca..5bc6bb692b7b0 100644
--- a/packages/components/src/toolbar-item/README.md
+++ b/packages/components/src/toolbar-item/README.md
@@ -1,6 +1,6 @@
 # ToolbarItem
 
-A ToolbarItem is a generic headless component that can be used to make any custom component a [Toolbar](/packages/components/src/toolbar/README.md) item.
+A ToolbarItem is a generic headless component that can be used to make any custom component a [Toolbar](/packages/components/src/toolbar/README.md) item. It should be inside a [Toolbar](/packages/components/src/toolbar/README.md) or [ToolbarGroup](/packages/components/src/toolbar-group/README.md) when used to create general interfaces. If you're using it to add controls to your custom block, you should consider using [BlockControls](/docs/designers-developers/developers/tutorials/block-tutorial/block-controls-toolbar-and-sidebar.md).
 
 ## Usage
 
@@ -47,6 +47,26 @@ function MyToolbar() {
 }
 ```
 
+### Inside BlockControls
+
+If you're working on a custom block and you want to add controls to the block toolbar, you should use [BlockControls](/docs/designers-developers/developers/tutorials/block-tutorial/block-controls-toolbar-and-sidebar.md) instead. Optinally wrapping it with [ToolbarGroup](/packages/components/src/toolbar-group/README.md).
+
+```jsx
+import { BlockControls } from '@wordpress/block-editor';
+import { Toolbar, ToolbarGroup, ToolbarItem, Button } from '@wordpress/components';
+import { edit } from '@wordpress/icons';
+
+function Edit() {
+	return (
+		<BlockControls>
+			<ToolbarGroup>
+				<ToolbarItem as={ Button }>I am a toolbar button</ToolbarItem>
+			</ToolbarGroup>
+		</BlockControls>
+	);
+}
+```
+
 ## Related components
 
 * ToolbarItem should be used inside [Toolbar](/packages/components/src/toolbar/README.md) or [ToolbarGroup](/packages/components/src/toolbar-group/README.md).

From dd7ead5523cbdb14257763a80ab48b2bf6c5e2ca Mon Sep 17 00:00:00 2001
From: Haz <hazdiego@gmail.com>
Date: Mon, 10 Aug 2020 15:05:45 -0300
Subject: [PATCH 20/22] Update deprecation warning link on Navigable Toolbar

---
 packages/block-editor/src/components/navigable-toolbar/index.js | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/packages/block-editor/src/components/navigable-toolbar/index.js b/packages/block-editor/src/components/navigable-toolbar/index.js
index 83e89f355587c..931932b7ab6da 100644
--- a/packages/block-editor/src/components/navigable-toolbar/index.js
+++ b/packages/block-editor/src/components/navigable-toolbar/index.js
@@ -65,7 +65,7 @@ function useIsAccessibleToolbar( ref ) {
 			deprecated( 'Using custom components as toolbar controls', {
 				alternative: 'ToolbarItem or ToolbarButton components',
 				link:
-					'https://developer.wordpress.org/block-editor/components/toolbar-button/',
+					'https://developer.wordpress.org/block-editor/components/toolbar-button/#inside-blockcontrols',
 			} );
 		}
 		setIsAccessibleToolbar( onlyToolbarItem );

From e177fb189ee862094b21d7ba98ea1b97ec3763cb Mon Sep 17 00:00:00 2001
From: Haz <hazdiego@gmail.com>
Date: Mon, 10 Aug 2020 15:12:16 -0300
Subject: [PATCH 21/22] Update ToolbarItem README

---
 packages/components/src/toolbar-item/README.md | 1 -
 1 file changed, 1 deletion(-)

diff --git a/packages/components/src/toolbar-item/README.md b/packages/components/src/toolbar-item/README.md
index 5bc6bb692b7b0..b140b30ee766b 100644
--- a/packages/components/src/toolbar-item/README.md
+++ b/packages/components/src/toolbar-item/README.md
@@ -54,7 +54,6 @@ If you're working on a custom block and you want to add controls to the block to
 ```jsx
 import { BlockControls } from '@wordpress/block-editor';
 import { Toolbar, ToolbarGroup, ToolbarItem, Button } from '@wordpress/components';
-import { edit } from '@wordpress/icons';
 
 function Edit() {
 	return (

From c0acb8262ab9cd6990949bce0b2262d3b2d41e31 Mon Sep 17 00:00:00 2001
From: Haz <hazdiego@gmail.com>
Date: Mon, 10 Aug 2020 15:23:23 -0300
Subject: [PATCH 22/22] Update ToolbarItem README

---
 packages/components/src/toolbar-item/README.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/packages/components/src/toolbar-item/README.md b/packages/components/src/toolbar-item/README.md
index b140b30ee766b..db6d38da04168 100644
--- a/packages/components/src/toolbar-item/README.md
+++ b/packages/components/src/toolbar-item/README.md
@@ -53,7 +53,7 @@ If you're working on a custom block and you want to add controls to the block to
 
 ```jsx
 import { BlockControls } from '@wordpress/block-editor';
-import { Toolbar, ToolbarGroup, ToolbarItem, Button } from '@wordpress/components';
+import { ToolbarGroup, ToolbarItem, Button } from '@wordpress/components';
 
 function Edit() {
 	return (