@nationaldesignstudio/react 0.1.0 → 0.3.0

package/src/components/sections/banner/banner.tsx

@@ -26,13 +26,13 @@ const bannerVariants = tv({
 		"lg:px-spacing-72 lg:pb-spacing-72 lg:pt-0",
 	],
 	variants: {
-		variant: {
+		colorScheme: {
 			light: "bg-gray-50",
 			dark: "bg-gray-1200",
 		},
 	},
 	defaultVariants: {
-		variant: "light",
+		colorScheme: "light",
 	},
 });
 
@@ -74,9 +74,9 @@ export interface BannerProps
  *   />
  * </div>
  *
- * // Dark variant
+ * // Dark colorScheme
  * <Banner
- *   variant="dark"
+ *   colorScheme="dark"
  *   heading="Still Have Questions?"
  *   description="Contact us at support@example.com"
  *   action={<Button variant="secondary">Email Us</Button>}
@@ -84,19 +84,19 @@ export interface BannerProps
  * ```
  */
 const Banner = React.forwardRef<HTMLElement, BannerProps>(
-	({ className, variant, heading, description, action, ...props }, ref) => {
+	({ className, colorScheme, heading, description, action, ...props }, ref) => {
 		return (
 			<section
 				ref={ref}
-				className={bannerVariants({ variant, class: className })}
+				className={bannerVariants({ colorScheme, class: className })}
 				{...props}
 			>
-				{/* Inner container with border-top for dark variant */}
+				{/* Inner container with border-top for dark colorScheme */}
 				<div
 					className={cn(
 						// Uses primitive spacing tokens
 						"flex flex-col md:flex-row gap-spacing-20 items-start md:items-center md:justify-between",
-						variant === "dark" && "border-t border-gray-700 py-spacing-36",
+						colorScheme === "dark" && "border-t border-gray-700 py-spacing-36",
 					)}
 				>
 					{/* Copy section */}
@@ -104,7 +104,7 @@ const Banner = React.forwardRef<HTMLElement, BannerProps>(
 						<h2
 							className={cn(
 								"typography-subheading-small",
-								variant === "dark" ? "text-gray-100" : "text-gray-900",
+								colorScheme === "dark" ? "text-gray-100" : "text-gray-900",
 							)}
 						>
 							{heading}
@@ -112,7 +112,7 @@ const Banner = React.forwardRef<HTMLElement, BannerProps>(
 						<p
 							className={cn(
 								"typography-body-small",
-								variant === "dark" ? "text-gray-500" : "text-gray-800",
+								colorScheme === "dark" ? "text-gray-500" : "text-gray-800",
 							)}
 						>
 							{description}

package/src/components/sections/card-grid/card-grid.tsx

@@ -83,7 +83,7 @@ const CardGrid = React.forwardRef<HTMLElement, CardGridProps>(
 				<h2
 					className={cn(
 						"col-full",
-						"typography-headline-small text-gray-900",
+						"typography-h4 text-gray-900",
 						// Gap after title: mobile default, md: 56px, lg: 64px
 						"mb-spacing-36 md:mb-spacing-56 lg:mb-spacing-64",
 					)}

package/src/components/sections/faq-section/faq-section.stories.tsx

@@ -9,10 +9,10 @@ const meta = {
 		layout: "fullscreen",
 	},
 	argTypes: {
-		variant: {
+		colorScheme: {
 			control: "select",
 			options: ["dark", "light"],
-			description: "Color variant",
+			description: "Color scheme",
 		},
 		title: {
 			control: "text",
@@ -61,7 +61,7 @@ export const Playground: Story = {
 	),
 };
 Playground.args = {
-	variant: "dark",
+	colorScheme: "light",
 	title: "Frequently Asked Questions",
 };
 
@@ -110,12 +110,12 @@ export const Default: Story = {
 // =============================================================================
 
 /**
- * Dark variant (default) - dark background with light text
+ * Dark variant - dark background with light text
  */
 export const DarkVariant: Story = {
 	render: () => (
-		<FaqSection variant="dark">
-			<Accordion defaultExpanded="faq-1">
+		<FaqSection colorScheme="dark">
+			<Accordion colorScheme="dark" defaultExpanded="faq-1">
 				<AccordionItem
 					id="faq-1"
 					title="What is the US Tech Force (Tech Force)?"
@@ -147,7 +147,7 @@ export const DarkVariant: Story = {
  */
 export const LightVariant: Story = {
 	render: () => (
-		<FaqSection variant="light">
+		<FaqSection colorScheme="light">
 			<Accordion defaultExpanded="faq-1">
 				<AccordionItem
 					id="faq-1"

package/src/components/sections/faq-section/faq-section.tsx

@@ -41,7 +41,7 @@ export interface FaqSectionProps
  * </FaqSection>
  *
  * // With custom title
- * <FaqSection title="Common Questions" variant="light">
+ * <FaqSection title="Common Questions" colorScheme="light">
  *   ...
  * </FaqSection>
  * ```
