@nationaldesignstudio/react 0.0.15 → 0.0.16

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

@@ -0,0 +1,84 @@
+import type { Meta, StoryObj } from "@storybook/react-vite";
+
+/**
+ * Spatial Grid System
+ *
+ * Responsive grid tokens that adapt across breakpoints:
+ * - Large (lg): 1440px+ - 24 columns, 72px margin, 24px gutter
+ * - Medium (md): 768px+ - 12 columns, 56px margin, 20px gutter
+ * - Small (sm): 320px+ - 4 columns, 24px margin, 12px gutter
+ */
+
+const GridColumn = ({ index }: { index: number }) => (
+	<div className="h-12 bg-brand-primary/20 border border-brand-primary/40 rounded flex items-center justify-center">
+		<span className="text-xs font-mono text-brand-primary">{index + 1}</span>
+	</div>
+);
+
+const GridVisualization = () => (
+	<div className="w-full bg-gray-100 py-8">
+		<div className="w-full max-w-[90rem] mx-auto px-[var(--spatial-grid-small-margin)] md:px-[var(--spatial-grid-medium-margin)] lg:px-[var(--spatial-grid-large-margin)]">
+			<div className="grid grid-cols-4 md:grid-cols-12 lg:grid-cols-24 gap-[var(--spatial-grid-small-gutter)] md:gap-[var(--spatial-grid-medium-gutter)] lg:gap-[var(--spatial-grid-large-gutter)]">
+				{Array.from({ length: 24 }).map((_, i) => (
+					// biome-ignore lint/suspicious/noArrayIndexKey: Static grid columns never reorder
+					<GridColumn key={i} index={i} />
+				))}
+			</div>
+		</div>
+	</div>
+);
+
+const meta = {
+	title: "Design System/Grid System",
+	component: GridVisualization,
+	parameters: {
+		layout: "fullscreen",
+	},
+} satisfies Meta<typeof GridVisualization>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {};
+
+export const Desktop: Story = {
+	globals: { viewport: { value: "lg" } },
+};
+
+export const Tablet: Story = {
+	globals: { viewport: { value: "md" } },
+};
+
+export const Mobile: Story = {
+	globals: { viewport: { value: "sm" } },
+};
+
+const ColumnSpans = () => (
+	<div className="w-full py-8 px-[var(--spatial-grid-large-margin)]">
+		<div className="max-w-[90rem] mx-auto grid grid-cols-24 gap-[var(--spatial-grid-large-gutter)]">
+			<div className="col-span-full h-12 bg-gray-200 rounded flex items-center px-4">
+				<code className="text-sm font-mono">col-span-full</code>
+			</div>
+			<div className="col-start-4 col-end-22 h-12 bg-gray-200 rounded flex items-center px-4">
+				<code className="text-sm font-mono">
+					col-start-4 col-end-22 (18 cols)
+				</code>
+			</div>
+			<div className="col-start-7 col-end-19 h-12 bg-gray-200 rounded flex items-center px-4">
+				<code className="text-sm font-mono">
+					col-start-7 col-end-19 (12 cols)
+				</code>
+			</div>
+			<div className="col-start-9 col-end-17 h-12 bg-gray-200 rounded flex items-center px-4">
+				<code className="text-sm font-mono">
+					col-start-9 col-end-17 (8 cols)
+				</code>
+			</div>
+		</div>
+	</div>
+);
+
+export const Spans: Story = {
+	render: () => <ColumnSpans />,
+	globals: { viewport: { value: "lg" } },
+};

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
+```

package/src/stories/ThemeProvider.stories.tsx

@@ -0,0 +1,357 @@
+import type { Meta, StoryObj } from "@storybook/react";
+import { Button } from "../components/atoms/button";
+import {
+	Card,
+	CardActions,
+	CardBody,
+	CardContent,
+	CardDescription,
+	CardTitle,
+} from "../components/organisms/card";
+import { ThemeProvider, useCSSVars } from "../theme";
+
+/**
+ * Shared demo component using actual Button, Card, and Typography components.
+ * Used across all theme stories to showcase theming differences.
+ */
+function ThemeDemo({ title }: { title?: string }) {
+	const cssVars = useCSSVars();
+
+	return (
+		<div style={cssVars} className="p-6">
+			<div className="bg-bg-page p-6 rounded-lg min-h-[300px]">
+				{title && (
+					<h2 className="typography-subheading-small text-text-primary mb-4">
+						{title}
+					</h2>
+				)}
+
+				{/* Typography showcase */}
+				<div className="mb-6">
+					<p className="typography-body-large text-text-primary mb-2">
+						Primary text using typography tokens
+					</p>
+					<p className="typography-body-small text-text-secondary">
+						Secondary text for supporting content
+					</p>
+				</div>
+
+				{/* Button variants */}
+				<div className="flex flex-wrap gap-3 mb-6">
+					<Button variant="primary">Primary</Button>
+					<Button variant="secondary">Secondary</Button>
+					<Button variant="primaryOutline">Outline</Button>
+				</div>
+
+				{/* Card component */}
+				<Card className="max-w-sm">
+					<CardContent>
+						<CardBody>
+							<CardTitle>Card Title</CardTitle>
+							<CardDescription>
+								This card demonstrates surface tokens including border radius
+								and stroke width.
+							</CardDescription>
+						</CardBody>
+						<CardActions>
+							<Button variant="primary" size="sm">
+								Action
+							</Button>
+							<Button variant="secondary" size="sm">
+								Cancel
+							</Button>
+						</CardActions>
+					</CardContent>
+				</Card>
+			</div>
+		</div>
+	);
+}
+
+const meta: Meta<typeof ThemeProvider> = {
+	title: "Theme/ThemeProvider",
+	component: ThemeProvider,
+	parameters: {
+		layout: "fullscreen",
+		docs: {
+			description: {
+				component: `
+The ThemeProvider component applies theme tokens as CSS variables using type-safe theme names.
+
+## Props
+
+- \`color\`: Color theme name - "base" | "dark" | "institution" | "civic" (defaults to "base")
+- \`surface\`: Surface theme name - "base" | "sharp" | "framed" | "soft" (defaults to "base")
+
+## Usage
+
+\`\`\`tsx
+import { ThemeProvider, useCSSVars } from '@nationaldesignstudio/react';
+
+// Use defaults (base themes)
+function App() {
+  return (
+    <ThemeProvider>
+      <Layout />
+    </ThemeProvider>
+  );
+}
+
+// Use specific themes
+function ThemedApp() {
+  return (
+    <ThemeProvider color="civic" surface="sharp">
+      <Layout />
+    </ThemeProvider>
+  );
+}
+
+function Layout() {
+  const cssVars = useCSSVars();
+  return (
+    <div style={cssVars}>
+      <Button variant="primary">Click me</Button>
+    </div>
+  );
+}
+\`\`\`
+				`,
+			},
+		},
+	},
+	tags: ["autodocs"],
+};
+
+export default meta;
+type Story = StoryObj<typeof ThemeProvider>;
+
+// =============================================================================
+// Color Theme Stories
+// =============================================================================
+
+/**
+ * Base color theme - the default light color palette.
+ */
+export const BaseColor: Story = {
+	render: () => (
+		<ThemeProvider color="base">
+			<ThemeDemo title="Base Color Theme" />
+		</ThemeProvider>
+	),
+};
+
+/**
+ * Dark color theme - inverted colors for dark mode.
+ */
+export const DarkColor: Story = {
+	render: () => (
+		<ThemeProvider color="dark">
+			<ThemeDemo title="Dark Color Theme" />
+		</ThemeProvider>
+	),
+};
+
+/**
+ * Institution color theme - warm brown palette with green accents.
+ */
+export const InstitutionColor: Story = {
+	render: () => (
+		<ThemeProvider color="institution">
+			<ThemeDemo title="Institution Color Theme" />
+		</ThemeProvider>
+	),
+};
+
+/**
+ * Civic color theme - for government/public sector applications.
+ */
+export const CivicColor: Story = {
+	render: () => (
+		<ThemeProvider color="civic">
+			<ThemeDemo title="Civic Color Theme" />
+		</ThemeProvider>
+	),
+};
+
+/**
+ * Color theme comparison - all color variants side by side.
+ */
+export const ColorComparison: Story = {
+	render: () => (
+		<div className="grid grid-cols-2 gap-4">
+			<ThemeProvider color="base">
+				<ThemeDemo title="Base" />
+			</ThemeProvider>
+			<ThemeProvider color="dark">
+				<ThemeDemo title="Dark" />
+			</ThemeProvider>
+			<ThemeProvider color="institution">
+				<ThemeDemo title="Institution" />
+			</ThemeProvider>
+			<ThemeProvider color="civic">
+				<ThemeDemo title="Civic" />
+			</ThemeProvider>
+		</div>
+	),
+};
+
+// =============================================================================
+// Surface Theme Stories
+// =============================================================================
+
+/**
+ * Base surface theme - default border radius and stroke widths.
+ */
+export const BaseSurface: Story = {
+	render: () => (
+		<ThemeProvider surface="base">
+			<ThemeDemo title="Base Surface Theme" />
+		</ThemeProvider>
+	),
+};
+
+/**
+ * Sharp surface theme - minimal border radius for an angular look.
+ */
+export const SharpSurface: Story = {
+	render: () => (
+		<ThemeProvider surface="sharp">
+			<ThemeDemo title="Sharp Surface Theme" />
+		</ThemeProvider>
+	),
+};
+
+/**
+ * Framed surface theme - heavier borders and no button radius.
+ */
+export const FramedSurface: Story = {
+	render: () => (
+		<ThemeProvider surface="framed">
+			<ThemeDemo title="Framed Surface Theme" />
+		</ThemeProvider>
+	),
+};
+
+/**
+ * Soft surface theme - large rounded corners and minimal strokes.
+ */
+export const SoftSurface: Story = {
+	render: () => (
+		<ThemeProvider surface="soft">
+			<ThemeDemo title="Soft Surface Theme" />
+		</ThemeProvider>
+	),
+};
+
+/**
+ * Surface theme comparison - all surface variants side by side.
+ * Notice the different border radius and stroke widths on buttons and cards.
+ */
+export const SurfaceComparison: Story = {
+	render: () => (
+		<div className="grid grid-cols-2 gap-4">
+			<ThemeProvider surface="base">
+				<ThemeDemo title="Base" />
+			</ThemeProvider>
+			<ThemeProvider surface="sharp">
+				<ThemeDemo title="Sharp" />
+			</ThemeProvider>
+			<ThemeProvider surface="framed">
+				<ThemeDemo title="Framed" />
+			</ThemeProvider>
+			<ThemeProvider surface="soft">
+				<ThemeDemo title="Soft" />
+			</ThemeProvider>
+		</div>
+	),
+};
+
+// =============================================================================
+// Combined Theme Stories
+// =============================================================================
+
+/**
+ * Civic color + Sharp surface - example of combining color and surface themes.
+ */
+export const CivicSharp: Story = {
+	render: () => (
+		<ThemeProvider color="civic" surface="sharp">
+			<ThemeDemo title="Civic + Sharp" />
+		</ThemeProvider>
+	),
+};
+
+/**
+ * Institution color + Framed surface - example of combining color and surface themes.
+ */
+export const InstitutionFramed: Story = {
+	render: () => (
+		<ThemeProvider color="institution" surface="framed">
+			<ThemeDemo title="Institution + Framed" />
+		</ThemeProvider>
+	),
+};
+
+/**
+ * Dark color + Sharp surface - angular dark mode.
+ */
+export const DarkSharp: Story = {
+	render: () => (
+		<ThemeProvider color="dark" surface="sharp">
+			<ThemeDemo title="Dark + Sharp" />
+		</ThemeProvider>
+	),
+};
+
+/**
+ * Civic color + Soft surface - rounded, friendly civic theme.
+ */
+export const CivicSoft: Story = {
+	render: () => (
+		<ThemeProvider color="civic" surface="soft">
+			<ThemeDemo title="Civic + Soft" />
+		</ThemeProvider>
+	),
+};
+
+/**
+ * Default theme - no props needed, uses base for both.
+ */
+export const Default: Story = {
+	render: () => (
+		<ThemeProvider>
+			<ThemeDemo title="Default (Base + Base)" />
+		</ThemeProvider>
+	),
+};
+
+// =============================================================================
+// Interactive Playground
+// =============================================================================
+
+/**
+ * Interactive playground - use controls to select any combination of themes.
+ */
+export const Playground: Story = {
+	args: {
+		color: "base",
+		surface: "base",
+	},
+	argTypes: {
+		color: {
+			control: "select",
+			options: ["base", "dark", "institution", "civic"],
+			description: "Color theme",
+		},
+		surface: {
+			control: "select",
+			options: ["base", "sharp", "framed", "soft"],
+			description: "Surface theme",
+		},
+	},
+	render: (args) => (
+		<ThemeProvider color={args.color} surface={args.surface}>
+			<ThemeDemo title={`${args.color} + ${args.surface}`} />
+		</ThemeProvider>
+	),
+};

