# @bug-on/m3-expressive — Full AI Documentation (v1.1.1)

This file contains the complete context for the `@bug-on/m3-expressive` library (version 1.1.1), including core principles, multi-package architecture, styling guides, component references, and AI gotchas.

---

# PART 1: Core Principles & Architecture

## 1. Package Architecture & Dependencies

The Bug On MD3 Expressive suite consists of 4 specialized packages designed to work together:

```
  ┌────────────────────────────────────────────────────────┐
  │                    @bug-on/m3-tokens                   │  (Level 0: Base Tokens)
  └───────────────────────────┬────────────────────────────┘
                              │
         ┌────────────────────┴───────────────────┐
         ▼                                        ▼
┌──────────────────────────────────┐   ┌──────────────────────────────────┐
│        @bug-on/m3-tailwind       │   │        @bug-on/m3-fonts          │  (Level 1: Utilities & Assets)
│  (Tailwind CSS v4 theme plugin)  │   │   (Optional self-hosted fonts)   │
└────────────────┬─────────────────┘   └──────────────────────────────────┘
                 │
                 ▼
┌──────────────────────────────────────────────────────────┐
│                   @bug-on/m3-expressive                  │  (Level 2: Core React Component Library)
│   (Bundles tokens + Tailwind theme into index.css)       │
└──────────────────────────────────────────────────────────┘
```

- **`@bug-on/m3-expressive`** (`packages/react`): Main library containing all React components, `MD3ThemeProvider`, hooks, and motion primitives.
- **`@bug-on/m3-tokens`** (`packages/tokens`): Raw HCT color tokens, 10-level shape radii scales, typography tokens, and Framer Motion physics constants.
- **`@bug-on/m3-tailwind`** (`packages/tailwind`): Tailwind CSS v4 CSS-first theme configuration and utility classes (`elevation-*`, `icon-fill-*`, `transition-m3-*`).
- **`@bug-on/m3-fonts`** (`packages/fonts`): Optional self-hosted font assets (`Material Symbols` and `Google Sans Flex`).

---

## 2. The Mental Model: MD3 Expressive

Unlike standard MD3, **Expressive** layouts emphasize:
- **Shape Morphing**: Components dynamically morph corner radii (e.g., squircle to circle, pill to rounded square, or squished pill) during interactions.
- **Physics Springs**: We use physics-based spring transitions (`motion/react` v12+) instead of duration-based ease curves.
    - **Spatial Springs**: For position, size, shape (border-radius), scale (e.g., `FAST_SPATIAL_SPRING`, `DEFAULT_SPATIAL_SPRING`).
    - **Effects Springs**: For color, opacity (no bounce) (e.g., `FAST_EFFECTS_SPRING`).
    - **Expressive Spring**: `SPRING_TRANSITION_EXPRESSIVE` has strong bounce (`bounce: 0.45`), used for active indicator morphs and item selection.
- **Dynamic Color Engine (MD3 Spec 2025 + MCU v0.4.0)**: Uses `@material/material-color-utilities ^0.4.0` with `specVersion: '2025'` and `Variant.EXPRESSIVE` by default. Derived from CSS variables like `--md-sys-color-primary`, `--md-sys-color-surface-container-low`, `--md-sys-color-primary-fixed`, etc.

---

## 3. Theme Management

Always wrap your application in `MD3ThemeProvider`. It supports controlling scheme `variant` (`"expressive"`, `"tonal_spot"`, `"vibrant"`, `"fidelity"`, `"content"`, `"monochrome"`, `"neutral"`) and `contrastLevel` (`0` standard, `0.5` medium, `1` maximum contrast/WCAG AAA).

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

function App() {
  return (
    <MD3ThemeProvider
      mode="system"
      sourceColor="#6750A4"
      variant="expressive"
      contrastLevel={0}
      enableSnackbar
    >
      <Main />
    </MD3ThemeProvider>
  );
}
```

---

## 4. Polymorphism (`asChild`)

Most interactive components use the `asChild` pattern from Radix UI. This allows passing a custom element (like Next.js `Link`) and having it receive the component's styles and logic:

```tsx
<Button asChild>
  <Link href="/dashboard">Go to Dashboard</Link>
