@wordpress/ui 0.4.0 → 0.5.0

package/src/badge/stories/choosing-intent.mdx

@@ -0,0 +1,112 @@
+import { Meta } from '@storybook/addon-docs/blocks';
+import { Badge } from '../index';
+import '@wordpress/theme/design-tokens.css';
+
+<Meta title="Design System/Components/Badge/Choosing intent" />
+
+# Choosing intent
+
+<div style={ { padding: '2rem', display: 'flex', justifyContent: 'center', gap: '0.5rem', flexWrap: 'wrap', border: '1px solid #e0e0e0', borderRadius: '0.5rem' } }>
+	<Badge intent="high">high</Badge>
+	<Badge intent="medium">medium</Badge>
+	<Badge intent="low">low</Badge>
+	<Badge intent="stable">stable</Badge>
+	<Badge intent="informational">informational</Badge>
+	<Badge intent="draft">draft</Badge>
+	<Badge intent="none">none</Badge>
+</div>
+
+It can be difficult to determine which badge intent to use because the component's properties are not tied to any specific product view. Those properties should be balanced against the requirements of the view in which the badge appears, all while keeping an eye on high-level consistency (global statuses that appear across multiple views).
+
+Here is a decision tree to help identify which badge to use.
+
+## 1. Ask first: should this draw the eye?
+
+If the user scans this screen, should their attention be drawn to this badge?
+
+-   If **no** → use `none` (or even just plain text; no badge), even if the state is positive or "stable".
+-   If **yes** → pick an intent based on how important the action or awareness is.
+
+## 2. High / Medium / Low = action priority
+
+Use when there's something for the user to act on.
+
+### `high` – Critical / top priority
+
+* Needs attention as soon as possible
+* _E.g. "Payment declined", "Security issue"_
+
+<Badge intent="high">Payment declined</Badge> <Badge intent="high">Security issue</Badge>
+
+### `medium` – Important / blocks progress
+
+* Blocks a key task, should be handled soon
+* _E.g. "Approval required", "Review needed"_
+
+<Badge intent="medium">Approval required</Badge> <Badge intent="medium">Review needed</Badge>
+
+### `low` – Worth noticing / non‑urgent
+
+* Good to be aware of; action may be optional or later
+* _E.g. "Pending", "Queued", "Minor issues", "Optional setup"_
+
+<Badge intent="low">Pending</Badge> <Badge intent="low">Queued</Badge>
+
+## 3. Informational / draft = special non-final states
+
+### `informational` – Notable, no action / fix needed
+
+* Context only; no clear action
+* _E.g. "Scheduled", "Beta", "Internal only"_
+
+<Badge intent="informational">Scheduled</Badge> <Badge intent="informational">Beta</Badge>
+
+### `draft` – Not final / work in progress
+
+* _E.g. "Draft", "Unpublished", "Work in progress"_
+
+<Badge intent="draft">Draft</Badge> <Badge intent="draft">Unpublished</Badge>
+
+## 4. Stable / none = normal states
+
+### `stable` – Positive / "healthy" state
+
+* Use when confirming success or "all good" is important in that view
+* _E.g. "Healthy", "Active", "Live"_
+
+<Badge intent="stable">Healthy</Badge> <Badge intent="stable">Active</Badge>
+
+### `none` – Default for normal / background states
+
+* Especially in dense lists where too much color creates visual noise
+* _E.g. "Inactive", "Expired"_
+
+<Badge intent="none">Inactive</Badge> <Badge intent="none">Expired</Badge>
+
+## Examples
+
+### Comment status:
+
+-   "Approved" → `none`: <Badge intent="none">Approved</Badge>
+-   "Approval required" → `medium`: <Badge intent="medium">Approval required</Badge>
+
+### Page status:
+
+-   "Published" → `none`: <Badge intent="none">Published</Badge>
+-   "Pending" → `low`: <Badge intent="low">Pending</Badge>
+-   "Draft" → `draft`: <Badge intent="draft">Draft</Badge>
+-   "Scheduled" → `informational`: <Badge intent="informational">Scheduled</Badge>
+-   "Private" → `informational`: <Badge intent="informational">Private</Badge>
+
+### Plugin status:
+
+-   "Active" → `stable`: <Badge intent="stable">Active</Badge>
+-   "Inactive" → `none`: <Badge intent="none">Inactive</Badge>
+
+## 5. When in doubt…
+
+Use the least attention‑grabbing intent that still:
+
+-   Makes it clear what needs attention,
+-   Marks what isn't final, or
+-   Confirms a key success state in that context.

