docs(charts): Update pie chart size/dimension docs

The size prop no longer controls container dimensions — it
constrains the maximum pie diameter. Width and height now
control the container. Updated JSDoc, API reference, stories
argTypes, and the docs MDX to reflect the new behavior and
remove the broken Responsiveness story reference.

Co-authored-by: Cursor <cursoragent@cursor.com>

Author: adamwoodnz

projects/js-packages/charts/src/charts/pie-chart/stories/index.api.mdx

@@ -13,7 +13,10 @@ Main component for rendering pie and donut charts.
 | Prop | Type | Default | Description |
 | ---- | ---- | ------- | ----------- |
 | `data` | `DataPointPercentage[]` | - | **Required.** Array of data objects with label, value, and percentage |
-| `size` | `number` | - | Diameter of the chart in pixels (omit for responsive behavior) |
+| `width` | `number` | - | Width of the chart container in pixels. When omitted, fills parent width |
+| `height` | `number` | - | Height of the chart container in pixels. When omitted, fills parent height |
+| `size` | `number` | - | Maximum diameter of the pie in pixels. The pie shrinks if the container is smaller. When omitted, fills available space |
+| `gap` | `GapSize` | `'md'` | Gap between chart elements (SVG, legend, children). Uses WordPress design system tokens |
 | `thickness` | `number` | `1` | Thickness of the pie chart segments (0-1). Values less than 1 create donut charts |
 | `padding` | `number` | `20` | Padding around the chart in pixels |
 | `gapScale` | `number` | `0` | Scale of gaps between segments (0-1) |

projects/js-packages/charts/src/charts/pie-chart/stories/index.docs.mdx

@@ -41,7 +41,6 @@ The simplest pie chart requires only a `data` prop with percentage-based data:
 <Source
 	language="jsx"
 	code={ `<PieChart
-		size={ 400 }
 		data={[
 			{ label: 'MacOS', value: 30000, valueDisplay: '30K', percentage: 23 },
 			{ label: 'Linux', value: 22000, valueDisplay: '22K', percentage: 17 },
@@ -53,16 +52,18 @@ The simplest pie chart requires only a `data` prop with percentage-based data:
 ### Required Props
 
 - **`data`**: Array of `DataPointPercentage` objects containing label, value, and percentage
-- **`size`**: Diameter of the chart in pixels (when not using responsive mode)
 
 ### Optional Props
 
+- **`size`**: Maximum diameter of the pie in pixels. The pie shrinks if the container is smaller. When omitted, the pie fills available space.
+- **`width`** / **`height`**: Explicit container dimensions in pixels. When omitted, the chart fills its parent.
 - **`padding`** (default: `20`): Padding around the chart in pixels
 - **`withTooltips`** (default: `false`): Enables interactive tooltips on hover
 - **`showLegend`** (default: `false`): Shows a legend for the chart data
 - **`thickness`** (default: `1`): Thickness of the pie chart segments (0-1). Values less than 1 create donut charts
 - **`gapScale`** (default: `0`): Scale of gaps between segments (0-1)
 - **`cornerScale`** (default: `0`): Scale of corner rounding for segments (0-1)
+- **`gap`** (default: `'md'`): Gap between chart elements (SVG, legend, children). Uses WordPress design system tokens.
 - **`children`**: Optional React node to render inside the chart center (useful for donut charts)
 
 For detailed prop information, compound components, and type definitions, see the [Pie Chart API Reference](./?path=/docs/js-packages-charts-library-charts-pie-chart-api-reference--docs).
@@ -80,24 +81,24 @@ The composition API allows you to add custom SVG and HTML elements to your chart
 <Source
 	language="jsx"
 	code={ `<PieChart data={ data } size={ 400 }>
-	{/* HTML elements rendered outside the SVG */}
-	<PieChart.HTML>
-		<h3>Chart Title</h3>
-	</PieChart.HTML>
-
-	{/* SVG elements rendered inside the chart */}
-	<PieChart.SVG>
-		<text x={ 0 } y={ 0 } textAnchor="middle">
-			Center Text
-		</text>
-	</PieChart.SVG>
-
-	{/* More HTML elements */}
-	<PieChart.HTML>
-		<PieChart.Legend position="bottom" />
-		<p>Additional information</p>
-	</PieChart.HTML>
-</PieChart>` }
+		{/* HTML elements rendered outside the SVG */}
+		<PieChart.HTML>
+			<h3>Chart Title</h3>
+		</PieChart.HTML>
+
+		{/* SVG elements rendered inside the chart */}
+		<PieChart.SVG>
+			<text x={ 0 } y={ 0 } textAnchor="middle">
+				Center Text
+			</text>
+		</PieChart.SVG>
+
+		{/* More HTML elements */}
+		<PieChart.HTML>
+			<PieChart.Legend position="bottom" />
+			<p>Additional information</p>
+		</PieChart.HTML>
+	</PieChart>` }
 />
 
 ### Benefits of Composition API