</Button>
```

> **AI Warning**: When using `asChild`, ensure the child component is a single valid React element that accepts a `ref`.

---

## 5. Tailwind v4 Zero-Config Integration

The library uses a CSS-first architecture. All MD3 design tokens, resets, and utility classes are bundled in the stylesheet:

```css
@import "tailwindcss";
@import "@bug-on/m3-expressive/index.css";
```

By importing `@bug-on/m3-expressive/index.css`, Tailwind v4 automatically processes the `@theme` block so utility classes work out of the box:
- `bg-m3-primary`, `text-m3-on-primary`
- `bg-m3-surface-container-high`
- `border-m3-outline`
- `rounded-m3-xl`

> **Note**: Tailwind v3 is NOT supported.

---

## 6. Icons & Fonts

Icons use **Material Symbols** (Variable Font).

```tsx
<Icon name="search" weight={500} size={24} />
```

- Standard CDN imports: `@import "@bug-on/m3-expressive/typography.css";` and `@import "@bug-on/m3-expressive/material-symbols-cdn.css";`
- Offline / Self-hosted imports: `pnpm add @bug-on/m3-fonts`, then `@import "@bug-on/m3-fonts/typography.css";` and `@import "@bug-on/m3-fonts/material-symbols.css";`

---

## 7. Layout & State Composition Patterns

### 7.1 Compound Components & Responsive Layout Groups
Complex components use a structured compound pattern:
- **Dialog & Drawer**: `Dialog`, `DialogTrigger`, `DialogContent`, `DialogHeader`, `DialogTitle`, `DialogBody`, `DialogFooter`, `DialogClose`.
- **Tabs**: `Tabs`, `TabsList`, `Tab`, `TabsContent`.
- **SplitButton**: `SplitButtonLayout`, `SplitButtonLeading`, `SplitButtonTrailing` (or `SplitButtonTrailingUncheckable`).
- **ButtonDistribute**: `ButtonDistribute` (`mode="dynamic" | "fixed" | "mixed"`), spring-animated button layout container for responsive action bars.
- **Menu Family**: `Menu`, `MenuTrigger`, `MenuContent`, `MenuGroup`, `MenuItem`, `MenuDivider`, `SubMenu`. Features shape morphing (`12dp` standalone corners), `variant="expressive" | "baseline"`, `colorVariant="standard" | "vibrant"`, and `matchTriggerWidth`. Includes `ContextMenu` and static `VerticalMenu`.
- **Select**: `Select` (Exposed Dropdown Menu & Autocomplete). Wraps `TextField` + `Menu`. Supports `searchable` (real-time filtering), controlled/uncontrolled state, and `onChange={(value, option) => void}`.

### 7.2 Navigation Customization
- **NavigationBar & NavigationRail**: Support customizable `itemShape` (`"pill" | "circle" | "rounded-rectangle"`), `labelVisibility` (`"labeled" | "auto" | "unlabeled"`), and `fabAlignment` (`"left" | "center"`).

### 7.3 Hoisted State (Date & Time Pickers)
`DatePicker` and `TimePicker` are **stateless**. The caller owns state via hooks (`useDatePickerState`, `useTimePickerState`) and passes it as a prop.

### 7.4 Progress Indicator & Wavy Shapes
`ProgressIndicator` renders loading status as flat/wavy linear bars or circular indicators.
- **States**: Determinate (when `value: number` is provided, 0-100) and Indeterminate (when `value` is omitted/undefined).
- **Accessibility**: `aria-label` is strictly **required** (do not miss it).
- **API Cleanliness**: Do NOT pass `max` prop. Progress is mapped strictly 0-100.
- **Linear configuration**:
  - `shape="flat" | "wavy"` & `trackShape="flat" | "wavy"`
  - `amplitude`, `wavelength`, `indeterminateWavelength`, `waveSpeed`, `crawlerSpeed`, `gapSize`
  - `determinateAnimation="md3" | "continuous"` (md3 flattens wave at edges; continuous keeps wave height)
  - `indeterminateAnimation="md3" | "continuous"` (md3 uses physics-stretching sliders; continuous is a rolling path)
  - `showStopIndicator=boolean | "auto"` (fades in a stopping point dot at 100% if "auto")
- **Circular configuration**:
  - `size` (diameter in px, default 48)
  - `shape="flat" | "wavy"`, `amplitude`, `wavelength`, `crawlerSpeed`, `gapSize`
  - `showTrack=boolean | "auto"` (defaults to hidden for flat, visible for wavy circular)
  - `minProgress` & `maxProgress` (bounds the sliding arc size between 0 and 1)
  - `amplitudeRange=[min, max]` (modulates wave amplitude relative to current arc length)

```tsx
const state = useDatePickerState({ initialSelectedDateMs: Date.now() });
<DatePicker state={state} />
```

---

# PART 2: Styling & Design Tokens

## 1. Color Roles & State Overlays

Use the `m3-` prefix followed by the MD3 color role:
- **Primary**: `bg-m3-primary`, `text-m3-on-primary`, `border-m3-primary-container`
- **Secondary**: `bg-m3-secondary`, `text-m3-on-secondary`, `bg-m3-secondary-container`
- **Tertiary**: `bg-m3-tertiary`, `text-m3-on-tertiary`, `bg-m3-tertiary-container`
- **Surface**: `bg-m3-surface`, `bg-m3-surface-container-low`, `bg-m3-surface-container-high`, `bg-m3-surface-variant`, `bg-m3-surface-dim`, `bg-m3-surface-bright`
- **Background**: `bg-m3-background`, `text-m3-on-background`
- **Fixed Roles (Brand-stable across light/dark)**:
  - `bg-m3-primary-fixed`, `bg-m3-primary-fixed-dim`, `text-m3-on-primary-fixed`, `text-m3-on-primary-fixed-variant`
  - `bg-m3-secondary-fixed`, `bg-m3-secondary-fixed-dim`, `text-m3-on-secondary-fixed`, `text-m3-on-secondary-fixed-variant`
  - `bg-m3-tertiary-fixed`, `bg-m3-tertiary-fixed-dim`, `text-m3-on-tertiary-fixed`, `text-m3-on-tertiary-fixed-variant`
- **Expressive Dim Tones (Spec 2025)**: `bg-m3-primary-dim`, `bg-m3-secondary-dim`, `bg-m3-tertiary-dim`
- **Error**: `text-m3-error`, `bg-m3-error-container`, `text-m3-on-error-container`

State overlays in Tailwind v4:
- `hover:bg-m3-primary/8` (8% opacity overlay)
- `active:bg-m3-primary/12` (12% opacity overlay)
- `disabled:opacity-[0.38]` (Standard MD3 disabled opacity)

---

## 2. Shapes (10-level Scale)

- `rounded-m3-none`: 0px
- `rounded-m3-extra-small`: 4px
- `rounded-m3-small`: 8px
- `rounded-m3-medium`: 12px
- `rounded-m3-large`: 16px
- `rounded-m3-large-increased`: 20px
- `rounded-m3-extra-large`: 28px
- `rounded-m3-extra-large-increased`: 32px
- `rounded-m3-extra-extra-large`: 48px
- `rounded-m3-full`: Pill (9999px)

---

## 3. Motion & Springs Constants

```tsx
import { 
  FAST_SPATIAL_SPRING, 
  DEFAULT_SPATIAL_SPRING, 
  FAST_EFFECTS_SPRING,
  SPRING_TRANSITION_EXPRESSIVE
} from "@bug-on/m3-expressive";

