@tanishqkancharla/maui 0.0.62 → 0.0.63

package/dist/components/Banner.d.ts

@@ -0,0 +1,32 @@
+import type { ComponentPropsWithoutRef, ReactNode } from "react";
+export type BannerTone = "neutral" | "info" | "success" | "warning" | "danger";
+export type BannerLayout = "inline" | "stacked";
+export type BannerProps = Omit<ComponentPropsWithoutRef<"div">, "title"> & {
+    tone?: BannerTone;
+    /** Use stacked for multi-sentence messages or a title with supporting text. */
+    layout?: BannerLayout;
+    title?: ReactNode;
+    /** A decorative icon. Defaults to the tone's icon; false hides it. */
+    icon?: ReactNode | false;
+    actions?: ReactNode;
+    /** Adds a close button. The caller owns visibility. */
+    onDismiss?: () => void;
+    dismissLabel?: string;
+};
+/** Plain div parts; icon is decorative. Layout changes action placement, not semantics. */
+export declare const bannerStyles: {
+    readonly root: (args_0?: {
+        tone?: BannerTone;
+    } | undefined) => import("purse-styles").StyleElement;
+    readonly icon: import("purse-styles").StyleElement;
+    readonly body: (args_0?: {
+        layout?: BannerLayout;
+    } | undefined) => import("purse-styles").StyleElement;
+    readonly content: import("purse-styles").StyleElement;
+    readonly title: import("purse-styles").StyleElement;
+    readonly description: import("purse-styles").StyleElement;
+    readonly actions: import("purse-styles").StyleElement;
+    readonly dismiss: import("purse-styles").StyleElement;
+};
+/** Persistent in-flow message. Set role="status" or role="alert" explicitly to announce it. */
+export declare function Banner({ tone, layout, title, children, icon, actions, onDismiss, dismissLabel, className, ...props }: BannerProps): import("react").JSX.Element;

package/dist/components/Banner.js

