@nationaldesignstudio/react 0.2.0 → 0.3.0

package/src/components/foundation/typography/typography.stories.tsx

@@ -0,0 +1,401 @@
+import type { Meta, StoryObj } from "@storybook/react";
+
+const meta: Meta = {
+	title: "Foundation/Typography",
+	parameters: {
+		layout: "padded",
+	},
+};
+
+export default meta;
+
+/**
+ * Typography Scale showcases all typography styles in the design system.
+ * Each style is shown with its class name and a sample text.
+ */
+export const TypeScale: StoryObj = {
+	render: () => (
+		<div className="space-y-48 p-24">
+			{/* Headings */}
+			<section>
+				<h2 className="typography-h5 text-gray-500 mb-24 uppercase tracking-wide">
+					Headings
+				</h2>
+				<div className="space-y-24">
+					<div>
+						<code className="text-12 text-gray-500 block mb-8">
+							typography-h1-display
+						</code>
+						<p className="typography-h1-display text-gray-900">
+							Display Heading
+						</p>
+					</div>
+					<div>
+						<code className="text-12 text-gray-500 block mb-8">
+							typography-h1
+						</code>
+						<p className="typography-h1 text-gray-900">Heading 1</p>
+					</div>
+					<div>
+						<code className="text-12 text-gray-500 block mb-8">
+							typography-h2
+						</code>
+						<p className="typography-h2 text-gray-900">Heading 2</p>
+					</div>
+					<div>
+						<code className="text-12 text-gray-500 block mb-8">
+							typography-h3
+						</code>
+						<p className="typography-h3 text-gray-900">Heading 3</p>
+					</div>
+					<div>
+						<code className="text-12 text-gray-500 block mb-8">
+							typography-h4
+						</code>
+						<p className="typography-h4 text-gray-900">Heading 4</p>
+					</div>
+					<div>
+						<code className="text-12 text-gray-500 block mb-8">
+							typography-h5
+						</code>
+						<p className="typography-h5 text-gray-900">Heading 5</p>
+					</div>
+				</div>
+			</section>
+
+			{/* Body Text */}
+			<section>
+				<h2 className="typography-h5 text-gray-500 mb-24 uppercase tracking-wide">
+					Body Text
+				</h2>
+				<div className="space-y-24">
+					<div>
+						<code className="text-12 text-gray-500 block mb-8">
+							typography-body-large
+						</code>
+						<p className="typography-body-large text-gray-900 max-w-640">
+							Body large is used for important introductory text. The quick
+							brown fox jumps over the lazy dog.
+						</p>
+					</div>
+					<div>
+						<code className="text-12 text-gray-500 block mb-8">
+							typography-body-medium
+						</code>
+						<p className="typography-body-medium text-gray-900 max-w-640">
+							Body medium is the default body text size for most content. The
+							quick brown fox jumps over the lazy dog.
+						</p>
+					</div>
+					<div>
+						<code className="text-12 text-gray-500 block mb-8">
+							typography-body-small
+						</code>
+						<p className="typography-body-small text-gray-900 max-w-640">
+							Body small is used for secondary text and compact layouts. The
+							quick brown fox jumps over the lazy dog.
+						</p>
+					</div>
+				</div>
+			</section>
+
+			{/* Supporting Text */}
+			<section>
+				<h2 className="typography-h5 text-gray-500 mb-24 uppercase tracking-wide">
+					Supporting Text
+				</h2>
+				<div className="space-y-24">
+					<div>
+						<code className="text-12 text-gray-500 block mb-8">
+							typography-overline
+						</code>
+						<p className="typography-overline text-gray-700 uppercase tracking-wide">
+							Overline Text
+						</p>
+					</div>
+					<div>
+						<code className="text-12 text-gray-500 block mb-8">
+							typography-caption
+						</code>
+						<p className="typography-caption text-gray-600">
+							Caption text for supplementary information
+						</p>
+					</div>
+				</div>
+			</section>
+
+			{/* UI Typography */}
+			<section>
+				<h2 className="typography-h5 text-gray-500 mb-24 uppercase tracking-wide">
+					UI Typography
+				</h2>
+				<div className="space-y-24">
+					<div>
+						<code className="text-12 text-gray-500 block mb-8">
+							typography-ui-button-large
+						</code>
+						<p className="typography-ui-button-large text-gray-900">
+							Large Button Text
+						</p>
+					</div>
+					<div>
+						<code className="text-12 text-gray-500 block mb-8">
+							typography-ui-button-medium
+						</code>
+						<p className="typography-ui-button-medium text-gray-900">
+							Medium Button Text
+						</p>
+					</div>
+					<div>
+						<code className="text-12 text-gray-500 block mb-8">
+							typography-ui-button-small
+						</code>
+						<p className="typography-ui-button-small text-gray-900">
+							Small Button Text
+						</p>
+					</div>
+					<div>
+						<code className="text-12 text-gray-500 block mb-8">
+							typography-ui-label
+						</code>
+						<p className="typography-ui-label text-gray-900">Form Label</p>
+					</div>
+				</div>
+			</section>
+		</div>
+	),
+};
+
+/**
+ * Responsive Typography demonstrates how typography scales across breakpoints.
+ * Resize the viewport to see the typography adapt.
+ */
+export const ResponsiveTypography: StoryObj = {
+	render: () => (
+		<div className="space-y-32 p-24">
+			<div className="bg-gray-100 p-16 rounded-8">
+				<p className="typography-body-small text-gray-700 mb-8">
+					Resize the viewport to see responsive typography in action
+				</p>
+				<p className="typography-caption text-gray-500">
+					Mobile (&lt;768px) | Tablet (768px-1440px) | Desktop (&gt;1440px)
+				</p>
+			</div>
+
+			<section>
+				<h3 className="typography-h5 text-gray-500 mb-24 uppercase tracking-wide">
+					Responsive Headings
+				</h3>
+				<div className="space-y-24">
+					<div className="border-l-4 border-indigo-500 pl-16">
+						<code className="text-12 text-gray-500 block mb-4">
+							typography-h1 (responsive)
+						</code>
+						<p className="typography-h1 text-gray-900">Responsive H1</p>
+						<p className="typography-caption text-gray-500 mt-4">
+							48px (sm) → 72px (md) → 96px (lg)
+						</p>
+					</div>
+					<div className="border-l-4 border-indigo-500 pl-16">
+						<code className="text-12 text-gray-500 block mb-4">
+							typography-h2 (responsive)
+						</code>
+						<p className="typography-h2 text-gray-900">Responsive H2</p>
+						<p className="typography-caption text-gray-500 mt-4">
+							48px (sm) → 64px (md) → 72px (lg)
+						</p>
+					</div>
+					<div className="border-l-4 border-indigo-500 pl-16">
+						<code className="text-12 text-gray-500 block mb-4">
+							typography-h3 (responsive)
+						</code>
+						<p className="typography-h3 text-gray-900">Responsive H3</p>
+						<p className="typography-caption text-gray-500 mt-4">
+							32px (sm) → 48px (md) → 64px (lg)
+						</p>
+					</div>
+				</div>
+			</section>
+
+			<section>
+				<h3 className="typography-h5 text-gray-500 mb-24 uppercase tracking-wide">
+					Breakpoint-Specific Utilities
+				</h3>
+				<div className="space-y-16">
+					<div className="grid grid-cols-1 md:grid-cols-3 gap-16">
+						<div className="bg-gray-50 p-16 rounded-8">
+							<code className="text-12 text-gray-500 block mb-8">
+								typography-h4-small
+							</code>
+							<p className="typography-h4-small text-gray-900">H4 Small</p>
+						</div>
+						<div className="bg-gray-50 p-16 rounded-8">
+							<code className="text-12 text-gray-500 block mb-8">
+								typography-h4-medium
+							</code>
+							<p className="typography-h4-medium text-gray-900">H4 Medium</p>
+						</div>
+						<div className="bg-gray-50 p-16 rounded-8">
+							<code className="text-12 text-gray-500 block mb-8">
+								typography-h4-large
+							</code>
+							<p className="typography-h4-large text-gray-900">H4 Large</p>
+						</div>
+					</div>
+				</div>
+			</section>
+		</div>
+	),
+};
+
+/**
+ * Typography specimen shows a sample page layout using the typography system.
+ */
+export const Specimen: StoryObj = {
+	render: () => (
+		<article className="max-w-800 mx-auto p-32">
+			<header className="mb-48">
+				<p className="typography-overline text-indigo-600 uppercase tracking-wide mb-8">
+					Design System
+				</p>
+				<h1 className="typography-h1 text-gray-900 mb-16">
+					Typography Specimen
+				</h1>
+				<p className="typography-body-large text-gray-700">
+					A demonstration of the typography system in a realistic content
+					layout, showing how different styles work together.
+				</p>
+			</header>
+
+			<section className="mb-48">
+				<h2 className="typography-h3 text-gray-900 mb-16">
+					The Foundation of Good Design
+				</h2>
+				<p className="typography-body-medium text-gray-800 mb-16">
+					Typography is the art and technique of arranging type to make written
+					language legible, readable, and appealing when displayed. The
+					arrangement of type involves selecting typefaces, point sizes, line
+					lengths, line-spacing, and letter-spacing.
+				</p>
+				<p className="typography-body-medium text-gray-800 mb-16">
+					The term typography is also applied to the style, arrangement, and
+					appearance of the letters, numbers, and symbols created by the
+					process. Type design is a closely related craft, sometimes considered
+					part of typography.
+				</p>
+			</section>
+
+			<section className="mb-48">
+				<h3 className="typography-h4 text-gray-900 mb-16">Key Principles</h3>
+				<p className="typography-body-medium text-gray-800 mb-16">
+					Most typefaces can be classified into one of four basic groups: those
+					with serifs, those without serifs, scripts and decorative styles.
+				</p>
+
+				<div className="bg-gray-50 p-24 rounded-8 mb-16">
+					<h4 className="typography-h5 text-gray-900 mb-8">
+						Hierarchy Matters
+					</h4>
+					<p className="typography-body-small text-gray-700">
+						Visual hierarchy guides readers through content by creating clear
+						distinctions between headings, body text, and supporting elements.
+					</p>
+				</div>
+
+				<p className="typography-body-medium text-gray-800">
+					Good typography requires attention to detail and an understanding of
+					how type creates meaning and emotion.
+				</p>
+			</section>
+
+			<footer className="border-t border-gray-200 pt-24">
+				<p className="typography-caption text-gray-500">
+					Typography specimen created for the NDS Design System
+				</p>
+			</footer>
+		</article>
+	),
+};
+
+/**
+ * Font comparison shows the different font families in the design system.
+ */
+export const FontFamilies: StoryObj = {
+	render: () => (
+		<div className="space-y-48 p-24">
+			<section>
+				<h2 className="typography-h5 text-gray-500 mb-24 uppercase tracking-wide">
+					Heading Font: Inter Tight
+				</h2>
+				<div className="space-y-16">
+					<p className="typography-h2 text-gray-900">
+						The quick brown fox jumps over the lazy dog
+					</p>
+					<p className="typography-h4 text-gray-800">
+						ABCDEFGHIJKLMNOPQRSTUVWXYZ
+					</p>
+					<p className="typography-h4 text-gray-700">
+						abcdefghijklmnopqrstuvwxyz
+					</p>
+					<p className="typography-h4 text-gray-600">0123456789</p>
+				</div>
+			</section>
+
+			<section>
+				<h2 className="typography-h5 text-gray-500 mb-24 uppercase tracking-wide">
+					Body Font: Inter
+				</h2>
+				<div className="space-y-16">
+					<p className="typography-body-large text-gray-900">
+						The quick brown fox jumps over the lazy dog
+					</p>
+					<p className="typography-body-medium text-gray-800">
+						ABCDEFGHIJKLMNOPQRSTUVWXYZ
+					</p>
+					<p className="typography-body-medium text-gray-700">
+						abcdefghijklmnopqrstuvwxyz
+					</p>
+					<p className="typography-body-medium text-gray-600">0123456789</p>
+				</div>
+			</section>
+
+			<section>
+				<h2 className="typography-h5 text-gray-500 mb-24 uppercase tracking-wide">
+					Font Weights
+				</h2>
+				<div className="grid grid-cols-2 gap-24">
+					<div>
+						<p className="typography-caption text-gray-500 mb-4">
+							Regular (400)
+						</p>
+						<p className="typography-body-medium font-normal text-gray-900">
+							The quick brown fox
+						</p>
+					</div>
+					<div>
+						<p className="typography-caption text-gray-500 mb-4">
+							Medium (500)
+						</p>
+						<p className="typography-body-medium font-medium text-gray-900">
+							The quick brown fox
+						</p>
+					</div>
+					<div>
+						<p className="typography-caption text-gray-500 mb-4">
+							Semibold (600)
+						</p>
+						<p className="typography-body-medium font-semibold text-gray-900">
+							The quick brown fox
+						</p>
+					</div>
+					<div>
+						<p className="typography-caption text-gray-500 mb-4">Bold (700)</p>
+						<p className="typography-body-medium font-bold text-gray-900">
+							The quick brown fox
+						</p>
+					</div>
+				</div>
+			</section>
+		</div>
+	),
+};

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