@@ -50,7 +50,7 @@ const FaqSection = React.forwardRef<HTMLElement, FaqSectionProps>(
 	(
 		{
 			className,
-			variant = "dark",
+			colorScheme = "light",
 			title = "Frequently Asked Questions",
 			children,
 			layout,
@@ -61,14 +61,14 @@ const FaqSection = React.forwardRef<HTMLElement, FaqSectionProps>(
 		return (
 			<TwoColumnSection
 				ref={ref}
-				variant={variant}
+				colorScheme={colorScheme}
 				layout={layout ?? undefined}
 				title={title}
 				className={cn(
 					// Override title typography to be larger
-					"[&_h2]:typography-subheading-large",
+					"[&_h2]:typography-h4",
 					// Accordion typography overrides
-					"[&_button]:typography-body-large [&_button]:md:typography-subheading-small",
+					"[&_button]:typography-body-large [&_button]:md:typography-h5",
 					"[&_[data-accordion-panel]]:typography-body-medium [&_[data-accordion-panel]]:md:typography-body-large",
 					className,
 				)}

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

@@ -67,8 +67,8 @@ describe("Hero", () => {
 			render(<Hero title="Default" data-testid="hero" />);
 
 			const hero = page.getByTestId("hero");
-			// Uses semantic token bg-bg-overlay for default background
-			await expect.element(hero).toHaveClass(/bg-bg-overlay/);
+			// Uses semantic token bg-bg-page for default dark colorScheme
+			await expect.element(hero).toHaveClass(/bg-bg-page/);
 		});
 
 		test("applies minimum height for viewport coverage", async () => {
@@ -115,7 +115,7 @@ describe("Hero", () => {
 			render(<Hero title="A1 Hero" variant="A1" data-testid="hero" />);
 
 			const hero = page.getByTestId("hero");
-			await expect.element(hero).toHaveClass(/bg-bg-overlay/);
+			await expect.element(hero).toHaveClass(/bg-bg-page/);
 			await expect.element(hero).toHaveClass(/min-h-\[80vh\]/);
 		});
 
@@ -123,7 +123,7 @@ describe("Hero", () => {
 			render(<Hero title="A2 Hero" variant="A2" data-testid="hero" />);
 
 			const hero = page.getByTestId("hero");
-			await expect.element(hero).toHaveClass(/bg-bg-overlay/);
+			await expect.element(hero).toHaveClass(/bg-bg-page/);
 			await expect.element(hero).toHaveClass(/min-h-\[80vh\]/);
 		});
 
@@ -131,7 +131,7 @@ describe("Hero", () => {
 			render(<Hero title="A3 Hero" variant="A3" data-testid="hero" />);
 
 			const hero = page.getByTestId("hero");
-			await expect.element(hero).toHaveClass(/bg-bg-overlay/);
+			await expect.element(hero).toHaveClass(/bg-bg-page/);
 			await expect.element(hero).toHaveClass(/min-h-\[80vh\]/);
 		});
 	});

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

@@ -18,56 +18,54 @@ export {
 	type BackgroundVideoProps as HeroBackgroundVideoProps,
 } from "@/components/atoms/background";
 
-// =============================================================================
-// Hero Variants
-// =============================================================================
+const DEFAULT_TITLE_TYPOGRAPHY =
+	"text-64 leading-64 tracking-64 md:text-128 md:leading-128 md:tracking-128 lg:text-192 lg:leading-192 lg:tracking-192 font-medium";
 
-/**
- * Hero variants based on Figma BaseKit / Heros
- *
- * Slots:
- * - root: The outer container
- * - top: Full-width slot at top for banners/nav (no padding)
- * - content: Padded content area with alignment
- *
- * Variants:
- * - A1: Content aligned at bottom (default)
- * - A2: Content aligned at top
- * - A3: Content centered
- */
 const heroVariants = tv({
 	slots: {
 		root: "relative flex w-full flex-col overflow-hidden",
 		top: "relative z-10 w-full",
 		content: [
 			"relative z-10 mx-auto flex w-full max-w-screen-xl flex-1 flex-col",
-			// Mobile padding
 			"p-spacing-20",
-			// Tablet padding
 			"md:p-spacing-56",
 		],
+		title: DEFAULT_TITLE_TYPOGRAPHY,
 	},
 	variants: {
 		variant: {
-			// A1: Content at bottom
 			A1: {
 				root: "min-h-[80vh]",
 				content: ["justify-end", "lg:p-spacing-72"],
 			},
-			// A2: Content at top
 			A2: {
 				root: "min-h-[80vh]",
 				content: ["justify-start", "lg:p-spacing-64"],
 			},
-			// A3: Content centered
 			A3: {
 				root: "min-h-[80vh]",
 				content: ["items-center justify-center", "lg:p-spacing-64"],
 			},
 		},
+		colorScheme: {
+			dark: {
+				root: "bg-bg-page",
+				title: "text-text-primary",
+			},
+			light: {
+				root: "bg-gray-900",
+				title: "text-text-inverted",
+			},
+		},
+		hasBackground: {
+			true: {
+				root: "bg-transparent",
+			},
+		},
 	},
 	defaultVariants: {
 		variant: "A1",
+		colorScheme: "dark",
 	},
 });
 
@@ -141,6 +139,12 @@ export interface HeroProps
 	 * Default: "text-64 leading-64 tracking-64 md:text-128 md:leading-128 md:tracking-128 lg:text-192 lg:leading-192 lg:tracking-192"
 	 */
 	titleClassName?: string;
+	/**
+	 * Color scheme for text content.
+	 * - dark: Dark text for use on light backgrounds (default)
+	 * - light: Light text for use on dark backgrounds
+	 */
+	colorScheme?: "dark" | "light";
 	/**
 	 * Content for the top slot (full-width, no padding).
 	 * Use for USGovBanner, Navigation, etc.
@@ -172,13 +176,6 @@ export interface HeroProps
 	theme?: ComponentTheme;
 }
 
-/**
- * Default responsive typography for hero title using primitive tokens
- * Mobile: 64px, Tablet: 128px, Desktop: 192px
- */
-const DEFAULT_TITLE_TYPOGRAPHY =
-	"text-64 leading-64 tracking-64 md:text-128 md:leading-128 md:tracking-128 lg:text-192 lg:leading-192 lg:tracking-192 font-medium";
-
 /**
  * Checks if the background prop is a color string
  */
@@ -238,6 +235,7 @@ const Hero = React.forwardRef<HTMLElement, HeroProps>(
 			children,
 			title,
 			titleClassName,
+			colorScheme = "dark",
 			top,
 			variant,
 			background,
@@ -250,9 +248,13 @@ const Hero = React.forwardRef<HTMLElement, HeroProps>(
 		},
 		ref,
 	) => {
-		const styles = heroVariants({ variant });
 		const isColor = isColorString(background);
 		const hasMediaBackground = background && !isColor;
+		const styles = heroVariants({
+			variant,
+			colorScheme,
+			hasBackground: !!background,
+		});
 		const themeStyles = themeToStyleVars(theme);
 		const combinedStyles = {
 			...themeStyles,
@@ -264,22 +266,14 @@ const Hero = React.forwardRef<HTMLElement, HeroProps>(
 		return (
 			<section
 				ref={ref}
-				className={styles.root({
-					class: [
-						// Default background color when no background is provided
-						!background && "bg-bg-overlay",
-						className,
-					],
-				})}
+				className={styles.root({ class: className })}
 				style={
 					Object.keys(combinedStyles).length > 0 ? combinedStyles : undefined
 				}
 				{...props}
 			>
-				{/* Background slot (image, video, or stream) */}
 				{hasMediaBackground && background}
 
-				{/* Overlay */}
 				{hasMediaBackground && overlayOpacity > 0 && (
 					<BackgroundOverlay
 						opacity={overlayOpacity}
@@ -292,23 +286,11 @@ const Hero = React.forwardRef<HTMLElement, HeroProps>(
 					/>
 				)}
 
-				{/* Top slot - full width, no padding (for banners, nav) */}
 				{top && <div className={styles.top()}>{top}</div>}
 
-				{/* Content slot - padded area with alignment */}
 				<div className={styles.content()}>
-					{/* Title - convenience prop, renders h1 with default typography */}
 					{title && (
-						<h1
-							className={[
-								titleClassName || DEFAULT_TITLE_TYPOGRAPHY,
-								"text-text-inverted",
-							]
-								.filter(Boolean)
-								.join(" ")}
-						>
-							{title}
-						</h1>
+						<h1 className={styles.title({ class: titleClassName })}>{title}</h1>
 					)}
 
 					{/* Children - always render if provided */}

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

@@ -131,7 +131,7 @@ describe("Prose", () => {
 			);
 
 			const heading = page.getByRole("heading", { name: "H2 Test" });
-			await expect.element(heading).toHaveClass(/typography-headline-medium/);
+			await expect.element(heading).toHaveClass(/typography-h3/);
 		});
 
 		test("h3 heading has correct typography class", async () => {
@@ -144,7 +144,7 @@ describe("Prose", () => {
 			);
 
 			const heading = page.getByRole("heading", { name: "H3 Test" });
-			await expect.element(heading).toHaveClass(/typography-headline-small/);
+			await expect.element(heading).toHaveClass(/typography-h4/);
 		});
 	});
 

package/src/components/sections/prose/prose.tsx

@@ -52,15 +52,14 @@ export interface ProseSectionProps extends React.HTMLAttributes<HTMLElement> {
  * A section within Prose content, containing a heading and body text.
  *
  * Responsive typography:
- * - h2: Uses typography-headline-medium (42px mobile → 56px tablet → 72px desktop)
- * - h3: Uses typography-headline-small (32px mobile → 42px tablet → 56px desktop)
- * - Body: Uses typography-body-medium (16px mobile/tablet → 18px desktop)
+ * - h2: Uses typography-h3
+ * - h3: Uses typography-h4
+ * - Body: Uses typography-body-medium
  */
 const ProseSection = React.forwardRef<HTMLElement, ProseSectionProps>(
 	({ className, heading, as = "h2", children, ...props }, ref) => {
 		const Heading = as;
-		const headingClass =
-			as === "h2" ? "typography-headline-medium" : "typography-headline-small";
+		const headingClass = as === "h2" ? "typography-h3" : "typography-h4";
 
 		return (
 			<section

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

@@ -51,7 +51,7 @@ Playground.args = {
 	headline: "Feature Headline",
 	body: "Use rivers to present content with supporting media. They work great for feature highlights, product showcases, and storytelling sections.",
 	primaryAction: <Button>Primary Action</Button>,
-	secondaryAction: <Button variant="charcoalOutline">Secondary</Button>,
+	secondaryAction: <Button variant="outline">Secondary</Button>,
 	media: <PlaceholderImage />,
 };
 
@@ -69,7 +69,7 @@ export const VariantA: Story = {
 			headline="Text Left, Media Right"
 			body="Variant A places the text content on the left (9 columns) and media on the right (15 columns) on desktop viewports. On mobile and tablet, they stack vertically."
 			primaryAction={<Button>Primary Action</Button>}
-			secondaryAction={<Button variant="charcoalOutline">Secondary</Button>}
+			secondaryAction={<Button variant="outline">Secondary</Button>}
 			media={<PlaceholderImage />}
 		/>
 	),
@@ -85,7 +85,7 @@ export const VariantB: Story = {
 			headline="Media Left, Text Right"
 			body="Variant B places the media on the left (15 columns) and text content on the right (9 columns) on desktop viewports. On mobile and tablet, they stack vertically with text first."
 			primaryAction={<Button>Primary Action</Button>}
-			secondaryAction={<Button variant="charcoalOutline">Secondary</Button>}
+			secondaryAction={<Button variant="outline">Secondary</Button>}
 			media={<PlaceholderImage />}
 		/>
 	),
@@ -102,7 +102,7 @@ export const VariantADesktop: Story = {
 			headline="Desktop View"
 			body="On desktop (lg, 1440px), the content spans 9 columns and the media spans 15 columns in a horizontal layout."
 			primaryAction={<Button>Primary</Button>}
-			secondaryAction={<Button variant="charcoalOutline">Secondary</Button>}
+			secondaryAction={<Button variant="outline">Secondary</Button>}
 			media={<PlaceholderImage />}
 		/>
 	),
@@ -118,7 +118,7 @@ export const VariantATablet: Story = {
 			headline="Tablet View"
 			body="On tablet (md, 768px), the content and media stack vertically with the text above the media."
 			primaryAction={<Button>Primary</Button>}
-			secondaryAction={<Button variant="charcoalOutline">Secondary</Button>}
+			secondaryAction={<Button variant="outline">Secondary</Button>}
 			media={<PlaceholderImage />}
 		/>
 	),
@@ -135,7 +135,7 @@ export const VariantAMobile: Story = {
 			body="On mobile (sm, 320px), content is stacked with smaller button sizing."
 			primaryAction={<Button size="sm">Primary</Button>}
 			secondaryAction={
-				<Button size="sm" variant="charcoalOutline">
+				<Button size="sm" variant="outline">
 					Secondary
 				</Button>
 			}
@@ -154,7 +154,7 @@ export const VariantBDesktop: Story = {
 			headline="Desktop View - Reversed"
 			body="Variant B reverses the layout, placing media on the left and content on the right."
 			primaryAction={<Button>Primary</Button>}
-			secondaryAction={<Button variant="charcoalOutline">Secondary</Button>}
+			secondaryAction={<Button variant="outline">Secondary</Button>}
 			media={<PlaceholderImage />}
 		/>
 	),
@@ -224,7 +224,7 @@ export const WithImage: Story = {
 			headline="Real World Example"
 			body="Rivers work great with actual images, videos, or any media content. The media column is designed to accommodate various aspect ratios."
 			primaryAction={<Button>Get Started</Button>}
-			secondaryAction={<Button variant="charcoalOutline">Learn More</Button>}
+			secondaryAction={<Button variant="outline">Learn More</Button>}
 			media={
 				<img
 					src="https://images.unsplash.com/photo-1551434678-e076c223a692?w=800&h=600&fit=crop"

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

@@ -246,7 +246,7 @@ describe("River", () => {
 			);
 
 			const headline = page.getByRole("heading", { level: 2 });
-			await expect.element(headline).toHaveClass(/typography-headline-small/);
+			await expect.element(headline).toHaveClass(/typography-h4/);
 			await expect.element(headline).toHaveClass(/text-gray-900/);
 		});
 

package/src/components/sections/river/river.tsx

@@ -77,7 +77,7 @@ export interface RiverProps
  *     headline="Feature Headline"
  *     body="Description of the feature..."
  *     primaryAction={<Button>Primary</Button>}
- *     secondaryAction={<Button variant="charcoalOutline">Secondary</Button>}
+ *     secondaryAction={<Button variant="outline">Secondary</Button>}
  *     media={<img src="..." alt="Feature" />}
  *   />
  * </div>
@@ -107,9 +107,7 @@ const River = React.forwardRef<HTMLElement, RiverProps>(
 			>
 				{/* Text content with 16px gap - uses primitive spacing tokens */}
 				<div className="flex flex-col gap-spacing-16">
-					<h2 className="typography-headline-small text-gray-900">
-						{headline}
-					</h2>
+					<h2 className="typography-h4 text-gray-900">{headline}</h2>
 					<p className="typography-body-small text-gray-800">{body}</p>
 				</div>
 

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

@@ -43,7 +43,11 @@ Playground.args = {
 	headline: "Brand-Large/Headline/Small",
 	body: "A river pattern stacks content in a simple vertical flow: one clear heading, a short block of copy, then the next step. It's ideal for guiding citizens through a process or story, keeping focus moving straight down the page with minimal choices and well-timed calls to action.",
 	primaryAction: <Button>Primary</Button>,
-	secondaryAction: <Button variant="charcoalOutline">Secondary</Button>,
+	secondaryAction: (
+		<Button variant="outline" colorScheme="light">
+			Secondary
+		</Button>
+	),
 	backgroundMedia: <PlaceholderBackground />,
 };
 
@@ -57,7 +61,11 @@ export const Desktop: Story = {
 			headline="Brand-Large/Headline/Small"
 			body="A river pattern stacks content in a simple vertical flow: one clear heading, a short block of copy, then the next step. It's ideal for guiding citizens through a process or story, keeping focus moving straight down the page with minimal choices and well-timed calls to action."
 			primaryAction={<Button>Primary</Button>}
-			secondaryAction={<Button variant="charcoalOutline">Secondary</Button>}
+			secondaryAction={
+				<Button variant="outline" colorScheme="light">
+					Secondary
+				</Button>
+			}
 			backgroundMedia={<PlaceholderBackground />}
 		/>
 	),
@@ -72,7 +80,11 @@ export const Tablet: Story = {
 			headline="Brand-Large/Headline/Small"
 			body="A river pattern stacks content in a simple vertical flow: one clear heading, a short block of copy, then the next step. It's ideal for guiding citizens through a process or story, keeping focus moving straight down the page with minimal choices and well-timed calls to action."
 			primaryAction={<Button>Primary</Button>}
-			secondaryAction={<Button variant="charcoalOutline">Secondary</Button>}
+			secondaryAction={
+				<Button variant="outline" colorScheme="light">
+					Secondary
+				</Button>
+			}
 			backgroundMedia={<PlaceholderBackground />}
 		/>
 	),
@@ -88,7 +100,7 @@ export const Mobile: Story = {
 			body="A river pattern stacks content in a simple vertical flow: one clear heading, a short block of copy, then the next step. It's ideal for guiding citizens through a process or story, keeping focus moving straight down the page with minimal choices and well-timed calls to action."
 			primaryAction={<Button size="sm">Primary</Button>}
 			secondaryAction={
-				<Button size="sm" variant="charcoalOutline">
+				<Button size="sm" variant="outline" colorScheme="light">
 					Secondary
 				</Button>
 			}
@@ -113,7 +125,11 @@ export const WithImage: Story = {
 			headline="Work with Purpose"
 			body="Join a team that's building the future of government services. We're looking for passionate individuals who want to make a difference."
 			primaryAction={<Button>View Careers</Button>}
-			secondaryAction={<Button variant="charcoalOutline">Learn More</Button>}
+			secondaryAction={
+				<Button variant="outline" colorScheme="light">
+					Learn More
+				</Button>
+			}
 			backgroundMedia={<ImageBackground />}
 		/>
 	),
@@ -142,7 +158,11 @@ export const WithVideoPlaceholder: Story = {
 			headline="Experience Innovation"
 			body="See how modern technology is transforming the way government serves its citizens."
 			primaryAction={<Button>Watch Video</Button>}
-			secondaryAction={<Button variant="charcoalOutline">Learn More</Button>}
+			secondaryAction={
+				<Button variant="outline" colorScheme="light">
+					Learn More
+				</Button>
+			}
 			backgroundMedia={
 				<div className="absolute inset-0 bg-gray-800 flex items-center justify-center">
 					<span className="text-gray-400 typography-body-small">
@@ -163,7 +183,11 @@ export const WithNdstudioFooter: Story = {
 			headline="Work with Purpose"
 			body="Join a team that's building the future of government services. We're looking for passionate individuals who want to make a difference."
 			primaryAction={<Button>View Careers</Button>}
-			secondaryAction={<Button variant="charcoalOutline">Learn More</Button>}
+			secondaryAction={
+				<Button variant="outline" colorScheme="light">
+					Learn More
+				</Button>
+			}
 			backgroundMedia={<ImageBackground />}
 			footer={<NdstudioFooter />}
 		/>

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

@@ -220,7 +220,7 @@ describe("Tout", () => {
 			);
 
 			const headline = page.getByRole("heading", { level: 2 });
-			await expect.element(headline).toHaveClass(/typography-headline-small/);
+			await expect.element(headline).toHaveClass(/typography-h4/);
 			await expect.element(headline).toHaveClass(/text-gray-900/);
 		});