@bug-on/m3-expressive 1.3.1 → 1.3.3

package/llms-full.txt

@@ -0,0 +1,255 @@
+# @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 |

package/llms.txt

@@ -0,0 +1,102 @@
+# @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)
+

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bug-on/m3-expressive",
-  "version": "1.3.1",
+  "version": "1.3.3",
   "description": "Material Design 3 Expressive React components",
   "author": "Bug On",
   "license": "MIT",
@@ -27,7 +27,9 @@
   "files": [
     "dist",
     "README.md",
-    "CHANGELOG.md"
+    "CHANGELOG.md",
+    "llms.txt",
+    "llms-full.txt"
   ],
   "sideEffects": [
     "*.css"
@@ -153,7 +155,9 @@
         "types": "./dist/shapes.d.ts",
         "default": "./dist/shapes.js"
       }
-    }
+    },
+    "./llms.txt": "./llms.txt",
+    "./llms-full.txt": "./llms-full.txt"
   },
   "peerDependencies": {
     "motion": ">=12.0.0",
@@ -179,8 +183,8 @@
     "class-variance-authority": "^0.7.1",
     "clsx": "^2.1.1",
     "tailwind-merge": "^3.3.1",
-    "@bug-on/m3-tokens": "1.2.1",
-    "@bug-on/m3-tailwind": "1.2.1"
+    "@bug-on/m3-tokens": "1.2.2",
+    "@bug-on/m3-tailwind": "1.2.2"
   },
   "devDependencies": {
     "@testing-library/jest-dom": "^6.9.1",
@@ -199,6 +203,7 @@
     "vitest": "^4.1.6"
   },
   "scripts": {
+    "prebuild": "node -e \"const fs=require('fs'); if(fs.existsSync('../../llms.txt')) { fs.copyFileSync('../../llms.txt', 'llms.txt'); fs.copyFileSync('../../llms-full.txt', 'llms-full.txt'); }\"",
     "build": "tsup",
     "dev": "tsup --watch",
     "test": "vitest run",