From 0b07193920809352eb456d626d00d34112cc7852 Mon Sep 17 00:00:00 2001
From: James Koster <james@jameskoster.co.uk>
Date: Fri, 13 Dec 2024 16:51:59 +0000
Subject: [PATCH] Add examples

---
 .../foundations/layout/headers-code.tsx       | 147 +++++++++++++++++-
 .../stories/foundations/layout/headers.mdx    |  27 +++-
 2 files changed, 169 insertions(+), 5 deletions(-)

diff --git a/storybook/stories/foundations/layout/headers-code.tsx b/storybook/stories/foundations/layout/headers-code.tsx
index 8cba9a0bb65d6..46ce0889070f4 100644
--- a/storybook/stories/foundations/layout/headers-code.tsx
+++ b/storybook/stories/foundations/layout/headers-code.tsx
@@ -7,8 +7,149 @@ import React from 'react';
 /**
  * WordPress dependencies
  */
-import { Button } from '@wordpress/components';
+import {
+	Button,
+	__experimentalHStack as HStack,
+	__experimentalVStack as VStack,
+	__experimentalText as Text,
+	__experimentalHeading as Heading,
+	Card,
+	CardHeader,
+	CardBody,
+	CardFooter,
+	DropdownMenu,
+} from '@wordpress/components';
 
-export const HeaderExample = () => {
-	return <Button variant="primary">Click me</Button>;
+import { Icon, moreVertical, page, chevronLeft } from '@wordpress/icons';
+
+export const HeaderExampleLowDensity = () => {
+	return (
+		<Card size="large">
+			<CardHeader>
+				<VStack spacing={ 0 } style={ { width: '100%' } } as="header">
+					<HStack alignment="top">
+						<Button
+							icon={ chevronLeft }
+							style={ { flexShrink: '0' } }
+							__next40pxDefaultSize
+						/>
+						<Heading
+							as="h2"
+							level={ 3 }
+							weight={ 500 }
+							style={ { width: 'inherit' } }
+						>
+							Section title
+						</Heading>
+						<HStack
+							expanded={ false }
+							style={ { flexShrink: '0' } }
+						>
+							<Button
+								variant="primary"
+								style={ { flexShrink: '0' } }
+								__next40pxDefaultSize
+							>
+								Action
+							</Button>
+							<DropdownMenu
+								controls={ [
+									{
+										onClick: () => {},
+										title: 'Action',
+									},
+									{
+										onClick: () => {},
+										title: 'Action',
+									},
+								] }
+								icon={ moreVertical }
+								label="More actions"
+								onToggle={ () => {} }
+								style={ { flexShrink: '0' } }
+								toggleProps={ { __next40pxDefaultSize: true } }
+							/>
+						</HStack>
+					</HStack>
+					<Text
+						variant="muted"
+						as="p"
+						style={ { maxWidth: '600px' } }
+					>
+						Lorem ipsum dolor sit amet, consectetur adipiscing elit.
+						Etiam sollicitudin mauris tellus, vitae tempor urna
+						eleifend vel. Curabitur porttitor vulputate nulla, a
+						mollis enim condimentum convallis.
+					</Text>
+				</VStack>
+			</CardHeader>
+			<CardBody>Section body</CardBody>
+			<CardFooter>Section Footer</CardFooter>
+		</Card>
+	);
+};
+
+export const HeaderExampleHighDensity = () => {
+	return (
+		<Card size="small" style={ { width: '280px' } }>
+			<CardHeader>
+				<VStack spacing={ 0 } style={ { width: '100%' } } as="header">
+					<HStack alignment="top">
+						<Button
+							icon={ chevronLeft }
+							style={ { flexShrink: '0' } }
+							size="small"
+						/>
+						<Icon icon={ page } style={ { flexShrink: '0' } } />
+						<Heading
+							as="h3"
+							size="13px"
+							weight={ 500 }
+							style={ { width: 'inherit' } }
+						>
+							Section title
+						</Heading>
+						<HStack
+							expanded={ false }
+							style={ { flexShrink: '0' } }
+						>
+							<DropdownMenu
+								controls={ [
+									{
+										onClick: () => {},
+										title: 'Action',
+									},
+									{
+										onClick: () => {},
+										title: 'Action',
+									},
+									{
+										onClick: () => {},
+										title: 'Action',
+									},
+								] }
+								icon={ moreVertical }
+								label="More actions"
+								onToggle={ () => {} }
+								style={ { flexShrink: '0' } }
+								toggleProps={ { size: 'small' } }
+							/>
+						</HStack>
+					</HStack>
+					<Text
+						variant="muted"
+						as="p"
+						style={ { maxWidth: '600px' } }
+					>
+						Lorem ipsum dolor sit amet, consectetur adipiscing elit.
+						Etiam sollicitudin mauris tellus, vitae tempor urna
+						eleifend vel. Curabitur porttitor vulputate nulla, a
+						mollis enim condimentum convallis.
+					</Text>
+				</VStack>
+			</CardHeader>
+			<CardBody>Section body</CardBody>
+			<CardFooter>Section Footer</CardFooter>
+		</Card>
+	);
 };
diff --git a/storybook/stories/foundations/layout/headers.mdx b/storybook/stories/foundations/layout/headers.mdx
index 6449cf9f56743..be700fcfc5ff7 100644
--- a/storybook/stories/foundations/layout/headers.mdx
+++ b/storybook/stories/foundations/layout/headers.mdx
@@ -4,10 +4,33 @@ import './style.css';
 
 import { Meta } from '@storybook/addon-docs/blocks';
 
-import { HeaderExample } from './headers-code';
+import { HeaderExampleLowDensity } from './headers-code';
+import { HeaderExampleHighDensity } from './headers-code';
 
 <Meta title="Foundations/Layout/Headers" name="page" />
 
 # Headers
+Headers provide a high-level overview, and access to actions relating to a specific UI section. A standardised design gives users a predictable way to complete common tasks.
 
-<HeaderExample />
+While the general composition is consistent, there are two different header patterns to use, based on density. 
+
+## Low density
+
+<HeaderExampleLowDensity />
+
+* Use the low density header pattern in the primary section of an admin page. 
+* Always include a visible title, typically using the `h2` element.
+* Include no more than one visible action.
+* Secondary actions are accessible via 'More actions' menu.
+* Include a summary/description where appropriate, but keep it short.
+* Use a 'Back' icon-button to provide access to the parent secton
+
+## High density
+
+<HeaderExampleHighDensity />
+
+* Use the high density header pattern in narrower, secondary sections and editor panels.
+* Contain all actions in a Menu.
+* Always include a visible title, typically using the `h3` element, and use a smaller font size, typically `$font-size-medium`.
+* Optionally include a decorative element like an icon or an image. This element should be `24px` x `24px` and relate directly to the title.
+* Use a 'Back' icon-button to provide access to the parent secton