@nationaldesignstudio/react 0.0.7 → 0.0.8

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

@@ -0,0 +1,285 @@
+import type { Meta, StoryObj } from "@storybook/react-vite";
+import { TwoColumnSection } from ".";
+
+const meta: Meta<typeof TwoColumnSection> = {
+	title: "Sections/TwoColumnSection",
+	component: TwoColumnSection,
+	parameters: {
+		layout: "fullscreen",
+	},
+	argTypes: {
+		theme: {
+			control: "select",
+			options: ["dark", "light"],
+			description: "Color theme",
+		},
+		title: {
+			control: "text",
+			description: "The title text",
+		},
+		lead: {
+			control: "text",
+			description: "Lead content (prominent)",
+		},
+	},
+} as Meta<typeof TwoColumnSection>;
+
+export default meta;
+type Story = StoryObj<typeof TwoColumnSection>;
+
+// =============================================================================
+// Playground
+// =============================================================================
+
+export const Playground: Story = {
+	render: (args) => <TwoColumnSection {...args} />,
+};
+Playground.args = {
+	theme: "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: (
+		<>
+			<p>
+				Through a two-year program, participants will work in teams reporting
+				directly to agency leadership. In collaboration with leading technology
+				companies, participants will receive technical training, engage with
+				industry leaders, and work closely with senior managers from companies
+				partnering with the Tech Force.
+			</p>
+			<p>
+				Upon completing the program, engineers can seek employment with the
+				partnering private-sector companies for potential full-time roles –
+				demonstrating the value of combining civil service with technical
+				expertise.
+			</p>
+			<p>
+				If you are highly skilled in the areas of software engineering,
+				artificial intelligence, cybersecurity, data analytics, or technical
+				project management and want to build the future of American government
+				technology, join the Tech Force today.
+			</p>
+		</>
+	),
+};
+
+// =============================================================================
+// Theme Variants
+// =============================================================================
+
+/**
+ * Dark theme (default) - dark background with light text
+ */
+export const DarkTheme: Story = {
+	render: () => (
+		<TwoColumnSection
+			theme="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."
+		>
+			<p>
+				Through a two-year program, participants will work in teams reporting
+				directly to agency leadership.
+			</p>
+			<p>
+				Upon completing the program, engineers can seek employment with the
+				partnering private-sector companies for potential full-time roles.
+			</p>
+		</TwoColumnSection>
+	),
+};
+
+/**
+ * Light theme - light background with dark text
+ */
+export const LightTheme: Story = {
+	render: () => (
+		<TwoColumnSection
+			theme="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."
+		>
+			<p>
+				Through a two-year program, participants will work in teams reporting
+				directly to agency leadership.
+			</p>
+			<p>
+				Upon completing the program, engineers can seek employment with the
+				partnering private-sector companies for potential full-time roles.
+			</p>
+		</TwoColumnSection>
+	),
+};
+
+// =============================================================================
+// Responsive Variants
+// =============================================================================
+
+export const Desktop: Story = {
+	render: () => (
+		<TwoColumnSection
+			theme="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."
+		>
+			<p>
+				Through a two-year program, participants will work in teams reporting
+				directly to agency leadership. In collaboration with leading technology
+				companies, participants will receive technical training, engage with
+				industry leaders, and work closely with senior managers from companies
+				partnering with the Tech Force.
+			</p>
+			<p>
+				Upon completing the program, engineers can seek employment with the
+				partnering private-sector companies for potential full-time roles –
+				demonstrating the value of combining civil service with technical
+				expertise.
+			</p>
+			<p>
+				If you are highly skilled in the areas of software engineering,
+				artificial intelligence, cybersecurity, data analytics, or technical
+				project management and want to build the future of American government
+				technology, join the Tech Force today.
+			</p>
+		</TwoColumnSection>
+	),
+	globals: {
+		viewport: { value: "lg", isRotated: false },
+	},
+};
+
+export const Tablet: Story = {
+	render: () => (
+		<TwoColumnSection
+			theme="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."
+		>
+			<p>
+				Through a two-year program, participants will work in teams reporting
+				directly to agency leadership. In collaboration with leading technology
+				companies, participants will receive technical training, engage with
+				industry leaders, and work closely with senior managers from companies
+				partnering with the Tech Force.
+			</p>
+			<p>
+				Upon completing the program, engineers can seek employment with the
+				partnering private-sector companies for potential full-time roles –
+				demonstrating the value of combining civil service with technical
+				expertise.
+			</p>
+			<p>
+				If you are highly skilled in the areas of software engineering,
+				artificial intelligence, cybersecurity, data analytics, or technical
+				project management and want to build the future of American government
+				technology, join the Tech Force today.
+			</p>
+		</TwoColumnSection>
+	),
+	globals: {
+		viewport: { value: "md", isRotated: false },
+	},
+};
+
+export const Mobile: Story = {
+	render: () => (
+		<TwoColumnSection
+			theme="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."
+		>
+			<p>
+				Through a two-year program, participants will work in teams reporting
+				directly to agency leadership. In collaboration with leading technology
+				companies, participants will receive technical training, engage with
+				industry leaders, and work closely with senior managers from companies
+				partnering with the Tech Force.
+			</p>
+			<p>
+				Upon completing the program, engineers can seek employment with the
+				partnering private-sector companies for potential full-time roles –
+				demonstrating the value of combining civil service with technical
+				expertise.
+			</p>
+			<p>
+				If you are highly skilled in the areas of software engineering,
+				artificial intelligence, cybersecurity, data analytics, or technical
+				project management and want to build the future of American government
+				technology, join the Tech Force today.
+			</p>
+		</TwoColumnSection>
+	),
+	globals: {
+		viewport: { value: "sm", isRotated: false },
+	},
+};
+
+// =============================================================================
+// Content Variations
+// =============================================================================
+
+/**
+ * Without lead content - just title and body
+ */
+export const WithoutLead: Story = {
+	render: () => (
+		<TwoColumnSection theme="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
+				companies, participants will receive technical training, engage with
+				industry leaders, and work closely with senior managers from companies
+				partnering with the Tech Force.
+			</p>
+			<p>
+				Upon completing the program, engineers can seek employment with the
+				partnering private-sector companies for potential full-time roles.
+			</p>
+		</TwoColumnSection>
+	),
+};
+
+/**
+ * With rich lead content (ReactNode)
+ */
+export const RichLeadContent: Story = {
+	render: () => (
+		<TwoColumnSection
+			theme="dark"
+			title="Our Mission"
+			lead={
+				<>
+					<p>
+						The US Tech Force is recruiting an elite corps of engineers to build
+						the next generation of government technology.
+					</p>
+					<p>
+						Backed by the White House, Tech Force will tackle the most complex
+						and large-scale civic and defense challenges of our era.
+					</p>
+				</>
+			}
+		>
+			<p>
+				From administering critical financial infrastructure at the Treasury
+				Department to advancing cutting-edge programs at the Department of War –
+				and everything in between.
+			</p>
+		</TwoColumnSection>
+	),
+};
+
+/**
+ * Short content example
+ */
+export const ShortContent: Story = {
+	render: () => (
+		<TwoColumnSection
+			theme="dark"
+			title="Join Us"
+			lead="Build the future of American government technology."
+		>
+			<p>Applications are now open for qualified engineers.</p>
+		</TwoColumnSection>
+	),
+};

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

