@bug-on/m3-expressive

A high-performance, accessible React component library built strictly following the Material Design 3 Expressive design system specifications. Features fluid spring physics, flexible shape morphing, dynamic Material You color generation (2025 spec), SSR support, and native compatibility with Next.js 16 (App Router / Turbopack), React 19, and Tailwind CSS v4.

📖 Documentation & Interactive Demos

For live interactive component playgrounds, code examples, and API references, visit:
👉 Official Documentation & Live Demos
👉 GitHub Repository

📦 Installation

pnpm add @bug-on/m3-expressive motion
# or
npm install @bug-on/m3-expressive motion

Peer Dependencies

| Package | Version Requirement | Description | | :--- | :--- | :--- | | react | ^19.0.0 | React core framework | | react-dom | ^19.0.0 | React DOM renderer | | motion | >=12.0.0 (optional) | Spring physics animation engine (FABs, Carousels, Tabs, Sheets) | | tailwindcss | >=4.0.0 | Tailwind CSS v4 CSS-first framework |

🛠️ Configuration & Setup (Tailwind CSS v4)

[!WARNING] This library requires Tailwind CSS v4 (CSS-first architecture via @import "tailwindcss"). Tailwind CSS v3 is not supported.

Import the required stylesheets into your application's root CSS entry point (e.g., app/globals.css or src/index.css):

/* 1. Core Tailwind CSS v4 */
@import "tailwindcss";

/* 2. MD3 Expressive Tokens & Theme Resets (Required) */
@import "@bug-on/m3-expressive/index.css";

/* 3. (Optional) Extended MD3 Tailwind Utilities (Elevations, Transitions, Shiki) */
@import "@bug-on/m3-tailwind";

/* 4. (Optional) Typography Preset Classes */
@import "@bug-on/m3-expressive/typography.css";

Safe Areas

For full-bleed mobile layouts, import @bug-on/m3-tailwind, add viewport-fit=cover to the viewport meta tag, and add m3-safe-areas to html or body. Use pt-safe-*, pb-safe-*, px-safe-*, top-safe-*, bottom-safe-*, start-safe-*, and end-safe-* to combine the browser inset with Tailwind spacing. Use the document root rather than an inner application wrapper when using portals such as bottom sheets or dialogs.

<html lang="en" className="m3-safe-areas">
  <body>{children}</body>
</html>

BottomDockedToolbar, BottomSheet, and BottomSheetModal already consume the shared inset values. Do not add a second safe-area padding utility to the same component edge. See the safe-area guide for the full utility reference and troubleshooting.

Icon Font Setup (Material Symbols)

The <Icon /> component renders Material Symbols (defaulting to Material Symbols Rounded) variable font glyphs:

Option A: Automatic Google Fonts CDN (Recommended for Web)

No React, Vite, or Next.js setup is required. Render an Icon anywhere in the component tree and the library hoists only that variant's stylesheet with React 19. The icon occupies its final dimensions while loading and never reveals its ligature name.

import { Icon } from "@bug-on/m3-expressive/core";

<Icon name="search" />
<Icon name="favorite" variant="outlined" />

Option B: Offline / Self-Hosted Assets

For air-gapped networks, enterprise privacy, or offline PWAs, install @bug-on/m3-fonts:

pnpm add @bug-on/m3-fonts

@import "@bug-on/m3-fonts/material-symbols.css";
@import "@bug-on/m3-fonts/typography.css";

Wrap the application once to prevent the automatic CDN request:

import { MaterialSymbolsProvider } from "@bug-on/m3-expressive/core";

<MaterialSymbolsProvider source="local">{children}</MaterialSymbolsProvider>

To reduce local font bytes, generate a subset with m3-symbols before dev and build. Its manifest must list every runtime-provided icon under include; the scanner rejects undeclared dynamic names with the source file and location. Install the pinned FontTools/Brotli development tooling from @bug-on/m3-fonts/tools/requirements.txt. allowFallback: true is intended only for local development when that tooling is unavailable.

🧩 Subpath Exports Guide

Optimize your bundle size and tree-shaking by importing directly from modular subpaths:

| Subpath Import | Module Contents | | :--- | :--- | | @bug-on/m3-expressive/core | MD3ThemeProvider, MaterialSymbolsProvider, createMd3ExpressiveTheme, generateM3Theme, applyTheme, resolveMode, useTheme, useThemeMode, Icon, Ripple, MaterialSymbolsPreconnect (legacy), useMediaQuery, useDOMRipple | | @bug-on/m3-expressive/buttons | Button, IconButton, FAB, ExtendedFAB, FABMenu, SplitButton, ButtonGroup, ButtonDistribute | | @bug-on/m3-expressive/forms | TextField, Checkbox, TriStateCheckbox, RadioButton, RadioGroup, Switch, Slider, RangeSlider, Select, Chip | | @bug-on/m3-expressive/navigation | NavigationBar, NavigationRail, NavigationDrawer, Tabs, Tab, TabsList, TabsContent, SmallAppBar, MediumFlexibleAppBar, LargeFlexibleAppBar, BottomAppBar, DockedToolbar, HorizontalFloatingToolbar, VerticalFloatingToolbar, Menu, ContextMenu, VerticalMenu, Search | | @bug-on/m3-expressive/overlays | Dialog, DialogFullScreenContent, Drawer, BottomSheet, BottomSheetModal, SideSheet, SideSheetModal | | @bug-on/m3-expressive/feedback | Snackbar, SnackbarProvider, useSnackbar, ProgressIndicator (linear, circular, wavy), LoadingIndicator, Badge, BadgedBox, PlainTooltip, RichTooltip | | @bug-on/m3-expressive/layout | Card, Carousel (Morphing layout, Multi-browse, Uncontained), Divider, List, ListItem, ListDivider, ScrollArea, CodeBlock, TableOfContents, Text, Typography, FadingBlurMask | | @bug-on/m3-expressive/pickers | DatePicker, DatePickerDialog, DatePickerInput, DateRangePicker, TimePicker, TimePickerDialog, TimeInput, useDatePickerState, useDateRangePickerState, useTimePickerState | | @bug-on/m3-expressive/shapes | ShapeMedia, ShapeSvg, ShapeIcon, useShapeMorph, MD3 shape morphing engine |

🚀 Quick Code Example

import { MD3ThemeProvider } from "@bug-on/m3-expressive/core";
import { Button } from "@bug-on/m3-expressive/buttons";
import { TextField, Chip } from "@bug-on/m3-expressive/forms";
import { Icon } from "@bug-on/m3-expressive";

export default function App() {
  return (
    <MD3ThemeProvider sourceColor="#00639b" defaultMode="system">
      <div className="p-6 bg-m3-surface text-m3-on-surface rounded-m3-xl shadow-m3-elevation-2 max-w-sm space-y-4">
        <h2 className="text-m3-title-large font-bold">Welcome Back</h2>
        
        <TextField
          label="Email Address"
          variant="outlined"
          leadingIcon={<Icon name="mail" />}
        />
        
        <div className="flex gap-2">
          <Chip variant="filter" selected label="Remember me" />
        </div>
        
        <Button
          colorStyle="filled"
          size="md"
          icon={<Icon name="arrow_forward" />}
        >
          Sign In
        </Button>
      </div>
    </MD3ThemeProvider>
  );
}

🎨 Component Inventory

🔘 Buttons & Actions

• Button: Filled, Elevated, Tonal, Outlined, Text, Tertiary, Primary-Fixed, and Tertiary-Fixed color styles.
• IconButton: Standard, Filled, Tonal, Outlined, with toggle state support.
• FAB / ExtendedFAB: Small, Medium, Large, Extended with icon motion and responsive collapsing.
• FABMenu: Speed-dial expandable Floating Action Button menu with spring transition physics.
• SplitButton: Combined primary button action with trailing menu dropdown.
• ButtonGroup / ButtonDistribute: Segmented button groups with shared morphing shapes and dynamic width distribution.

🏷️ Chips

• Chip: Assist, Filter, Input, and Suggestion chip variants.
• ChipGroup: Horizontally scrollable and wrapping chip containers.
• Features: Leading avatars/icons, animated selection checkmarks, and trailing remove/action icons.

📝 Forms & Inputs

• TextField: Outlined and Filled text inputs with floating labels, character count, error helper text, and icon slots.
• Checkbox / TriStateCheckbox: Standard and indeterminate checkboxes with animated checkmarks.
• RadioButton / RadioGroup: Single-selection groups with smooth scale transitions.
• Switch: Expressive toggle switch with optional custom inline icons.
• Slider / RangeSlider: Continuous and discrete sliders with value tooltips and step indicators. Slider also has an opt-in wave media scrubber rail and a thumbHeight px override for the horizontal vertical pill; the 48px touch target and keyboard/touch seek semantics remain intact.
• Select: Exposed dropdown menu and autocomplete search select (searchable, matchTriggerWidth).
• Search / SearchBar / SearchView: Search input bars and full-screen docked/expanded search surfaces.