@@ -0,0 +1,106 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { style, useStyles } from "purse-styles";
+import { Button } from "./Button";
+import { Text } from "./Text";
+import { CheckCircle } from "../icons/CheckCircle";
+import { Close } from "../icons/Close";
+import { CircleX } from "../icons/CircleX";
+import { Information } from "../icons/Information";
+import { WarningTriangle } from "../icons/WarningTriangle";
+import { colors } from "../tokens/colors";
+import { radius } from "../tokens/radius";
+import { controlSize } from "../tokens/sizing";
+import { spacing } from "../tokens/spacing";
+import { text } from "../tokens/text";
+import { cls } from "../utils/cls";
+import { memoize } from "../utils/memoize";
+const palettes = {
+    neutral: "gray",
+    info: "blue",
+    success: "green",
+    warning: "amber",
+    danger: "red",
+};
+const icons = {
+    neutral: Information,
+    info: Information,
+    success: CheckCircle,
+    warning: WarningTriangle,
+    danger: CircleX,
+};
+const root = memoize(({ tone = "neutral" } = {}) => style(text({ size: "sm" }), radius.lg, spacing.padding({ all: 3 }), {
+    display: "flex",
+    alignItems: "flex-start",
+    gap: spacing.value(3),
+    minWidth: 0,
+    backgroundColor: colors[palettes[tone]][2],
+    border: `1px solid ${colors[palettes[tone]][6]}`,
+    // Give text and icons the same inset beside standard-height controls.
+    "--banner-text-inset": `max(0px, calc((${controlSize.height} - 1lh) / 2))`,
+    "--banner-icon-color": colors[palettes[tone]][11],
+}));
+const icon = style({
+    flex: "0 0 auto",
+    width: "1lh",
+    height: "1lh",
+    marginBlockStart: "var(--banner-text-inset)",
+    color: "var(--banner-icon-color)",
+    display: "flex",
+    alignItems: "center",
+    justifyContent: "center",
+    "& > svg": { width: "100%", height: "100%" },
+});
+const body = memoize(({ layout = "inline" } = {}) => style({
+    display: "flex",
+    flex: "1 1 auto",
+    minWidth: 0,
+    flexDirection: layout === "stacked" ? "column" : "row",
+    flexWrap: "wrap",
+    alignItems: "flex-start",
+    gap: spacing.value(4),
+    "& > :first-child": {
+        flex: layout === "inline" ? "1 1 12rem" : "0 1 auto",
+    },
+}));
+const content = style({
+    minWidth: 0,
+    maxWidth: "100%",
+    paddingBlock: "var(--banner-text-inset)",
+    overflowWrap: "anywhere",
+});
+const title = style({ display: "block" });
+const description = style({ display: "block" });
+const actions = style({
+    display: "flex",
+    alignItems: "center",
+    justifyContent: "flex-end",
+    flexWrap: "wrap",
+    gap: spacing.value(4),
+    maxWidth: "100%",
+    marginInlineStart: "auto",
+});
+const dismiss = style({ flexShrink: 0 });
+/** Plain div parts; icon is decorative. Layout changes action placement, not semantics. */
+export const bannerStyles = {
+    root,
+    icon,
+    body,
+    content,
+    title,
+    description,
+    actions,
+    dismiss,
+};
+/** Persistent in-flow message. Set role="status" or role="alert" explicitly to announce it. */
+export function Banner({ tone = "neutral", layout = "inline", title, children, icon, actions, onDismiss, dismissLabel = "Dismiss notification", className, ...props }) {
+    const rootClassName = useStyles(bannerStyles.root({ tone }));
+    const iconClassName = useStyles(bannerStyles.icon);
+    const bodyClassName = useStyles(bannerStyles.body({ layout }));
+    const contentClassName = useStyles(bannerStyles.content);
+    const titleClassName = useStyles(bannerStyles.title);
+    const descriptionClassName = useStyles(bannerStyles.description, title != null && style({ color: colors.gray[11] }));
+    const actionsClassName = useStyles(bannerStyles.actions);
+    const dismissClassName = useStyles(bannerStyles.dismiss);
+    const Icon = icons[tone];
+    return (_jsxs("div", { ...props, className: cls(rootClassName, className), children: [icon !== false && (_jsx("div", { className: iconClassName, "aria-hidden": "true", children: icon ?? _jsx(Icon, {}) })), _jsxs("div", { className: bodyClassName, children: [_jsxs("div", { className: contentClassName, children: [title != null && (_jsx(Text, { size: "sm", fontWeight: 500, className: titleClassName, children: title })), children != null && (_jsx("div", { className: descriptionClassName, children: children }))] }), actions != null && actions !== false && (_jsx("div", { className: actionsClassName, children: actions }))] }), onDismiss && (_jsx(Button, { variant: "quiet", variantColor: palettes[tone], "aria-label": dismissLabel, onPress: onDismiss, className: dismissClassName, children: _jsx(Close, { size: "sm" }) }))] }));
+}

package/dist/maui.d.ts

@@ -20,6 +20,7 @@ export { prose, proseRhythm, proseHtml, proseStreamingMarkers, type ProseSize, }
 export { visuallyHidden } from "./tokens/visuallyHidden";
 export { Avatar, avatarStyles } from "./components/Avatar";
 export { Badge, badgeStyles } from "./components/Badge";
+export { Banner, bannerStyles, type BannerProps, type BannerTone, type BannerLayout, } from "./components/Banner";
 export { LogoIcon, type LogoIconProps } from "./components/LogoIcon";
 export { Button, buttonStyles, useButton, type ButtonCssColor, type ButtonProps, type ButtonSize, type ButtonVariant, type ButtonVariantColor, } from "./components/Button";
 export { TabBar, tabBarStyles, type TabBarItem, type TabBarProps, } from "./components/TabBar";

package/dist/maui.js

@@ -23,6 +23,7 @@ export { visuallyHidden } from "./tokens/visuallyHidden";
 // Components
 export { Avatar, avatarStyles } from "./components/Avatar";
 export { Badge, badgeStyles } from "./components/Badge";
+export { Banner, bannerStyles, } from "./components/Banner";
 export { LogoIcon } from "./components/LogoIcon";
 export { Button, buttonStyles, useButton, } from "./components/Button";
 export { TabBar, tabBarStyles, } from "./components/TabBar";

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@tanishqkancharla/maui",
-	"version": "0.0.62",
+	"version": "0.0.63",
 	"description": "Maui design system",
 	"type": "module",
 	"main": "./dist/maui.js",

package/skills/maui/SKILL.md

@@ -5,10 +5,8 @@ description: Conventions for installing, updating, and consuming the Maui design
 
 # Maui
 
-Read the reference for the work you are doing:
-
 - When installing or updating the Maui package, read [installing_maui.md](references/installing_maui.md).
