一键在 Manus 中运行任何 Skill

setup-m3-baseui

星标0

分支0

更新时间2026年6月28日 10:52

Integrates @m3-baseui/* (Material Design 3 on Base UI) into React apps. Supports Tailwind v4 and vanilla-extract engines, migration from @otomatty/*, ThemeProvider wiring, and framework-specific setup (Vite, Next.js, Astro). Use when adding m3-baseui, @m3-baseui/react-tailwind, @m3-baseui/react-vanilla-extract, or migrating from @otomatty/*.

安装

用 Codex 或 Claude 帮你安装复制这段 Prompt，粘贴到 Codex、Claude 或其他助手里，让它检查 Skill 页面并帮你完成安装。

在 Manus 中运行

来源

otomatty

otomatty/m3-baseui

打开 GitHub 仓库查看创作者相关仓库

下载

在 Manus 中运行

Setup @m3-baseui

Integrate m3-baseui into a consumer React project.

Workflow checklist

Copy and track progress:

- [ ] Step 1: Detect project context
- [ ] Step 2: Choose styling engine (one only)
- [ ] Step 3: Install packages
- [ ] Step 4: Wire CSS / build config
- [ ] Step 5: Wrap app with ThemeProvider
- [ ] Step 6: (Optional) Add icons
- [ ] Step 7: Verify

Run verification when done:

bash skills/setup-m3-baseui/scripts/verify-setup.sh
# Or, after installing via npx skills add:
bash ~/.agents/skills/setup-m3-baseui/scripts/verify-setup.sh

Step 1: Detect project context

Inspect before changing anything:

Signal	How to detect
Package manager	`package-lock.json` → npm, `pnpm-lock.yaml` → pnpm, `bun.lock` → bun
Framework	`vite.config.` → Vite, `next.config.` → Next.js, `astro.config.*` → Astro
Existing Tailwind	`tailwindcss` ^4 in deps + `@tailwindcss/vite` or `@tailwindcss/postcss`
Existing VE	`@vanilla-extract/css` + build plugin in vite/next config
Legacy scope	imports or deps containing `@otomatty/` → migrate (see below)

Requirements: React 18+ or 19+, @base-ui/react ^1.6 as peer dependency.

Step 2: Choose engine (pick ONE)

Engine	Install	When to use
Tailwind v4	`@m3-baseui/react-tailwind`	App already uses or will use Tailwind v4
vanilla-extract	`@m3-baseui/react-vanilla-extract`	App uses VE recipes; no Tailwind component classes

Both engines emit identical DOM and data-* attributes — drop-in compatible.

Do not install both engine packages unless migrating (replace imports, then remove the old one).

Step 3: Install packages

Tailwind v4 engine

npm i @m3-baseui/react-tailwind @base-ui/react react react-dom
npm i -D tailwindcss@^4 @tailwindcss/vite

For Next.js use @tailwindcss/postcss instead of @tailwindcss/vite. See frameworks.md.

@m3-baseui/core and @m3-baseui/tokens are pulled in automatically for the Tailwind engine. For vanilla-extract, add @m3-baseui/tokens directly (see above).

vanilla-extract engine

npm i @m3-baseui/react-vanilla-extract @m3-baseui/tokens @base-ui/react react react-dom
npm i -D @vanilla-extract/css @vanilla-extract/recipes @vanilla-extract/vite-plugin

Install @m3-baseui/tokens directly — the app CSS imports @m3-baseui/tokens/tokens.css, and strict package managers (pnpm) do not expose transitive dependencies to the app.

Optional icons

npm i @m3-baseui/icons

Add Material Symbols font in HTML <head>:

<link rel="preconnect" href="https://fonts.googleapis.com" />
<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
<link
  rel="stylesheet"
  href="https://fonts.googleapis.com/css2?family=Material+Symbols+Outlined:opsz,wght,FILL,GRAD@20..48,100..700,0..1,-50..200"
/>

Step 4: Wire CSS and build

Tailwind v4 (default path)

Vite — add Tailwind plugin:

import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';
import tailwindcss from '@tailwindcss/vite';

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

Main CSS — import order matters. Prefer the one-line preset:

@import '@m3-baseui/react-tailwind/preset.css';

/* Required: scan published component classes (omit = unstyled components) */
@source "../node_modules/@m3-baseui/react-tailwind/dist";
@source "./";

Equivalent manual setup:

@import '@m3-baseui/tokens/tokens.css';
@import 'tailwindcss';
@import '@m3-baseui/tokens/theme.css';
@source "../node_modules/@m3-baseui/react-tailwind/dist";
@source "./";

Import the CSS from the app entry (main.tsx, root layout, or Astro layout).