<m.div animate={{ x: 100 }} transition={FAST_SPATIAL_SPRING} />
```

- **FAST_SPATIAL**: Snappy, high stiffness. Use for hover/tap feedback.
- **DEFAULT_SPATIAL**: Balanced damping. Use for page transitions and layout morphs.
- **SPRING_TRANSITION_EXPRESSIVE**: High bounce spring (`bounce: 0.45`). Used for active indicator morphs.

---

# PART 3: Subpath Exports & Gotchas Reference

## Subpath Exports Map

- `@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, hooks, motion tokens
- `@bug-on/m3-expressive/buttons` — Button, IconButton, ButtonDistribute, FAB, ExtendedFAB, FABMenu, SplitButton, ButtonGroup
- `@bug-on/m3-expressive/forms` — Select, TextField, Checkbox, RadioButton, Switch, Slider, Search
- `@bug-on/m3-expressive/feedback` — Dialog, Menu, ContextMenu, VerticalMenu, Tooltip, SnackbarProvider, ProgressIndicator
- `@bug-on/m3-expressive/navigation` — NavigationBar, NavigationRail, Drawer, Tabs
- `@bug-on/m3-expressive/overlays` — BottomSheet, SideSheet
- `@bug-on/m3-expressive/pickers` — DatePicker, DateRangePicker, TimePicker, state hooks
- `@bug-on/m3-expressive/shapes` — ShapeMedia, ShapeSvg

---

## Common AI Mistakes & Gotchas

| Mistake | Correct |
| :--- | :--- |
| `<Icon name="ArrowForward" />` | `<Icon name="arrow_forward" />` (use snake_case) |
| `<Button variant="toggle">` (without `selected`) | Must pass both `variant="toggle"` and `selected={boolean}` |
| `<IconButton>` (without `aria-label`) | `aria-label` is required on icon buttons for accessibility |
| Manually writing flex math for responsive action bars | Use `<ButtonDistribute mode="dynamic">` for spring-animated responsive width distribution |
| `onChange={e => setValue(e.target.value)}` on TextField | `onChange={(value) => setValue(value)}` (first argument is a string) |
| `Select` `onChange` assuming standard React `SyntheticEvent` | Signature is `onChange={(value: string, option?: SelectOption) => void}` |
| `<TabsList>` (without `variant`) | `variant` prop is required on `TabsList` (`"primary"` or `"secondary"`) |
| Using `useSnackbar()` outside `MD3ThemeProvider` or `SnackbarProvider` | Ensure provider wraps the tree with `enableSnackbar` |
| `<DatePicker />` or `<TimePicker />` without `state` prop | Always create state via `useDatePickerState()` or `useTimePickerState()` |
| `<BottomSheet isOpen={...}>` | Correct prop names are `open` and `onOpenChange` |
| `<MenuContent>` with nested `<SubMenu>` clipping overflow | Pass `hasOverflow={true}` to `MenuContent` or `ContextMenuContent` so submenus escape container bounds |
| `<ProgressIndicator max={100} />` | ProgressIndicator does not support `max` prop. Progress is mapped strictly from 0 to 100 on the `value` prop |
| `<ProgressIndicator>` without `aria-label` | `aria-label` is required on all progress indicators for accessibility |
| `<ProgressIndicator value={0} />` for indeterminate mode | Omit `value` prop entirely (or pass `undefined`) to trigger indeterminate loading. Setting `value={0}` indicates 0% determinate progress |