@@ -43,10 +43,10 @@ export const Default: Story = {
 						</div>
 					</CardBody>
 					<CardActions>
-						<Button size="default" variant="charcoal">
+						<Button size="default" variant="solid">
 							Primary
 						</Button>
-						<Button size="default" variant="charcoalOutline">
+						<Button size="default" variant="outline">
 							Secondary
 						</Button>
 					</CardActions>
@@ -77,10 +77,10 @@ export const Vertical: Story = {
 						</div>
 					</CardBody>
 					<CardActions>
-						<Button size="default" variant="charcoal">
+						<Button size="default" variant="solid">
 							Primary
 						</Button>
-						<Button size="default" variant="charcoalOutline">
+						<Button size="default" variant="outline">
 							Secondary
 						</Button>
 					</CardActions>
@@ -109,10 +109,10 @@ export const Horizontal: Story = {
 						</div>
 					</CardBody>
 					<CardActions>
-						<Button size="sm" variant="charcoal">
+						<Button size="sm" variant="solid">
 							Primary
 						</Button>
-						<Button size="sm" variant="charcoalOutline">
+						<Button size="sm" variant="outline">
 							Secondary
 						</Button>
 					</CardActions>
@@ -141,7 +141,7 @@ export const WithoutImage: Story = {
 						</div>
 					</CardBody>
 					<CardActions>
-						<Button size="default" variant="charcoal">
+						<Button size="default" variant="solid">
 							Learn More
 						</Button>
 					</CardActions>
@@ -166,7 +166,7 @@ export const WithoutEyebrow: Story = {
 						</div>
 					</CardBody>
 					<CardActions>
-						<Button size="default" variant="charcoal">
+						<Button size="default" variant="solid">
 							Primary
 						</Button>
 					</CardActions>
@@ -236,7 +236,7 @@ export const CardGrid: Story = {
 							</div>
 						</CardBody>
 						<CardActions>
-							<Button size="sm" variant="charcoal">
+							<Button size="sm" variant="solid">
 								Action
 							</Button>
 						</CardActions>
@@ -270,10 +270,10 @@ export const Playground: Story = {
 						</div>
 					</CardBody>
 					<CardActions>
-						<Button size="default" variant="charcoal">
+						<Button size="default" variant="solid">
 							Primary
 						</Button>
-						<Button size="default" variant="charcoalOutline">
+						<Button size="default" variant="outline">
 							Secondary
 						</Button>
 					</CardActions>

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

@@ -94,7 +94,7 @@ describe("Card", () => {
 						</CardBody>
 						<CardActions>
 							<Button>Primary Action</Button>
-							<Button variant="charcoalOutline">Secondary Action</Button>
+							<Button variant="outline">Secondary Action</Button>
 						</CardActions>
 					</CardContent>
 				</Card>,

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

@@ -142,7 +142,7 @@ const CardContent = React.forwardRef<HTMLDivElement, CardContentProps>(
 CardContent.displayName = "CardContent";
 
 const cardEyebrowVariants = tv({
-	base: "typography-caption-large text-text-muted",
+	base: "typography-overline text-text-muted uppercase tracking-wider",
 });
 
 export interface CardEyebrowProps
@@ -165,7 +165,7 @@ const CardEyebrow = React.forwardRef<HTMLParagraphElement, CardEyebrowProps>(
 CardEyebrow.displayName = "CardEyebrow";
 
 const cardTitleVariants = tv({
-	base: "typography-subheading-small text-text-primary",
+	base: "typography-h5 text-text-primary",
 });
 
 export interface CardTitleProps

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

@@ -32,10 +32,10 @@ describe("Card Visual Regression", () => {
 							</div>
 						</CardBody>
 						<CardActions>
-							<Button size="default" variant="charcoal">
+							<Button size="default" variant="solid">
 								Primary
 							</Button>
-							<Button size="default" variant="charcoalOutline">
+							<Button size="default" variant="outline">
 								Secondary
 							</Button>
 						</CardActions>
@@ -69,10 +69,10 @@ describe("Card Visual Regression", () => {
 							</div>
 						</CardBody>
 						<CardActions>
-							<Button size="sm" variant="charcoal">
+							<Button size="sm" variant="solid">
 								Primary
 							</Button>
-							<Button size="sm" variant="charcoalOutline">
+							<Button size="sm" variant="outline">
 								Secondary
 							</Button>
 						</CardActions>
@@ -101,7 +101,7 @@ describe("Card Visual Regression", () => {
 							</div>
 						</CardBody>
 						<CardActions>
-							<Button size="default" variant="charcoal">
+							<Button size="default" variant="solid">
 								Learn More
 							</Button>
 						</CardActions>
@@ -132,7 +132,7 @@ describe("Card Visual Regression", () => {
 							</div>
 						</CardBody>
 						<CardActions>
-							<Button size="default" variant="charcoal">
+							<Button size="default" variant="solid">
 								Primary
 							</Button>
 						</CardActions>

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

@@ -138,7 +138,7 @@ const NavbarLink = React.forwardRef<HTMLAnchorElement, NavbarLinkProps>(
 			<Comp
 				ref={ref}
 				className={cn(
-					"typography-brand-medium-link-small text-gray-900 transition-colors hover:text-gray-700",
+					"typography-body-small font-medium text-gray-900 transition-colors hover:text-gray-700",
 					active && "text-gray-1100",
 					className,
 				)}
@@ -301,7 +301,7 @@ const NavbarMobileMenuLink = React.forwardRef<
 		<Comp
 			ref={ref}
 			className={cn(
-				"typography-brand-medium-link-medium text-gray-900 transition-colors hover:text-gray-700",
+				"typography-body-medium font-medium text-gray-900 transition-colors hover:text-gray-700",
 				"py-spacing-component-navbar-padding-y-mobile",
 				active && "text-gray-1100",
 				className,

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

@@ -26,7 +26,7 @@ describe("Navbar Visual Regression", () => {
 					<NavbarLink href="#">Contact</NavbarLink>
 				</NavbarLinks>
 				<NavbarActions>
-					<Button size="sm" variant="charcoal">
+					<Button size="sm" variant="solid">
 						Sign In
 					</Button>
 				</NavbarActions>
@@ -55,7 +55,7 @@ describe("Navbar Visual Regression", () => {
 					<NavbarLink href="#">Contact</NavbarLink>
 				</NavbarLinks>
 				<NavbarActions>
-					<Button size="sm" variant="charcoal">
+					<Button size="sm" variant="solid">
 						Sign In
 					</Button>
 				</NavbarActions>

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

@@ -66,9 +66,9 @@ const FaqSection = React.forwardRef<HTMLElement, FaqSectionProps>(
 				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/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/);
 		});
 	});