@nationaldesignstudio/react 0.2.0 → 0.5.0

package/src/stories/grid-system.stories.tsx

@@ -0,0 +1,309 @@
+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
+ */
+
+// Enhanced grid column with solid color styling
+const GridColumn = ({ index }: { index: number }) => {
+	const colors = [
+		"bg-blue-100",
+		"bg-indigo-100",
+		"bg-purple-100",
+		"bg-pink-100",
+		"bg-red-100",
+		"bg-orange-100",
+		"bg-amber-100",
+		"bg-yellow-100",
+		"bg-lime-100",
+		"bg-green-100",
+		"bg-emerald-100",
+		"bg-teal-100",
+		"bg-cyan-100",
+		"bg-sky-100",
+		"bg-blue-100",
+		"bg-indigo-100",
+		"bg-purple-100",
+		"bg-pink-100",
+		"bg-red-100",
+		"bg-orange-100",
+		"bg-amber-100",
+		"bg-yellow-100",
+		"bg-lime-100",
+		"bg-green-100",
+	];
+	return (
+		<div
+			className={`h-16 rounded-2 border-2 border-white/50 flex items-center justify-center shadow-sm transition-all hover:scale-105 ${colors[index % colors.length]}`}
+		>
+			<span className="text-xs font-bold font-mono text-gray-700">
+				{index + 1}
+			</span>
+		</div>
+	);
+};
+
+// Grid visualization with better styling
+const GridVisualization = () => (
+	<div className="w-full bg-gray-50 py-16">
+		<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="mb-8">
+				<h2 className="typography-h3 text-gray-900 mb-2">
+					Responsive Grid System
+				</h2>
+				<p className="typography-body text-gray-600">
+					The grid adapts across breakpoints: 4 columns (mobile), 12 columns
+					(tablet), 24 columns (desktop)
+				</p>
+			</div>
+			<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>
+);
+
+// Enhanced spans visualization with content examples
+const ColumnSpans = () => (
+	<div className="w-full bg-white py-16">
+		<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="mb-12">
+				<h2 className="typography-h3 text-gray-900 mb-2">
+					Column Spans & Positioning
+				</h2>
+				<p className="typography-body text-gray-600">
+					Use col-span and col-start/col-end to create flexible layouts
+				</p>
+			</div>
+
+			{/* Full width */}
+			<div className="mb-8 grid grid-cols-1 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)]">
+				<div className="col-span-full rounded-8 bg-blue-600 p-8 text-white shadow-lg">
+					<div className="flex items-center justify-between">
+						<div>
+							<code className="text-sm font-mono bg-white/20 px-3 py-1 rounded">
+								col-span-full
+							</code>
+							<p className="mt-4 typography-body-large">
+								Full-width hero section or banner
+							</p>
+						</div>
+					</div>
+				</div>
+			</div>
+
+			{/* Centered wide content */}
+			<div className="mb-8 grid grid-cols-1 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)]">
+				<div className="col-span-full lg:col-start-4 lg:col-end-22 rounded-8 bg-purple-600 p-8 text-white shadow-lg">
+					<div>
+						<code className="text-sm font-mono bg-white/20 px-3 py-1 rounded mb-4 inline-block">
+							col-start-4 col-end-22 (18 cols)
+						</code>
+						<p className="typography-body-large">
+							Centered wide content area - perfect for dashboards or data tables
+						</p>
+					</div>
+				</div>
+			</div>
+
+			{/* Two column layout */}
+			<div className="mb-8 grid grid-cols-1 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)]">
+				<div className="col-span-full lg:col-start-3 lg:col-end-13 rounded-8 bg-green-600 p-8 text-white shadow-lg">
+					<code className="text-sm font-mono bg-white/20 px-3 py-1 rounded mb-4 inline-block">
+						col-start-3 col-end-13 (10 cols)
+					</code>
+					<p className="typography-body">Left column content</p>
+				</div>
+				<div className="col-span-full lg:col-start-13 lg:col-end-23 rounded-8 bg-orange-600 p-8 text-white shadow-lg">
+					<code className="text-sm font-mono bg-white/20 px-3 py-1 rounded mb-4 inline-block">
+						col-start-13 col-end-23 (10 cols)
+					</code>
+					<p className="typography-body">Right column content</p>
+				</div>
+			</div>
+
+			{/* Narrow centered content */}
+			<div className="grid grid-cols-1 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)]">
+				<div className="col-span-full lg:col-start-7 lg:col-end-19 rounded-8 bg-indigo-600 p-8 text-white shadow-lg">
+					<code className="text-sm font-mono bg-white/20 px-3 py-1 rounded mb-4 inline-block">
+						col-start-7 col-end-19 (12 cols)
+					</code>
+					<p className="typography-body">
+						Narrow centered content - ideal for reading or forms
+					</p>
+				</div>
+			</div>
+		</div>
+	</div>
+);
+
+// Content layout utilities demonstration
+const ContentLayoutsDemo = () => (
+	<div className="w-full bg-white py-16">
+		<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="mb-12">
+				<h2 className="typography-h3 text-gray-900 mb-2">
+					Content Layout Utilities
+				</h2>
+				<p className="typography-body text-gray-600">
+					Pre-built utilities for common content widths: narrow, medium, and
+					wide
+				</p>
+			</div>
+
+			{/* Grid container */}
+			<div className="grid grid-cols-1 md:grid-cols-12 lg:grid-cols-24 gap-y-32 md:gap-y-48 lg:gap-y-64 gap-[var(--spatial-grid-small-gutter)] md:gap-[var(--spatial-grid-medium-gutter)] lg:gap-[var(--spatial-grid-large-gutter)]">
+				{/* Narrow content */}
+				<div className="grid-content-narrow">
+					<div className="rounded-8 bg-white border-2 border-gray-200 p-12 shadow-md">
+						<div className="mb-4">
+							<code className="text-sm font-mono text-blue-600 bg-blue-50 px-3 py-1 rounded">
+								grid-content-narrow
+							</code>
+						</div>
+						<h3 className="typography-h4 text-gray-900 mb-4">Narrow Content</h3>
+						<p className="typography-body text-gray-700">
+							Perfect for reading content, mission statements, or focused text
+							blocks. This layout centers content with optimal reading width.
+						</p>
+					</div>
+				</div>
+
+				{/* Medium content */}
+				<div className="grid-content-medium">
+					<div className="rounded-8 bg-white border-2 border-gray-200 p-12 shadow-md">
+						<div className="mb-4">
+							<code className="text-sm font-mono text-green-600 bg-green-50 px-3 py-1 rounded">
+								grid-content-medium
+							</code>
+						</div>
+						<h3 className="typography-h4 text-gray-900 mb-4">Medium Content</h3>
+						<p className="typography-body text-gray-700">
+							Great for forms, general content, or sections that need a bit more
+							width than narrow but still maintain readability.
+						</p>
+					</div>
+				</div>
+
+				{/* Wide content */}
+				<div className="grid-content-wide">
+					<div className="rounded-8 bg-white border-2 border-gray-200 p-12 shadow-md">
+						<div className="mb-4">
+							<code className="text-sm font-mono text-purple-600 bg-purple-50 px-3 py-1 rounded">
+								grid-content-wide
+							</code>
+						</div>
+						<h3 className="typography-h4 text-gray-900 mb-4">Wide Content</h3>
+						<p className="typography-body text-gray-700">
+							Ideal for dashboards, data tables, or content that needs maximum
+							width while still respecting grid margins.
+						</p>
+					</div>
+				</div>
+			</div>
+		</div>
+	</div>
+);
+
+// Real-world example
+const RealWorldExampleDemo = () => (
+	<div className="w-full bg-white py-16">
+		<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="mb-12">
+				<h2 className="typography-h3 text-gray-900 mb-2">Real-World Example</h2>
+				<p className="typography-body text-gray-600">
+					How the grid system is used in practice
+				</p>
+			</div>
+
+			<div className="grid grid-cols-1 md:grid-cols-12 lg:grid-cols-24 gap-y-32 md:gap-y-48 lg:gap-y-64 gap-[var(--spatial-grid-small-gutter)] md:gap-[var(--spatial-grid-medium-gutter)] lg:gap-[var(--spatial-grid-large-gutter)]">
+				{/* Hero section */}
+				<div className="col-span-full rounded-12 bg-blue-600 p-16 text-white shadow-xl">
+					<div className="max-w-3xl">
+						<h1 className="typography-h1 mb-6">Hero Section</h1>
+						<p className="typography-body-large opacity-90">
+							Full-width hero sections use col-span-full to create impactful
+							introductions.
+						</p>
+					</div>
+				</div>
+
+				{/* Narrow content section */}
+				<div className="grid-content-narrow">
+					<div className="space-y-6">
+						<h2 className="typography-h3 text-gray-900">Mission Statement</h2>
+						<p className="typography-body text-gray-700">
+							This narrow content area is perfect for focused reading. The
+							grid-content-narrow utility automatically centers the content with
+							optimal width for readability.
+						</p>
+					</div>
+				</div>
+
+				{/* Two-column card layout */}
+				<div className="col-span-full lg:col-start-3 lg:col-end-11 rounded-8 bg-white border-2 border-gray-200 p-8 shadow-md">
+					<div className="h-32 bg-blue-500 rounded-4 mb-4" />
+					<h3 className="typography-h4 text-gray-900 mb-2">Card Title</h3>
+					<p className="typography-body-small text-gray-600">
+						Card content spans 8 columns
+					</p>
+				</div>
+				<div className="col-span-full lg:col-start-13 lg:col-end-21 rounded-8 bg-white border-2 border-gray-200 p-8 shadow-md">
+					<div className="h-32 bg-purple-500 rounded-4 mb-4" />
+					<h3 className="typography-h4 text-gray-900 mb-2">Card Title</h3>
+					<p className="typography-body-small text-gray-600">
+						Card content spans 8 columns
+					</p>
+				</div>
+			</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" } },
+};
+
+export const Spans: Story = {
+	render: () => <ColumnSpans />,
+	globals: { viewport: { value: "lg" } },
+};
+
+export const ContentLayouts: Story = {
+	render: () => <ContentLayoutsDemo />,
+	globals: { viewport: { value: "lg" } },
+};
+
+export const RealWorldExample: Story = {
+	render: () => <RealWorldExampleDemo />,
+	globals: { viewport: { value: "lg" } },
+};

