# @bug-on/m3-expressive

> MD3 Expressive Design System for React + Tailwind v4 + Framer Motion. Version: 1.3.1

> [!WARNING]
> Bug On MD3 Expressive only supports **Tailwind CSS v4** (peer dependency `tailwindcss: ">=4.0.0"`). **Tailwind CSS v3 is no longer supported**.

---

## Ecosystem Package Map

- **`@bug-on/m3-expressive`** (`packages/react`): Core UI library with 30+ components, dynamic provider (`MD3ThemeProvider`), hooks, and motion primitives.
- **`@bug-on/m3-tokens`** (`packages/tokens`): Base design tokens for color palettes, shape scales, typography, and spring constants.
- **`@bug-on/m3-tailwind`** (`packages/tailwind`): CSS-first Tailwind v4 theme plugin, elevations, Shiki code styling, and utility classes (`icon-fill-*`, `transition-m3-*`).
- **`@bug-on/m3-fonts`** (`packages/fonts`): Optional self-hosted font assets for offline or air-gapped environments (`Material Symbols` & Typography).

---

## Quick Installation & Setup

```bash
pnpm add @bug-on/m3-expressive motion
```

```css
/* globals.css — Zero Config Tailwind v4 setup */
@import "tailwindcss";
@import "@bug-on/m3-expressive/index.css";         /* tokens + @theme + resets (REQUIRED) */
@import "@bug-on/m3-tailwind";                     /* optional: MD3 utilities & elevation */
@import "@bug-on/m3-expressive/typography.css";    /* optional: typography preset classes */
@import "@bug-on/m3-expressive/material-symbols-cdn.css"; /* optional: Material Symbols (CDN) */
```

For offline or self-hosted fonts:
```bash
pnpm add @bug-on/m3-fonts
```
```css
@import "@bug-on/m3-fonts/typography.css";
@import "@bug-on/m3-fonts/material-symbols.css";
```

```tsx
// App layout wrapper
import { MD3ThemeProvider } from "@bug-on/m3-expressive/core";

function Root({ children }: { children: React.ReactNode }) {
  return (
    <MD3ThemeProvider
      defaultMode="system"
      sourceColor="#6750A4"
      variant="expressive"
      contrastLevel={0}
      enableSnackbar
    >
      {children}
    </MD3ThemeProvider>
  );
}
```

---

## Core Principles for AI Code Generators

- **Dynamic Color (MD3 Spec 2025 + MCU v0.4.0)**: Palette generation uses `specVersion: '2025'` with `Variant.EXPRESSIVE` as default. Supports scheme `variant` (`"expressive"`, `"tonal_spot"`, `"vibrant"`, `"fidelity"`, `"content"`, `"monochrome"`, `"neutral"`) and `contrastLevel` (`0`, `0.5`, `1`).
- **Expressive Color Tokens**: Fixed color roles (`bg-m3-primary-fixed`, `bg-m3-secondary-fixed`, `bg-m3-tertiary-fixed` + dim/on variants) remain light/dark invariant. Dim tones (`bg-m3-primary-dim`, etc.) provide subdued accent surfaces.
- **Button Color Styles & Layouts**: Supports 8 color styles: `"filled"`, `"tonal"`, `"outlined"`, `"text"`, `"elevated"`, `"tertiary"`, `"primary-fixed"`, `"tertiary-fixed"`. `ButtonDistribute` (`mode="dynamic" | "fixed" | "mixed"`) handles responsive button row weighting.
- **Carousel (Morphing & Multi-browse)**: `Carousel` component implements Material Design 3 Expressive motion keyline math (`useCarouselKeylines`) for dynamic item shrinking/expansion during scrolling.
- **Chips**: 4 standard variants (`variant="assist" | "filter" | "input" | "suggestion"`) supporting leading avatar/icons, animated selection checkmarks, and trailing remove buttons, grouped via `ChipGroup`.
- **Shape Morphing & Custom Shapes**: Elements dynamically morph corner radii during interactions. `NavigationBar` and `NavigationRail` support custom item shapes (`"pill" | "circle" | "rounded-rectangle"`).
- **Physics Springs**: Powered by `motion/react` (Framer Motion ≥12). Uses spatial (`FAST_SPATIAL_SPRING`, `DEFAULT_SPATIAL_SPRING`) and effects (`FAST_EFFECTS_SPRING`) springs.
- **Polymorphism (`asChild`)**: Supported across buttons, cards, drawers, and dialog triggers for custom routing links.
- **Hoisted State**: `DatePicker` and `TimePicker` are stateless and require `useDatePickerState()` / `useTimePickerState()`.
- **TextField & Select onChange**: Parameter signature receives `(value: string)` — NOT a raw React SyntheticEvent. `Select` returns `(value: string, option?: SelectOption)`.
- **Select & Exposed Dropdowns**: `Select` supports standard dropdown and `searchable` autocomplete mode with real-time option filtering and `matchTriggerWidth` (default `true`).
- **Menu Family & Morphing**: `Menu`, `ContextMenu`, and `VerticalMenu` feature container shape morphing (`12dp` standalone corners). `MenuContent` `matchTriggerWidth` matches popover width to trigger.
- **ProgressIndicator & Wavy Motion**: Supports `"linear"` and `"circular"` variants with dynamic `"wavy"` shapes (`shape="wavy"`, `trackShape`, `amplitude`, `wavelength`). `aria-label` is strictly **required**. Indeterminate mode is triggered by omitting the `value` prop (do not use `max` prop). Supports co-elastic animations (`determinateAnimation`, `indeterminateAnimation`) and track stop dots (`showStopIndicator`).

---

## Package Subpath Exports

- `@bug-on/m3-expressive` — complete package exports
- `@bug-on/m3-expressive/index.css` — **REQUIRED**: bundled tokens + Tailwind `@theme` + resets
- `@bug-on/m3-expressive/core` — base providers (`MD3ThemeProvider`), hooks (`useTheme`, `useThemeMode`, `useSnackbar`), `Icon`, `Ripple`
- `@bug-on/m3-expressive/buttons` — Button, IconButton, ButtonDistribute, FAB, ExtendedFAB, FABMenu, SplitButton, ButtonGroup
- `@bug-on/m3-expressive/forms` — TextField, Chip, Checkbox, TriStateCheckbox, RadioButton, RadioGroup, Switch, Slider, RangeSlider, Select, Search
- `@bug-on/m3-expressive/feedback` — Snackbar, SnackbarProvider, useSnackbar, ProgressIndicator (linear, circular, wavy), LoadingIndicator, Badge, BadgedBox, PlainTooltip, RichTooltip
- `@bug-on/m3-expressive/navigation` — NavigationBar, NavigationRail, NavigationDrawer, Tabs, Tab, 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/layout` — Card, Carousel, Divider, List, ListItem, ListDivider, ScrollArea, CodeBlock, TableOfContents, Text, Typography
- `@bug-on/m3-expressive/pickers` — DatePicker, DatePickerDialog, DatePickerInput, DateRangePicker, TimePicker, TimePickerDialog, TimeInput, state hooks
- `@bug-on/m3-expressive/shapes` — ShapeMedia, ShapeSvg, ShapeIcon, useShapeMorph

---

## Documentation Links

- [Full AI Context Document](./llms-full.txt) - **Recommended for AI Agents** (Detailed APIs, gotchas, gotcha matrix)
- [Component Reference Site](https://bug-on-md3.vercel.app/docs/components)