@bug-on/md3-react 3.0.2 → 3.0.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bug-on/md3-react",
-  "version": "3.0.2",
+  "version": "3.0.3",
   "description": "Material Design 3 Expressive React components",
   "author": "Bug Ổn",
   "license": "MIT",
@@ -23,9 +23,14 @@
   "types": "./dist/index.d.ts",
   "exports": {
     ".": {
-      "types": "./dist/index.d.ts",
-      "import": "./dist/index.mjs",
-      "require": "./dist/index.js"
+      "import": {
+        "types": "./dist/index.d.mts",
+        "default": "./dist/index.mjs"
+      },
+      "require": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      }
     },
     "./typography.css": {
       "types": "./dist/typography.css.d.ts",
@@ -69,8 +74,8 @@
     "class-variance-authority": "^0.7.1",
     "clsx": "^2.1.1",
     "tailwind-merge": "^3.3.1",
-    "@bug-on/md3-tokens": "3.0.1",
-    "@bug-on/md3-tailwind": "3.0.1"
+    "@bug-on/md3-tokens": "3.0.3",
+    "@bug-on/md3-tailwind": "3.0.3"
   },
   "devDependencies": {
     "@testing-library/jest-dom": "^6.9.1",

package/scripts/copy-assets.js

@@ -26,16 +26,13 @@ if (fs.existsSync(srcCss)) {
 	console.log("✅ Copied typography.css to dist/typography.css");
 }
 
-// Bundle index.css = md3-tokens CSS + react component base styles.
-// This ensures users only need to import @bug-on/md3-react/index.css
-// and get all required design tokens automatically.
+// Bundle index.css = md3-tokens CSS + react component base styles + @theme block.
+// Users only need: @import "@bug-on/md3-react/index.css" — zero manual config.
 const tokensCssDir = path.join(__dirname, "../../tokens/dist");
 const tokensColorsCss = path.join(tokensCssDir, "colors.css");
 const tokensShapeCss = path.join(tokensCssDir, "shape.css");
 
-const bundleParts = [
-	"/* @bug-on/md3-tokens — MD3 System Color Tokens */",
-];
+const bundleParts = ["/* @bug-on/md3-tokens — MD3 System Color Tokens */"];
 
 if (fs.existsSync(tokensColorsCss)) {
 	bundleParts.push(fs.readFileSync(tokensColorsCss, "utf-8"));
@@ -58,9 +55,117 @@ if (fs.existsSync(srcIndexCss)) {
 	);
 }
 
-fs.writeFileSync(distIndexCss, bundleParts.join("\n"));
-console.log("✅ Built bundled index.css (tokens + component base) to dist/index.css");
+// ── Tailwind v4 @theme block ─────────────────────────────────────────────────
+// Registers MD3 system tokens as Tailwind design tokens so utility classes
+// like bg-m3-primary, text-m3-on-surface, rounded-m3-xl work automatically.
+// Tailwind v4 processes @theme blocks inside @imported CSS files.
+const tailwindThemeBlock = `
+/* @bug-on/md3-react — Tailwind v4 Theme Registration */
+/* Registers MD3 tokens as Tailwind utilities. No manual @theme mapping needed. */
+@theme {
+  /* ── Colors: Primary ── */
+  --color-m3-primary: var(--md-sys-color-primary);
+  --color-m3-on-primary: var(--md-sys-color-on-primary);
+  --color-m3-primary-container: var(--md-sys-color-primary-container);
+  --color-m3-on-primary-container: var(--md-sys-color-on-primary-container);
+  --color-m3-primary-fixed: var(--md-sys-color-primary-fixed);
+  --color-m3-primary-fixed-dim: var(--md-sys-color-primary-fixed-dim);
+  --color-m3-on-primary-fixed: var(--md-sys-color-on-primary-fixed);
+  --color-m3-on-primary-fixed-variant: var(--md-sys-color-on-primary-fixed-variant);
+
+  /* ── Colors: Secondary ── */
+  --color-m3-secondary: var(--md-sys-color-secondary);
+  --color-m3-on-secondary: var(--md-sys-color-on-secondary);
+  --color-m3-secondary-container: var(--md-sys-color-secondary-container);
+  --color-m3-on-secondary-container: var(--md-sys-color-on-secondary-container);
+  --color-m3-secondary-fixed: var(--md-sys-color-secondary-fixed);
+  --color-m3-secondary-fixed-dim: var(--md-sys-color-secondary-fixed-dim);
+  --color-m3-on-secondary-fixed: var(--md-sys-color-on-secondary-fixed);
+  --color-m3-on-secondary-fixed-variant: var(--md-sys-color-on-secondary-fixed-variant);
+
+  /* ── Colors: Tertiary ── */
+  --color-m3-tertiary: var(--md-sys-color-tertiary);
+  --color-m3-on-tertiary: var(--md-sys-color-on-tertiary);
+  --color-m3-tertiary-container: var(--md-sys-color-tertiary-container);
+  --color-m3-on-tertiary-container: var(--md-sys-color-on-tertiary-container);
+  --color-m3-tertiary-fixed: var(--md-sys-color-tertiary-fixed);
+  --color-m3-tertiary-fixed-dim: var(--md-sys-color-tertiary-fixed-dim);
+  --color-m3-on-tertiary-fixed: var(--md-sys-color-on-tertiary-fixed);
+  --color-m3-on-tertiary-fixed-variant: var(--md-sys-color-on-tertiary-fixed-variant);
+
+  /* ── Colors: Error ── */
+  --color-m3-error: var(--md-sys-color-error);
+  --color-m3-on-error: var(--md-sys-color-on-error);
+  --color-m3-error-container: var(--md-sys-color-error-container);
+  --color-m3-on-error-container: var(--md-sys-color-on-error-container);
+
+  /* ── Colors: Surface ── */
+  --color-m3-surface: var(--md-sys-color-surface);
+  --color-m3-surface-dim: var(--md-sys-color-surface-dim);
+  --color-m3-surface-bright: var(--md-sys-color-surface-bright);
+  --color-m3-on-surface: var(--md-sys-color-on-surface);
+  --color-m3-surface-variant: var(--md-sys-color-surface-variant);
+  --color-m3-on-surface-variant: var(--md-sys-color-on-surface-variant);
+  --color-m3-surface-container-lowest: var(--md-sys-color-surface-container-lowest);
+  --color-m3-surface-container-low: var(--md-sys-color-surface-container-low);
+  --color-m3-surface-container: var(--md-sys-color-surface-container);
+  --color-m3-surface-container-high: var(--md-sys-color-surface-container-high);
+  --color-m3-surface-container-highest: var(--md-sys-color-surface-container-highest);
+
+  /* ── Colors: Inverse ── */
+  --color-m3-inverse-surface: var(--md-sys-color-inverse-surface);
+  --color-m3-inverse-on-surface: var(--md-sys-color-inverse-on-surface);
+  --color-m3-inverse-primary: var(--md-sys-color-inverse-primary);
+
+  /* ── Colors: Outline / Shadow / Scrim ── */
+  --color-m3-outline: var(--md-sys-color-outline);
+  --color-m3-outline-variant: var(--md-sys-color-outline-variant);
+  --color-m3-shadow: var(--md-sys-color-shadow);
+  --color-m3-scrim: var(--md-sys-color-scrim);
+  --color-m3-surface-tint: var(--md-sys-color-surface-tint);
+
+  /* ── Colors: Background ── */
+  --color-m3-background: var(--md-sys-color-background);
+  --color-m3-on-background: var(--md-sys-color-on-background);
+
+  /* ── Colors: Navigation Indicator ── */
+  --color-m3-indicator-active: var(--md-sys-color-indicator-active);
+  --color-m3-indicator-container: var(--md-sys-color-indicator-container);
+  --color-m3-indicator-contained-active: var(--md-sys-color-indicator-contained-active);
+  --color-m3-indicator-contained-container: var(--md-sys-color-indicator-contained-container);
+  --color-m3-indicator-track: var(--md-sys-color-indicator-track);
+  --color-m3-indicator-stop: var(--md-sys-color-indicator-stop);
+
+  /* ── Shape: Corner Radius Scale (10 levels, M3 Expressive) ── */
+  --radius-m3-none: var(--md-sys-shape-corner-none, 0px);
+  --radius-m3-xs: var(--md-sys-shape-corner-extra-small, 4px);
+  --radius-m3-sm: var(--md-sys-shape-corner-small, 8px);
+  --radius-m3-md: var(--md-sys-shape-corner-medium, 12px);
+  --radius-m3-lg: var(--md-sys-shape-corner-large, 16px);
+  --radius-m3-lg-inc: var(--md-sys-shape-corner-large-increased, 20px);
+  --radius-m3-xl: var(--md-sys-shape-corner-extra-large, 28px);
+  --radius-m3-xl-inc: var(--md-sys-shape-corner-extra-large-increased, 32px);
+  --radius-m3-xxl: var(--md-sys-shape-corner-extra-extra-large, 48px);
+  --radius-m3-full: var(--md-sys-shape-corner-full, 9999px);
+
+  /* ── Motion Easing ── */
+  --ease-m3-emphasized: cubic-bezier(0.2, 0, 0, 1);
+  --ease-m3-emphasized-accelerate: cubic-bezier(0.3, 0, 0.8, 0.15);
+  --ease-m3-emphasized-decelerate: cubic-bezier(0.05, 0.7, 0.1, 1);
+  --ease-m3-standard: cubic-bezier(0.2, 0, 0, 1);
+  --ease-m3-standard-accelerate: cubic-bezier(0.3, 0, 1, 1);
+  --ease-m3-standard-decelerate: cubic-bezier(0, 0, 0, 1);
+}
+`;
+bundleParts.push(tailwindThemeBlock);
 
+fs.writeFileSync(distIndexCss, bundleParts.join("\n"));
+console.log(
+	"✅ Built bundled index.css (tokens + @theme + component base) to dist/index.css",
+);
+console.log(
+	"✅ Tailwind v4 @theme block injected — bg-m3-primary etc. work without manual mapping",
+);
 
 // Copy Material Symbols CSS variants
 const cssVariants = [

package/src/index.ts

@@ -62,10 +62,34 @@ export {
 export type { BadgedBoxProps, BadgeProps } from "./ui/badge";
 // Badge — MD3 Expressive status indicator
 export { Badge, BadgedBox } from "./ui/badge";
-export type { BaseButtonProps, ButtonProps } from "./ui/button";
-export { Button } from "./ui/button";
-export type { ButtonGroupProps } from "./ui/button-group";
-export { ButtonGroup } from "./ui/button-group";
+export type { BaseButtonProps, ButtonProps } from "./ui/buttons/button";
+export {
+	BUTTON_COLOR_TOKENS,
+	BUTTON_SIZE_TOKENS,
+	Button,
+} from "./ui/buttons/button";
+export type {
+	ButtonGroupOrientation,
+	ButtonGroupProps,
+	ButtonGroupVariant,
+} from "./ui/buttons/button-group";
+export { ButtonGroup } from "./ui/buttons/button-group";
+export type { FABPositionProps, FABProps } from "./ui/buttons/fabs/fab";
+// Floating Action Button
+export { FAB, FABPosition } from "./ui/buttons/fabs/fab";
+export type {
+	FABMenuItemData,
+	FABMenuItemProps,
+	FABMenuProps,
+	ToggleFABProps,
+} from "./ui/buttons/fabs/fab-menu";
+// FAB Menu
+export { FABMenu, FABMenuItem, ToggleFAB } from "./ui/buttons/fabs/fab-menu";
+export type {
+	BaseIconButtonProps,
+	IconButtonProps,
+} from "./ui/buttons/icon-button";
+export { IconButton } from "./ui/buttons/icon-button";
 export type { CardProps } from "./ui/card";
 export { Card } from "./ui/card";
 // Checkbox — MD3 Expressive tri-state checkbox
@@ -117,22 +141,9 @@ export {
 	DrawerTitle,
 	DrawerTrigger,
 } from "./ui/drawer";
-export type { FABPositionProps, FABProps } from "./ui/fab";
-// Floating Action Button
-export { FAB, FABPosition } from "./ui/fab";
-export type {
-	FABMenuItemData,
-	FABMenuItemProps,
-	FABMenuProps,
-	ToggleFABProps,
-} from "./ui/fab-menu";
-// FAB Menu
-export { FABMenu, FABMenuItem, ToggleFAB } from "./ui/fab-menu";
 // Icon — Material Symbols variable font
 export type { IconProps } from "./ui/icon";
 export { Icon } from "./ui/icon";
-export type { BaseIconButtonProps, IconButtonProps } from "./ui/icon-button";
-export { IconButton } from "./ui/icon-button";
 export type { LoadingIndicatorProps } from "./ui/loading-indicator";
 export { LoadingIndicator } from "./ui/loading-indicator";
 // MD3 Expressive Menu — Standard + Vibrant + shape morphing
@@ -198,8 +209,8 @@ export {
 } from "./ui/menu";
 // Navigation Bar
 export type {
-	NavigationBarItemProps,
 	NavigationBarItemLayout,
+	NavigationBarItemProps,
 	NavigationBarProps,
 	NavigationBarVariant,
 } from "./ui/navigation-bar";
@@ -289,7 +300,6 @@ export {
 // Switch — MD3 Expressive toggle
 export type { SwitchProps } from "./ui/switch";
 export { Switch, SwitchColors, SwitchTokens } from "./ui/switch";
-export { Text, type TextProps } from "./ui/Text";
 // Tabs — MD3 Expressive navigation tabs
 export type {
 	TabProps,
@@ -306,6 +316,9 @@ export {
 	TabsList,
 	TabsTokens,
 } from "./ui/tabs";
+// Text — MD3 Expressive Typography component
+export type { TextProps } from "./ui/text";
+export { Text } from "./ui/text";
 // TextField — MD3 Expressive
 export type {
 	TextFieldHandle,
@@ -319,6 +332,33 @@ export type { MD3ThemeProviderProps } from "./ui/theme-provider";
 export { MD3ThemeProvider, useTheme, useThemeMode } from "./ui/theme-provider";
 export type { TableOfContentsProps, ToCItem } from "./ui/toc";
 export { TableOfContents } from "./ui/toc";
+// Toolbar — MD3 Expressive
+export type {
+	BottomDockedToolbarProps,
+	FloatingToolbarColors,
+	FloatingToolbarProps,
+	FloatingToolbarScrollBehavior,
+	FloatingToolbarWithFabProps,
+	ToolbarDividerProps,
+	ToolbarIconButtonProps,
+	ToolbarIconButtonSize,
+	ToolbarIconButtonVariant,
+	UseFloatingToolbarScrollBehaviorOptions,
+} from "./ui/toolbar";
+export {
+	BottomDockedToolbar,
+	HorizontalFloatingToolbar,
+	HorizontalFloatingToolbarWithFab,
+	standardFloatingToolbarColors,
+	ToolbarDivider,
+	ToolbarDividerTokens,
+	ToolbarIconButton,
+	ToolbarIconButtonTokens,
+	useFloatingToolbarScrollBehavior,
+	VerticalFloatingToolbar,
+	VerticalFloatingToolbarWithFab,
+	vibrantFloatingToolbarColors,
+} from "./ui/toolbar";
 // Tooltip — MD3 Expressive
 export type {
 	CaretConfig,

package/src/test/button.test.tsx

@@ -1,7 +1,7 @@
 import { render, screen } from "@testing-library/react";
 import userEvent from "@testing-library/user-event";
 import { describe, expect, it, vi } from "vitest";
-import { Button } from "../ui/button";
+import { Button } from "../ui/buttons/button";
 
 describe("Button Loading State", () => {
 	it("does not render LoadingIndicator by default", () => {

package/src/ui/app-bar/app-bar.tokens.ts

@@ -14,6 +14,8 @@
  * @see docs/m3/app-bars/
  */
 
+import { DEFAULT_SPATIAL_SPRING } from "../shared/motion-tokens";
+
 // ─── Dimensional Tokens ───────────────────────────────────────────────────────
 
 /**
@@ -186,32 +188,11 @@ export const APP_BAR_COLOR_TRANSITION = {
  * Spring animation for enterAlways behavior (hide/show on scroll direction).
  * Equivalent to MD3 FastSpatial motion scheme.
  */
-export const APP_BAR_ENTER_ALWAYS_SPRING = {
-	type: "spring",
-	stiffness: 380,
-	damping: 40,
-	mass: 1,
-} as const;
+export const APP_BAR_ENTER_ALWAYS_SPRING = DEFAULT_SPATIAL_SPRING;
 
-/**
- * Spring animation for Bottom App Bar hide/show.
- * Slightly looser feel for bottom navigation.
- */
-export const APP_BAR_BOTTOM_SPRING = {
-	type: "spring",
-	stiffness: 300,
-	damping: 30,
-} as const;
+export const APP_BAR_BOTTOM_SPRING = DEFAULT_SPATIAL_SPRING;
 
-/**
- * SearchView appearance/disappearance transition.
- * Uses spring for natural feel of expanding overlay.
- */
-export const SEARCH_VIEW_SPRING = {
-	type: "spring",
-	stiffness: 400,
-	damping: 35,
-} as const;
+export const SEARCH_VIEW_SPRING = DEFAULT_SPATIAL_SPRING;
 
 /**
  * Title crossfade transition for flexible App Bars.

package/src/ui/badge.tsx

@@ -32,6 +32,7 @@ import {
 } from "motion/react";
 import * as React from "react";
 import { cn } from "../lib/utils";
+import { FAST_SPATIAL_SPRING } from "./shared/motion-tokens";
 
 // ─────────────────────────────────────────────────────────────────────────────
 // Types
@@ -159,7 +160,7 @@ const BadgeImpl = React.forwardRef<HTMLSpanElement, BadgeProps>(
 
 		const springTransition = reducedMotion
 			? { duration: 0 }
-			: { type: "spring" as const, stiffness: 500, damping: 30, mass: 0.8 };
+			: FAST_SPATIAL_SPRING;
 
 		const colorStyle: React.CSSProperties = {
 			...(containerColor && { backgroundColor: containerColor }),

package/src/ui/buttons/button/button-tokens.ts

@@ -0,0 +1,118 @@
+import { cornerRadius } from "@bug-on/md3-tokens";
+import type { Transition } from "motion";
+import {
+	FAST_EFFECTS_SPRING,
+	FAST_SPATIAL_SPRING,
+} from "../../shared/motion-tokens";
+
+/**
+ * Shape morphing spring animation for layout/width morphing.
+ * MD3: `fast.spatial` — stiffness 800, dampingRatio 0.6 (has bounce).
+ */
+export const BUTTON_SHAPE_MORPH_SPRING: Transition = FAST_SPATIAL_SPRING;
+
+/**
+ * Spring for border-radius changes on press/release and shape toggle.
+ * MD3: `fast.effects` — stiffness 3800, critically damped (dampingRatio 1.0).
+ * No overshoot; border-radius never goes negative.
+ */
+export const BUTTON_RADIUS_SPRING: Transition = FAST_EFFECTS_SPRING;
+
+export const ROUND_SHAPE_RADIUS = 9999;
+
+export const BUTTON_SIZE_TOKENS = {
+	xs: {
+		height: "2rem", // 32dp
+		leadingSpace: "1rem", // 16dp
+		trailingSpace: "1rem", // 16dp
+		iconSize: "1.25rem", // 20dp
+		iconLabelSpace: "0.5rem", // 8dp
+		outlineWidth: 1, // 1dp
+		squareShapeRadius: cornerRadius.medium, // 12dp
+		pressedShapeRadius: cornerRadius.small, // 8dp
+		roundShapeRadius: 16,
+	},
+	sm: {
+		height: "2.5rem", // 40dp
+		leadingSpace: "1rem", // 16dp
+		trailingSpace: "1rem", // 16dp
+		iconSize: "1.25rem", // 20dp
+		iconLabelSpace: "0.5rem", // 8dp
+		outlineWidth: 1, // 1dp
+		squareShapeRadius: cornerRadius.medium, // 12dp
+		pressedShapeRadius: cornerRadius.small, // 8dp
+		roundShapeRadius: 20,
+	},
+	md: {
+		height: "3.5rem", // 56dp
+		leadingSpace: "1.5rem", // 24dp
+		trailingSpace: "1.5rem", // 24dp
+		iconSize: "1.5rem", // 24dp
+		iconLabelSpace: "0.5rem", // 8dp
+		outlineWidth: 1, // 1dp
+		squareShapeRadius: cornerRadius.large, // 16dp
+		pressedShapeRadius: cornerRadius.medium, // 12dp
+		roundShapeRadius: 28,
+	},
+	lg: {
+		height: "6rem", // 96dp
+		leadingSpace: "3rem", // 48dp
+		trailingSpace: "3rem", // 48dp
+		iconSize: "2rem", // 32dp
+		iconLabelSpace: "0.75rem", // 12dp
+		outlineWidth: 2, // 2dp
+		squareShapeRadius: cornerRadius.extraLarge, // 28dp
+		pressedShapeRadius: cornerRadius.large, // 16dp
+		roundShapeRadius: 48,
+	},
+	xl: {
+		height: "8.5rem", // 136dp
+		leadingSpace: "4rem", // 64dp
+		trailingSpace: "4rem", // 64dp
+		iconSize: "2.5rem", // 40dp
+		iconLabelSpace: "1rem", // 16dp
+		outlineWidth: 3, // 3dp
+		squareShapeRadius: cornerRadius.extraLarge, // 28dp
+		pressedShapeRadius: cornerRadius.large, // 16dp
+		roundShapeRadius: 68,
+	},
+} as const;
+
+export const BUTTON_TYPOGRAPHY_TOKENS = {
+	xs: "text-sm font-medium tracking-wide", // labelLarge
+	sm: "text-sm font-medium tracking-wide", // labelLarge
+	md: "text-base font-medium", // titleMedium
+	lg: "text-xl font-normal", // headlineSmall
+	xl: "text-[2rem] font-normal leading-none", // headlineLarge
+} as const;
+
+export const BUTTON_COLOR_TOKENS = {
+	elevated: {
+		default: "bg-m3-surface-container-low text-m3-primary shadow-md",
+		selected: "bg-m3-primary text-m3-on-primary shadow-md",
+		unselected: "bg-m3-surface-container-low text-m3-primary shadow-md",
+	},
+	filled: {
+		default: "bg-m3-primary text-m3-on-primary",
+		selected: "bg-m3-primary text-m3-on-primary",
+		unselected: "bg-m3-surface-container text-m3-on-surface-variant",
+	},
+	tonal: {
+		default: "bg-m3-secondary-container text-m3-on-secondary-container",
+		selected: "bg-m3-secondary text-m3-on-secondary",
+		unselected: "bg-m3-secondary-container text-m3-on-secondary-container",
+	},
+	outlined: {
+		default:
+			"bg-transparent text-m3-on-surface-variant border-m3-outline-variant",
+		selected:
+			"bg-m3-inverse-surface text-m3-inverse-on-surface border-transparent",
+		unselected:
+			"bg-transparent text-m3-on-surface-variant border-m3-outline-variant",
+	},
+	text: {
+		default: "bg-transparent text-m3-primary",
+		selected: "bg-transparent text-m3-primary",
+		unselected: "bg-transparent text-m3-primary",
+	},
+} as const;

package/src/ui/{button.test.tsx → buttons/button/button.test.tsx}

@@ -4,14 +4,11 @@ import { fireEvent, render, screen } from "@testing-library/react";
 import { describe, expect, it, vi } from "vitest";
 import { Button } from "./button";
 
-// ── Inline SVG test icon (no external deps) ───────────────────────────────────
 const TestIcon = () => (
 	<svg data-testid="test-icon" aria-hidden="true" viewBox="0 0 24 24" />
 );
 
 describe("Button Component", () => {
-	// ── Existing tests (preserved) ─────────────────────────────────────────────
-
 	it("renders correctly with default props", () => {
 		render(<Button>Click me</Button>);
 		const button = screen.getByRole("button");
@@ -56,8 +53,6 @@ describe("Button Component", () => {
 		fireEvent.pointerDown(button, { clientX: 10, clientY: 10 });
 	});
 
-	// ── New: Disabled state ────────────────────────────────────────────────────
-
 	describe("disabled state", () => {
 		it("has disabled attribute when disabled prop is passed", () => {
 			render(<Button disabled>Disabled</Button>);
@@ -76,8 +71,6 @@ describe("Button Component", () => {
 		});
 	});
 
-	// ── New: Keyboard navigation ───────────────────────────────────────────────
-
 	describe("keyboard navigation", () => {
 		it("triggers onClick when Enter is pressed", () => {
 			const handleClick = vi.fn();
@@ -105,8 +98,6 @@ describe("Button Component", () => {
 		});
 	});
 
-	// ── New: Icon position ─────────────────────────────────────────────────────
-
 	describe("icon position", () => {
 		it("renders leading icon before label in DOM order", () => {
 			render(
@@ -153,7 +144,6 @@ describe("Button Component", () => {
 				</Button>,
 			);
 			const button = screen.getByRole("button");
-			// Icon wrapper span should be aria-hidden
 			const iconWrapper = button.querySelector(
 				"span[aria-hidden='true']:has([data-testid='test-icon'])",
 			);
@@ -178,8 +168,6 @@ describe("Button Component", () => {
 		});
 	});
 
-	// ── New: RTL layout ────────────────────────────────────────────────────────
-
 	describe("RTL layout", () => {
 		it("renders without crash inside dir=rtl container", () => {
 			const { container } = render(
@@ -215,13 +203,10 @@ describe("Button Component", () => {
 			const labelIndex = spans.findIndex((s) =>
 				s.textContent?.includes("RTL Trailing"),
 			);
-			// DOM order is still trailing (CSS handles visual flip in RTL via flex)
 			expect(iconIndex).toBeGreaterThan(labelIndex);
 		});
 	});
 
-	// ── New: aria-label ────────────────────────────────────────────────────────
-
 	describe("aria-label", () => {
 		it("sets aria-label to children string as fallback", () => {
 			render(<Button>Submit</Button>);
@@ -245,14 +230,10 @@ describe("Button Component", () => {
 					<span>Node child</span>
 				</Button>,
 			);
-			// aria-label should be undefined (not set) for non-string children
-			// unless explicitly provided
 			expect(screen.getByRole("button")).not.toHaveAttribute("aria-label");
 		});
 	});
 
-	// ── New: asChild prop ──────────────────────────────────────────────────────
-
 	describe("asChild prop", () => {
 		it("renders children as the root element", () => {
 			render(
@@ -281,8 +262,6 @@ describe("Button Component", () => {
 		});
 	});
 
-	// ── New: loading prop ──────────────────────────────────────────────────────
-
 	describe("loading prop", () => {
 		it("disables interaction and sets aria-busy", () => {
 			const handleClick = vi.fn();