Maz-UI
Maz-UI v5.0.0

Maz-UI v5.0.0 - Theming, perfected ​

After the v4 rebuild, Maz-UI v5 is a focused major: theming, the move to Tailwind v4, and a few long-standing rough edges I wanted gone before tagging stable.

Why v5 ​

Two things forced the major.

Tailwind v4 landed. v4's CSS-first config, new prefix syntax and renamed utilities don't migrate behind the scenes. Bumping Tailwind is a real version change.

Theming had outgrown the v4 design. The single foundation radius, the background / border color names that meant something else than what components actually used, the dual-stage critical-CSS pipeline — none of that aged well. v5 cleans the surface, switches the color system to OKLCh for perceptually uniform scales, and exposes proper scales and components blocks.

The rest builds on those: components flip cleanly under dir="rtl", the chart is lighter, the icon API is simpler, and there's a CLI for the mechanical part of the upgrade.

What's new ​

Theming, top to bottom ​

OKLCh under the hood. Bundled presets and the dynamic scale generator emit oklch() strings. Generated scales (primary-50 → primary-950) ramp consistently across hues — yellow-700 no longer looks muddy next to blue-700, and Display P3 is on the table. Existing custom presets in hsl(), rgb(), #hex or the legacy '210 100% 56%' form keep parsing.

Honest names. background is now surface, border is now divider — same rename in the runtime CSS variables (--maz-surface[-N], --maz-divider[-N]).

A real radius scale. foundation.radius becomes scales.rounded.{xs..3xl}, so maz:rounded-md, maz:rounded-lg, etc. all move with your preset.

A components block. Per-component tokens (button font weight, container/input backgrounds, …) are now explicit knobs you can override. Optional, with sensible defaults.

A new bundled preset, nova — electric violet primary, cyan accent, hot coral secondary, Geist font stack — joins mazUi, pristine, ocean and obsidian. Each existing preset got a palette refresh so secondary and accent voices actually pop.

Preset persistence. v5 remembers the user's last preset choice in a maz-preset cookie (1-year, SameSite=Lax) so a runtime theme switcher survives reloads. Opt out with persistPreset: false.

Single rendering path. The two-stage critical-CSS / async-full-CSS dance is gone. Strategy is now 'runtime' | 'buildtime'. Less surface, less to worry about.

Components that respect direction ​

Every prop, slot and CSS hook that named a visual edge is now a logical edge:

  • left-icon / right-icon → start-icon / end-icon (props, slots, classes)
  • MazCard footer-align and MazDrawer variant flip from left | right to start | end
  • top / bottom stay (block-axis edges that don't flip in RTL)

Drop dir="rtl" on <html> and components mirror correctly. Same approach as Radix, MUI or native CSS logical properties.

A lighter chart ​

MazChart no longer wraps vue-chartjs. It talks to chart.js directly, lazy-loads the engine on mount, and only registers the modules the chart type actually needs. update-mode defaults to 'none' so reactive data updates don't re-animate every frame — pass update-mode="default" for the v4 behavior.

A simpler icon API ​

MazIcon v4 had four ways to specify an icon. v5 collapses everything into a single icon prop that accepts a Vue component, a URL/data: URI, or a raw SVG string.

Plus three small additions:

  • fallback — used when the icon is missing or fails to load.
  • flip-icon-for-rtl — auto-mirrors chevrons / arrows in RTL.
  • @maz-ui/icons/raw/* — every bundled icon as a raw SVG string for inlining without a Vue component or async chunk.

MazBadge size, standardized ​

The numeric size="0.8rem" form is gone. Like the rest of the library, MazBadge's size is one of 'mini' | 'xs' | 'sm' | 'md' | 'lg' | 'xl'.

Modern browsers, finally ​

v5 leans on color-mix(), @property and native CSS nesting. That means Chromium 111+, Safari 16.4+, Firefox 128+ — no polyfill path. If your audience still relies on older browsers, stay on v4. Full rationale on the Browser Support page.

Migration ​

Two tools so the upgrade isn't a chore.

@maz-ui/upgrade — a one-shot CLI ​

bash
# Preview
npx @maz-ui/upgrade ./ --dry-run

# Apply
npx @maz-ui/upgrade ./

It handles the mechanical part of the migration (CSS subpath imports, prop renames, CSS var renames, Nuxt config keys, custom preset color keys, and package.json version bumps)

@maz-ui/mcp — for everything else ​

A few changes need a human eye: MazIcon API (needs your original asset paths), MazBadge numeric size mapping, foundation.radius → scales.rounded.md reshape, and MazChart update-mode default.

The @maz-ui/mcp server exposes the migration guide and every other Maz-UI doc to your AI assistant. Connect it once, then walk the guide section by section against your codebase — there's a step-by-step flow ready to copy-paste.

bash
# Claude Code
claude mcp add maz-ui npx @maz-ui/mcp --scope project

Cursor, Windsurf, VS Code Copilot, Cline and Claude Desktop are all in the MCP guide.

The full guide ​

Everything that changed: v5 migration guide.

Solo maintainer notice ​

Maz-UI is maintained by a single developer. After v5 stable, v4 will no longer receive support — no security fixes, no backports. Plan your upgrade.

Getting Started ​

For Vue projects ​

bash
npm install maz-ui@5
typescript
// main.ts
import { createApp } from 'vue'
import { MazUi } from 'maz-ui/plugins/maz-ui'
import { mazUi } from '@maz-ui/themes/presets'
import { fr } from '@maz-ui/translations'
import 'maz-ui/style.css'

const app = createApp(App)

app.use(MazUi, {
  theme: { preset: mazUi },
  translations: { locale: 'fr', fallbackLocale: 'en', messages: { fr } },
})

app.mount('#app')

For Nuxt projects ​

bash
npm install @maz-ui/nuxt@5
typescript
// nuxt.config.ts
export default defineNuxtConfig({
  modules: ['@maz-ui/nuxt'],
})

Get Started ​

Ready to upgrade to Maz-UI v5?

Migration Guide Get Started View on GitHub

Feedback and contributions welcome — open an issue or discussion on GitHub.

Made by LouisMazel with 🖤