-- When designing, implementing, or reviewing UI with Maui, read [design_conventions.md](references/design_conventions.md), then open every matching component, pattern, or app reference below.
+- For Maui UI work, read [design_conventions.md](references/design_conventions.md) and all matching references below.
 
 Use Maui components. When one can't do what you need, build from the matching `react-aria-components` element with that component's exported styles (`buttonStyles`, `listBoxStyles`, …).
 
@@ -24,6 +22,7 @@ Use Maui components. When one can't do what you need, build from the matching `r
 | ---------------- | -------------------------------------------------------------------------------------------- |
 | Avatar           | [avatar.md](references/components/avatar.md)                                                 |
 | Badge            | [badge.md](references/components/badge.md)                                                   |
+| Banner           | [banner.md](references/components/banner.md)                                                 |
 | Buttons          | [buttons.md](references/components/buttons.md) (`Button`, `Overlay`, `Dialog`)               |
 | Tab bar          | [tab-bar.md](references/components/tab-bar.md)                                               |
 | Drawer           | [drawer.md](references/components/drawer.md)                                                 |

package/skills/maui/references/components/banner.md

@@ -0,0 +1,42 @@
+# Banner
+
+Gallery: `/components/banner`. Import `Banner` from `"maui"`.
+
+Persistent in-flow message. Use `layout="inline"` (default) for one sentence,
+even when it wraps. Always use `layout="stacked"` for multiple sentences or a
+title with supporting text. Choose layout explicitly; Banner does not parse copy.
+
+```tsx
+<Banner
+	tone="info"
+	actions={<Button variant="quiet" variantColor="blue" onPress={reload}>Reload</Button>}
+>
+	A new version is available.
+</Banner>
+
+<Banner
+	tone="warning"
+	layout="stacked"
+	title="Your connection was interrupted."
+	actions={<Button variant="quiet" variantColor="amber" onPress={reconnect}>Reconnect</Button>}
+>
+	Changes are saved on this device. Reconnect to sync.
+</Banner>
+```
+
+- `tone`: `neutral` (default), `info`, `success`, `warning`, `danger`.
+- Compose `actions` with quiet buttons in the matching palette: gray, blue, green,
+  amber, red respectively. Banner does not restyle supplied actions. Stacked and
+  wrapped actions align right.
+- `title` and children accept React nodes. `icon` defaults to the tone's icon;
+  supply a decorative SVG or `false` to hide it. Icons match the first line height.
+  Icon-to-text gap and outer padding share spacing step 3 (6px; 8px at large scale).
+- `onDismiss` adds a close button; caller owns visibility. `dismissLabel` defaults
+  to `"Dismiss notification"`. No timer or automatic dismissal.
+- No automatic announcements. Set `role="status"` for live updates or
+  `role="alert"` for urgent failures; tone does not determine urgency.
+
+## Styles
+
+**Banner** — `bannerStyles`: `root({ tone })`, `icon`, `body({ layout })`, `content`,
+`title`, `description`, `actions`, `dismiss`. Plain div parts; icon is decorative.

package/src/apps/JsxEditor/catalog.ts

@@ -1,5 +1,6 @@
 import { Avatar } from "../../components/Avatar"
 import { Badge } from "../../components/Badge"
+import { Banner } from "../../components/Banner"
 import { Button } from "../../components/Button"
 import { Checkbox } from "../../components/Checkbox"
 import { Code, Kbd } from "../../components/Code"
@@ -337,6 +338,21 @@ export const catalog: CatalogComponent[] = [
 		html: true,
 		attributes: [],
 	},
