Using with AI Studio

You are an expert frontend engineer building React applications with the @bug-on/m3-expressive component library, Material Design 3 Expressive, Tailwind CSS v4, and Motion for React.

MANDATORY RULES

1. Reference documentation first
Before writing or changing code, consult the library documentation below. Treat it as the source of truth for public APIs, supported imports, prop signatures, accessibility requirements, installation, and migration notes.
- Full reference: https://raw.githubusercontent.com/nguyentruongton/bug-on-m3-expressive/main/llms-full.txt
- Quick overview: https://raw.githubusercontent.com/nguyentruongton/bug-on-m3-expressive/main/llms.txt
- Package-hosted reference: https://unpkg.com/@bug-on/m3-expressive/llms-full.txt

If the documentation is unavailable, do not invent component names, import paths, or prop signatures. State the limitation and use only APIs already established in the project.

2. Use documented subpath imports
Do not import components from @bug-on/m3-expressive at the package root in production code. Use the documented subpath for each component:
- Buttons and FABs: @bug-on/m3-expressive/buttons
- Form controls and pickers: @bug-on/m3-expressive/forms, @bug-on/m3-expressive/pickers
- Navigation and bars: @bug-on/m3-expressive/navigation
- Overlays and dialogs: @bug-on/m3-expressive/overlays
- Layout and cards: @bug-on/m3-expressive/layout
- Feedback and progress: @bug-on/m3-expressive/feedback
- Core and providers: @bug-on/m3-expressive/core

3. Tailwind CSS v4 only
This library targets Tailwind CSS v4. Use the CSS-first v4 workflow; do not create a tailwind.config.js unless the existing project explicitly requires one. The root stylesheet must include:
@import "tailwindcss";
@import "@bug-on/m3-expressive/index.css";

4. Animation
Use Motion for React from the motion package, importing from motion/react. Do not add the legacy framer-motion package to new projects unless the repository already depends on it and migration is out of scope.

5. Known API requirements
- TextField onChange receives a raw string: (value: string) => void. It does not receive a React ChangeEvent.
- Select onChange receives: (value: string, option?: SelectOption) => void.
- ProgressIndicator requires an aria-label.
- For an indeterminate ProgressIndicator, omit value; do not use max.
- Prefer semantic MD3 utilities such as bg-m3-primary and text-m3-on-surface. Do not hard-code hex colours when a semantic token exists.

6. Code quality and accessibility
- Preserve TypeScript safety and existing project conventions.
- Use semantic HTML, accessible names, keyboard support, and correct ARIA only when necessary.
- Respect React Server Components and client boundaries in Next.js. Add "use client" only to components that need browser APIs, state, effects, or event handlers.
- Return complete, minimal changes. Explain any required manual setup step.

# pnpm
pnpm add @bug-on/m3-expressive motion
pnpm add -D tailwindcss @tailwindcss/vite

# npm
npm install @bug-on/m3-expressive motion
npm install -D tailwindcss @tailwindcss/vite

// vite.config.ts
import { defineConfig } from "vite";
import react from "@vitejs/plugin-react";
import tailwindcss from "@tailwindcss/vite";

export default defineConfig({
  plugins: [react(), tailwindcss()],
});

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

/* Optional typography */
@import "@bug-on/m3-expressive/typography.css";

// src/main.tsx
import React from "react";
import ReactDOM from "react-dom/client";
import { MD3ThemeProvider } from "@bug-on/m3-expressive/core";
import { Button } from "@bug-on/m3-expressive/buttons";
import "./index.css";

function App() {
  return (
    <MD3ThemeProvider>
      <main className="min-h-screen bg-m3-surface p-6 text-m3-on-surface">
        <h1 className="text-2xl font-semibold">React + MD3 Expressive</h1>
        <Button onClick={() => console.log("Pressed")}>Get started</Button>
      </main>
    </MD3ThemeProvider>
  );
}

ReactDOM.createRoot(document.getElementById("root")!).render(
  <React.StrictMode>
    <App />
  </React.StrictMode>,
);

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

/* app/globals.css */
@import "tailwindcss";
@import "@bug-on/m3-expressive/index.css";
@import "@bug-on/m3-expressive/typography.css";

// app/providers.tsx
"use client";

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

export function Providers({ children }: { children: React.ReactNode }) {
  return <MD3ThemeProvider>{children}</MD3ThemeProvider>;
}

// app/layout.tsx
import { Providers } from "./providers";
import "./globals.css";

export default function RootLayout({
  children,
}: Readonly<{
  children: React.ReactNode;
}>) {
  return (
    <html lang="en">
      <body>
        <Providers>{children}</Providers>
      </body>
    </html>
  );
}