package/src/badge/stories/index.story.tsx

@@ -0,0 +1,120 @@
+import type { Meta, StoryObj } from '@storybook/react-vite';
+import { Fragment } from '@wordpress/element';
+import { Badge } from '../index';
+
+const meta: Meta< typeof Badge > = {
+	title: 'Design System/Components/Badge',
+	component: Badge,
+};
+export default meta;
+
+type Story = StoryObj< typeof Badge >;
+
+export const Default: Story = {
+	args: {
+		children: 'Badge',
+	},
+};
+
+export const High: Story = {
+	...Default,
+	args: {
+		...Default.args,
+		intent: 'high',
+	},
+};
+
+export const Medium: Story = {
+	...Default,
+	args: {
+		...Default.args,
+		intent: 'medium',
+	},
+};
+
+export const Low: Story = {
+	...Default,
+	args: {
+		...Default.args,
+		intent: 'low',
+	},
+};
+
+export const Stable: Story = {
+	...Default,
+	args: {
+		...Default.args,
+		intent: 'stable',
+	},
+};
+
+export const Informational: Story = {
+	...Default,
+	args: {
+		...Default.args,
+		intent: 'informational',
+	},
+};
+
+export const Draft: Story = {
+	...Default,
+	args: {
+		...Default.args,
+		intent: 'draft',
+	},
+};
+
+export const None: Story = {
+	...Default,
+	args: {
+		...Default.args,
+		intent: 'none',
+	},
+};
+
+export const AllIntents: Story = {
+	...Default,
+	render: ( args ) => (
+		<div
+			style={ {
+				display: 'grid',
+				gridTemplateColumns: 'max-content min-content',
+				gap: '1rem',
+				color: 'var(--wpds-color-fg-content-neutral)',
+			} }
+		>
+			{ (
+				[
+					'high',
+					'medium',
+					'low',
+					'stable',
+					'informational',
+					'draft',
+					'none',
+				] as const
+			 ).map( ( intent ) => (
+				<Fragment key={ intent }>
+					<div
+						style={ {
+							paddingInlineEnd: '1rem',
+							display: 'flex',
+							alignItems: 'center',
+						} }
+					>
+						{ intent }
+					</div>
+					<div
+						style={ {
+							padding: '0.5rem 1rem',
+							display: 'flex',
+							alignItems: 'center',
+						} }
+					>
+						<Badge { ...args } intent={ intent } />
+					</div>
+				</Fragment>
+			) ) }
+		</div>
+	),
+};

package/src/badge/types.ts

@@ -0,0 +1,22 @@
+import { type ComponentProps } from '../utils/types';
+
+export interface BadgeProps extends ComponentProps< 'span' > {
+	/**
+	 * The text to display in the badge.
+	 */
+	children: string;
+
+	/**
+	 * The semantic intent of the badge, communicating its meaning through color.
+	 *
+	 * @default "none"
+	 */
+	intent?:
+		| 'high'
+		| 'medium'
+		| 'low'
+		| 'stable'
+		| 'informational'
+		| 'draft'
+		| 'none';
+}

package/src/box/box.tsx

@@ -1,18 +1,9 @@
-/**
- * WordPress dependencies
- */
+import { useRender, mergeProps } from '@base-ui/react';
 import { forwardRef } from '@wordpress/element';
-
-/**
- * Internal dependencies
- */
 import { type BoxProps } from './types';
