skills

2026-04-01 10:43:03 +08:00
parent 816db7568c
commit 39d659acd0
175 changed files with 21765 additions and 0 deletions
--- a/.agents/skills/mantine-dev/references/getting-started.md
+++ b/.agents/skills/mantine-dev/references/getting-started.md
@@ -0,0 +1,215 @@
+# Getting Started Reference
+
+## Vite Template (Recommended)
+
+The fastest way to start — official template includes everything:
+
+```bash
+# Clone template
+git clone https://github.com/mantinedev/vite-template my-app
+cd my-app
+
+# Install dependencies
+yarn install  # or npm install
+
+# Start development
+yarn dev
+```
+
+### Template Features
+- PostCSS with `postcss-preset-mantine`
+- TypeScript configured
+- Storybook setup
+- Vitest with React Testing Library
+- ESLint with `eslint-config-mantine`
+- Prettier configured
+
+## Manual Setup
+
+### 1. Create Vite Project
+
+```bash
+npm create vite@latest my-app -- --template react-ts
+cd my-app
+```
+
+### 2. Install Packages
+
+```bash
+# Core (required)
+npm install @mantine/core @mantine/hooks
+
+# PostCSS (required for responsive styles)
+npm install -D postcss postcss-preset-mantine postcss-simple-vars
+
+# Optional packages
+npm install @mantine/form          # Forms with validation
+npm install @mantine/dates dayjs   # Date/time components
+npm install @mantine/notifications # Toast notifications
+npm install @mantine/modals        # Modal manager
+npm install @mantine/charts recharts # Charts
+npm install @mantine/dropzone      # File upload
+npm install @mantine/spotlight     # Command palette (Cmd+K)
+npm install @mantine/code-highlight # Code syntax highlighting
+npm install @mantine/carousel embla-carousel-react # Carousel
+npm install @mantine/tiptap @tiptap/react @tiptap/pm @tiptap/starter-kit # Rich text editor
+```
+
+### 3. Configure PostCSS
+
+Create `postcss.config.cjs`:
+
+```js
+module.exports = {
+  plugins: {
+    'postcss-preset-mantine': {},
+    'postcss-simple-vars': {
+      variables: {
+        'mantine-breakpoint-xs': '36em',
+        'mantine-breakpoint-sm': '48em',
+        'mantine-breakpoint-md': '62em',
+        'mantine-breakpoint-lg': '75em',
+        'mantine-breakpoint-xl': '88em',
+      },
+    },
+  },
+};
+```
+
+### 4. Import Styles
+
+In your entry file (e.g., `src/main.tsx` or `src/App.tsx`):
+
+```tsx
+// Required - core styles
+import '@mantine/core/styles.css';
+
+// Package-specific styles (import only what you use)
+import '@mantine/dates/styles.css';
+import '@mantine/notifications/styles.css';
+import '@mantine/code-highlight/styles.css';
+import '@mantine/dropzone/styles.css';
+import '@mantine/spotlight/styles.css';
+import '@mantine/carousel/styles.css';
+import '@mantine/tiptap/styles.css';
+// Note: @mantine/form and @mantine/hooks have no styles
+```
+
+### 5. Setup MantineProvider
+
+```tsx
+// src/App.tsx
+import '@mantine/core/styles.css';
+
+import { MantineProvider, createTheme } from '@mantine/core';
+import { BrowserRouter, Routes, Route } from 'react-router-dom';
+
+const theme = createTheme({
+  // Your theme customization
+  primaryColor: 'blue',
+  fontFamily: 'Inter, sans-serif',
+});
+
+function App() {
+  return (
+    <MantineProvider theme={theme}>
+      <BrowserRouter>
+        <Routes>
+          {/* Your routes */}
+        </Routes>
+      </BrowserRouter>
+    </MantineProvider>
+  );
+}
+
+export default App;
+```
+
+## Project Structure
+
+Recommended structure for Mantine projects:
+
+```
+src/
+├── components/
+│   ├── Layout/
+│   │   ├── AppShell.tsx
+│   │   ├── Header.tsx
+│   │   └── Navbar.tsx
+│   └── ui/                # Custom UI components
+├── pages/
+│   ├── Home.tsx
+│   └── Settings.tsx
+├── hooks/                  # Custom hooks
+├── theme/
+│   ├── index.ts           # createTheme export
+│   └── components.ts      # Component default props
+├── utils/
+├── App.tsx
+├── main.tsx
+└── App.module.css         # CSS modules
+```
+
+## VS Code Setup
+
+Install recommended extensions:
+
+1. **PostCSS Intellisense and Highlighting**  
+   For postcss syntax support and `$variable` recognition.
+
+2. **CSS Variable Autocomplete**  
+   For Mantine CSS variables autocomplete.
+
+Create `.vscode/settings.json`:
+
+```json
+{
+  "cssVariables.lookupFiles": [
+    "**/*.css",
+    "node_modules/@mantine/core/styles.css"
+  ]
+}
+```
+
+## TypeScript Configuration
+
+Mantine is fully typed. Your `tsconfig.json` should have:
+
+```json
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "lib": ["ES2020", "DOM", "DOM.Iterable"],
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "strict": true,
+    "jsx": "react-jsx",
+    "skipLibCheck": true
+  }
+}
+```
+
+## Common Issues
+
+### Styles Not Loading
+Ensure `@mantine/core/styles.css` is imported before any component usage.
+
+### PostCSS Mixins Not Working
+Check that `postcss-preset-mantine` is installed and configured in `postcss.config.cjs`.
+
+### Dark Mode Flash
+For SSR apps, add `ColorSchemeScript` to `<head>`:
+```tsx
+import { ColorSchemeScript } from '@mantine/core';
+
+// In your HTML head
+<ColorSchemeScript defaultColorScheme="auto" />
+```
+
+### Hydration Warning
+Spread `mantineHtmlProps` on `<html>` element:
+```tsx
+import { mantineHtmlProps } from '@mantine/core';
+
+<html {...mantineHtmlProps}>
+```