@@ -128,27 +129,31 @@ Enable interactive tooltips that display data information on hover:
 
 ### Responsive Behavior
 
-The Pie Chart component supports responsive sizing by omitting the `size` prop:
-
-<Canvas of={ PieChartStories.Responsiveness } />
+By default, charts **fill their parent container's dimensions**. The parent must have an explicit height:
 
 <Source
 	language="jsx"
-	code={ `// Responsive - fills parent container
-	<PieChart
-		data={ data }
-		maxWidth={ 600 }
-		aspectRatio={ 1 }
-	/>
+	code={ `// Fill parent container (default) - parent needs explicit height
+	<div style={{ width: '100%', height: '400px' }}>
+		<PieChart data={data} />
+	</div>
 
-    // Fixed size
-    <PieChart
-    	size={ 400 }
-    	data={ data }
-    />` }
+	// Fixed dimensions
+	<PieChart data={data} width={400} height={400} />` }
+/>
+
+Use the `size` prop to constrain the maximum pie diameter. The pie will shrink if the container is smaller, but won't grow beyond this value:
+
+<Canvas of={ PieChartStories.WithSize } />
 
+<Source
+	language="jsx"
+	code={ `// Constrained pie diameter (container still fills parent)
+<PieChart data={data} size={200} />` }
 />
 
+For more details on responsive behavior, see the [Responsive Design section](./?path=/docs/js-packages-charts-library-introduction--docs#responsive-design) in the introduction.
+
 ### Data Validation and Error Handling
 
 The component includes built-in data validation with helpful error states:

projects/js-packages/charts/src/charts/pie-chart/stories/index.stories.tsx

@@ -35,7 +35,8 @@ const meta: Meta< StoryArgs > = {
 				step: 10,
 				default: 400,
 			},
-			description: 'Diameter of the pie chart in pixels',
+			description:
+				'Maximum diameter of the pie in pixels. The pie shrinks if the container is smaller. When omitted, fills available space.',
 			table: { category: 'Dimensions' },
 		},
 		thickness: {
@@ -137,6 +138,14 @@ export const WithSize: Story = {
 	},
 };
 
+export const FixedDimensions: Story = {
+	args: {
+		...Default.args,
+		width: 300,
+		height: 300,
+	},
+};
+
 export const Animation: Story = {
 	args: {
 		...Default.args,

projects/js-packages/charts/src/types.ts

@@ -364,15 +364,17 @@ export type BaseChartProps< T = DataPoint | DataPointDate | LeaderboardEntry > =
 	 */
 	className?: string;
 	/**
-	 * Width of the chart in pixels
+	 * Width of the chart container in pixels. When omitted, the chart fills its parent's width.
 	 */
 	width?: number;
 	/**
-	 * Height of the chart in pixels
+	 * Height of the chart container in pixels. When omitted, the chart fills its parent's height.
 	 */
 	height?: number;
 	/**
-	 * Size of the chart in pixels for pie and donut charts
+	 * Maximum diameter of the pie in pixels (pie and donut charts only).
+	 * The pie will shrink if the container is smaller than this value.
+	 * When omitted, the pie fills the available space.
 	 */
 	size?: number;
 	/**