-import { renderElement } from '../utils/element';
 
 /**
  * Default render function that renders a div element with the given props.
- *
- * @param props The props to apply to the HTML element.
  */
 const DEFAULT_RENDER = ( props: React.ComponentPropsWithoutRef< 'div' > ) => (
 	<div { ...props } />
@@ -20,30 +11,25 @@ const DEFAULT_RENDER = ( props: React.ComponentPropsWithoutRef< 'div' > ) => (
 
 /**
  * Capitalizes the first character of a string.
- *
- * @param str The string to capitalize.
- * @return The capitalized string.
  */
 const capitalize = ( str: string ): string =>
 	str.charAt( 0 ).toUpperCase() + str.slice( 1 );
 
 /**
- * Converts a size value to a CSS design token property reference (with
- * fallback) or a calculated value based on the base unit.
+ * Converts a size token name to a CSS design token property reference (with
+ * fallback).
  *
  * @param property The CSS property name.
  * @param target   The design system token target.
- * @param value    The size value, either a number (multiplier of base unit) or a string (token name).
+ * @param value    The size token name.
  * @return A CSS value string with variable references.
  */
 const getSpacingValue = (
 	property: string,
 	target: string,
-	value: number | string
+	value: string
 ): string =>
-	typeof value === 'number'
-		? `calc(var(--wpds-dimension-base) * ${ value })`
-		: `var(--wpds-dimension-${ property }-${ target }-${ value }, var(--wpds-dimension-${ property }-surface-${ value }))`;
+	`var(--wpds-dimension-${ property }-${ target }-${ value }, var(--wpds-dimension-${ property }-surface-${ value }))`;
 
 /**
  * Generates CSS styles for properties with optionally directional values,
@@ -92,7 +78,7 @@ export const Box = forwardRef< HTMLDivElement, BoxProps >( function Box(
 	},
 	ref
 ) {
-	const style: React.CSSProperties = { ...props.style };
+	const style: React.CSSProperties = {};
 
 	if ( backgroundColor ) {
 		style.backgroundColor = `var(--wpds-color-bg-${ target }-${ backgroundColor }, var(--wpds-color-bg-surface-${ backgroundColor }))`;
@@ -122,9 +108,11 @@ export const Box = forwardRef< HTMLDivElement, BoxProps >( function Box(
 		style.borderColor = `var(--wpds-color-stroke-${ target }-${ borderColor }, var(--wpds-color-stroke-surface-${ borderColor }))`;
 	}
 
-	return renderElement< 'div' >( {
+	const element = useRender( {
 		render,
 		ref,
-		props: { ...props, style },
+		props: mergeProps< 'div' >( props, { style } ),
 	} );
+
+	return element;
 } );

package/src/box/stories/index.story.tsx

@@ -1,22 +1,10 @@
-/**
- * External dependencies
- */
-import { type Meta, type StoryObj } from '@storybook/react';
-
-/**
- * WordPress dependencies
- */
-import '@wordpress/theme/design-tokens.css';
-
-/**
- * Internal dependencies
- */
+import { type Meta, type StoryObj } from '@storybook/react-vite';
+import { type PaddingSize } from '@wordpress/theme';
 import { Box } from '../box';
 
 const meta: Meta< typeof Box > = {
 	title: 'Design System/Components/Box',
 	component: Box,
-	tags: [ 'status-experimental' ],
 };
 export default meta;
 
@@ -35,7 +23,7 @@ export const Default: Story = {
 	argTypes: {
 		padding: {
 			control: 'select',
-			options: [ '2xs', 'xs', 'sm', 'md', 'lg', 1, 2, 3, 4 ],
+			options: [ '2xs', 'xs', 'sm', 'md', 'lg' ] satisfies PaddingSize[],
 		},
 	},
 };

package/src/box/types.ts

@@ -1,57 +1,14 @@
-/**
- * Internal dependencies
- */
+import {
+	type PaddingSize,
+	type BorderRadiusSize,
+	type BorderWidthSize,
+	type Target,
+	type SurfaceBackgroundColor,
+	type ContentForegroundColor,
+	type SurfaceStrokeColor,
+} from '@wordpress/theme';
 import { type ComponentProps } from '../utils/types';
 
-type SizeToken = '2xs' | 'xs' | 'sm' | 'md' | 'lg';
-
-type Size = number | SizeToken;
-
-type BackgroundColor =
-	| 'neutral'
-	| 'neutral-strong'
-	| 'neutral-weak'
-	| 'brand'
-	| 'success'
-	| 'success-weak'
-	| 'info'
-	| 'info-weak'
-	| 'warning'
-	| 'warning-weak'
-	| 'caution'
-	| 'caution-weak'
-	| 'error'
-	| 'error-weak';
-
-type ForegroundColor =
-	| 'neutral'
-	| 'neutral-weak'
-	| 'success'
-	| 'success-weak'
-	| 'info'
-	| 'info-weak'
-	| 'warning'
-	| 'warning-weak'
-	| 'caution'
-	| 'caution-weak'
-	| 'error'
-	| 'error-weak';
-
-type StrokeColor =
-	| 'brand'
-	| 'brand-strong'
-	| 'error'
-	| 'error-strong'
-	| 'info'
-	| 'info-strong'
-	| 'neutral'
-	| 'neutral-strong'
-	| 'neutral-weak'
-	| 'success'
-	| 'success-strong'
-	| 'warning'
-	| 'warning-strong';
-
 type DimensionVariant< T > = {
 	block?: T;
 	blockStart?: T;
@@ -65,37 +22,37 @@ export interface BoxProps extends ComponentProps< 'div' > {
 	/**
 	 * The target rendering element design token grouping to use for the box.
 	 */
-	target?: string;
+	target?: Target;
 
 	/**
 	 * The surface background design token for box background color.
 	 */
-	backgroundColor?: BackgroundColor;
+	backgroundColor?: SurfaceBackgroundColor;
 
 	/**
 	 * The surface foreground design token for box text color.
 	 */
-	color?: ForegroundColor;
+	color?: ContentForegroundColor;
 
 	/**
 	 * The surface spacing design token or base unit multiplier for box padding.
 	 */
-	padding?: Size | DimensionVariant< Size >;
+	padding?: PaddingSize | DimensionVariant< PaddingSize >;
 
 	/**
 	 * The surface border radius design token.
 	 */
-	borderRadius?: Exclude< SizeToken, '2xs' >;
+	borderRadius?: BorderRadiusSize;
 
 	/**
 	 * The surface border width design token.
 	 */
-	borderWidth?: Exclude< SizeToken, '2xs' >;
+	borderWidth?: BorderWidthSize;
 
 	/**
 	 * The surface border stroke color design token.
 	 */
-	borderColor?: StrokeColor;
+	borderColor?: SurfaceStrokeColor;
 
 	/**
 	 * The content to be rendered inside the component.

package/src/button/button.tsx

@@ -0,0 +1,57 @@
+import { Button as _Button } from '@base-ui/react/button';
+import clsx from 'clsx';
+import { speak } from '@wordpress/a11y';
+import { forwardRef, useEffect } from '@wordpress/element';
+import { __ } from '@wordpress/i18n';
+import { type ButtonProps } from './types';
+import styles from './style.module.css';
+import resetStyles from '../utils/css/resets.module.css';
+import focusStyles from '../utils/css/focus.module.css';
+
+export const Button = forwardRef< HTMLButtonElement, ButtonProps >(
+	function Button(
+		{
+			tone = 'brand',
+			variant = 'solid',
+			size = 'default',
+			className,
+			focusableWhenDisabled = true,
+			disabled,
+			loading,
+			loadingAnnouncement = __( 'Loading' ),
+			children,
+			...props
+		},
+		ref
+	) {
+		const mergedClassName = clsx(
+			resetStyles[ 'box-sizing' ],
+			focusStyles[ 'outset-ring--focus-except-active' ],
+			variant !== 'unstyled' && styles.button,
+			styles[ `is-${ tone }` ],
+			styles[ `is-${ variant }` ],
+			styles[ `is-${ size }` ],
+			loading && styles[ 'is-loading' ],
+			className
+		);
+
+		// Announce loading state to assistive technology
+		useEffect( () => {
+			if ( loading && loadingAnnouncement ) {
+				speak( loadingAnnouncement );
+			}
+		}, [ loading, loadingAnnouncement ] );
+
+		return (
+			<_Button
+				ref={ ref }
+				className={ mergedClassName }
+				focusableWhenDisabled={ focusableWhenDisabled }
+				disabled={ disabled ?? loading }
+				{ ...props }
+			>
+				{ children }
+			</_Button>
+		);
+	}
+);

package/src/button/icon.tsx

@@ -0,0 +1,24 @@
+import { forwardRef } from '@wordpress/element';
+import { type IconProps } from '../icon/types';
+import { Icon } from '../icon';
+
+interface ButtonIconProps extends IconProps {
+	/**
+	 * The icon to display, from the `@wordpress/icons` package.
+	 */
+	icon: IconProps[ 'icon' ];
+}
+
+export const ButtonIcon = forwardRef< SVGSVGElement, ButtonIconProps >(
+	function ButtonIcon( { icon, ...props }, ref ) {
+		return (
+			<Icon
+				ref={ ref }
+				icon={ icon }
+				viewBox="4 4 16 16"
+				size={ 16 }
+				{ ...props }
+			/>
+		);
+	}
+);

package/src/button/index.ts

@@ -0,0 +1,16 @@
+import { Button as ButtonButton } from './button';
+import { ButtonIcon } from './icon';
+
+/**
+ * A versatile button component with multiple variants, tones, and sizes.
+ * Built on design tokens for consistent theming and accessibility.
+ */
+export const Button = Object.assign( ButtonButton, {
+	/**
+	 * An icon component specifically designed to work well when rendered inside
+	 * a `Button` component.
+	 */
+	Icon: ButtonIcon,
+} ) as typeof ButtonButton & {
+	Icon: typeof ButtonIcon;
+};