Critical: @source pointing at node_modules/@m3-baseui/react-tailwind/dist is required for Tailwind v4 to generate component utility classes. Forgetting this is the most common integration failure.

vanilla-extract engine

Add vanillaExtractPlugin() to Vite (before React plugin). Import tokens once:

@import '@m3-baseui/tokens/tokens.css';

Component styles are pre-compiled in the VE package — no @source needed.

Framework specifics

See frameworks.md for Next.js App Router, Astro islands, and SSR notes.

Step 5: Wrap app with ThemeProvider

All interactive components must render inside ThemeProvider:

import { Button, ThemeProvider } from '@m3-baseui/react-tailwind';
// VE: '@m3-baseui/react-vanilla-extract'

export default function App() {
  return (
    <ThemeProvider seed="#6750A4" scheme="tonalSpot" mode="system" contrast="standard">
      <Button variant="filled">Submit</Button>
    </ThemeProvider>
  );
}

Prop	Default	Notes
`seed`	—	Hex color; enables dynamic color via material-color-utilities
`scheme`	`tonalSpot`	M3 scheme variant
`mode`	`system`	`light` \| `dark` \| `system`
`contrast`	`standard`	Contrast level

For Next.js App Router, mark the provider wrapper 'use client' or place it in a dedicated client component.

Compound components use namespace API: Menu.Root, Dialog.Trigger, Select.Item, etc.

Tree-shaking (subpath imports)

import { Button } from '@m3-baseui/react-tailwind/button';
import { Dialog } from '@m3-baseui/react-tailwind/dialog';

Step 6: Migrate from `@otomatty/*`

If the project used the legacy scope, replace all imports:

Legacy	New
`@otomatty/tokens`	`@m3-baseui/tokens`
`@otomatty/core`	`@m3-baseui/core` (usually transitive; rarely imported directly)
`@otomatty/icons`	`@m3-baseui/icons`
`@otomatty/react-tailwind`	`@m3-baseui/react-tailwind`
`@otomatty/react-vanilla-extract`	`@m3-baseui/react-vanilla-extract`

Update CSS @import paths and @source paths accordingly. Remove old @otomatty/* from package.json.

Step 7: Verify

Run bash scripts/verify-setup.sh (or the skill's bundled copy).
Start dev server; confirm a Button variant="filled" renders with M3 colors and ripple.
Run the project's typecheck (tsc --noEmit, npm run typecheck, etc.).
Toggle light/dark via ThemeProvider / useTheme() if dynamic color is used.

Common failures

Symptom	Fix
Components render but no M3 styling	Add `@source` for `react-tailwind/dist`; check CSS import order
`useTheme must be used within ThemeProvider`	Wrap route/layout with `ThemeProvider`
Tailwind layout utilities missing	Ensure `@import 'tailwindcss'` is present (via preset)
Icons show blank squares	Add Material Symbols font link
VE build error	Add `vanillaExtractPlugin()`; import `tokens.css` once

Reference

npm: https://www.npmjs.com/org/m3-baseui
Repo: https://github.com/otomatty/m3-baseui
Live demo patterns: examples/playground (Vite + Tailwind), examples/landing (Astro + Tailwind)

name	setup-m3-baseui
description	Integrates @m3-baseui/* (Material Design 3 on Base UI) into React apps. Supports Tailwind v4 and vanilla-extract engines, migration from @otomatty/, ThemeProvider wiring, and framework-specific setup (Vite, Next.js, Astro). Use when adding m3-baseui, @m3-baseui/react-tailwind, @m3-baseui/react-vanilla-extract, or migrating from @otomatty/.

setup-m3-baseui

Setup @m3-baseui

Workflow checklist

Step 1: Detect project context

Step 2: Choose engine (pick ONE)

Step 3: Install packages

Tailwind v4 engine

vanilla-extract engine

Optional icons

Step 4: Wire CSS and build

Tailwind v4 (default path)

vanilla-extract engine

Framework specifics

Step 5: Wrap app with ThemeProvider

Tree-shaking (subpath imports)

Step 6: Migrate from @otomatty/*

Step 7: Verify

Common failures

Reference

Setup @m3-baseui

Workflow checklist

Step 1: Detect project context

Step 2: Choose engine (pick ONE)

Step 3: Install packages

Tailwind v4 engine

vanilla-extract engine

Optional icons

Step 4: Wire CSS and build

Tailwind v4 (default path)

vanilla-extract engine

Framework specifics

Step 5: Wrap app with ThemeProvider

Tree-shaking (subpath imports)

Step 6: Migrate from @otomatty/*

Step 7: Verify

Common failures

Reference

Step 6: Migrate from `@otomatty/*`

Step 6: Migrate from `@otomatty/*`