package/src/stories/{Introduction.mdx → introduction.mdx}

@@ -40,33 +40,47 @@ function App() {
 
 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
+### Headings
 
-For app UIs, dashboards, and interfaces:
+For headlines and titles:
 
 ```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>
+<h1 class="typography-h1-display">Display Title</h1>
+<h1 class="typography-h1">Page Title</h1>
+<h2 class="typography-h2">Section Header</h2>
+<h3 class="typography-h3">Subsection Header</h3>
+<h4 class="typography-h4">Smaller Header</h4>
+<h5 class="typography-h5">Smallest Header</h5>
 ```
 
-Available styles: `typography-product-{category}-{size}` where category is: `title`, `headline`, `body`, `label`, `caption`, `button`, `input`, `link`, `navigation`, `overline`, `tabbar`
+### Body Text
 
-### Brand Typography
+For body content:
 
-For landing pages and promotional content:
+```html
+<p class="typography-body-large">Large body text...</p>
+<p class="typography-body-medium">Standard body text...</p>
+<p class="typography-body-small">Small body text...</p>
+```
+
+### Supporting Text
+
+For captions and labels:
 
 ```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>
+<span class="typography-caption">Caption text</span>
+<span class="typography-overline">OVERLINE TEXT</span>
 ```
 
-Available namespaces: `brand-large` (desktop), `brand-medium` (tablet), `brand-small` (mobile)
+### UI Typography
 
-Available styles: `typography-brand-{breakpoint}-{category}-{size}` where category is: `display`, `headline`, `subheading`, `body`, `label`, `caption`, `button`, `link`
+For buttons and interactive elements:
+
+```html
+<button class="typography-ui-button-large">Large Button</button>
+<button class="typography-ui-button-medium">Medium Button</button>
+<button class="typography-ui-button-small">Small Button</button>
+```
 
 ## Color Tokens
 

package/src/stories/{ThemeProvider.stories.tsx → theme-provider.stories.tsx}

@@ -8,22 +8,14 @@ import {
 	CardDescription,
 	CardTitle,
 } from "../components/organisms/card";
-import { ThemeProvider, useCSSVars } from "../theme";
+import { ThemeProvider } 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="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>
+					<h2 className="typography-h5 text-text-primary mb-4">{title}</h2>
 				)}
 
 				{/* Typography showcase */}
