secondsky/claude-skills / plugins/maz-ui/skills/maz-ui
maz-ui
VerifiedMaz-UI v4 - Modern Vue & Nuxt component library with 50+ standalone components, composables, directives, theming, i18n, and SSR support. Use when building Vue/Nuxt applications with forms, dialogs, tables, animations, or need responsive design system with dark mode.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 17.7 KB |
| references/accessibility.md | markdown | 16.2 KB |
| references/cli.md | markdown | 10.8 KB |
| references/components-feedback.md | markdown | 19.1 KB |
| references/components-forms.md | markdown | 8.4 KB |
| references/components-layout.md | markdown | 17.8 KB |
| references/components-navigation.md | markdown | 19.5 KB |
| references/composables.md | markdown | 28.3 KB |
| references/directives.md | markdown | 17.0 KB |
| references/form-validation.md | markdown | 22.7 KB |
| references/icons.md | markdown | 14.9 KB |
| references/mcp.md | markdown | 13.6 KB |
| references/migration-v4.md | markdown | 21.0 KB |
| references/performance.md | markdown | 17.0 KB |
| references/plugins.md | markdown | 25.1 KB |
| references/resolvers.md | markdown | 26.2 KB |
| references/setup-nuxt.md | markdown | 26.0 KB |
| references/setup-vue.md | markdown | 21.7 KB |
| references/ssr-ssg.md | markdown | 13.9 KB |
| references/theming.md | markdown | 7.2 KB |
| references/translations.md | markdown | 20.1 KB |
| references/troubleshooting.md | markdown | 9.0 KB |
references/cli.md
View on GitHub# Maz-UI CLI Reference
Guide to @maz-ui/cli theme generator for Maz-UI v3.x (legacy) and migration to v4.x themes.
## Overview
The `@maz-ui/cli` package provides a command-line tool for generating CSS variable files for theming Maz-UI.
::: warning Version Notice
**This CLI is for Maz-UI v3.x users only.**
If you're using **Maz-UI v4.x** (v4.9.3+), you should use the **[@maz-ui/themes package](./theming.md)** instead, which provides:
- Built-in theme presets (maz-ui, ocean, pristine, obsidian)
- Runtime theme switching
- Better TypeScript support
- Optimized performance
:::
---
## For v4.x Users (Current Version)
### Modern Theming with @maz-ui/themes
**Installation**:
```bash
pnpm add @maz-ui/themes
```
**Usage**:
```typescript
import { MazUi } from 'maz-ui/plugins/maz-ui'
import { mazUi, ocean, pristine, obsidian } from '@maz-ui/themes'
app.use(MazUi, {
theme: {
preset: ocean // Use built-in presets
}
})
```
**Custom Theme**:
```typescript
import { defineTheme } from '@maz-ui/themes'
const customTheme = defineTheme({
colors: {
primary: '#007AFF',
secondary: '#5856D6',
success: '#34C759',
warning: '#FF9500',
destructive: '#FF3B30',
info: '#5AC8FA'
},
borderRadius: '12px',
fontFamily: 'Inter, system-ui, sans-serif'
})
app.use(MazUi, {
theme: { preset: customTheme }
})
```
**Learn More**: See [Theming Guide](./theming.md) for complete v4 documentation.
---
## For v3.x Users (Legacy)
### Installation
```bash
# Install CLI package
npm install @maz-ui/cli
# Or with pnpm
pnpm add @maz-ui/cli
```
---
## Configuration File
Create a configuration file in your project root:
**File**: `maz-ui.config.ts` (or `.js`, `.mjs`, `.cjs`)
```typescript
import { defineConfig } from '@maz-ui/cli'
export default defineConfig({
outputCssFilePath: './css/maz-ui-variables.css',
theme: {
colors: {
primary: 'hsl(210, 100%, 56%)',
secondary: 'hsl(164, 76%, 46%)',
info: 'hsl(188, 78%, 41%)',
success: 'hsl(80, 61%, 50%)',
warning: 'hsl(40, 97%, 59%)',
danger: 'hsl(1, 100%, 71%)',
bgOverlay: 'hsl(0, 0%, 0% / 30%)',
lightTheme: {
textColor: 'hsl(0, 0%, 85%)',
colorMuted: 'hsla(0, 0%, 0%, 0.54)',
bgColor: 'hsl(0, 0%, 100%)',
},
darkTheme: {
textColor: 'hsl(210, 8%, 14%)',
colorMuted: 'hsla(0, 0%, 100%, 0.54)',
bgColor: 'hsl(235, 16%, 15%)',
},
},
borderColor: 'hsl(220deg 13.04% 90.98%)',
borderWidth: '0.125rem',
borderRadius: '0.5rem',
fontFamily: `system-ui, -apple-system, blinkmacsystemfont, 'Segoe UI', roboto, oxygen,
ubuntu, cantarell, 'Fira Sans', 'Droid Sans', 'Helvetica Neue', sans-serif`,
},
})
```
### Configuration Options
```typescript
interface MazUiConfig {
/**
* Path and name of generated CSS file
* @example './css/maz-ui-variables.css'
*/
outputCssFilePath: string
theme: {
colors: {
primary?: string
secondary?: string
info?: string
danger?: string
success?: string
warning?: string
bgOverlay?: string
lightTheme?: {
textColor?: string
colorMuted?: string
bgColor?: string
}
darkTheme?: {
textColor?: string
colorMuted?: string
bgColor?: string
}
}
/**
* Border color applied to components like inputs, cards, etc.
*/
borderColor?: string
/**
* Border width applied to components
*/
borderWidth?: string
/**
* Border radius for rounded components
*/
borderRadius?: string
/**
* Font family for text
*/
fontFamily?: string
}
}
```
### Color Formats
All colors support multiple formats:
```typescript
// HEX
primary: '#007AFF'
// RGB
secondary: 'rgb(52, 199, 89)'
// RGBA
bgOverlay: 'rgba(0, 0, 0, 0.3)'
// HSL
success: 'hsl(80, 61%, 50%)'
// HSLA
danger: 'hsla(1, 100%, 71%, 1)'
// Named colors
warning: 'orange'
```
---
## Generating CSS Variables
### Method 1: Direct CLI Command
Run the CLI directly without installing:
```bash
# Using npx
npx maz-ui generate-css-vars
# Using pnpm
pnpx maz-ui generate-css-vars
```
### Method 2: Package.json Script
**1. Add script to package.json**:
```json
{
"scripts": {
"generate-css-vars": "maz-ui generate-css-vars"
}
}
```
**2. Run the script**:
```bash
# npm
npm run generate-css-vars
# yarn
yarn generate-css-vars
# pnpm
pnpm generate-css-vars
```
### Output
The CLI will generate a CSS file at the specified `outputCssFilePath`:
```css
/* css/maz-ui-variables.css */
:root {
--maz-color-primary: hsl(210, 100%, 56%);
--maz-color-primary-50: hsl(210, 100%, 95%);
--maz-color-primary-100: hsl(210, 100%, 90%);
/* ... more primary shades */
--maz-color-secondary: hsl(164, 76%, 46%);
/* ... more colors */
--maz-border-color: hsl(220deg 13.04% 90.98%);
--maz-border-width: 0.125rem;
--maz-border-radius: 0.5rem;
--maz-font-family: system-ui, ...;
}
[data-theme="dark"] {
--maz-text-color: hsl(0, 0%, 85%);
--maz-color-muted: hsla(0, 0%, 0%, 0.54);
--maz-bg-color: hsl(0, 0%, 100%);
}
```
---
## Using Generated CSS
**Import in your main entry file**:
```typescript
// main.ts (Vue)
import './css/maz-ui-variables.css'
import 'maz-ui/css/main.css' // v3.x Maz-UI styles
```
```typescript
// nuxt.config.ts (Nuxt)
export default defineNuxtConfig({
css: [
'./css/maz-ui-variables.css',
'maz-ui/css/main.css'
]
})
```
---
## Examples
### Minimal Configuration
```typescript
// maz-ui.config.ts
import { defineConfig } from '@maz-ui/cli'
export default defineConfig({
outputCssFilePath: './src/assets/maz-ui-variables.css',
theme: {
colors: {
primary: '#007AFF',
secondary: '#5856D6'
}
}
})
```
### Full Configuration
```typescript
// maz-ui.config.ts
import { defineConfig } from '@maz-ui/cli'
export default defineConfig({
outputCssFilePath: './public/css/maz-ui-variables.css',
theme: {
colors: {
primary: 'hsl(210, 100%, 56%)',
secondary: 'hsl(164, 76%, 46%)',
info: 'hsl(188, 78%, 41%)',
success: 'hsl(80, 61%, 50%)',
warning: 'hsl(40, 97%, 59%)',
danger: 'hsl(1, 100%, 71%)',
bgOverlay: 'hsla(0, 0%, 0%, 0.3)',
lightTheme: {
textColor: 'hsl(0, 0%, 15%)',
colorMuted: 'hsla(0, 0%, 0%, 0.54)',
bgColor: 'hsl(0, 0%, 100%)',
},
darkTheme: {
textColor: 'hsl(0, 0%, 85%)',
colorMuted: 'hsla(0, 0%, 100%, 0.54)',
bgColor: 'hsl(235, 16%, 15%)',
},
},
borderColor: 'hsl(220, 13%, 91%)',
borderWidth: '2px',
borderRadius: '12px',
fontFamily: 'Inter, -apple-system, sans-serif',
},
})
```
### Brand-Specific Theme
```typescript
// maz-ui.config.ts
import { defineConfig } from '@maz-ui/cli'
export default defineConfig({
outputCssFilePath: './src/styles/brand-theme.css',
theme: {
colors: {
primary: '#FF6B6B', // Brand red
secondary: '#4ECDC4', // Brand teal
success: '#95E1D3', // Mint green
warning: '#F9CA24', // Bright yellow
danger: '#EE5A6F', // Coral red
info: '#00B8D4', // Cyan
lightTheme: {
textColor: '#2C3E50',
colorMuted: 'rgba(44, 62, 80, 0.6)',
bgColor: '#FAFAFA',
},
darkTheme: {
textColor: '#ECF0F1',
colorMuted: 'rgba(236, 240, 241, 0.6)',
bgColor: '#1A1A2E',
},
},
borderColor: '#E0E0E0',
borderWidth: '1px',
borderRadius: '8px',
fontFamily: 'Poppins, sans-serif',
},
})
```
---
## Migration from v3 to v4
### v3 (CLI Approach)
**v3 Configuration**:
```typescript
// maz-ui.config.ts (v3)
export default defineConfig({
outputCssFilePath: './css/vars.css',
theme: {
colors: {
primary: '#007AFF',
secondary: '#5856D6'
},
borderRadius: '8px'
}
})
```
**v3 Usage**:
```bash
npx maz-ui generate-css-vars
```
```typescript
// main.ts
import './css/vars.css'
import 'maz-ui/css/main.css'
```
### v4 (Themes Package)
**v4 Configuration**:
```typescript
// theme.ts (v4)
import { defineTheme } from '@maz-ui/themes'
export const customTheme = defineTheme({
colors: {
primary: '#007AFF',
secondary: '#5856D6'
},
borderRadius: '8px'
})
```
**v4 Usage**:
```typescript
// main.ts
import { MazUi } from 'maz-ui/plugins/maz-ui'
import { customTheme } from './theme'
import 'maz-ui/styles'
app.use(MazUi, {
theme: { preset: customTheme }
})
```
### Benefits of v4 Approach
1. **No Build Step**: Themes work runtime, no CSS file generation needed
2. **Type Safety**: Full TypeScript support with autocomplete
3. **Theme Switching**: Dynamic theme changes without reloading
4. **Better DX**: Simpler API, less configuration
5. **Built-in Presets**: 4 professional themes out of the box
6. **Tree-Shaking**: Better optimized bundle sizes
---
## Troubleshooting (v3 CLI)
### CLI Command Not Found
**Error**: `maz-ui: command not found`
**Solution**: Ensure @maz-ui/cli is installed:
```bash
npm install @maz-ui/cli
# or use npx/pnpx
```
### Config File Not Found
**Error**: `Could not find maz-ui.config file`
**Solution**: Create `maz-ui.config.ts` in project root:
```typescript
import { defineConfig } from '@maz-ui/cli'
export default defineConfig({
outputCssFilePath: './src/maz-ui-vars.css',
theme: { colors: {} }
})
```
### Generated CSS Not Applied
**Error**: Styles don't match configuration
**Solution**: Ensure CSS is imported BEFORE Maz-UI's main CSS:
```typescript
import './css/maz-ui-variables.css' // Custom variables FIRST
import 'maz-ui/css/main.css' // Then Maz-UI styles
```
### Color Variants Look Wrong
**Warning**: "Depending on chosen colors, some variants may need adjustment"
**Solution**: Manually adjust generated CSS variables if auto-generated shades don't look right:
```css
/* Manually override problematic shades */
:root {
--maz-color-primary-500: #007AFF; /* Your exact brand color */
}
```
---
## Related Documentation
- **[Theming Guide](./theming.md)** - v4 theming with @maz-ui/themes (recommended)
- **[Migration v4 Guide](./migration-v4.md)** - Upgrading from v3 to v4
- **[Setup Vue](./setup-vue.md)** - Vue 3 installation and configuration
- **[Setup Nuxt](./setup-nuxt.md)** - Nuxt 3 module setup
---
## External Resources
- **[@maz-ui/cli NPM](https://www.npmjs.com/package/@maz-ui/cli)** - Legacy v3 CLI package
- **[@maz-ui/themes NPM](https://www.npmjs.com/package/@maz-ui/themes)** - Modern v4 theming package
- **[Official CLI Docs](https://maz-ui.com/guide/cli)** - v3 CLI documentation
- **[Official Themes Docs](https://maz-ui.com/guide/themes)** - v4 themes documentation
---
**CLI Version**: @maz-ui/cli v3.x (legacy)
**Recommended**: @maz-ui/themes v4.9.3+
**Last Updated**: 2025-12-14
::: tip Recommendation
For new projects, use **@maz-ui/themes** (v4) instead of @maz-ui/cli (v3) for better performance, developer experience, and runtime theme switching.
:::
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation). | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK). | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |