@nationaldesignstudio/react 0.1.0 → 0.2.0

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,7 +61,7 @@ const FaqSection = React.forwardRef<HTMLElement, FaqSectionProps>(
 		return (
 			<TwoColumnSection
 				ref={ref}
-				variant={variant}
+				colorScheme={colorScheme}
 				layout={layout ?? undefined}
 				title={title}
 				className={cn(

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/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.tsx

@@ -16,10 +16,8 @@ const toutVariants = tv({
 		"h-[600px] md:h-[750px] lg:h-[900px]",
 	],
 	variants: {
-		variant: {
-			// Default light content styling
+		colorScheme: {
 			light: "",
-			// Dark content styling
 			dark: "",
 		},
 		align: {
@@ -28,7 +26,7 @@ const toutVariants = tv({
 		},
 	},
 	defaultVariants: {
-		variant: "light",
+		colorScheme: "light",
 		align: "left",
 	},
 });
@@ -39,7 +37,7 @@ const toutVariants = tv({
  * A full-bleed section with a background image and overlaid content.
  * Content can be positioned on the left side or centered.
  *
- * Variants:
+ * Color schemes:
  * - light: Light text styling (default)
  * - dark: Dark text styling
  *
@@ -121,7 +119,7 @@ const Tout = React.forwardRef<HTMLElement, ToutProps>(
 	(
 		{
 			className,
-			variant = "light",
+			colorScheme = "light",
 			align = "left",
 			headline,
 			body,
@@ -136,13 +134,13 @@ const Tout = React.forwardRef<HTMLElement, ToutProps>(
 		ref,
 	) => {
 		const isCentered = align === "center";
-		const isDark = variant === "dark";
+		const isDark = colorScheme === "dark";
 		const themeStyles = themeToStyleVars(theme);
 
 		return (
 			<section
 				ref={ref}
-				className={toutVariants({ variant, align, class: className })}
+				className={toutVariants({ colorScheme, align, class: className })}
 				style={{ ...themeStyles, ...style }}
 				{...props}
 			>

package/src/components/sections/two-column-section/two-column-section.stories.tsx

@@ -8,10 +8,10 @@ const meta: Meta<typeof TwoColumnSection> = {
 		layout: "fullscreen",
 	},
 	argTypes: {
-		variant: {
+		colorScheme: {
 			control: "select",
 			options: ["dark", "light"],
-			description: "Color variant",
+			description: "Color scheme",
 		},
 		title: {
 			control: "text",
@@ -35,7 +35,7 @@ export const Playground: Story = {
 	render: (args) => <TwoColumnSection {...args} />,
 };
 Playground.args = {
-	variant: "dark",
+	colorScheme: "dark",
 	title: "US Tech Force",
 	lead: "The US Tech Force is recruiting an elite corps of engineers to build the next generation of government technology. Backed by the White House, Tech Force will tackle the most complex and large-scale civic and defense challenges of our era – from administering critical financial infrastructure at the Treasury Department to advancing cutting-edge programs at the Department of War – and everything in between.",
 	children: (
@@ -73,7 +73,7 @@ Playground.args = {
 export const DarkVariant: Story = {
 	render: () => (
 		<TwoColumnSection
-			variant="dark"
+			colorScheme="dark"
 			title="US Tech Force"
 			lead="The US Tech Force is recruiting an elite corps of engineers to build the next generation of government technology."
 		>
@@ -95,7 +95,7 @@ export const DarkVariant: Story = {
 export const LightVariant: Story = {
 	render: () => (
 		<TwoColumnSection
-			variant="light"
+			colorScheme="light"
 			title="US Tech Force"
 			lead="The US Tech Force is recruiting an elite corps of engineers to build the next generation of government technology."
 		>
@@ -118,7 +118,7 @@ export const LightVariant: Story = {
 export const Desktop: Story = {
 	render: () => (
 		<TwoColumnSection
-			variant="dark"
+			colorScheme="dark"
 			title="US Tech Force"
 			lead="The US Tech Force is recruiting an elite corps of engineers to build the next generation of government technology. Backed by the White House, Tech Force will tackle the most complex and large-scale civic and defense challenges of our era."
 		>
@@ -151,7 +151,7 @@ export const Desktop: Story = {
 export const Tablet: Story = {
 	render: () => (
 		<TwoColumnSection
-			variant="dark"
+			colorScheme="dark"
 			title="US Tech Force"
 			lead="The US Tech Force is recruiting an elite corps of engineers to build the next generation of government technology. Backed by the White House, Tech Force will tackle the most complex and large-scale civic and defense challenges of our era."
 		>
@@ -184,7 +184,7 @@ export const Tablet: Story = {
 export const Mobile: Story = {
 	render: () => (
 		<TwoColumnSection
-			variant="dark"
+			colorScheme="dark"
 			title="US Tech Force"
 			lead="The US Tech Force is recruiting an elite corps of engineers to build the next generation of government technology. Backed by the White House, Tech Force will tackle the most complex and large-scale civic and defense challenges of our era."
 		>
@@ -223,7 +223,7 @@ export const Mobile: Story = {
  */
 export const WithoutLead: Story = {
 	render: () => (
-		<TwoColumnSection variant="dark" title="About the Program">
+		<TwoColumnSection colorScheme="dark" title="About the Program">
 			<p>
 				Through a two-year program, participants will work in teams reporting
 				directly to agency leadership. In collaboration with leading technology
@@ -245,7 +245,7 @@ export const WithoutLead: Story = {
 export const RichLeadContent: Story = {
 	render: () => (
 		<TwoColumnSection
-			variant="dark"
+			colorScheme="dark"
 			title="Our Mission"
 			lead={
 				<>
@@ -275,7 +275,7 @@ export const RichLeadContent: Story = {
 export const ShortContent: Story = {
 	render: () => (
 		<TwoColumnSection
-			variant="dark"
+			colorScheme="dark"
 			title="Join Us"
 			lead="Build the future of American government technology."
 		>

package/src/components/sections/two-column-section/two-column-section.tsx

@@ -23,19 +23,17 @@ const twoColumnSectionVariants = tv({
 		"lg:px-spacing-72 lg:pt-spacing-72 lg:pb-spacing-112",
 	],
 	variants: {
-		variant: {
+		colorScheme: {
 			dark: "bg-gray-1200",
 			light: "bg-white",
 		},
 		layout: {
-			/** Default 24-column grid with asymmetric split (title: 9, content: 15) */
 			asymmetric: "",
-			/** Equal 2-column layout at md+ breakpoints */
 			equal: "",
 		},
 	},
 	defaultVariants: {
-		variant: "dark",
+		colorScheme: "dark",
 		layout: "asymmetric",
 	},
 });
@@ -86,14 +84,22 @@ export interface TwoColumnSectionProps
  */
 const TwoColumnSection = React.forwardRef<HTMLElement, TwoColumnSectionProps>(
 	(
-		{ className, variant = "dark", layout, title, lead, children, ...props },
+		{
+			className,
+			colorScheme = "dark",
+			layout,
+			title,
+			lead,
+			children,
+			...props
+		},
 		ref,
 	) => {
 		return (
 			<section
 				ref={ref}
 				className={twoColumnSectionVariants({
-					variant,
+					colorScheme,
 					layout,
 					class: className,
 				})}
@@ -103,7 +109,7 @@ const TwoColumnSection = React.forwardRef<HTMLElement, TwoColumnSectionProps>(
 				<div
 					className={cn(
 						"border-t pt-spacing-36",
-						variant === "dark" ? "border-gray-700" : "border-gray-300",
+						colorScheme === "dark" ? "border-gray-700" : "border-gray-300",
 						// Grid layout - uses primitive spacing tokens
 						"grid grid-cols-1 gap-spacing-56",
 						layout === "equal"
@@ -115,7 +121,7 @@ const TwoColumnSection = React.forwardRef<HTMLElement, TwoColumnSectionProps>(
 					<h2
 						className={cn(
 							"typography-subheading-medium",
-							variant === "dark" ? "text-gray-100" : "text-gray-900",
+							colorScheme === "dark" ? "text-gray-100" : "text-gray-900",
 							// Column span based on layout
 							layout !== "equal" && "lg:col-span-9",
 						)}
@@ -135,7 +141,7 @@ const TwoColumnSection = React.forwardRef<HTMLElement, TwoColumnSectionProps>(
 							<div
 								className={cn(
 									"typography-body-large",
-									variant === "dark" ? "text-gray-100" : "text-gray-900",
+									colorScheme === "dark" ? "text-gray-100" : "text-gray-900",
 								)}
 							>
 								{typeof lead === "string" ? <p>{lead}</p> : lead}
@@ -146,7 +152,7 @@ const TwoColumnSection = React.forwardRef<HTMLElement, TwoColumnSectionProps>(
 						<div
 							className={cn(
 								"typography-body-medium flex flex-col gap-[1em]",
-								variant === "dark" ? "text-gray-400" : "text-gray-600",
+								colorScheme === "dark" ? "text-gray-400" : "text-gray-600",
 							)}
 						>
 							{children}