📅 Date & Time Pickers

• DatePicker / DatePickerDialog / DatePickerInput: Modal and inline calendar date pickers with hoisted useDatePickerState().
• DateRangePicker: Range selection date picker with useDateRangePickerState().
• TimePicker / TimePickerDialog / TimeInput: Dial clock face and numeric time inputs with useTimePickerState().

🧭 Navigation & Toolbars

• NavigationBar: Bottom navigation bar with animated pill active indicator and label visibility controls.
• NavigationRail: Vertical navigation bar for tablets and desktop viewports.
• NavigationDrawer / Drawer: Standard docked and modal side navigation drawers.
• Tabs / Tab / TabsList / TabsContent: Primary and Secondary tabs with sliding underline indicator.
• SmallAppBar / MediumFlexibleAppBar / LargeFlexibleAppBar / BottomAppBar: Collapsible header app bars with scroll behavior binding (useAppBarScroll).
• DockedToolbar / HorizontalFloatingToolbar / VerticalFloatingToolbar: Floating and docked adaptive toolbars with optional embedded FAB.

📜 Menus

• Menu: Popup menus with cascading submenu support and trigger width matching.
• ContextMenu: Right-click contextual popover menu.
• VerticalMenu: Always-visible static vertical navigation menu with container shape morphing.

🖼️ Overlays & Sheets

• Dialog / DialogFullScreenContent: Expressive modal dialogs, alert confirmations, and full-screen dialogs.
• BottomSheet / BottomSheetModal: Draggable bottom sheets with snap points and drag gestures (useBottomSheet).
• SideSheet / SideSheetModal: Contextual docked and modal side panels.

⚡ Feedback & Status

• Snackbar / SnackbarProvider / useSnackbar: Imperative queue toast notification system with action triggers.
• ProgressIndicator: Linear and circular progress indicators (determinate, indeterminate, wavy shape shape="wavy", and track stop dots).
• LoadingIndicator: Expressive indeterminate loading animations.
• Badge / BadgedBox: Small status dots and numerical count notification badges.
• PlainTooltip / RichTooltip: Informative plain tooltips and rich interactive popover tooltips with carets and actions.

📐 Layout, Surfaces & Carousel

• Carousel: MD3 Expressive morphing carousel supporting Multi-browse, Uncontained, and Hero layouts (useCarouselKeylines, useCarouselA11y).
• Card: Elevated, Filled, and Outlined surface cards with header, media, content, and footer slots.
• Divider: Full-bleed, inset, and decorative wavy dividers (buildWavePath).
• List / ListItem / ListDivider: Single and multi-line list rows with avatar, checkbox, and action controls.
• ScrollArea: Lightweight customized scrollable container.
• CodeBlock: Syntax-highlighted code container with copy button.
• TableOfContents: Interactive documentation navigation anchor list.
• Text / Typography: Expressive typography renderers with standard MD3 type scales.

🔮 Shapes & Motion Engine

• ShapeMedia / ShapeSvg / ShapeIcon: Morphing media frames supporting MD3 expressive geometry (Full, Extra Large, Large, Medium, Small, Star, Clover, Arch, etc.).
• useShapeMorph: Dynamic spring-based corner shape interpolation hook.

🤖 AI Agent Integration

This package ships with machine-readable LLM documentation (llms.txt and llms-full.txt) adhering to the llmstxt.org standard. When installed in your project, AI coding assistants (Cursor, GitHub Copilot, Claude Code, ChatGPT Codex) can read the bundled specification directly to understand APIs and avoid hallucinating props.

📚 Locating LLM Documentation

• Local (in your project after install):
  • node_modules/@bug-on/m3-expressive/llms-full.txt (Full API & Gotchas reference - Recommended)
  • node_modules/@bug-on/m3-expressive/llms.txt (Quick overview)
• Remote CDN:
  • https://unpkg.com/@bug-on/m3-expressive/llms-full.txt
  • https://cdn.jsdelivr.net/npm/@bug-on/m3-expressive/llms-full.txt
  • https://raw.githubusercontent.com/nguyentruongton/bug-on-m3-expressive/main/llms-full.txt

💡 Suggested Prompt for your AI Assistant

Add this instruction to your project's CLAUDE.md, .cursorrules, or system prompt:

Before generating or modifying UI components using @bug-on/m3-expressive, read:
- Local: node_modules/@bug-on/m3-expressive/llms-full.txt
- CDN: https://unpkg.com/@bug-on/m3-expressive/llms-full.txt

⚖️ License

MIT