+	{
+		name: "Banner",
+		info: "Persistent in-flow message. Inline or stacked actions; caller owns dismissal. Icons match the first line height.",
+		html: true,
+		attributes: [
+			{ name: "tone", values: ["neutral", "info", "success", "warning", "danger"] },
+			{ name: "layout", values: ["inline", "stacked"] },
+			{ name: "title" },
+			{ name: "icon" },
+			{ name: "actions" },
+			{ name: "onDismiss" },
+			{ name: "dismissLabel" },
+			{ name: "role", values: ["status", "alert"] },
+		],
+	},
 	{
 		name: "Avatar",
 		info: "Initials avatar from a name.",
@@ -569,6 +585,7 @@ export const catalog: CatalogComponent[] = [
 export const previewScope: Record<string, unknown> = {
 	Avatar,
 	Badge,
+	Banner,
 	Button,
 	Checkbox,
 	Code,

package/src/apps/JsxEditor/evaluate.test.ts

@@ -3,10 +3,21 @@ import { evaluateJsx } from "./evaluate"
 
 describe("evaluateJsx", () => {
 	test("evaluates Flex justifyContent and background", () => {
-		const result = evaluateJsx(`<Flex row alignItems="center" justifyContent="between" background="element" p={4} radius="lg">
+		const result =
+			evaluateJsx(`<Flex row alignItems="center" justifyContent="between" background="element" p={4} radius="lg">
   <Text>Left</Text>
   <Text>Right</Text>
 </Flex>`)
 		expect(result.ok).toBe(true)
 	})
+
+	test("evaluates Banner layouts with composed actions", () => {
+		for (const layout of ["inline", "stacked"]) {
+			const result =
+				evaluateJsx(`<Banner layout="${layout}" tone="warning" title="Connection interrupted" actions={<Button>Reconnect</Button>}>
+  Changes are saved on this device.
+</Banner>`)
+			expect(result.ok).toBe(true)
+		}
+	})
 })

package/src/components/Banner.test.tsx

@@ -0,0 +1,52 @@
+import { renderToStaticMarkup } from "react-dom/server"
+import { PurseProvider } from "purse-styles"
+import type { ReactNode } from "react"
+import { afterAll, beforeAll, expect, it, vi } from "vitest"
+import { Banner } from "./Banner"
+
+beforeAll(() => {
+	vi.stubGlobal("document", { createElement: () => ({}) })
+})
+
+afterAll(() => vi.unstubAllGlobals())
+
+function render(children: ReactNode) {
+	return renderToStaticMarkup(<PurseProvider>{children}</PurseProvider>)
+}
+
+it("keeps tone separate from announcement urgency and makes the icon optional", () => {
+	const quiet = render(<Banner tone="danger">Sync failed.</Banner>)
+	expect(quiet).toContain("Sync failed.")
+	expect(quiet).not.toMatch(/role="(?:alert|status|banner)"/)
+	expect(quiet).not.toContain("<button")
+	expect(quiet).toContain('aria-hidden="true"')
+
+	for (const role of ["status", "alert"] as const) {
+		const announced = render(
+			<Banner role={role} icon={false}>
+				Sync failed.
+			</Banner>,
+		)
+		expect(announced).toContain(`role="${role}"`)
+		expect(announced).not.toContain("<svg")
+	}
+})
+
+it("preserves composed content, actions, and custom icons in both layouts", () => {
+	for (const layout of ["inline", "stacked"] as const) {
+		const html = render(
+			<Banner
+				layout={layout}
+				title="Connection interrupted"
+				icon={<svg data-custom-icon="bell" />}
+				actions={<a href="/connection">Reconnect</a>}
+			>
+				Your <strong>local changes</strong> are safe.
+			</Banner>,
+		)
+		expect(html).toContain("Connection interrupted")
+		expect(html).toContain("<strong>local changes</strong>")
+		expect(html).toContain('<a href="/connection">Reconnect</a>')
+		expect(html).toContain('data-custom-icon="bell"')
+	}
+})

package/src/components/Banner.tsx

@@ -0,0 +1,184 @@
+import type { ComponentPropsWithoutRef, ReactNode } from "react"
+import { style, useStyles } from "purse-styles"
+import { Button } from "./Button"
+import { Text } from "./Text"
+import { CheckCircle } from "../icons/CheckCircle"
+import { Close } from "../icons/Close"
+import { CircleX } from "../icons/CircleX"
+import { Information } from "../icons/Information"
+import { WarningTriangle } from "../icons/WarningTriangle"
+import { colors } from "../tokens/colors"
+import { radius } from "../tokens/radius"
+import { controlSize } from "../tokens/sizing"
+import { spacing } from "../tokens/spacing"
+import { text } from "../tokens/text"
+import { cls } from "../utils/cls"
+import { memoize } from "../utils/memoize"
+
+export type BannerTone = "neutral" | "info" | "success" | "warning" | "danger"
+export type BannerLayout = "inline" | "stacked"
+
+export type BannerProps = Omit<ComponentPropsWithoutRef<"div">, "title"> & {
+	tone?: BannerTone
+	/** Use stacked for multi-sentence messages or a title with supporting text. */
+	layout?: BannerLayout
+	title?: ReactNode
+	/** A decorative icon. Defaults to the tone's icon; false hides it. */
+	icon?: ReactNode | false
+	actions?: ReactNode
+	/** Adds a close button. The caller owns visibility. */
+	onDismiss?: () => void
+	dismissLabel?: string
+}
+
+const palettes = {
+	neutral: "gray",
+	info: "blue",
+	success: "green",
+	warning: "amber",
+	danger: "red",
+} as const
+
+const icons = {
+	neutral: Information,
+	info: Information,
+	success: CheckCircle,
+	warning: WarningTriangle,
+	danger: CircleX,
+} as const
+
+const root = memoize(({ tone = "neutral" }: { tone?: BannerTone } = {}) =>
+	style(text({ size: "sm" }), radius.lg, spacing.padding({ all: 3 }), {
+		display: "flex",
+		alignItems: "flex-start",
+		gap: spacing.value(3),
+		minWidth: 0,
+		backgroundColor: colors[palettes[tone]][2],
+		border: `1px solid ${colors[palettes[tone]][6]}`,
+		// Give text and icons the same inset beside standard-height controls.
+		"--banner-text-inset": `max(0px, calc((${controlSize.height} - 1lh) / 2))`,
+		"--banner-icon-color": colors[palettes[tone]][11],
+	}),
+)
+
+const icon = style({
+	flex: "0 0 auto",
+	width: "1lh",
+	height: "1lh",
+	marginBlockStart: "var(--banner-text-inset)",
+	color: "var(--banner-icon-color)",
+	display: "flex",
+	alignItems: "center",
+	justifyContent: "center",
+	"& > svg": { width: "100%", height: "100%" },
+})
+
+const body = memoize(({ layout = "inline" }: { layout?: BannerLayout } = {}) =>
+	style({
+		display: "flex",
+		flex: "1 1 auto",
+		minWidth: 0,
+		flexDirection: layout === "stacked" ? "column" : "row",
+		flexWrap: "wrap",
+		alignItems: "flex-start",
+		gap: spacing.value(4),
+		"& > :first-child": {
+			flex: layout === "inline" ? "1 1 12rem" : "0 1 auto",
+		},
+	}),
+)
+
+const content = style({
+	minWidth: 0,
+	maxWidth: "100%",
+	paddingBlock: "var(--banner-text-inset)",
+	overflowWrap: "anywhere",
+})
+
+const title = style({ display: "block" })
+const description = style({ display: "block" })
+const actions = style({
+	display: "flex",
+	alignItems: "center",
+	justifyContent: "flex-end",
+	flexWrap: "wrap",
+	gap: spacing.value(4),
+	maxWidth: "100%",
+	marginInlineStart: "auto",
+})
+const dismiss = style({ flexShrink: 0 })
+
+/** Plain div parts; icon is decorative. Layout changes action placement, not semantics. */
+export const bannerStyles = {
+	root,
+	icon,
+	body,
+	content,
+	title,
+	description,
+	actions,
+	dismiss,
+} as const
+
+/** Persistent in-flow message. Set role="status" or role="alert" explicitly to announce it. */
+export function Banner({
+	tone = "neutral",
+	layout = "inline",
+	title,
+	children,
+	icon,
+	actions,
+	onDismiss,
+	dismissLabel = "Dismiss notification",
+	className,
+	...props
+}: BannerProps) {
+	const rootClassName = useStyles(bannerStyles.root({ tone }))
+	const iconClassName = useStyles(bannerStyles.icon)
+	const bodyClassName = useStyles(bannerStyles.body({ layout }))
+	const contentClassName = useStyles(bannerStyles.content)
+	const titleClassName = useStyles(bannerStyles.title)
+	const descriptionClassName = useStyles(
+		bannerStyles.description,
+		title != null && style({ color: colors.gray[11] }),
+	)
+	const actionsClassName = useStyles(bannerStyles.actions)
+	const dismissClassName = useStyles(bannerStyles.dismiss)
+	const Icon = icons[tone]
+
+	return (
+		<div {...props} className={cls(rootClassName, className)}>
+			{icon !== false && (
+				<div className={iconClassName} aria-hidden="true">
+					{icon ?? <Icon />}
+				</div>
+			)}
+			<div className={bodyClassName}>
+				<div className={contentClassName}>
+					{title != null && (
+						<Text size="sm" fontWeight={500} className={titleClassName}>
+							{title}
+						</Text>
+					)}
+					{children != null && (
+						<div className={descriptionClassName}>{children}</div>
+					)}
+				</div>
+				{actions != null && actions !== false && (
+					<div className={actionsClassName}>{actions}</div>
+				)}
+			</div>
+			{onDismiss && (
+				<Button
+					variant="quiet"
+					variantColor={palettes[tone]}
+					aria-label={dismissLabel}
+					onPress={onDismiss}
+					className={dismissClassName}
+				>
+					<Close size="sm" />
+				</Button>
+			)}
+		</div>
+	)
+}

package/src/maui.ts

@@ -58,6 +58,13 @@ export { visuallyHidden } from "./tokens/visuallyHidden"
 // Components
 export { Avatar, avatarStyles } from "./components/Avatar"
 export { Badge, badgeStyles } from "./components/Badge"
+export {
+	Banner,
+	bannerStyles,
+	type BannerProps,
+	type BannerTone,
+	type BannerLayout,
+} from "./components/Banner"
 export { LogoIcon, type LogoIconProps } from "./components/LogoIcon"
 export {
 	Button,

package/src/pages/BannerPage.tsx

@@ -0,0 +1,214 @@
+import { useState } from "react"
+import {
+	Banner,
+	type BannerLayout,
+	type BannerTone,
+} from "../components/Banner"
+import { Button } from "../components/Button"
+import { Code } from "../components/Code"
+import { CodeBlock } from "../components/CodeBlock"
+import { Prose } from "../components/Prose"
+import { Text } from "../components/Text"
+import { H2, H3, P } from "../components/Typography"
+import { Flex } from "../components/Utils"
+import { Bell } from "../icons/Bell"
+import { Panel } from "./Panel"
+
+const tones: { tone: BannerTone; message: string; layout?: BannerLayout }[] = [
+	{ tone: "neutral", message: "Maintenance is scheduled for Sunday." },
+	{ tone: "info", message: "A new version is available." },
+	{ tone: "success", message: "All changes are synced." },
+	{ tone: "warning", message: "You’re approaching your storage limit." },
+	{
+		tone: "danger",
+		message: "Sync is unavailable. Your changes are safe on this device.",
+		layout: "stacked",
+	},
+]
+
+export function BannerPage() {
+	const [showUpdate, setShowUpdate] = useState(true)
+	const [updated, setUpdated] = useState(false)
+	const [connected, setConnected] = useState(false)
+
+	return (
+		<Prose style={{ paddingBottom: "32px" }}>
+			<H2>Banner</H2>
+			<P>
+				Persistent messages that stay in the page flow. Use inline for a single
+				sentence, even when it wraps. Always use stacked for multi-sentence
+				messages or a title with supporting text. Icons match the first line
+				height, including at the large platform scale.
+			</P>
+
+			<H3>Inline</H3>
+			<Panel data-example="inline">
+				<Flex column gap={8}>
+					{showUpdate ? (
+						<Banner
+							tone={updated ? "success" : "info"}
+							onDismiss={() => setShowUpdate(false)}
+							dismissLabel="Dismiss update notice"
+							actions={
+								!updated && (
+									<Button
+										variant="quiet"
+										variantColor="blue"
+										onPress={() => setUpdated(true)}
+									>
+										Reload
+									</Button>
+								)
+							}
+						>
+							{updated
+								? "You’re on the latest version."
+								: "A new version is available."}
+						</Banner>
+					) : (
+						<Text size="sm" color="lowContrast">
+							Update notice dismissed.
+						</Text>
+					)}
+					<Button
+						variant="quiet"
+						onPress={() => {
+							setShowUpdate(true)
+							setUpdated(false)
+						}}
+					>
+						Reset update example
+					</Button>
+				</Flex>
+			</Panel>
+
+			<H3>Stacked</H3>
+			<Panel data-example="stacked">
+				<Flex column gap={8}>
+					<Banner
+						layout="stacked"
+						tone={connected ? "success" : "warning"}
+						title={
+							connected
+								? "You’re connected."
+								: "Your connection was interrupted."
+						}
+						actions={
+							!connected && (
+								<Button
+									variant="quiet"
+									variantColor="amber"
+									onPress={() => setConnected(true)}
+								>
+									Reconnect
+								</Button>
+							)
+						}
+					>
+						{connected
+							? "All changes are synced."
+							: "Changes are saved on this device. Reconnect to sync."}
+					</Banner>
+					<Button variant="quiet" onPress={() => setConnected(false)}>
+						Reset connection example
+					</Button>
+				</Flex>
+			</Panel>
+
+			<H3>Tones</H3>
+			<Panel data-example="tones">
+				<Flex column gap={6}>
+					{tones.map(({ tone, message, layout }) => (
+						<Banner key={tone} tone={tone} layout={layout}>
+							{message}
+						</Banner>
+					))}
+				</Flex>
+			</Panel>
+
+			<H3>Narrow layouts</H3>
+			<P>
+				Messages wrap without truncation, with stacked actions on the right.
+			</P>
+			<Panel data-example="narrow">
+				<Flex column gap={6} style={{ maxWidth: "320px" }}>
+					<Banner
+						layout="stacked"
+						tone="info"
+						actions={
+							<Button
+								variant="quiet"
+								variantColor="blue"
+								onPress={() => setUpdated(true)}
+							>
+								{updated ? "Up to date" : "Reload"}
+							</Button>
+						}
+					>
+						A new version is available. Reload to get the latest improvements.
+					</Banner>
+					<Banner
+						layout="stacked"
+						tone="warning"
+						title="Your connection was interrupted."
+						actions={
+							<Button
+								variant="quiet"
+								variantColor="amber"
+								onPress={() => setConnected(true)}
+							>
+								{connected ? "Connected" : "Reconnect"}
+							</Button>
+						}
+					>
+						Changes are saved on this device. Reconnect to sync.
+					</Banner>
+				</Flex>
+			</Panel>
+
+			<H3>Custom icon and no icon</H3>
+			<Panel data-example="icons">
+				<Flex column gap={6}>
+					<Banner icon={<Bell />}>
+						Notifications are paused until tomorrow.
+					</Banner>
+					<Banner icon={false}>Maintenance is scheduled for Sunday.</Banner>
+				</Flex>
+			</Panel>
+
+			<H3>Usage</H3>
+			<CodeBlock lang="tsx">{`<Banner
+  tone="info"
+  layout="inline"
+  actions={<Button variant="quiet" variantColor="blue" onPress={reload}>Reload</Button>}
+  onDismiss={() => setVisible(false)}
+>
+  A new version is available.
+</Banner>
+
+<Banner
+  tone="warning"
+  layout="stacked"
+  title="Your connection was interrupted."
+  actions={<Button variant="quiet" variantColor="amber" onPress={reconnect}>Reconnect</Button>}
+>
+  Changes are saved on this device. Reconnect to sync.
+</Banner>`}</CodeBlock>
+			<P>
+				Neutral tone and inline layout are the defaults. Actions accept composed
+				buttons or links; use quiet buttons with a matching palette: gray for
+				neutral, blue for info, green for success, amber for warning, and red
+				for danger. Stacked and wrapped actions align to the right. The caller
+				controls visibility through <Code>onDismiss</Code>; there is no timer or
+				automatic dismissal. Customize the close button’s accessible name with{" "}
+				<Code>dismissLabel</Code>.
+			</P>
+			<P>
+				Banners do not announce themselves by default. Use{" "}
+				<Code>role="status"</Code> for live updates or <Code>role="alert"</Code>{" "}
+				for urgent failures. Tone alone does not determine urgency. Style parts
+				are available through <Code>bannerStyles</Code>.
+			</P>
+		</Prose>
+	)
+}

package/src/pages/Maui.tsx

@@ -32,6 +32,7 @@ import { ReadmePage } from "./ReadmePage"
 import { ActivityIndicatorPage } from "./ActivityIndicatorPage"
 import { AvatarPage } from "./AvatarPage"
 import { BadgePage } from "./BadgePage"
+import { BannerPage } from "./BannerPage"
 import { BackgroundColorTokenPage } from "./BackgroundColorTokenPage"
 import { BordersTokenPage } from "./BordersTokenPage"
 import { ButtonsPage } from "./ButtonsPage"
@@ -143,6 +144,7 @@ const navigation: NavEntry[] = [
 		children: [
 			{ label: "Avatar", path: "/components/avatar", page: AvatarPage },
 			{ label: "Badge", path: "/components/badge", page: BadgePage },
+			{ label: "Banner", path: "/components/banner", page: BannerPage },
 			{ label: "Buttons", path: "/components/buttons", page: ButtonsPage },
 			{ label: "Dialog", path: "/components/dialog", page: DialogPage },
 			{ label: "Tab bar", path: "/components/tab-bar", page: TabBarPage },