Button: Revise documentation

packages/components/src/button/docs-manifest.json

@@ -0,0 +1,5 @@
+{
+	"$schema": "../../schemas/docs-manifest.json",
+	"displayName": "Button",
+	"filePath": "./index.tsx"
+}

packages/components/src/button/stories/best-practices.mdx

@@ -0,0 +1,31 @@
+import { Meta } from '@storybook/blocks';
+
+<Meta title="Components/Actions/Button/Best Practices" />
+
+# Button
+
+## Usage
+Buttons indicate available actions and allow user interaction within the interface. As key elements in the WordPress UI, they appear in toolbars, modals, and forms. Default buttons support most actions, while primary buttons emphasize the main action in a view. Secondary buttons pair as secondary actions next to a primary action. 
+
+Each layout contains one prominently placed, high-emphasis button. If you need multiple buttons, use one primary button for the main action, secondary for the rest of the actions and tertiary sparingly when an action needs to not stand out at all.
+
+### Sizes
+
+- `'default'`: For normal text-label buttons, unless it is a toggle button.
+- `'compact'`: For toggle buttons, icon buttons, and buttons when used in context of either.
+- `'small'`: For icon buttons associated with more advanced or auxiliary features.
+
+## Best practices
+
+- Label buttons to show that a click or tap initiates an action.
+- Use established color conventions; for example, reserve red buttons for irreversible or dangerous actions.
+- Avoid crowding the screen with multiple calls to action, which confuses users.
+- Keep button locations consistent across the interface.
+
+## Content guidelines
+
+Buttons should be clear and predictable, showing users what will happen when clicked. Make labels reflect actions accurately to avoid confusion. 
+
+Start button text with a strong action verb and include a noun to specify the change, except for common actions like Save, Close, Cancel, or OK. 
+
+For other actions, use a `{verb}+{noun}` format for context. Keep button text brief and remove unnecessary words like "the," "an," or "a" for easy scanning.

packages/components/src/button/stories/index.story.tsx

@@ -65,30 +65,48 @@ Default.args = {
 	children: 'Code is poetry',
 };
 
+/**
+ * Primary buttons stand out with bold color fills, making them distinct
+ * from the background. Since they naturally draw attention, each layout should contain
+ * only one primary button to guide users toward the most important action.
+ */
 export const Primary = Template.bind( {} );
 Primary.args = {
 	...Default.args,
 	variant: 'primary',
 };
 
+/**
+ * Secondary buttons complement primary buttons. Use them for standard actions that may appear alongside a primary action.
+ */
 export const Secondary = Template.bind( {} );
 Secondary.args = {
 	...Default.args,
 	variant: 'secondary',
 };
 
+/**
+ * Tertiary buttons have minimal emphasis. Use them sparingly to subtly highlight an action.
+ */
 export const Tertiary = Template.bind( {} );
 Tertiary.args = {
 	...Default.args,
 	variant: 'tertiary',
 };
 
+/**
+ * Link buttons have low emphasis and blend into the page, making them suitable for supplementary actions,
+ * especially those involving navigation away from the current view.
+ */
 export const Link = Template.bind( {} );
 Link.args = {
 	...Default.args,
 	variant: 'link',
 };
 
+/**
+ * Use this variant for irreversible actions. Apply sparingly and only for actions with significant impact.
+ */
 export const IsDestructive = Template.bind( {} );
 IsDestructive.args = {
 	...Default.args,

packages/components/src/button/types.ts

@@ -111,11 +111,13 @@ type BaseButtonProps = {
 	tooltipPosition?: PopoverProps[ 'position' ];
 	/**
 	 * Specifies the button's style.
+	 *
 	 * The accepted values are:
-	 * 'primary' (the primary button styles)
-	 * 'secondary' (the default button styles)
-	 * 'tertiary' (the text-based button styles)
-	 * 'link' (the link button styles)
+	 *
+	 * 1. `'primary'` (the primary button styles)
+	 * 2. `'secondary'` (the default button styles)
+	 * 3. `'tertiary'` (the text-based button styles)
+	 * 4. `'link'` (the link button styles)
 	 */
 	variant?: 'primary' | 'secondary' | 'tertiary' | 'link';
 };

storybook/components/figma-embed/index.js

@@ -0,0 +1,47 @@
+/**
+ * Internal dependencies
+ */
+import './style.scss';
+
+// See https://www.figma.com/developers/embed#embed-a-figma-file
+const CONFIG = {
+	'embed-host': 'wordpress-storybook',
+	footer: false,
+	'page-selector': false,
+	'viewport-controls': true,
+};
+
+/**
+ * Embed Figma links in the Storybook.
+ *
+ * @param {Object} props
+ * @param {string} props.url   - Figma URL to embed.
+ * @param {string} props.title - Accessible title for the iframe.
+ */
+function FigmaEmbed( { url, title, ...props } ) {
+	const urlObj = new URL( url );
+
+	const queryParams = new URLSearchParams( urlObj.search );
+	Object.entries( CONFIG ).forEach( ( [ key, value ] ) => {
+		queryParams.set( key, value );
+	} );
+	urlObj.search = queryParams.toString();
+
+	urlObj.hostname = urlObj.hostname.replace(
+		'www.figma.com',
+		'embed.figma.com'
+	);
+
+	const normalizedUrl = urlObj.toString();
+
+	return (
+		<iframe
+			title={ title }
+			src={ normalizedUrl }
+			className="wp-storybook-figma-embed"
+			{ ...props }
+		/>
+	);
+}
+
+export default FigmaEmbed;

storybook/components/figma-embed/style.scss

@@ -0,0 +1,4 @@
+.wp-storybook-figma-embed {
+	width: 100%;
+	border: none;
+}

storybook/main.js

@@ -31,7 +31,8 @@ const stories = [
 	process.env.NODE_ENV !== 'test' && './stories/**/*.story.@(js|tsx)',
 	process.env.NODE_ENV !== 'test' && './stories/**/*.mdx',
 	'../packages/block-editor/src/**/stories/*.story.@(js|tsx|mdx)',
-	'../packages/components/src/**/stories/*.story.@(js|tsx|mdx)',
+	'../packages/components/src/**/stories/*.story.@(js|tsx)',
+	'../packages/components/src/**/stories/*.mdx',
 	'../packages/icons/src/**/stories/*.story.@(js|tsx|mdx)',
 	'../packages/edit-site/src/**/stories/*.story.@(js|tsx|mdx)',
 	'../packages/dataviews/src/**/stories/*.story.@(js|tsx|mdx)',