@@ -0,0 +1,155 @@
+import { cva, type VariantProps } from "class-variance-authority";
+import * as React from "react";
+import { cn } from "@/lib/utils";
+
+/**
+ * TwoColumnSection component for text-heavy content sections
+ *
+ * Layout:
+ * - Desktop (lg+): Title left, content right with border-top divider
+ * - Mobile/Tablet: Stacked vertically
+ *
+ * Uses the 24-column grid system.
+ */
+const twoColumnSectionVariants = cva(
+	// Base styles - responsive padding
+	[
+		"w-full",
+		// Small (mobile): 20px x, 56px top, 20px bottom
+		"px-spacing-20 pt-spacing-56 pb-spacing-20",
+		// Medium (tablet): 56px x, 56px y
+		"md:px-spacing-56 md:py-spacing-56",
+		// Large (desktop): 72px x, 72px top, 112px bottom
+		"lg:px-spacing-72 lg:pt-spacing-72 lg:pb-spacing-112",
+	],
+	{
+		variants: {
+			theme: {
+				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: {
+			theme: "dark",
+			layout: "asymmetric",
+		},
+	},
+);
+
+export interface TwoColumnSectionProps
+	extends React.HTMLAttributes<HTMLElement>,
+		VariantProps<typeof twoColumnSectionVariants> {
+	/**
+	 * The title text displayed in the left column
+	 */
+	title: string;
+	/**
+	 * Lead content - prominently styled (brighter text)
+	 * Can be a string or ReactNode for rich content
+	 */
+	lead?: React.ReactNode;
+	/**
+	 * Body content - secondary styled (muted text)
+	 * Can be a string or ReactNode for rich content
+	 */
+	children: React.ReactNode;
+	/**
+	 * Layout style for the columns
+	 * - "asymmetric" (default): Uses 24-column grid with ~40/60 split (title: 9, content: 15)
+	 * - "equal": Simple 2-column equal-width layout at md+ breakpoints
+	 */
+	layout?: "asymmetric" | "equal";
+}
+
+/**
+ * TwoColumnSection component for text-heavy content with title/content split.
+ *
+ * Layout:
+ * - Mobile/Tablet: Stacked (title above content)
+ * - Desktop (lg+): Title left (~40%), Content right (~60%)
+ *
+ * @example
+ * ```tsx
+ * <TwoColumnSection
+ *   title="US Tech Force"
+ *   lead="The US Tech Force is recruiting an elite corps of engineers..."
+ *   theme="dark"
+ * >
+ *   <p>Through a two-year program, participants will work...</p>
+ *   <p>Upon completing the program, engineers can seek...</p>
+ * </TwoColumnSection>
+ * ```
+ */
+const TwoColumnSection = React.forwardRef<HTMLElement, TwoColumnSectionProps>(
+	({ className, theme, layout, title, lead, children, ...props }, ref) => {
+		const isDark = theme === "dark" || theme === undefined;
+		const isEqual = layout === "equal";
+
+		return (
+			<section
+				ref={ref}
+				className={cn(twoColumnSectionVariants({ theme, layout }), className)}
+				{...props}
+			>
+				{/* Inner container with border-top */}
+				<div
+					className={cn(
+						"border-t pt-spacing-36",
+						isDark ? "border-gray-700" : "border-gray-300",
+						// Grid layout
+						"grid grid-cols-1 gap-spacing-56",
+						isEqual
+							? "md:grid-cols-2"
+							: "lg:grid-cols-24 lg:gap-spacing-56",
+					)}
+				>
+					{/* Title column */}
+					<h2
+						className={cn(
+							"typography-subheading-medium",
+							isDark ? "text-gray-100" : "text-gray-900",
+							// Column span based on layout
+							!isEqual && "lg:col-span-9",
+						)}
+					>
+						{title}
+					</h2>
+
+					{/* Content column */}
+					<div className={cn("flex flex-col gap-spacing-56", !isEqual && "lg:col-span-15")}>
+						{/* Lead content - brighter/prominent */}
+						{lead && (
+							<div
+								className={cn(
+									"typography-body-large",
+									isDark ? "text-gray-100" : "text-gray-900",
+								)}
+							>
+								{typeof lead === "string" ? <p>{lead}</p> : lead}
+							</div>
+						)}
+
+						{/* Body content - muted */}
+						<div
+							className={cn(
+								"typography-body-medium flex flex-col gap-[1em]",
+								isDark ? "text-gray-400" : "text-gray-600",
+							)}
+						>
+							{children}
+						</div>
+					</div>
+				</div>
+			</section>
+		);
+	},
+);
+TwoColumnSection.displayName = "TwoColumnSection";
+
+export { TwoColumnSection, twoColumnSectionVariants };

package/src/index.ts

@@ -0,0 +1,98 @@
+// =============================================================================
+// Atoms
+// =============================================================================
+export type {
+	AccordionItemProps,
+	AccordionProps,
+} from "./components/atoms/accordion";
+export { Accordion, AccordionItem } from "./components/atoms/accordion";
+export type { ButtonProps, IconButtonProps } from "./components/atoms/button";
+export {
+	Button,
+	buttonVariants,
+	IconButton,
+	iconButtonVariants,
+} from "./components/atoms/button";
+export type { PagerControlProps } from "./components/atoms/pager-control";
+export {
+	PagerControl,
+	pagerControlVariants,
+} from "./components/atoms/pager-control";
+
+// =============================================================================
+// Organisms
+// =============================================================================
+export type {
+	CardActionsProps,
+	CardBodyProps,
+	CardContentProps,
+	CardDescriptionProps,
+	CardEyebrowProps,
+	CardImageProps,
+	CardProps,
+	CardTitleProps,
+} from "./components/organisms/card";
+export {
+	Card,
+	CardActions,
+	CardBody,
+	CardContent,
+	CardDescription,
+	CardEyebrow,
+	CardImage,
+	CardTitle,
+	cardVariants,
+} from "./components/organisms/card";
+export type {
+	NavbarActionsProps,
+	NavbarBrandProps,
+	NavbarLinkProps,
+	NavbarLinksProps,
+	NavbarMobileMenuButtonProps,
+	NavbarMobileMenuLinkProps,
+	NavbarMobileMenuProps,
+	NavbarProps,
+} from "./components/organisms/navbar";
+export {
+	Navbar,
+	NavbarActions,
+	NavbarBrand,
+	NavbarLink,
+	NavbarLinks,
+	NavbarMobileMenu,
+	NavbarMobileMenuButton,
+	NavbarMobileMenuLink,
+} from "./components/organisms/navbar";
+export type { USGovBannerProps } from "./components/organisms/us-gov-banner";
+export { USGovBanner } from "./components/organisms/us-gov-banner";
+
+// =============================================================================
+// Sections
+// =============================================================================
+export type { BannerProps } from "./components/sections/banner";
+export { Banner, bannerVariants } from "./components/sections/banner";
+export type { CardGridProps } from "./components/sections/card-grid";
+export { CardGrid, cardGridVariants } from "./components/sections/card-grid";
+export type { FaqSectionProps } from "./components/sections/faq-section";
+export { FaqSection } from "./components/sections/faq-section";
+export type { HeroProps } from "./components/sections/hero";
+export { Hero } from "./components/sections/hero";
+export type {
+	ProseProps,
+	ProseSectionProps,
+} from "./components/sections/prose";
+export { Prose, ProseSection } from "./components/sections/prose";
+export type { RiverProps } from "./components/sections/river";
+export { River, riverVariants } from "./components/sections/river";
+export type { ToutProps } from "./components/sections/tout";
+export { Tout } from "./components/sections/tout";
+export type { TwoColumnSectionProps } from "./components/sections/two-column-section";
+export {
+	TwoColumnSection,
+	twoColumnSectionVariants,
+} from "./components/sections/two-column-section";
+
+// =============================================================================
+// Utilities
+// =============================================================================
+export { cn } from "./lib/utils";

package/src/lib/utils.ts

@@ -0,0 +1,6 @@
+import { type ClassValue, clsx } from "clsx";
+import { twMerge } from "tailwind-merge";
+
+export function cn(...inputs: ClassValue[]) {
+	return twMerge(clsx(inputs));
+}

package/src/main.tsx

@@ -0,0 +1,13 @@
+import { StrictMode } from "react";
+import { createRoot } from "react-dom/client";
+import "./styles.css";
+import App from "./App.tsx";
+
+const rootElement = document.getElementById("root");
+if (rootElement) {
+	createRoot(rootElement).render(
+		<StrictMode>
+			<App />
+		</StrictMode>,
+	);
+}

package/src/stories/Introduction.mdx

@@ -0,0 +1,114 @@
+import { Meta } from "@storybook/addon-docs/blocks";
+
+<Meta title="Introduction" />
+
+# NDS Design System
+
+Welcome to the **NDS Design System** component library. This Storybook documents all available components, their variants, and design tokens.
+
+## Getting Started
+
+### Installation
+
+```bash
+bun add @nationaldesignstudio/react
+```
+
+### Setup Tailwind CSS v4
+
+Import the generated tokens CSS in your main CSS file:
+
+```css
+/* app.css or globals.css */
+@import "tailwindcss";
+@import "@nationaldesignstudio/react/tokens.css";
+```
+
+This gives you access to all design tokens as CSS variables and Tailwind utilities.
+
+### Using Components
+
+```tsx
+import { Button } from "@nationaldesignstudio/react";
+
+function App() {
+  return <Button variant="primary">Click me</Button>;
+}
+```
+
+## Typography Styles
+
+The design system provides pre-built typography classes for consistent text styling. Typography utilities use the `typography-` prefix to avoid conflicts with Tailwind's `text-*` color utilities.
+
+### Product Typography
+
+For app UIs, dashboards, and interfaces:
+
+```html
+<h1 class="typography-product-title-large">Page Title</h1>
+<h2 class="typography-product-headline-medium">Section Header</h2>
+<p class="typography-product-body-medium">Body text content...</p>
+<span class="typography-product-caption-small">Caption text</span>
+<button class="typography-product-button-medium">Click me</button>
+```
+
+Available styles: `typography-product-{category}-{size}` where category is: `title`, `headline`, `body`, `label`, `caption`, `button`, `input`, `link`, `navigation`, `overline`, `tabbar`
+
+### Brand Typography
+
+For landing pages and promotional content:
+
+```html
+<h1 class="typography-brand-medium-display-hero">Hero</h1>
+<h2 class="typography-brand-medium-headline-large">Big Headline</h2>
+<p class="typography-brand-medium-body-large">Marketing copy...</p>
+```
+
+Available namespaces: `brand-large` (desktop), `brand-medium` (tablet), `brand-small` (mobile)
+
+Available styles: `typography-brand-{breakpoint}-{category}-{size}` where category is: `display`, `headline`, `subheading`, `body`, `label`, `caption`, `button`, `link`
+
+## Color Tokens
+
+All colors are available as Tailwind utilities:
+
+```html
+<div class="bg-blue-500 text-gray-900">...</div>
+<div class="bg-alpha-black-50">Semi-transparent overlay</div>
+```
+
+See **Design System > Tokens > Colors** for the full palette.
+
+## Spacing Tokens
+
+Consistent spacing values:
+
+```html
+<div class="p-spacing-16 m-spacing-24 gap-spacing-8">...</div>
+```
+
+## Features
+
+- **Design Tokens** - Comprehensive token system for colors, spacing, and typography
+- **Accessibility** - Components tested for WCAG compliance
+- **TypeScript** - Full type safety with detailed prop documentation
+- **Tailwind CSS v4** - Built on modern Tailwind with CSS variables
+
+## Structure
+
+- **Components** - Reusable UI components (Button, etc.)
+- **Design System > Tokens** - Visual token documentation
+
+## Development
+
+```bash
+# Run Storybook locally
+cd packages/react
+bun run storybook
+
+# Build tokens after changes
+bun run build
+
+# Run tests
+bun run test
+```