@@ -38,15 +30,9 @@ function ThemeDemo({ title }: { title?: string }) {
 
 				{/* Button variants */}
 				<div className="flex flex-wrap gap-3 mb-6">
-					<Button variant="solid" colorScheme="dark">
-						Solid Dark
-					</Button>
-					<Button variant="solid" colorScheme="light">
-						Solid Light
-					</Button>
-					<Button variant="outline" colorScheme="dark">
-						Outline
-					</Button>
+					<Button variant="primary">Primary</Button>
+					<Button variant="primary-outline">Primary Outline</Button>
+					<Button variant="ghost">Ghost</Button>
 				</div>
 
 				{/* Card component */}
@@ -60,10 +46,10 @@ function ThemeDemo({ title }: { title?: string }) {
 							</CardDescription>
 						</CardBody>
 						<CardActions>
-							<Button variant="solid" colorScheme="dark" size="sm">
+							<Button variant="primary" size="sm">
 								Action
 							</Button>
-							<Button variant="outline" colorScheme="dark" size="sm">
+							<Button variant="primary-outline" size="sm">
 								Cancel
 							</Button>
 						</CardActions>

package/src/stories/{TokenShowcase.stories.tsx → token-showcase.stories.tsx}

@@ -3,11 +3,10 @@ import type { ComponentProps } from "react";
 import {
 	ColorTokens,
 	ResponsiveTypography,
-	SemanticSpacingTokens,
 	SpacingTokens,
 	TokenShowcase,
 	TypographyTokens,
-} from "./TokenShowcase";
+} from "./token-showcase";
 
 const meta = {
 	title: "Design System/Tokens",
@@ -57,24 +56,6 @@ export const Typography: Story = {
 	),
 };
 
-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">