@nationaldesignstudio/react 0.0.17 → 0.0.19

package/src/components/atoms/button/icon-button.tsx

@@ -17,70 +17,115 @@ import { tv, type VariantProps } from "tailwind-variants";
  * <IconButton aria-label="Close menu">
  *   <CloseIcon />
  * </IconButton>
- *
- * // Correct usage with aria-labelledby
- * <IconButton aria-labelledby="close-label">
- *   <CloseIcon />
- * </IconButton>
- * <span id="close-label" className="sr-only">Close menu</span>
  * ```
  *
  * Variants:
- * - charcoal: Dark filled button (for light backgrounds)
- * - charcoalOutline: Dark outlined button (for light backgrounds)
- * - charcoalOutlineQuiet: Subtle dark outlined button (for light backgrounds)
- * - ghost: No background/border, just icon (for light backgrounds)
- * - ghostDark: No background/border, just icon (for dark backgrounds)
- * - ivory: Light filled button (for dark backgrounds)
- * - ivoryOutline: Light outlined button (for dark backgrounds)
- * - ivoryOutlineQuiet: Subtle light outlined button (for dark backgrounds)
+ * - solid: Filled button
+ * - outline: Outlined button
+ * - ghost: No background/border, just icon
+ * - subtle: Subtle outlined button
+ *
+ * Color Schemes:
+ * - dark: Dark colors for use on light backgrounds (default)
+ * - light: Light colors for use on dark backgrounds
  *
  * Sizes:
- * - lg: Large (46x46)
- * - default: Medium (36x36)
- * - sm: Small (29x29)
+ * - lg: Large (48x48)
+ * - default: Medium (40x40)
+ * - sm: Small (32x32)
+ *
+ * Rounded:
+ * - default: Standard border radius
+ * - sm: Smaller border radius
+ * - full: Fully circular
  */
 const iconButtonVariants = tv({
 	base: "inline-flex items-center justify-center whitespace-nowrap transition-colors duration-150 cursor-pointer focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-offset-2 disabled:pointer-events-none disabled:opacity-50",
 	variants: {
 		variant: {
-			// Charcoal (dark filled) - primary dark
-			charcoal:
+			solid: "",
+			outline: "border",
+			ghost: "",
+			subtle: "border",
+		},
+		colorScheme: {
+			dark: "",
+			light: "",
+		},
+		size: {
+			lg: "size-48",
+			default: "size-40",
+			sm: "size-32",
+		},
+		rounded: {
+			default: "rounded-radius-12",
+			sm: "rounded-radius-10",
+			full: "rounded-full",
+		},
+	},
+	compoundVariants: [
+		// Solid + Dark (for light backgrounds)
+		{
+			variant: "solid",
+			colorScheme: "dark",
+			class:
 				"bg-gray-1200 text-gray-100 hover:bg-gray-1100 active:bg-gray-1000 focus-visible:ring-gray-1000",
-			// Charcoal Outline - outlined dark (for light backgrounds)
-			charcoalOutline:
-				"border border-alpha-black-30 text-gray-1000 hover:bg-alpha-black-5 active:bg-alpha-black-10 focus-visible:ring-gray-1000",
-			// Charcoal Outline Quiet - subtle outlined dark (for light backgrounds)
-			charcoalOutlineQuiet:
-				"border border-alpha-black-20 text-alpha-black-60 hover:border-alpha-black-30 hover:text-alpha-black-80 active:bg-alpha-black-5 focus-visible:ring-gray-1000",
-			// Ghost - no background/border (for light backgrounds)
-			ghost:
+		},
+		// Solid + Light (for dark backgrounds)
+		{
+			variant: "solid",
+			colorScheme: "light",
+			class:
+				"bg-gray-50 text-gray-1000 hover:bg-gray-100 active:bg-gray-200 focus-visible:ring-gray-50 focus-visible:ring-offset-gray-1000",
+		},
+		// Outline + Dark (for light backgrounds)
+		{
+			variant: "outline",
+			colorScheme: "dark",
+			class:
+				"border-alpha-black-30 text-gray-1000 hover:bg-alpha-black-5 active:bg-alpha-black-10 focus-visible:ring-gray-1000",
+		},
+		// Outline + Light (for dark backgrounds)
+		{
+			variant: "outline",
+			colorScheme: "light",
+			class:
+				"border-gray-50 text-gray-50 hover:bg-alpha-white-10 active:bg-alpha-white-20 focus-visible:ring-gray-50 focus-visible:ring-offset-gray-1000",
+		},
+		// Ghost + Dark (for light backgrounds)
+		{
+			variant: "ghost",
+			colorScheme: "dark",
+			class:
 				"text-gray-700 hover:text-gray-900 hover:bg-alpha-black-5 active:bg-alpha-black-10 focus-visible:ring-gray-1000",
-			// Ghost Dark - no background/border (for dark backgrounds)
-			ghostDark:
+		},
+		// Ghost + Light (for dark backgrounds)
+		{
+			variant: "ghost",
+			colorScheme: "light",
+			class:
 				"text-gray-300 hover:text-gray-100 hover:bg-alpha-white-10 active:bg-alpha-white-20 focus-visible:ring-gray-50 focus-visible:ring-offset-gray-1000",
-			// Ivory (light filled) - primary light (for dark backgrounds)
-			ivory:
-				"bg-gray-50 text-gray-1000 hover:bg-gray-100 active:bg-gray-200 focus-visible:ring-gray-50 focus-visible:ring-offset-gray-1000",
-			// Ivory Outline - outlined light (for dark backgrounds)
-			ivoryOutline:
-				"border border-gray-50 text-gray-50 hover:bg-alpha-white-10 active:bg-alpha-white-20 focus-visible:ring-gray-50 focus-visible:ring-offset-gray-1000",
-			// Ivory Outline Quiet - subtle light outline (for dark backgrounds)
-			ivoryOutlineQuiet:
-				"border border-alpha-white-20 text-alpha-white-60 hover:border-alpha-white-30 hover:text-alpha-white-80 active:bg-alpha-white-5 focus-visible:ring-gray-50 focus-visible:ring-offset-gray-1000",
 		},
-		size: {
-			// Large (48x48) - uses primitive spacing tokens
-			lg: "rounded-radius-12 size-spacing-48",
-			// Medium (40x40) - default - uses primitive spacing tokens
-			default: "rounded-radius-12 size-spacing-40",
-			// Small (32x32) - uses primitive spacing tokens
-			sm: "rounded-radius-10 size-spacing-32",
+		// Subtle + Dark (for light backgrounds)
+		{
+			variant: "subtle",
+			colorScheme: "dark",
+			class:
+				"border-alpha-black-20 text-alpha-black-60 hover:border-alpha-black-30 hover:text-alpha-black-80 active:bg-alpha-black-5 focus-visible:ring-gray-1000",
 		},
-	},
+		// Subtle + Light (for dark backgrounds)
+		{
+			variant: "subtle",
+			colorScheme: "light",
+			class:
+				"border-alpha-white-20 text-alpha-white-60 hover:border-alpha-white-30 hover:text-alpha-white-80 active:bg-alpha-white-5 focus-visible:ring-gray-50 focus-visible:ring-offset-gray-1000",
+		},
+	],
 	defaultVariants: {
-		variant: "charcoal",
+		variant: "solid",
+		colorScheme: "dark",
 		size: "default",
+		rounded: "default",
 	},
 });
 
@@ -91,7 +136,18 @@ export interface IconButtonProps
 }
 
 const IconButton = React.forwardRef<HTMLButtonElement, IconButtonProps>(
-	({ className, variant, size, asChild = false, ...props }, ref) => {
+	(
+		{
+			className,
+			variant,
+			colorScheme,
+			size,
+			rounded,
+			asChild = false,
+			...props
+		},
+		ref,
+	) => {
 		// Development warning for missing accessible label
 		React.useEffect(() => {
 			if (import.meta.env?.DEV) {
@@ -108,7 +164,13 @@ const IconButton = React.forwardRef<HTMLButtonElement, IconButtonProps>(
 		const Comp = asChild ? Slot : "button";
 		return (
 			<Comp
-				className={iconButtonVariants({ variant, size, class: className })}
+				className={iconButtonVariants({
+					variant,
+					colorScheme,
+					size,
+					rounded,
+					class: className,
+				})}
 				ref={ref}
 				{...props}
 			/>

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/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 };