package/src/stories/TokenShowcase.stories.tsx

@@ -0,0 +1,92 @@
+import type { Meta, StoryObj } from "@storybook/react-vite";
+import type { ComponentProps } from "react";
+import {
+	ColorTokens,
+	ResponsiveTypography,
+	SemanticSpacingTokens,
+	SpacingTokens,
+	TokenShowcase,
+	TypographyTokens,
+} from "./TokenShowcase";
+
+const meta = {
+	title: "Design System/Tokens",
+	component: TokenShowcase,
+	parameters: {
+		layout: "fullscreen",
+		docs: {
+			description: {
+				component:
+					"Design tokens from the design system. These tokens provide a consistent foundation for colors, spacing, and typography across the application.",
+			},
+		},
+	},
+	tags: ["autodocs"],
+} satisfies Meta<ComponentProps<typeof TokenShowcase>>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+export const AllTokens: Story = {};
+
+export const Colors: Story = {
+	render: () => (
+		<div className="p-8">
+			<ColorTokens />
+		</div>
+	),
+};
+
+export const Spacing: Story = {
+	render: () => (
+		<div className="p-8 min-h-screen">
+			<div className="max-w-4xl mx-auto">
+				<SpacingTokens />
+			</div>
+		</div>
+	),
+};
+
+export const Typography: Story = {
+	render: () => (
+		<div className="p-8 min-h-screen">
+			<div className="max-w-6xl mx-auto">
+				<TypographyTokens />
+			</div>
+		</div>
+	),
+};
+
+export const SemanticSpacing: Story = {
+	render: () => (
+		<div className="p-8 min-h-screen">
+			<div className="max-w-4xl mx-auto">
+				<SemanticSpacingTokens />
+			</div>
+		</div>
+	),
+	parameters: {
+		docs: {
+			description: {
+				story:
+					"Purpose-driven spacing tokens for components (buttons, cards, forms), layouts (hero, sections, containers, grids), and content stacks (vertical rhythm between elements).",
+			},
+		},
+	},
+};
+
+export const Breakpoints: Story = {
+	render: () => (
+		<div className="p-8">
+			<ResponsiveTypography />
+		</div>
+	),
+	parameters: {
+		docs: {
+			description: {
+				story:
+					"Typography that adapts across breakpoints. Use the viewport toolbar to switch between sm (320px), md (768px), and lg (1440px).",
+			},
+		},
+	},
+};