Make accessible toolbar stable and deprecate old usage

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 );

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

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).