UI Card: full bleed as header hero image & content cover

packages/ui/CHANGELOG.md

@@ -2,6 +2,12 @@
 
 ## Unreleased
 
+### New Features
+
+-   `Card`: `Card.FullBleed` now supports edge-bumping in additional positions ([#77856](https://github.com/WordPress/gutenberg/pull/77856)):
+    -   As the **first child of `Card.Header`**, it extends flush to the card's top and side edges — ideal for hero images. Inter-sibling spacing is consumer-managed: compose `Card.Header` with `Stack` via the `render` prop to add a gap between the hero and following siblings (e.g. `Card.Title`).
+    -   As the **sole child of `Card.Content`**, it extends flush to the card's side edges and additionally to the top edge when `Content` is the first card child, or the bottom edge when it is the last. This enables full-bleed content panels with or without a header above them.
+
 ### Enhancements
 
 -   Export `getWpCompatOverlaySlot()` so consumers can route their own portals into the compat overlay slot ([#78183](https://github.com/WordPress/gutenberg/pull/78183)).

packages/ui/src/card/full-bleed.tsx

@@ -7,6 +7,24 @@ import type { FullBleedProps } from './types';
  * A container that breaks out of the card's padding to span edge-to-edge.
  * Useful for full-width images, dividers, or embedded content.
  *
+ * Additional edge-bumping behavior based on placement:
+ *
+ * - As the **first child** of `Card.Header`, it extends flush to the card's
+ *   top edge — ideal for hero images.
+ * - As the **only child** of `Card.Content`, it extends flush to the card's
+ *   top edge when `Content` is the first card section, and to the bottom edge
+ *   when it is the last.
+ *
+ * Inter-sibling spacing inside `Card.Header` / `Card.Content` is consumer-
+ * managed. To add space between a hero `FullBleed` and the following
+ * siblings, compose the parent with `Stack` via the `render` prop:
+ * `<Card.Header render={ <Stack direction="column" gap="lg" /> }>`. This
+ * keeps `FullBleed` a direct child of `Card.Header` so the edge-bump still
+ * fires, while `Stack` provides the gap.
+ *
+ * Inside `CollapsibleCard`, place full-bleed media in `CollapsibleCard.Content`
+ * (not the header). The trigger/panel gap is preserved by design.
+ *
  * Must be used as a direct child of `Card.Content` or `Card.Header`.
  */
 export const FullBleed = forwardRef< HTMLDivElement, FullBleedProps >(

packages/ui/src/card/stories/index.story.tsx

@@ -1,4 +1,5 @@
 import type { Meta, StoryObj } from '@storybook/react-vite';
+import { Stack } from '@wordpress/ui';
 import * as Card from '../index';
 
 /**
@@ -71,6 +72,56 @@ export const Default: Story = {
 	},
 };
 
+/**
+ * `Card.FullBleed` as the sole child of `Card.Content` spans edge-to-edge
+ * with no padding around it.
+ */
+export const FullBleedCoverOnly: Story = {
+	args: {
+		children: (
+			<Card.Content>
+				<Card.FullBleed>
+					<div
+						style={ {
+							height: 180,
+							background:
+								'linear-gradient(135deg, #f093fb 0%, #f5576c 100%)',
+						} }
+					/>
+				</Card.FullBleed>
+			</Card.Content>
+		),
+	},
+};
+
+/**
+ * When `Card.FullBleed` is the sole child of `Card.Content` and a
+ * `Card.Header` sits above it, the image bumps against the card's side and
+ * bottom edges while the header retains its normal padding.
+ */
+export const FullBleedCoverWithHeader: Story = {
+	args: {
+		children: (
+			<>
+				<Card.Header>
+					<Card.Title>Card title</Card.Title>
+				</Card.Header>
+				<Card.Content>
+					<Card.FullBleed>
+						<div
+							style={ {
+								height: 180,
+								background:
+									'linear-gradient(135deg, #f093fb 0%, #f5576c 100%)',
+							} }
+						/>
+					</Card.FullBleed>
+				</Card.Content>
+			</>
+		),
+	},
+};
+
 /**
  * `Card.FullBleed` breaks out of the card's padding to span
  * edge-to-edge. Useful for images, dividers, or embedded content.
@@ -82,7 +133,7 @@ export const WithFullBleed: Story = {
 				<Card.Header>
 					<Card.Title>Featured image</Card.Title>
 				</Card.Header>
-				<Card.Content>
+				<Card.Content render={ <Stack direction="column" gap="lg" /> }>
 					<Card.FullBleed>
 						<div
 							style={ {
@@ -112,6 +163,69 @@ export const HeaderOnly: Story = {
 	},
 };
 
+/**
+ * When `Card.FullBleed` is the **first child** of `Card.Header`, it extends
+ * flush to the card's top and side edges — ideal for hero images. Content
+ * that follows inside the header is padded normally.
+ */
+export const FullBleedHeroWithTitle: Story = {
+	args: {
+		children: (
+			<>
+				<Card.Header render={ <Stack direction="column" gap="lg" /> }>
+					<Card.FullBleed>
+						<div
+							style={ {
+								height: 180,
+								background:
+									'linear-gradient(135deg, #f093fb 0%, #f5576c 100%)',
+							} }
+						/>
+					</Card.FullBleed>
+					<Card.Title>Hero image card</Card.Title>
+				</Card.Header>
+				<Card.Content>
+					<Text>
+						The image above bleeds to the card&apos;s top and side
+						edges.
+					</Text>
+				</Card.Content>
+			</>
+		),
+	},
+};
+
+/**
+ * When `Card.FullBleed` is the **only child** of `Card.Header`, it fills the
+ * header entirely — top and sides flush to the card edges, no extra padding
+ * below.
+ */
+export const FullBleedHeroOnly: Story = {
+	args: {
+		children: (
+			<>
+				<Card.Header>
+					<Card.FullBleed>
+						<div
+							style={ {
+								height: 180,
+								background:
+									'linear-gradient(135deg, #f093fb 0%, #f5576c 100%)',
+							} }
+						/>
+					</Card.FullBleed>
+				</Card.Header>
+				<Card.Content>
+					<Text>
+						The image above bleeds to the card&apos;s top and side
+						edges.
+					</Text>
+				</Card.Content>
+			</>
+		),
+	},
+};
+
 /**
  * Use the `render` prop to change the underlying HTML elements for
  * better semantics. Here, `Card.Root` renders as a `<section>` and

packages/ui/src/card/style.module.css

@@ -38,4 +38,20 @@
 		margin-inline: calc(-1 * var(--wp-ui-card-padding));
 		width: calc(100% + 2 * var(--wp-ui-card-padding));
 	}
+
+	/*
+	 * When FullBleed sits at the start of the first *root* card section, extend
+	 * it flush to the card's top edge. Must use `.root >` so `Card.Content`
+	 * nested inside `CollapsibleCard`'s panel is not treated as `:first-child`
+	 * (which would pull FullBleed up into the header gap).
+	 */
+	.root > :is(.header, .content):first-child > .fullbleed:first-child {
+		margin-block-start: calc(-1 * var(--wp-ui-card-padding));
+	}
+
+	/* When FullBleed sits at the end of the last card section, extend it flush to the card's bottom edge. */
+	:is(.header, .content):last-child > .fullbleed:last-child {
+		margin-block-end: calc(-1 * var(--wp-ui-card-padding));
+	}
+
 }

packages/ui/src/card/test/index.test.tsx

@@ -49,7 +49,7 @@ describe( 'Card', () => {
 	} );
 
 	describe( 'fullbleed', () => {
-		it( 'renders children', () => {
+		it( 'renders children inside Content', () => {
 			render(
 				<Card.Root>
 					<Card.Content>
@@ -65,6 +65,23 @@ describe( 'Card', () => {
 
 			expect( screen.getByRole( 'img', { name: 'test' } ) ).toBeVisible();
 		} );
+
+		it( 'renders children inside Header', () => {
+			render(
+				<Card.Root>
+					<Card.Header>
+						<Card.FullBleed>
+							<img
+								src="https://example.com/hero.jpg"
+								alt="hero"
+							/>
+						</Card.FullBleed>
+					</Card.Header>
+				</Card.Root>
+			);
+
+			expect( screen.getByRole( 'img', { name: 'hero' } ) ).toBeVisible();
+		} );
 	} );
 
 	describe( 'render prop', () => {

packages/ui/src/collapsible-card/header.tsx

@@ -25,6 +25,8 @@ import type { HeaderProps } from './types';
  * Avoid placing interactive elements (buttons, links, inputs) inside the
  * header, since the entire area is clickable and their events will bubble
  * to trigger the collapse toggle.
+ *
+ * Place full-bleed media in `CollapsibleCard.Content`, not the header.
  */
 export const Header = forwardRef< HTMLDivElement, HeaderProps >(
 	function CollapsibleCardHeader(

packages/ui/src/collapsible-card/stories/index.story.tsx

@@ -33,6 +33,7 @@ const meta: Meta< typeof CollapsibleCard.Root > = {
 		'CollapsibleCard.Header': CollapsibleCard.Header,
 		'CollapsibleCard.HeaderDescription': CollapsibleCard.HeaderDescription,
 		'CollapsibleCard.Content': CollapsibleCard.Content,
+		'Card.FullBleed': Card.FullBleed,
 	},
 	parameters: {
 		componentStatus: {
@@ -314,3 +315,68 @@ export const ComparedToCard: Story = {
 		</div>
 	),
 };
+
+/**
+ * When `Card.FullBleed` is the sole child of `CollapsibleCard.Content` and a
+ * header sits above it, the media bumps against the card&apos;s side and
+ * bottom edges while the header retains its normal padding. (Unlike a plain
+ * `Card`, a header is always required here for the collapse trigger — see
+ * `Card` stories for a body-only `FullBleedCoverOnly` example.)
+ */
+export const FullBleedCoverWithHeader: Story = {
+	argTypes: { open: { control: false } },
+	args: {
+		defaultOpen: true,
+		children: (
+			<>
+				<CollapsibleCard.Header>
+					<Card.Title>Card title</Card.Title>
+				</CollapsibleCard.Header>
+				<CollapsibleCard.Content>
+					<Card.FullBleed>
+						<div
+							style={ {
+								height: 180,
+								background:
+									'linear-gradient(135deg, #f093fb 0%, #f5576c 100%)',
+							} }
+						/>
+					</Card.FullBleed>
+				</CollapsibleCard.Content>
+			</>
+		),
+	},
+};
+
+/**
+ * `Card.FullBleed` breaks out of the content padding to span edge-to-edge.
+ * Useful for images, dividers, or embedded content inside the collapsible
+ * region.
+ */
+export const WithFullBleed: Story = {
+	argTypes: { open: { control: false } },
+	args: {
+		defaultOpen: true,
+		children: (
+			<>
+				<CollapsibleCard.Header>
+					<Card.Title>Featured image</Card.Title>
+				</CollapsibleCard.Header>
+				<CollapsibleCard.Content
+					render={ <Stack direction="column" gap="lg" /> }
+				>
+					<Card.FullBleed>
+						<div
+							style={ {
+								height: 160,
+								background:
+									'linear-gradient(135deg, #667eea 0%, #764ba2 100%)',
+							} }
+						/>
+					</Card.FullBleed>
+					<Text>Content below the full-bleed area.</Text>
+				</CollapsibleCard.Content>
+			</>
+		),
+	},
+};