@devadeboye/react-material-components 0.0.1 → 0.0.2

package/dist/styles.css

@@ -0,0 +1,7 @@
+@import "tailwindcss";
+
+/* src/base.css */
+@theme inline { --animate-ripple: ripple 600ms linear; --color-surface-container-low: #f7f2fa; --color-surface-container-highest: #e6e0e9; --color-outline: #79747e; --color-primary: #65558F; --color-on-primary: #FFFFFF; --color-primary-container: #EADDFF; --color-on-primary-container: #21005D; --color-secondary-container: #E8DEF8; --color-on-secondary-container: #1D192B; --color-on-surface: #1D1B20; --color-on-surface-variant: #49454F; --shadow-elevation-1: 0px 1px 3px 1px rgba(0, 0, 0, 0.15), 0px 1px 2px 0px rgba(0, 0, 0, 0.3); --shadow-elevation-2: 0px 2px 6px 2px rgba(0, 0, 0, 0.15), 0px 1px 2px 0px rgba(0, 0, 0, 0.3); --radius-xl: 12px; --font-label-l: 500 14px/20px var(--font-sans); --font-label-m: 500 12px/16px var(--font-sans); --font-label-s: 500 11px/16px var(--font-sans); --font-title-m: 500 16px/24px var(--font-sans); @keyframes ripple { 0% { transform: scale(0); opacity: 0.35; } 100% { transform: scale(4); opacity: 0; } } }
+
+/* src/styles.css */
+/*# sourceMappingURL=styles.css.map */

package/dist/styles.css.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/base.css"],"sourcesContent":["@theme inline {\n  --animate-ripple: ripple 600ms linear;\n\n  /* M3 Surface Container Colors */\n  --color-surface-container-low: #f7f2fa;\n  --color-surface-container-highest: #e6e0e9;\n  --color-outline: #79747e;\n  \n  /* M3 Colors */\n  --color-primary: #65558F;\n  --color-on-primary: #FFFFFF;\n  --color-primary-container: #EADDFF;\n  --color-on-primary-container: #21005D;\n  --color-secondary-container: #E8DEF8;\n  --color-on-secondary-container: #1D192B;\n  --color-on-surface: #1D1B20;\n  --color-on-surface-variant: #49454F;\n\n  /* M3 Elevations */\n  --shadow-elevation-1: 0px 1px 3px 1px rgba(0, 0, 0, 0.15), 0px 1px 2px 0px rgba(0, 0, 0, 0.3);\n  --shadow-elevation-2: 0px 2px 6px 2px rgba(0, 0, 0, 0.15), 0px 1px 2px 0px rgba(0, 0, 0, 0.3);\n\n  /* M3 Corner Radius */\n  --radius-xl: 12px;\n\n  /* M3 Typography (Simplified for demo) */\n  --font-label-l: 500 14px/20px var(--font-sans);\n  --font-label-m: 500 12px/16px var(--font-sans);\n  --font-label-s: 500 11px/16px var(--font-sans);\n  --font-title-m: 500 16px/24px var(--font-sans);\n\n  @keyframes ripple {\n    0% {\n      transform: scale(0);\n      opacity: 0.35;\n    }\n    100% {\n      transform: scale(4);\n      opacity: 0;\n    }\n  }\n}\n"],"mappings":";;;AAAA,OAAO,OAAO,EACZ,gBAAgB,EAAE,OAAO,MAAM,MAAM,EAGrC,6BAA6B,EAAE,OAAO,EACtC,iCAAiC,EAAE,OAAO,EAC1C,eAAe,EAAE,OAAO,EAGxB,eAAe,EAAE,OAAO,EACxB,kBAAkB,EAAE,OAAO,EAC3B,yBAAyB,EAAE,OAAO,EAClC,4BAA4B,EAAE,OAAO,EACrC,2BAA2B,EAAE,OAAO,EACpC,8BAA8B,EAAE,OAAO,EACvC,kBAAkB,EAAE,OAAO,EAC3B,0BAA0B,EAAE,OAAO,EAGnC,oBAAoB,EAAE,IAAI,IAAI,IAAI,IAAI,KAAK,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,KAAK,EAAE,IAAI,IAAI,IAAI,IAAI,KAAK,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,IAAI,EAC7F,oBAAoB,EAAE,IAAI,IAAI,IAAI,IAAI,KAAK,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,KAAK,EAAE,IAAI,IAAI,IAAI,IAAI,KAAK,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,IAAI,EAG7F,WAAW,EAAE,IAAI,EAGjB,cAAc,EAAE,IAAI,IAAI,CAAC,KAAK,IAAI,YAAY,EAC9C,cAAc,EAAE,IAAI,IAAI,CAAC,KAAK,IAAI,YAAY,EAC9C,cAAc,EAAE,IAAI,IAAI,CAAC,KAAK,IAAI,YAAY,EAC9C,cAAc,EAAE,IAAI,IAAI,CAAC,KAAK,IAAI,YAAY,EAE9C,WAAW,OAAO,EAChB,GAAG,EACD,SAAS,EAAE,MAAM,EAAE,EACnB,OAAO,EAAE,IAAI,IAEf,KAAK,EACH,SAAS,EAAE,MAAM,EAAE,EACnB,OAAO,EAAE,CAAC;","names":[]}

package/dist/styles.d.mts

@@ -0,0 +1,2 @@
+
+export {  }

package/dist/styles.d.ts

@@ -0,0 +1,2 @@
+
+export {  }

package/package.json

@@ -1,10 +1,11 @@
 {
   "name": "@devadeboye/react-material-components",
-  "version": "0.0.1",
+  "version": "0.0.2",
   "sideEffects": false,
   "license": "MIT",
   "files": [
-    "dist"
+    "dist",
+    "src"
   ],
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",
@@ -14,7 +15,8 @@
       "types": "./dist/index.d.ts",
       "import": "./dist/index.mjs",
       "require": "./dist/index.js"
-    }
+    },
+    "./styles.css": "./dist/styles.css"
   },
   "peerDependencies": {
     "react": ">=19",

package/src/base.css

@@ -0,0 +1,42 @@
+@theme inline {
+  --animate-ripple: ripple 600ms linear;
+
+  /* M3 Surface Container Colors */
+  --color-surface-container-low: #f7f2fa;
+  --color-surface-container-highest: #e6e0e9;
+  --color-outline: #79747e;
+  
+  /* M3 Colors */
+  --color-primary: #65558F;
+  --color-on-primary: #FFFFFF;
+  --color-primary-container: #EADDFF;
+  --color-on-primary-container: #21005D;
+  --color-secondary-container: #E8DEF8;
+  --color-on-secondary-container: #1D192B;
+  --color-on-surface: #1D1B20;
+  --color-on-surface-variant: #49454F;
+
+  /* M3 Elevations */
+  --shadow-elevation-1: 0px 1px 3px 1px rgba(0, 0, 0, 0.15), 0px 1px 2px 0px rgba(0, 0, 0, 0.3);
+  --shadow-elevation-2: 0px 2px 6px 2px rgba(0, 0, 0, 0.15), 0px 1px 2px 0px rgba(0, 0, 0, 0.3);
+
+  /* M3 Corner Radius */
+  --radius-xl: 12px;
+
+  /* M3 Typography (Simplified for demo) */
+  --font-label-l: 500 14px/20px var(--font-sans);
+  --font-label-m: 500 12px/16px var(--font-sans);
+  --font-label-s: 500 11px/16px var(--font-sans);
+  --font-title-m: 500 16px/24px var(--font-sans);
+
+  @keyframes ripple {
+    0% {
+      transform: scale(0);
+      opacity: 0.35;
+    }
+    100% {
+      transform: scale(4);
+      opacity: 0;
+    }
+  }
+}

package/src/components/button/button.stories.tsx

@@ -0,0 +1,131 @@
+import type { Meta, StoryObj } from "@storybook/react";
+import { fn } from "@storybook/test";
+import { Button } from ".";
+
+const meta = {
+	title: "Components/Button",
+	component: Button,
+	parameters: {
+		layout: "centered",
+	},
+	tags: ["autodocs"],
+	argTypes: {
+		variant: {
+			control: "select",
+			options: ["filled", "tonal", "outlined", "text", "elevated"],
+		},
+		size: {
+			control: "radio",
+			options: ["xs", "s", "m", "l", "xl"],
+		},
+		shape: {
+			control: "radio",
+			options: ["round", "square"],
+		},
+		disabled: {
+			control: "boolean",
+		},
+		fullWidth: {
+			control: "boolean",
+		},
+	},
+	args: {
+		onClick: fn(),
+	},
+} satisfies Meta<typeof Button>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+export const Filled: Story = {
+	args: {
+		variant: "filled",
+		children: "Filled Button",
+		size: "m",
+		shape: "round",
+	},
+};
+
+export const Tonal: Story = {
+	args: {
+		variant: "tonal",
+		children: "Tonal Button",
+		size: "m",
+		shape: "round",
+	},
+};
+
+export const Outlined: Story = {
+	args: {
+		variant: "outlined",
+		children: "Outlined Button",
+	},
+};
+
+export const Text: Story = {
+	args: {
+		variant: "text",
+		children: "Text Button",
+	},
+};
+
+export const Small: Story = {
+	args: {
+		size: "xs",
+		children: "Small",
+	},
+};
+
+export const Large: Story = {
+	args: {
+		size: "l",
+		children: "Large",
+		shape: "round",
+	},
+};
+
+export const Disabled: Story = {
+	args: {
+		disabled: true,
+		children: "Disabled",
+	},
+};
+
+export const Elevated: Story = {
+	args: {
+		variant: "elevated",
+		children: "Elevated Button",
+	},
+};
+
+export const CustomColor: Story = {
+	args: {
+		variant: "filled",
+		className: "bg-orange-500 text-white hover:bg-orange-600",
+		children: "Custom Color",
+	},
+};
+
+const PlusIcon = (
+	<svg
+		xmlns="http://www.w3.org/2000/svg"
+		width="100%"
+		height="100%"
+		viewBox="0 0 24 24"
+		fill="none"
+		stroke="currentColor"
+		strokeWidth="2"
+		strokeLinecap="round"
+		strokeLinejoin="round"
+	>
+		<path d="M5 12h14"></path>
+		<path d="M12 5v14"></path>
+	</svg>
+);
+
+export const WithLeadingIcon: Story = {
+	args: {
+		children: "Add Item",
+		leadingIcon: PlusIcon,
+	},
+};

package/src/components/button/index.tsx

@@ -0,0 +1,162 @@
+/**
+ * Buttons prompt most actions in a UI
+ * https://m3.material.io/components/buttons/specs
+ */
+
+import React from "react";
+import { cva, type VariantProps } from "class-variance-authority";
+import { clsx, type ClassValue } from "clsx";
+import { twMerge } from "tailwind-merge";
+import { Ripple } from "../ripple";
+
+// Utils
+function cn(...inputs: ClassValue[]) {
+	return twMerge(clsx(inputs));
+}
+
+const buttonVariants = cva(
+	"relative inline-flex items-center justify-center gap-2 font-medium transition-all hover:cursor-pointer disabled:pointer-events-none disabled:opacity-50 overflow-hidden",
+	{
+		variants: {
+			variant: {
+				filled:
+					"bg-primary text-on-primary hover:bg-primary/90 shadow-sm hover:shadow-md",
+				tonal:
+					"bg-secondary-container text-on-secondary-container hover:bg-secondary-container/90",
+				outlined:
+					"border border-outline bg-transparent text-primary hover:bg-primary/10 active:bg-primary/10",
+				text: "bg-transparent text-primary hover:bg-primary/10 active:bg-primary/10",
+				elevated:
+					"bg-surface-container-low text-primary shadow-elevation-1 hover:shadow-elevation-2 hover:bg-surface-container-low/80",
+			},
+
+			size: {
+				/** extra small */
+				xs: "h-8 px-3 text-label-s",
+				/** small */
+				s: "h-9 px-3 text-label-l",
+				/** medium (M3 Default) */
+				m: "h-10 px-6 text-label-l",
+				/** large */
+				l: "h-12 px-8 text-label-l",
+				/** extra large */
+				xl: "h-14 px-10 text-title-m",
+			},
+
+
+			shape: {
+				round: "rounded-full",
+				square: "",
+			},
+			fullWidth: {
+				true: "w-full",
+			},
+		},
+
+		compoundVariants: [
+			{
+				shape: "square",
+				size: "xs",
+				className: "rounded-xl active:rounded-lg",
+			},
+			{
+				shape: "square",
+				size: "s",
+				className: "rounded-lg active:rounded-lg",
+			},
+			{
+				shape: "square",
+				size: "m",
+				className: "rounded-2xl active:rounded-xl",
+			},
+			{
+				shape: "square",
+				size: "l",
+				className: "rounded-[28px] active:rounded-2xl",
+			},
+			{
+				shape: "square",
+				size: "xl",
+				className: "rounded-[28px] active:rounded-2xl",
+			},
+		],
+
+		defaultVariants: {
+			variant: "filled",
+			size: "m",
+			shape: "round",
+		},
+	}
+);
+
+export interface ButtonProps
+	extends
+		React.ButtonHTMLAttributes<HTMLButtonElement>,
+		VariantProps<typeof buttonVariants> {
+	asChild?: boolean;
+	leadingIcon?: React.ReactNode;
+}
+
+/** determines the gap between leading icon and button text */
+const determineGapAndIconSize = (
+	size: "xs" | "s" | "m" | "l" | "xl" | null | undefined
+) => {
+	switch (size) {
+		case "xs":
+			return ["gap-1", "w-5 h-5"];
+		case "s":
+			return ["gap-2", "w-5 h-5"];
+		case "m":
+			return ["gap-2", "w-6 h-6"];
+		case "l":
+			return ["gap-3", "w-8 h-8"];
+		case "xl":
+			return ["gap-4", "w-10 h-10"];
+		default:
+			return ["gap-2", "w-6 h-6"];
+	}
+};
+
+export const Button = React.forwardRef<HTMLButtonElement, ButtonProps>(
+	(
+		{
+			className,
+			variant,
+			size,
+			shape,
+			fullWidth,
+			children,
+			leadingIcon,
+			...props
+		},
+		ref
+	) => {
+		let [gap, iconSize] = determineGapAndIconSize(size);
+		return (
+			<button
+				className={cn(
+					buttonVariants({ variant, size, shape, fullWidth, className })
+				)}
+				ref={ref}
+				{...props}
+			>
+				{/* State Layer (Hover/Reset) handled via hover:bg utilities or overlay below */}
+				<div className="absolute inset-0 z-0 bg-current opacity-0 transition-opacity hover:opacity-[0.08] focus:opacity-[0.12] active:opacity-[0.12]" />
+				
+				<span
+					className={`relative z-10 flex items-center justify-center ${gap}`}
+				>
+					{leadingIcon && (
+						<div className={`flex items-center justify-center ${iconSize}`}>
+							{leadingIcon}
+						</div>
+					)}
+
+					{children}
+				</span>
+				<Ripple />
+			</button>
+		);
+	}
+);
+Button.displayName = "Button";

package/src/components/card.stories.tsx

@@ -0,0 +1,109 @@
+import type { Meta, StoryObj } from "@storybook/react";
+import { Card } from "./card";
+
+const meta: Meta<typeof Card> = {
+  title: "Components/Card",
+  component: Card,
+  parameters: {
+    layout: "centered",
+  },
+  tags: ["autodocs"],
+  argTypes: {
+    variant: {
+      control: "select",
+      options: ["elevated", "filled", "outlined"],
+    },
+    padding: {
+      control: "select",
+      options: ["none", "sm", "md", "lg"],
+    },
+    radius: {
+      control: "select",
+      options: ["none", "sm", "md", "lg", "xl", "2xl"],
+    },
+    interactive: {
+      control: "boolean",
+    },
+  },
+};
+
+export default meta;
+type Story = StoryObj<typeof Card>;
+
+export const Elevated: Story = {
+  args: {
+    variant: "elevated",
+    children: (
+      <div className="flex flex-col gap-2">
+        <h3 className="text-xl font-medium">Elevated Card</h3>
+        <p className="text-gray-600 dark:text-gray-400">
+          This is an elevated card with a default shadow and color.
+        </p>
+      </div>
+    ),
+    className: "w-[300px]",
+  },
+};
+
+export const Filled: Story = {
+  args: {
+    variant: "filled",
+    children: (
+      <div className="flex flex-col gap-2">
+        <h3 className="text-xl font-medium">Filled Card</h3>
+        <p className="text-gray-600 dark:text-gray-400">
+          This is a filled card with a darker background.
+        </p>
+      </div>
+    ),
+    className: "w-[300px]",
+  },
+};
+
+export const Outlined: Story = {
+  args: {
+    variant: "outlined",
+    children: (
+      <div className="flex flex-col gap-2">
+        <h3 className="text-xl font-medium">Outlined Card</h3>
+        <p className="text-gray-600 dark:text-gray-400">
+          This is an outlined card with a thin border.
+        </p>
+      </div>
+    ),
+    className: "w-[300px]",
+  },
+};
+
+export const Interactive: Story = {
+  args: {
+    variant: "elevated",
+    interactive: true,
+    children: (
+      <div className="flex flex-col gap-2">
+        <h3 className="text-xl font-medium">Interactive Card</h3>
+        <p className="text-gray-600 dark:text-gray-400">
+          Click me to see the ripple effect and state layer!
+        </p>
+      </div>
+    ),
+    className: "w-[300px]",
+    onClick: () => alert("Card clicked!"),
+  },
+};
+
+export const CustomPadding: Story = {
+  args: {
+    variant: "filled",
+    padding: "lg",
+    children: (
+      <div className="flex flex-col gap-2">
+        <h3 className="text-xl font-medium">Large Padding</h3>
+        <p className="text-gray-600 dark:text-gray-400">
+          This card has extra padding for a more spacious feel.
+        </p>
+      </div>
+    ),
+    className: "w-[300px]",
+  },
+};

package/src/components/card.tsx

@@ -0,0 +1,92 @@
+import React from "react";
+import { cva, type VariantProps } from "class-variance-authority";
+import { clsx, type ClassValue } from "clsx";
+import { twMerge } from "tailwind-merge";
+import { Ripple } from "./ripple";
+
+// Utils
+function cn(...inputs: ClassValue[]) {
+  return twMerge(clsx(inputs));
+}
+
+const cardVariants = cva(
+	"relative overflow-hidden transition-all duration-200",
+	{
+		variants: {
+			variant: {
+				elevated:
+					"bg-surface-container-low shadow-elevation-1 hover:shadow-elevation-2 dark:bg-gray-900 dark:text-gray-100",
+				filled:
+					"bg-surface-container-highest dark:bg-gray-800 dark:text-gray-100",
+				outlined:
+					"border border-outline bg-transparent dark:border-gray-700 dark:text-gray-100",
+			},
+			padding: {
+				none: "p-0",
+				sm: "p-4",
+				md: "p-6",
+				lg: "p-8",
+			},
+			radius: {
+				none: "rounded-none",
+				sm: "rounded-sm",
+				md: "rounded-md",
+				lg: "rounded-lg",
+				xl: "rounded-xl", // M3 default (12px)
+				"2xl": "rounded-2xl",
+			},
+		},
+		defaultVariants: {
+			variant: "elevated",
+			padding: "md",
+			radius: "xl",
+		},
+	}
+);
+
+export interface CardProps
+	extends
+		React.HTMLAttributes<HTMLDivElement>,
+		VariantProps<typeof cardVariants> {
+	interactive?: boolean;
+}
+
+export const Card = React.forwardRef<HTMLDivElement, CardProps>(
+	(
+		{
+			className,
+			variant,
+			padding,
+			radius,
+			interactive,
+			children,
+			onClick,
+			...props
+		},
+		ref
+	) => {
+		const isInteractive = interactive || !!onClick;
+
+		return (
+			<div
+				ref={ref}
+				onClick={onClick}
+				className={cn(
+					cardVariants({ variant, padding, radius, className }),
+					isInteractive && "hover:cursor-pointer group"
+				)}
+				{...props}
+			>
+				{/* State Layer for interactive cards */}
+				{isInteractive && (
+					<div className="absolute inset-0 z-0 bg-current opacity-0 transition-opacity group-hover:opacity-[0.08] group-focus:opacity-[0.12] group-active:opacity-[0.12]" />
+				)}
+
+				<div className="relative z-10 w-full h-full">{children}</div>
+
+				{isInteractive && <Ripple />}
+			</div>
+		);
+	}
+);
+Card.displayName = "Card";

package/src/components/fabs/Fab.tsx

@@ -0,0 +1,81 @@
+/**
+ * Floating action buttons (FABs) help people take primary actions.
+ * https://m3.material.io/components/floating-action-button/specs
+ */
+
+import React from "react";
+import { cva, type VariantProps } from "class-variance-authority";
+import { Ripple } from "../ripple";
+import { cn } from "../../../lib/utils/helpers";
+
+
+const fabVariants = cva(
+	"relative inline-flex items-center justify-center transition-all hover:cursor-pointer disabled:pointer-events-none disabled:opacity-50 overflow-hidden",
+	{
+		variants: {
+			color: {
+				surface: "bg-white text-gray-900 dark:bg-gray-800 dark:text-gray-100",
+				primary: "bg-blue-100 text-blue-900 dark:bg-blue-900 dark:text-blue-100",
+				secondary: "bg-green-100 text-green-900 dark:bg-green-900 dark:text-green-100",
+				tertiary: "bg-pink-100 text-pink-900 dark:bg-pink-900 dark:text-pink-100",
+			},
+			size: {
+				small: "w-10 h-10 rounded-xl",
+				regular: "w-14 h-14 rounded-2xl",
+				medium: "w-20 h-20 rounded-3xl", // M3 Expressive
+				large: "w-24 h-24 rounded-[28px]",
+			},
+			variant: {
+				standard: "shadow-md hover:shadow-lg focus:shadow-md active:shadow-sm",
+				lowered: "shadow-sm hover:shadow-md focus:shadow-sm active:shadow-none",
+			},
+		},
+		defaultVariants: {
+			color: "surface",
+			size: "regular",
+			variant: "standard",
+		},
+	}
+);
+
+export interface FABProps
+	extends
+		Omit<React.ButtonHTMLAttributes<HTMLButtonElement>, "color">,
+		VariantProps<typeof fabVariants> {
+	children?: React.ReactNode;
+}
+
+const determineIconSize = (size: "small" | "regular" | "medium" | "large" | null | undefined) => {
+	switch (size) {
+		case "small":
+			return "w-6 h-6";
+		case "regular":
+			return "w-6 h-6";
+		case "medium":
+			return "w-7 h-7"; // 28x28dp
+		case "large":
+			return "w-9 h-9"; // 36x36dp
+		default:
+			return "w-6 h-6";
+	}
+};
+
+export const FAB = React.forwardRef<HTMLButtonElement, FABProps>(
+	({ className, color, size, variant, children, ...props }, ref) => {
+		const iconSize = determineIconSize(size);
+		return (
+			<button
+				className={cn(fabVariants({ color, size, variant, className }))}
+				ref={ref}
+				{...props}
+			>
+				<span className={cn("relative z-10 flex items-center justify-center", iconSize)}>
+					{children}
+				</span>
+				<Ripple />
+			</button>
+		);
+	}
+);
+
+FAB.displayName = "FAB";

package/src/components/fabs/extended-fab.tsx

@@ -0,0 +1,96 @@
+/**
+ * Extended Floating Action Buttons (FABs) help people take primary actions.
+ * https://m3.material.io/components/extended-fab/specs
+ */
+
+import React from "react";
+import { cva, type VariantProps } from "class-variance-authority";
+import { clsx, type ClassValue } from "clsx";
+import { twMerge } from "tailwind-merge";
+import { Ripple } from "../ripple";
+
+// Utils
+function cn(...inputs: ClassValue[]) {
+	return twMerge(clsx(inputs));
+}
+
+const extendedFabVariants = cva(
+	"relative inline-flex flex-row items-center justify-center transition-all hover:cursor-pointer disabled:pointer-events-none disabled:opacity-50 overflow-hidden h-14 w-fit rounded-2xl pr-5 pl-4 gap-2",
+	{
+		variants: {
+			color: {
+				surface: "bg-surface-container-high text-primary hover:bg-surface-container-highest", // M3 default for surface-colored FAB
+				primary: "bg-primary-container text-on-primary-container hover:bg-primary-container/90",
+				secondary: "bg-secondary-container text-on-secondary-container hover:bg-secondary-container/90",
+				tertiary: "bg-tertiary-container text-on-tertiary-container hover:bg-tertiary-container/90",
+			},
+			size: {
+				small: "h-14 rounded-2xl px-4 text-[16px] font-medium tracking-[0.15px]",
+				medium: "h-20 rounded-[20px] px-6.5 text-[22px] font-normal tracking-normal",
+				large: "h-24 rounded-[28px] px-7 text-2xl font-medium tracking-normal"
+			},
+			variant: {
+				standard: "shadow-md hover:shadow-lg focus:shadow-md active:shadow-sm",
+				lowered: "shadow-sm hover:shadow-md focus:shadow-sm active:shadow-none",
+			},
+		},
+		defaultVariants: {
+			color: "primary",
+			variant: "standard",
+			size: "medium"
+		},
+	}
+);
+
+export interface ExtendedFABProps
+	extends
+		Omit<React.ButtonHTMLAttributes<HTMLButtonElement>, "color">,
+		VariantProps<typeof extendedFabVariants> {
+	icon?: React.ReactNode;
+	label: string;
+	size?: "small" | "medium" | "large";
+}
+
+const determineGapAndIconSize = (
+	size: "small" | "medium" | "large" | null | undefined
+) => {
+	switch (size) {
+		case "small":
+			return ["gap-2", "w-6 h-6"];
+		case "medium":
+			return ["gap-3", "w-7 h-7"];
+		case "large":
+			return ["gap-4", "w-9 h-9"];
+		default:
+			return ["gap-3", "w-7 h-7"];
+	}
+};
+
+export const ExtendedFAB = React.forwardRef<HTMLButtonElement, ExtendedFABProps>(
+	({ className, color, variant, icon, label, size, ...props }, ref) => {
+		let [gap, iconSize] = determineGapAndIconSize(size);
+
+		return (
+			<button
+				className={`${cn(extendedFabVariants({ color, variant, size, className }))} ${gap}`}
+				ref={ref}
+				{...props}
+			>
+				{/* State Layer (Hover/Reset) handled via hover:bg utilities */}
+				{icon && (
+					<span
+						className={`relative z-10 flex items-center justify-center ${iconSize}`}
+					>
+						{icon}
+					</span>
+				)}
+				<span className="relative z-10 font-medium text-sm tracking-wide">
+					{label}
+				</span>
+				<Ripple />
+			</button>
+		);
+	}
+);
+
+ExtendedFAB.displayName = "ExtendedFAB";

package/src/components/fabs/fab.stories.tsx

@@ -0,0 +1,101 @@
+import type { Meta, StoryObj } from "@storybook/react";
+import { FAB } from "./fab";
+
+const meta: Meta<typeof FAB> = {
+	title: "Components/FAB",
+	component: FAB,
+	parameters: {
+		layout: "centered",
+	},
+	tags: ["autodocs"],
+	argTypes: {
+		color: {
+			control: "select",
+			options: ["surface", "primary", "secondary", "tertiary"],
+		},
+		size: {
+			control: "select",
+			options: ["small", "regular", "medium", "large"],
+		},
+		variant: {
+			control: "select",
+			options: ["standard", "lowered"],
+		},
+	},
+};
+
+export default meta;
+type Story = StoryObj<typeof FAB>;
+
+const PlusIcon = (
+	<svg
+		xmlns="http://www.w3.org/2000/svg"
+		width="100%"
+		height="100%"
+		viewBox="0 0 24 24"
+		fill="none"
+		stroke="currentColor"
+		strokeWidth="2"
+		strokeLinecap="round"
+		strokeLinejoin="round"
+	>
+		<path d="M5 12h14" />
+		<path d="M12 5v14" />
+	</svg>
+);
+
+export const Regular: Story = {
+	args: {
+		size: "regular",
+		children: PlusIcon,
+	},
+};
+
+export const Small: Story = {
+	args: {
+		size: "small",
+		children: PlusIcon,
+	},
+};
+
+export const MediumExpressive: Story = {
+	args: {
+		size: "medium",
+		children: PlusIcon,
+	},
+};
+
+export const Large: Story = {
+	args: {
+		size: "large",
+		children: PlusIcon,
+	},
+};
+
+export const Primary: Story = {
+	args: {
+		color: "primary",
+		children: PlusIcon,
+	},
+};
+
+export const Secondary: Story = {
+	args: {
+		color: "secondary",
+		children: PlusIcon,
+	},
+};
+
+export const Tertiary: Story = {
+	args: {
+		color: "tertiary",
+		children: PlusIcon,
+	},
+};
+
+export const Lowered: Story = {
+	args: {
+		variant: "lowered",
+		children: PlusIcon,
+	},
+};

package/src/components/navigation-rail/action.tsx

@@ -0,0 +1,44 @@
+import { ExtendedFAB, ExtendedFABProps } from "../fabs/extended-fab";
+import { FAB } from "../fabs/fab";
+import { cn } from "../../../lib/utils/helpers";
+import { clsx } from "clsx";
+import { FabConfig } from "../../../types/navigation-rail";
+
+interface ActionProps {
+	isExpanded: boolean;
+	fabConfig: FabConfig;
+}
+
+export const Action = ({ isExpanded, fabConfig }: ActionProps) => {
+	return (
+		<div
+			className={cn(
+				`px-4 py-2 flex-col ${clsx({ "items-center": !isExpanded })} min-h-14 transition-all duration-300`,
+				!isExpanded ? "hidden md:flex" : "flex"
+			)}
+		>
+			{isExpanded ? (
+				<ExtendedFAB
+					icon={fabConfig.icon}
+					label={fabConfig.label}
+					onClick={fabConfig.onClick}
+					color={fabConfig.color as ExtendedFABProps["color"]}
+					variant={fabConfig.variant}
+					size={"small"}
+					className={fabConfig.className}
+				/>
+			) : (
+				<FAB
+					size="regular" // Standard 56dp container
+					color={fabConfig.color}
+					variant={fabConfig.variant}
+					onClick={fabConfig.onClick}
+					aria-label={fabConfig.label}
+					className={fabConfig.className}
+				>
+					{fabConfig.icon}
+				</FAB>
+			)}
+		</div>
+	);
+};

package/src/components/navigation-rail/index.tsx

@@ -0,0 +1,126 @@
+"use client";
+
+/**
+ * Navigation rails provide access to primary destinations in apps.
+ * https://m3.material.io/components/navigation-rail/overview
+ */
+
+import React from "react";
+import { cva } from "class-variance-authority";
+import { clsx } from "clsx";
+import {
+	NavRailProps,
+	NavRailDestinationConfig,
+} from "../../../types/navigation-rail";
+export type { NavRailProps, NavRailDestinationConfig };
+import { NavigationRailDestination } from "./navigation-rail-destination";
+import { cn } from "../../../lib/utils/helpers";
+import { MenuButton } from "./menu-button";
+import { Action } from "./action";
+
+export const NavigationRail = ({
+	expanded: expandedProp,
+	destinations,
+	activeId,
+	showFab = false,
+	fabConfig,
+	showMenuButton = true,
+	onExpandedChange,
+	className,
+	alignment = "center",
+	backgroundColor = "bg-surface",
+	textColor = "text-on-surface hover:text-on-surface",
+	activeBgColor,
+	activeTextColor,
+	...props
+}: NavRailProps) => {
+	const [internalExpanded, setInternalExpanded] = React.useState(false);
+	const isExpanded = expandedProp ?? internalExpanded;
+
+	const handleToggle = () => {
+		const newState = !isExpanded;
+		if (expandedProp == null) {
+			setInternalExpanded(newState);
+		}
+		onExpandedChange?.(newState);
+	};
+
+	const visibleDestinations = destinations.filter((d) => !d.hidden).slice(0, 6);
+
+	// Handle backdrop click to close on mobile
+	const handleBackdropClick = () => {
+		if (expandedProp == null) {
+			setInternalExpanded(false);
+		}
+		onExpandedChange?.(false);
+	};
+
+	const navRailVariants = cva(
+		"flex flex-col transition-all duration-300 ease-[cubic-bezier(0.2,0,0,1)] z-50 scrollbar-none py-4",
+		{
+			variants: {
+				expanded: {
+					true: `fixed ${backgroundColor} inset-y-0 left-0 w-72 shadow-2xl h-dvh md:relative md:w-80 md:shadow-none`, // Mobile: Fixed Drawer. Desktop: Relative Rail.
+					false: `w-fit h-auto bg-transparent absolute md:relative md:w-24 md:${backgroundColor} md:h-dvh`, // Mobile: Just button. Desktop: Standard Rail.
+				},
+			},
+			defaultVariants: {
+				expanded: false,
+			},
+		}
+	);
+
+	return (
+		<>
+			{/* Mobile Backdrop */}
+			{isExpanded && (
+				<div
+					className="fixed inset-0 bg-black/40 z-40 md:hidden transition-opacity duration-300"
+					onClick={handleBackdropClick}
+					aria-hidden="true"
+				/>
+			)}
+
+			<nav
+				className={cn(navRailVariants({ expanded: isExpanded, className }))}
+				{...props}
+			>
+				<div className="flex flex-col gap-2">
+					<MenuButton
+						isExpanded={isExpanded}
+						showMenuButton={showMenuButton}
+						handleToggle={handleToggle}
+					/>
+
+					{/* FAB - Hidden on mobile collapsed */}
+					{showFab && fabConfig && (
+						<Action isExpanded={isExpanded} fabConfig={fabConfig} />
+					)}
+				</div>
+
+				{/* destinations - Hidden on mobile collapsed */}
+				<div
+					className={cn(
+						`flex-1 flex-col gap-1 py-4 ${clsx({ "justify-center": alignment === "center" })}`,
+						!isExpanded ? "hidden md:flex" : "flex"
+					)}
+				>
+					<div>
+						{visibleDestinations.map((dest) => (
+							<NavigationRailDestination
+								key={dest.id}
+								icon={dest.icon}
+								label={dest.label}
+								badge={dest.badge}
+								active={dest.id === activeId}
+								expanded={isExpanded}
+								onClick={dest.onClick}
+								href={dest.href}
+							/>
+						))}
+					</div>
+				</div>
+			</nav>
+		</>
+	);
+};

package/src/components/navigation-rail/menu-button.tsx

@@ -0,0 +1,33 @@
+import { MenuIcon } from "../../../lib/icons/menu-icon";
+import { MenuOpenIcon } from "../../../lib/icons/menu-open-icon";
+import { Ripple } from "../ripple";
+import { clsx } from "clsx";
+
+interface MenuButtonProps {
+	isExpanded: boolean;
+	showMenuButton?: boolean;
+	handleToggle: () => void;
+}
+
+export const MenuButton = ({
+	isExpanded,
+	showMenuButton = true,
+	handleToggle,
+}: MenuButtonProps) => {
+	return (
+		<div
+			className={`p-4 flex flex-col ${clsx({ "items-center": !isExpanded, "block md:hidden": !showMenuButton })}`}
+		>
+			<button
+				onClick={handleToggle}
+				className="w-12 h-12 flex items-center justify-center rounded-full hover:bg-on-surface/10 transition-colors cursor-pointer relative overflow-hidden"
+				aria-label={isExpanded ? "Collapse navigation" : "Expand navigation"}
+			>
+				<div className="relative z-10">
+					{isExpanded ? <MenuOpenIcon /> : <MenuIcon />}
+				</div>
+				<Ripple />
+			</button>
+		</div>
+	);
+};

package/src/components/navigation-rail/navigation-rail-destination.tsx

@@ -0,0 +1,83 @@
+import { cva } from "class-variance-authority";
+import { Ripple } from "../ripple";
+import { NavRailDestinationProps } from "../../../types/navigation-rail";
+import {cn} from "../../../lib/utils/helpers";
+
+const navItemVariants = cva(
+	"relative flex items-center group cursor-pointer transition-all duration-300 ease-[cubic-bezier(0.2,0,1)] px-4 py-3 outline-none focus-visible:outline-2 focus-visible:outline-primary w-fit",
+	{
+		variants: {
+			expanded: {
+				true: "flex-row gap-4 h-14 rounded-full mx-3",
+				false: "flex-col gap-1 h-auto min-h-14 justify-center",
+			},
+		},
+		defaultVariants: {
+			expanded: false,
+		},
+	}
+);
+
+export const NavigationRailDestination = ({
+	icon,
+	label,
+	active = false,
+	expanded = false,
+	badge,
+	activeBgColor = "bg-secondary-container",
+	activeTextColor = "text-on-secondary-container",
+	className,
+	href,
+	...props
+}: NavRailDestinationProps) => {
+	const Component = href ? "a" : "div";
+	const activeIndicatorVariants = cva(
+		"absolute rounded-full z-0 transition-all duration-300 ease-[cubic-bezier(0.2,0,0,1)]" +
+			` ${activeBgColor} ${activeTextColor}`,
+		{
+			variants: {
+				active: {
+					true: "opacity-100",
+					false: "opacity-0 scale-x-50",
+				},
+				expanded: {
+					true: "inset-0 h-14 px-4 w-full",
+					false: "inset-x-0 mx-auto top-3 h-8 w-14", // 56dp indicator in collapsed
+				},
+			},
+		}
+	);
+
+	return (
+		<Component
+			className={cn(navItemVariants({ expanded, className }), "no-underline")}
+			href={href}
+			{...(props as any)}
+		>
+			<div className={cn(activeIndicatorVariants({ active, expanded }))} />
+
+			<div className="relative z-10 flex items-center justify-center w-14 h-8">
+				<div className="relative">
+					{icon}
+					{badge !== undefined && (
+						<span className="absolute -top-1 -right-1 flex h-4 min-w-4 px-1 items-center justify-center rounded-full bg-error text-on-error text-[10px] font-medium border-2 border-surface">
+							{badge}
+						</span>
+					)}
+				</div>
+			</div>
+
+			<span
+				className={cn(
+					"relative z-10 transition-all duration-300 font-medium text-center",
+					expanded
+						? "text-base whitespace-nowrap overflow-hidden text-ellipsis"
+						: "text-xs"
+				)}
+			>
+				{label}
+			</span>
+			<Ripple />
+		</Component>
+	);
+};

package/src/components/navigation-rail/navigation-rail.stories.tsx

@@ -0,0 +1,123 @@
+import type { Meta, StoryObj } from "@storybook/react";
+import { NavigationRail, type NavRailDestinationConfig } from ".";
+import { useState } from "react";
+
+const meta: Meta<typeof NavigationRail> = {
+	title: "Components/NavigationRail",
+	component: NavigationRail,
+	parameters: {
+		layout: "fullscreen",
+	},
+	tags: ["autodocs"],
+};
+
+export default meta;
+
+const HomeIcon = () => (
+	<svg width="24" height="24" viewBox="0 0 24 24" fill="currentColor">
+		<path d="M10 20v-6h4v6h5v-8h3L12 3 2 12h3v8z" />
+	</svg>
+);
+
+const SearchIcon = () => (
+	<svg width="24" height="24" viewBox="0 0 24 24" fill="currentColor">
+		<path d="M15.5 14h-.79l-.28-.27A6.471 6.471 0 0 0 16 9.5 6.5 6.5 0 1 0 9.5 16c1.61 0 3.09-.59 4.23-1.57l.27.28v.79l5 4.99L20.49 19l-4.99-5zm-6 0C7.01 14 5 11.99 5 9.5S7.01 5 9.5 5 14 7.01 14 9.5 11.99 14 9.5 14z" />
+	</svg>
+);
+
+const InboxIcon = () => (
+	<svg width="24" height="24" viewBox="0 0 24 24" fill="currentColor">
+		<path d="M19 3H5c-1.1 0-2 .9-2 2v14c0 1.1.9 2 2 2h14c1.1 0 2-.9 2-2V5c0-1.1-.9-2-2-2zm0 16H5v-3h3.56c.69 1.19 1.97 2 3.44 2s2.75-.81 3.44-2H19v3zm0-5h-4.99c0 1.1-.9 2-2 2s-2-.9-2-2H5V5h14v9z" />
+	</svg>
+);
+
+const SettingsIcon = () => (
+	<svg width="24" height="24" viewBox="0 0 24 24" fill="currentColor">
+		<path d="M19.14 12.94c.04-.3.06-.61.06-.94 0-.32-.02-.64-.07-.94l2.03-1.58c.18-.14.23-.41.12-.61l-1.92-3.32c-.12-.22-.37-.29-.59-.22l-2.39.96c-.5-.38-1.03-.7-1.62-.94l-.36-2.54c-.04-.24-.24-.41-.48-.41h-3.84c-.24 0-.43.17-.47.41l-.36 2.54c-.59.24-1.13.57-1.62.94l-2.39-.96c-.22-.08-.47 0-.59.22L2.74 8.87c-.12.21-.08.47.12.61l2.03 1.58c-.05.3-.09.63-.09.94s.02.64.07.94l-2.03 1.58c-.18.14-.23.41-.12.61l1.92 3.32c.12.22.37.29.59.22l2.39-.96c.5.38 1.03.7 1.62.94l.36 2.54c.05.24.24.41.48.41h3.84c.24 0 .44-.17.47-.41l.36-2.54c.59-.24 1.13-.56 1.62-.94l2.39.96c.22.08.47 0 .59-.22l1.92-3.32c.12-.22.07-.47-.12-.61l-2.01-1.58zM12 15.6c-1.98 0-3.6-1.62-3.6-3.6s1.62-3.6 3.6-3.6 3.6 1.62 3.6 3.6-1.62 3.6-3.6 3.6z" />
+	</svg>
+);
+
+const demoDestinations: NavRailDestinationConfig[] = [
+	{ id: "home", icon: <HomeIcon />, label: "Home" },
+	{ id: "search", icon: <SearchIcon />, label: "Search" },
+	{ id: "inbox", icon: <InboxIcon />, label: "Inbox", badge: 3 },
+	{ id: "settings", icon: <SettingsIcon />, label: "Settings" },
+];
+
+export const Interactive: StoryObj<typeof NavigationRail> = {
+	render: () => {
+		const [active, setActive] = useState("home");
+
+		const destinationsWithClick = demoDestinations.map((d) => ({
+			...d,
+			onClick: () => setActive(d.id),
+		}));
+
+		return (
+			<div className="flex h-screen bg-surface-container-low">
+				<NavigationRail destinations={destinationsWithClick} activeId={active} />
+				<main className="flex-1 p-8">
+					<h1 className="text-2xl font-bold">Content Area</h1>
+					<p className="mt-4 text-on-surface-variant">The menu button is built-in and state-aware.</p>
+				</main>
+			</div>
+		);
+	},
+};
+
+export const Collapsed: StoryObj<typeof NavigationRail> = {
+	args: {
+		expanded: false,
+		destinations: demoDestinations,
+		activeId: "home",
+	},
+};
+
+export const Expanded: StoryObj<typeof NavigationRail> = {
+	args: {
+		expanded: true,
+		destinations: demoDestinations,
+		activeId: "home",
+	},
+};
+
+export const HiddenSlots: StoryObj<typeof NavigationRail> = {
+	args: {
+		expanded: false,
+		destinations: [
+			...demoDestinations,
+			{ id: "hidden", icon: <SettingsIcon />, label: "Hidden", hidden: true },
+		],
+		activeId: "home",
+	},
+};
+
+export const NoMenuButton: StoryObj<typeof NavigationRail> = {
+	args: {
+		showMenuButton: false,
+		destinations: demoDestinations,
+		activeId: "home",
+	},
+};
+export const WithLinks: StoryObj<typeof NavigationRail> = {
+	args: {
+		destinations: [
+			{ id: "home", icon: <HomeIcon />, label: "Home", href: "/" },
+			{ id: "search", icon: <SearchIcon />, label: "Search", href: "/search" },
+			{
+				id: "inbox",
+				icon: <InboxIcon />,
+				label: "Inbox",
+				badge: 3,
+				href: "/inbox",
+			},
+			{
+				id: "settings",
+				icon: <SettingsIcon />,
+				label: "Settings",
+				href: "/settings",
+			},
+		],
+		activeId: "home",
+	},
+};

package/src/components/ripple.tsx

@@ -0,0 +1,64 @@
+"use client";
+
+import React, { useState, useEffect } from "react";
+
+// Types
+interface RippleType {
+	x: number;
+	y: number;
+	size: number;
+}
+
+/**
+ * A material design ripple effect component.
+ * To use this, the parent container must have `relative` and `overflow-hidden`.
+ */
+export const Ripple = () => {
+	const [ripples, setRipples] = useState<RippleType[]>([]);
+
+	useEffect(() => {
+		let bounce: NodeJS.Timeout | null = null;
+		if (ripples.length > 0) {
+			bounce = setTimeout(() => {
+				setRipples([]);
+			}, 600);
+		}
+		return () => {
+			if (bounce) clearTimeout(bounce);
+		};
+	}, [ripples.length]);
+
+	const addRipple = (event: React.MouseEvent<HTMLDivElement>) => {
+		const container = event.currentTarget.getBoundingClientRect();
+		const size =
+			container.width > container.height ? container.width : container.height;
+		const x = event.clientX - container.left - size / 2;
+		const y = event.clientY - container.top - size / 2;
+		const newRipple = { x, y, size };
+
+		setRipples((prev) => [...prev, newRipple]);
+	};
+
+	return (
+		<div
+			className="absolute inset-0 z-0 overflow-hidden rounded-[inherit]"
+			onMouseDown={addRipple}
+		>
+			{ripples.map((ripple, index) => {
+				return (
+					<span
+						key={index}
+						className="absolute animate-ripple rounded-full bg-white opacity-25"
+						style={{
+							top: ripple.y,
+							left: ripple.x,
+							width: ripple.size,
+							height: ripple.size,
+							transform: "scale(0)",
+						}}
+					/>
+				);
+			})}
+		</div>
+	);
+};

package/src/index.ts

@@ -0,0 +1,10 @@
+export * from "./components/button";
+export * from "./components/card";
+export * from "./components/fabs/fab";
+export * from "./components/navigation-rail";
+// Ripple is internal-ish but we can export it if users want raw ripples
+export { Ripple } from "./components/ripple";
+export * from "./components/fabs/extended-fab";
+
+// types
+export * from "../types/navigation-rail";

package/src/styles.css

@@ -0,0 +1,2 @@
+@import "tailwindcss";
+@import "./base.css";