@nationaldesignstudio/react 0.0.17 → 0.1.0

package/src/components/organisms/card/card.tsx

@@ -1,13 +1,17 @@
 import * as React from "react";
 import { tv, type VariantProps } from "tailwind-variants";
-import { cn } from "@/lib/utils";
 
 const cardVariants = tv({
-	base: "flex overflow-hidden rounded-surface-card bg-card-background stroke-surface-card border-border-subtle border-solid",
+	base: "relative flex overflow-hidden rounded-surface-card bg-card-background stroke-surface-card border-border-subtle border-solid",
 	variants: {
 		layout: {
 			vertical: "w-full flex-col",
 			horizontal: "w-full flex-row",
+			/**
+			 * Overlay layout - content sits on top of full-bleed background.
+			 * Use with Background components for images/gradients.
+			 */
+			overlay: "w-full flex-col",
 		},
 	},
 	defaultVariants: {
@@ -25,8 +29,10 @@ export interface CardProps
  * Layouts:
  * - vertical: Image on top, content below (default)
  * - horizontal: Image on left, content on right
+ * - overlay: Full-bleed background with content on top
  *
  * Use with CardImage, CardContent, CardEyebrow, CardTitle, CardDescription, and CardActions.
+ * For overlay layout, use Background components for full-bleed backgrounds.
  */
 const Card = React.forwardRef<HTMLDivElement, CardProps>(
 	({ className, layout, ...props }, ref) => {
@@ -41,6 +47,16 @@ const Card = React.forwardRef<HTMLDivElement, CardProps>(
 );
 Card.displayName = "Card";
 
+const cardImageVariants = tv({
+	base: [
+		"relative shrink-0 bg-bg-muted",
+		// Vertical: full width with aspect ratio
+		"aspect-video w-full",
+		// When in horizontal card (parent has flex-row), override
+		"[.flex-row>&]:aspect-auto [.flex-row>&]:w-2/5 [.flex-row>&]:self-stretch",
+	],
+});
+
 export interface CardImageProps extends React.HTMLAttributes<HTMLDivElement> {
 	/**
 	 * The image source URL
@@ -61,14 +77,7 @@ const CardImage = React.forwardRef<HTMLDivElement, CardImageProps>(
 		return (
 			<div
 				ref={ref}
-				className={cn(
-					"relative shrink-0 bg-gray-500",
-					// Vertical: full width with aspect ratio
-					"aspect-video w-full",
-					// When in horizontal card (parent has flex-row), override
-					"[.flex-row>&]:aspect-auto [.flex-row>&]:w-2/5 [.flex-row>&]:self-stretch",
-					className,
-				)}
+				className={cardImageVariants({ class: className })}
 				{...props}
 			>
 				{src && (
@@ -84,22 +93,47 @@ const CardImage = React.forwardRef<HTMLDivElement, CardImageProps>(
 );
 CardImage.displayName = "CardImage";
 
+const cardContentVariants = tv({
+	base: "flex w-full flex-1 flex-col gap-spatial-card-large-gap p-spatial-card-large-padding",
+	variants: {
+		/**
+		 * Vertical alignment of content within the card.
+		 * Useful for overlay layouts to position content at top/center/bottom.
+		 */
+		justify: {
+			start: "justify-start",
+			center: "justify-center",
+			end: "justify-end",
+		},
+	},
+});
+
 export interface CardContentProps
-	extends React.HTMLAttributes<HTMLDivElement> {}
+	extends React.HTMLAttributes<HTMLDivElement>,
+		VariantProps<typeof cardContentVariants> {}
 
 /**
  * Card content container with proper padding and spacing.
  * Uses spatial card tokens for consistent sizing.
+ * For overlay layout, add `relative z-10` to ensure content sits above background.
+ *
+ * @example
+ * ```tsx
+ * // Content at bottom of overlay card
+ * <Card layout="overlay">
+ *   <Background.Image src="/hero.jpg" />
+ *   <CardContent justify="end" className="relative z-10">
+ *     <CardTitle>Title</CardTitle>
+ *   </CardContent>
+ * </Card>
+ * ```
  */
 const CardContent = React.forwardRef<HTMLDivElement, CardContentProps>(
-	({ className, ...props }, ref) => {
+	({ className, justify, ...props }, ref) => {
 		return (
 			<div
 				ref={ref}
-				className={cn(
-					"flex w-full flex-1 flex-col gap-spatial-card-large-gap p-spatial-card-large-padding",
-					className,
-				)}
+				className={cardContentVariants({ justify, class: className })}
 				{...props}
 			/>
 		);
@@ -107,6 +141,10 @@ const CardContent = React.forwardRef<HTMLDivElement, CardContentProps>(
 );
 CardContent.displayName = "CardContent";
 
+const cardEyebrowVariants = tv({
+	base: "typography-caption-large text-text-muted",
+});
+
 export interface CardEyebrowProps
 	extends React.HTMLAttributes<HTMLParagraphElement> {}
 
@@ -118,7 +156,7 @@ const CardEyebrow = React.forwardRef<HTMLParagraphElement, CardEyebrowProps>(
 		return (
 			<p
 				ref={ref}
-				className={cn("typography-caption-large text-gray-500", className)}
+				className={cardEyebrowVariants({ class: className })}
 				{...props}
 			/>
 		);
@@ -126,6 +164,10 @@ const CardEyebrow = React.forwardRef<HTMLParagraphElement, CardEyebrowProps>(
 );
 CardEyebrow.displayName = "CardEyebrow";
 
+const cardTitleVariants = tv({
+	base: "typography-subheading-small text-text-primary",
+});
+
 export interface CardTitleProps
 	extends React.HTMLAttributes<HTMLHeadingElement> {
 	/**
@@ -142,7 +184,7 @@ const CardTitle = React.forwardRef<HTMLHeadingElement, CardTitleProps>(
 		return (
 			<Component
 				ref={ref}
-				className={cn("typography-subheading-small text-gray-1100", className)}
+				className={cardTitleVariants({ class: className })}
 				{...props}
 			/>
 		);
@@ -150,6 +192,10 @@ const CardTitle = React.forwardRef<HTMLHeadingElement, CardTitleProps>(
 );
 CardTitle.displayName = "CardTitle";
 
+const cardDescriptionVariants = tv({
+	base: "typography-body-small text-text-secondary",
+});
+
 export interface CardDescriptionProps
 	extends React.HTMLAttributes<HTMLParagraphElement> {}
 
@@ -163,13 +209,17 @@ const CardDescription = React.forwardRef<
 	return (
 		<p
 			ref={ref}
-			className={cn("typography-body-small text-gray-800", className)}
+			className={cardDescriptionVariants({ class: className })}
 			{...props}
 		/>
 	);
 });
 CardDescription.displayName = "CardDescription";
 
+const cardBodyVariants = tv({
+	base: "flex w-full flex-col gap-spatial-card-small-gap",
+});
+
 export interface CardBodyProps extends React.HTMLAttributes<HTMLDivElement> {}
 
 /**
@@ -181,10 +231,7 @@ const CardBody = React.forwardRef<HTMLDivElement, CardBodyProps>(
 		return (
 			<div
 				ref={ref}
-				className={cn(
-					"flex w-full flex-col gap-spatial-card-small-gap",
-					className,
-				)}
+				className={cardBodyVariants({ class: className })}
 				{...props}
 			/>
 		);
@@ -192,6 +239,10 @@ const CardBody = React.forwardRef<HTMLDivElement, CardBodyProps>(
 );
 CardBody.displayName = "CardBody";
 
+const cardActionsVariants = tv({
+	base: "flex gap-spacing-12",
+});
+
 export interface CardActionsProps
 	extends React.HTMLAttributes<HTMLDivElement> {}
 
@@ -204,7 +255,7 @@ const CardActions = React.forwardRef<HTMLDivElement, CardActionsProps>(
 		return (
 			<div
 				ref={ref}
-				className={cn("flex gap-spacing-12", className)}
+				className={cardActionsVariants({ class: className })}
 				{...props}
 			/>
 		);
@@ -216,10 +267,17 @@ export {
 	Card,
 	cardVariants,
 	CardImage,
+	cardImageVariants,
 	CardContent,
+	cardContentVariants,
 	CardEyebrow,
+	cardEyebrowVariants,
 	CardTitle,
+	cardTitleVariants,
 	CardDescription,
+	cardDescriptionVariants,
 	CardBody,
+	cardBodyVariants,
 	CardActions,
+	cardActionsVariants,
 };

package/src/components/organisms/card/index.ts

@@ -15,5 +15,12 @@ export {
 	type CardProps,
 	CardTitle,
 	type CardTitleProps,
+	cardActionsVariants,
+	cardBodyVariants,
+	cardContentVariants,
+	cardDescriptionVariants,
+	cardEyebrowVariants,
+	cardImageVariants,
+	cardTitleVariants,
 	cardVariants,
 } from "./card";

package/src/components/organisms/navbar/navbar.tsx

@@ -1,3 +1,5 @@
+"use client";
+
 import { Dialog } from "@base-ui-components/react/dialog";
 import { Slot } from "@radix-ui/react-slot";
 import * as React from "react";

package/src/components/organisms/us-gov-banner/index.ts

@@ -1 +1,5 @@
-export { USGovBanner, type USGovBannerProps } from "./us-gov-banner";
+export {
+	USGovBanner,
+	type USGovBannerProps,
+	usGovBannerVariants,
+} from "./us-gov-banner";

package/src/components/organisms/us-gov-banner/us-gov-banner.tsx

@@ -1,7 +1,34 @@
 import * as React from "react";
-import { cn } from "@/lib/utils";
+import { tv, type VariantProps } from "tailwind-variants";
 
-export interface USGovBannerProps extends React.HTMLAttributes<HTMLDivElement> {
+const usGovBannerVariants = tv({
+	slots: {
+		root: "flex w-full items-center justify-center py-spacing-12",
+		content: "flex items-center gap-spacing-8",
+		text: "text-[11px] leading-[13px] tracking-[0.17px]",
+	},
+	variants: {
+		variant: {
+			default: {
+				root: "bg-gray-50",
+				content: "opacity-70",
+				text: "text-gray-900",
+			},
+			inverted: {
+				root: "bg-transparent",
+				content: "opacity-70",
+				text: "text-text-inverted",
+			},
+		},
+	},
+	defaultVariants: {
+		variant: "default",
+	},
+});
+
+export interface USGovBannerProps
+	extends React.HTMLAttributes<HTMLDivElement>,
+		VariantProps<typeof usGovBannerVariants> {
 	/**
 	 * Custom flag icon element. Defaults to a US flag SVG.
 	 */
@@ -17,31 +44,39 @@ export interface USGovBannerProps extends React.HTMLAttributes<HTMLDivElement> {
  * US Government official website banner.
  * Displays the official government website notice with flag icon.
  * Commonly placed at the very top of government websites.
+ *
+ * Variants:
+ * - default: Light background with dark text (for light pages)
+ * - inverted: Transparent background with white text/flag (for dark backgrounds/heroes)
+ *
+ * @example
+ * ```tsx
+ * // Default (light)
+ * <USGovBanner />
+ *
+ * // Inverted (for dark backgrounds)
+ * <USGovBanner variant="inverted" />
+ * ```
  */
 const USGovBanner = React.forwardRef<HTMLDivElement, USGovBannerProps>(
 	(
 		{
 			className,
+			variant,
 			flagIcon,
 			text = "An official website of the United States government",
 			...props
 		},
 		ref,
 	) => {
+		const styles = usGovBannerVariants({ variant });
+		const isInverted = variant === "inverted";
+
 		return (
-			<div
-				ref={ref}
-				className={cn(
-					"flex w-full items-center justify-center bg-gray-50 py-spacing-12",
-					className,
-				)}
-				{...props}
-			>
-				<div className="flex items-center gap-spacing-8 opacity-70">
-					{flagIcon ?? <DefaultUSFlag />}
-					<p className="text-[11px] leading-[13px] tracking-[0.17px] text-gray-900">
-						{text}
-					</p>
+			<div ref={ref} className={styles.root({ class: className })} {...props}>
+				<div className={styles.content()}>
+					{flagIcon ?? (isInverted ? <WhiteUSFlag /> : <DefaultUSFlag />)}
+					<p className={styles.text()}>{text}</p>
 				</div>
 			</div>
 		);
@@ -70,4 +105,25 @@ function DefaultUSFlag() {
 	);
 }
 
-export { USGovBanner };
+function WhiteUSFlag() {
+	return (
+		<svg
+			width="16"
+			height="12"
+			viewBox="0 0 16 12"
+			fill="none"
+			xmlns="http://www.w3.org/2000/svg"
+			aria-hidden="true"
+		>
+			<path d="M0 0H16V12H0V0Z" fill="white" fillOpacity="0.1" />
+			<path
+				d="M0 0H16V0.923077H0V0ZM0 1.84615H16V2.76923H0V1.84615ZM0 3.69231H16V4.61538H0V3.69231ZM0 5.53846H16V6.46154H0V5.53846ZM0 7.38462H16V8.30769H0V7.38462ZM0 9.23077H16V10.1538H0V9.23077ZM0 11.0769H16V12H0V11.0769Z"
+				fill="white"
+				fillOpacity="0.8"
+			/>
+			<path d="M0 0H8V6.46154H0V0Z" fill="white" fillOpacity="0.6" />
+		</svg>
+	);
+}
+
+export { USGovBanner, usGovBannerVariants };

package/src/components/sections/hero/hero.stories.tsx

@@ -1,5 +1,5 @@
 import type { Meta, StoryObj } from "@storybook/react-vite";
-import { Hero, HeroBackground } from ".";
+import { Hero, HeroBackground, HeroContent, HeroHeader } from ".";
 
 const meta: Meta<typeof Hero> = {
 	title: "Sections/Hero",
@@ -30,6 +30,11 @@ const meta: Meta<typeof Hero> = {
 			control: "color",
 			description: "Color of the overlay",
 		},
+		borderRadius: {
+			control: "text",
+			description:
+				"Border radius for the hero container (e.g., '0 0 20px 20px')",
+		},
 	},
 } as Meta<typeof Hero>;
 
@@ -146,6 +151,124 @@ export const WithCloudflareStream: Story = {
 	),
 };
 
+// =============================================================================
+// Composition - Top Slot & Border Radius
+// =============================================================================
+
+/**
+ * Mock banner component for story demonstration
+ */
+const MockBanner = () => (
+	<div className="bg-gray-1200 px-spacing-16 py-spacing-8 text-center text-14 text-text-inverted">
+		An official website of the United States government
+	</div>
+);
+
+/**
+ * Mock navigation component for story demonstration
+ */
+const MockNavigation = () => (
+	<nav className="flex items-center justify-between px-spacing-56 py-spacing-16">
+		<div className="flex items-center gap-spacing-24">
+			<div className="size-48 rounded-full bg-gray-50" />
+			<div className="flex gap-spacing-24 text-14 text-text-inverted">
+				<span className="cursor-pointer hover:opacity-80">Link 1</span>
+				<span className="cursor-pointer hover:opacity-80">Link 2</span>
+			</div>
+		</div>
+		<div className="text-14 text-text-inverted">Actions</div>
+	</nav>
+);
+
+/**
+ * Hero with top slot containing a banner
+ */
+export const WithTopSlot: Story = {
+	render: () => (
+		<Hero
+			variant="A1"
+			title="Hero with Top Slot"
+			background="#1a1a1a"
+			top={<MockBanner />}
+		/>
+	),
+};
+
+/**
+ * Hero with rounded bottom corners
+ */
+export const WithRoundedCorners: Story = {
+	render: () => (
+		<div className="bg-bg-page p-spacing-32">
+			<Hero
+				variant="A1"
+				title="Rounded Corners"
+				background="#1a1a1a"
+				borderRadius="0 0 20px 20px"
+			/>
+		</div>
+	),
+};
+
+/**
+ * Hero with both top slot and rounded corners
+ */
+export const WithTopAndRoundedCorners: Story = {
+	render: () => (
+		<div className="bg-bg-page">
+			<Hero
+				variant="A1"
+				title="Full Composition"
+				background={
+					<HeroBackground.Image
+						src="https://images.unsplash.com/photo-1451187580459-43490279c0fa?w=1920&q=80"
+						position="center"
+					/>
+				}
+				overlayOpacity={0.5}
+				borderRadius="0 0 20px 20px"
+				top={
+					<>
+						<MockBanner />
+						<MockNavigation />
+					</>
+				}
+			>
+				<p className="mt-spacing-16 max-w-[560px] text-20 text-text-inverted">
+					A subtitle or description can be added as children
+				</p>
+			</Hero>
+		</div>
+	),
+};
+
+// =============================================================================
+// Sub-components
+// =============================================================================
+
+/**
+ * Using Hero.Header and Hero.Content sub-components directly
+ * for more control over the layout
+ */
+export const UsingSubComponents: Story = {
+	render: () => (
+		<section className="relative flex min-h-[80vh] flex-col bg-gray-1200">
+			<HeroHeader>
+				<MockBanner />
+				<MockNavigation />
+			</HeroHeader>
+			<HeroContent className="flex-1 justify-end">
+				<h1 className="text-64 font-medium text-text-inverted lg:text-128">
+					Custom Layout
+				</h1>
+				<p className="mt-spacing-16 text-20 text-text-inverted">
+					Using HeroHeader and HeroContent sub-components
+				</p>
+			</HeroContent>
+		</section>
+	),
+};
+
 // =============================================================================
 // Responsive Variants - A1 (Content at bottom)
 // =============================================================================

package/src/components/sections/hero/hero.test.tsx

@@ -63,73 +63,76 @@ describe("Hero", () => {
 	});
 
 	describe("Styling", () => {
-		test("applies default background color", async () => {
+		test("applies default background color when no background provided", async () => {
 			render(<Hero title="Default" data-testid="hero" />);
 
 			const hero = page.getByTestId("hero");
-			await expect.element(hero).toHaveClass(/bg-gray-1000/);
+			// Uses semantic token bg-bg-overlay for default background
+			await expect.element(hero).toHaveClass(/bg-bg-overlay/);
 		});
 
-		test("applies responsive height classes", async () => {
+		test("applies minimum height for viewport coverage", async () => {
 			render(<Hero title="Responsive" data-testid="hero" />);
 
 			const hero = page.getByTestId("hero");
-			// Mobile height
-			await expect.element(hero).toHaveClass(/h-\[500px\]/);
+			// Uses min-h-[80vh] for all variants
+			await expect.element(hero).toHaveClass(/min-h-\[80vh\]/);
 		});
 	});
 
 	describe("Variants", () => {
-		test("A1 variant applies items-end alignment (default)", async () => {
+		test("A1 variant applies flex column layout", async () => {
 			render(<Hero title="A1 Hero" variant="A1" data-testid="hero" />);
 
 			const hero = page.getByTestId("hero");
-			await expect.element(hero).toHaveClass(/items-end/);
+			await expect.element(hero).toHaveClass(/flex-col/);
 		});
 
 		test("A1 variant is default when no variant specified", async () => {
 			render(<Hero title="Default Hero" data-testid="hero" />);
 
 			const hero = page.getByTestId("hero");
-			await expect.element(hero).toHaveClass(/items-end/);
+			// Default variant still applies min-height and flex layout
+			await expect.element(hero).toHaveClass(/min-h-\[80vh\]/);
+			await expect.element(hero).toHaveClass(/flex-col/);
 		});
 
-		test("A2 variant applies items-start alignment", async () => {
+		test("A2 variant applies flex column layout", async () => {
 			render(<Hero title="A2 Hero" variant="A2" data-testid="hero" />);
 
 			const hero = page.getByTestId("hero");
-			await expect.element(hero).toHaveClass(/items-start/);
+			await expect.element(hero).toHaveClass(/flex-col/);
 		});
 
-		test("A3 variant applies items-center alignment", async () => {
+		test("A3 variant applies flex column layout", async () => {
 			render(<Hero title="A3 Hero" variant="A3" data-testid="hero" />);
 
 			const hero = page.getByTestId("hero");
-			await expect.element(hero).toHaveClass(/items-center/);
+			await expect.element(hero).toHaveClass(/flex-col/);
 		});
 
 		test("A1 variant maintains common styles", async () => {
 			render(<Hero title="A1 Hero" variant="A1" data-testid="hero" />);
 
 			const hero = page.getByTestId("hero");
-			await expect.element(hero).toHaveClass(/bg-gray-1000/);
-			await expect.element(hero).toHaveClass(/h-\[500px\]/);
+			await expect.element(hero).toHaveClass(/bg-bg-overlay/);
+			await expect.element(hero).toHaveClass(/min-h-\[80vh\]/);
 		});
 
 		test("A2 variant maintains common styles", async () => {
 			render(<Hero title="A2 Hero" variant="A2" data-testid="hero" />);
 
 			const hero = page.getByTestId("hero");
-			await expect.element(hero).toHaveClass(/bg-gray-1000/);
-			await expect.element(hero).toHaveClass(/h-\[500px\]/);
+			await expect.element(hero).toHaveClass(/bg-bg-overlay/);
+			await expect.element(hero).toHaveClass(/min-h-\[80vh\]/);
 		});
 
 		test("A3 variant maintains common styles", async () => {
 			render(<Hero title="A3 Hero" variant="A3" data-testid="hero" />);
 
 			const hero = page.getByTestId("hero");
-			await expect.element(hero).toHaveClass(/bg-gray-1000/);
-			await expect.element(hero).toHaveClass(/h-\[500px\]/);
+			await expect.element(hero).toHaveClass(/bg-bg-overlay/);
+			await expect.element(hero).toHaveClass(/min-h-\[80vh\]/);
 		});
 	});
 });