@maz-ui/mcp 5.3.1-beta.0 → 5.4.0

package/dist/chunks/theme.mjs

@@ -15089,6 +15089,10 @@ function presetColors(preset) {
     ...names.map((name) => `| \`${name}\` | ${colorClasses(name)} | ${display(light[name])} | ${display(dark[name])} |`)
   ];
 }
+function presetColorScale(preset) {
+  const mode = asRecord(preset.overrides.scales).color;
+  return typeof mode === "string" ? [`Color scales: \`${mode}\` (\`scales.color\`), the derivation of the \`-50\`..\`-950\` steps of the brand colors (\`bg-primary-100\`, \`text-accent-700\`...). \`perceptual\` keeps their order and hue with very light or very dark brand colors.`] : [];
+}
 function presetFoundation(preset, wanted) {
   const rows = Object.entries(asRecord(preset.overrides.foundation)).filter(([key]) => wanted(FOUNDATION_USAGE[key]?.topic ?? "css-variables")).map(([key, value]) => `| \`${key}\` | \`--maz-${key}\` | ${FOUNDATION_USAGE[key]?.usage ?? "-"} | ${display(value)} |`);
   return rows.length > 0 ? ["| Foundation | CSS variable | Used by | Value |", "| --- | --- | --- | --- |", ...rows] : [];
@@ -15120,6 +15124,7 @@ function renderPreset(preset, wanted, filtered) {
   const origin = [preset.exportName && `\`${preset.exportName}\``, preset.base && `base \`${preset.base}\``].filter(Boolean).join(", ");
   const tables = [
     wanted("colors") ? presetColors(preset) : [],
+    wanted("colors") ? presetColorScale(preset) : [],
     presetFoundation(preset, wanted),
     presetScales(preset, wanted),
     wanted("colors") ? presetComponents(preset) : []

package/docs/components/maz-animated-element.md

@@ -18,6 +18,10 @@ url: "https://maz-ui.com/components/maz-animated-element"
 
 ## Basic usage
 
+**Tip:**
+
+This component is SSR friendly: its content is in the server markup and the animation is pure CSS, so it starts on the first paint when the element is in the viewport, without waiting for JavaScript. Below the viewport, it plays when the element enters it. With `prefers-reduced-motion: reduce`, the content is displayed without animation.
+
 ```vue
 <script lang="ts" setup>
 import MazAnimatedElement from 'maz-ui/components/MazAnimatedElement'

package/docs/components/maz-animated-text.md

@@ -20,7 +20,7 @@ url: "https://maz-ui.com/components/maz-animated-text"
 
 **Tip:**
 
-This component is SSR friendly. It will display the brut text on the server side with the chosen tag, and the animated text on the client side.
+This component is SSR friendly: the server renders the same markup as the client, so the text keeps its layout on hydration (no layout shift). The animation is pure CSS and starts on the first paint when the text is in the viewport, without waiting for JavaScript; below the viewport, it plays when the text enters it. With `prefers-reduced-motion: reduce`, the text is displayed without animation.
 
 ```vue
 <script lang="ts" setup>

package/docs/components/maz-btn.md

@@ -146,13 +146,17 @@ Choose the size of the rounded with the attribute `rounded-size` and value `none
 
 The button can be a fab button with the attribute `fab`
 
+**Tip: Accessible name**
+
+A button that only shows an icon has no text for screen readers: give it an `aria-label` describing the action (`aria-label="Light mode"`), or a `title` on the icon (`:icon="{ icon: MazSun, title: 'Light mode' }"`), which names the icon and so the button.
+
 ```html
-<MazBtn fab icon="/sun.svg" size="mini" />
-<MazBtn fab icon="/sun.svg" size="xs" />
-<MazBtn fab icon="/sun.svg" size="sm" />
+<MazBtn fab icon="/sun.svg" aria-label="Light mode" size="mini" />
+<MazBtn fab icon="/sun.svg" aria-label="Light mode" size="xs" />
+<MazBtn fab icon="/sun.svg" aria-label="Light mode" size="sm" />
 <MazBtn fab> fab </MazBtn>
-<MazBtn fab icon="/sun.svg" size="lg" />
-<MazBtn fab icon="/sun.svg" size="xl" />
+<MazBtn fab icon="/sun.svg" aria-label="Light mode" size="lg" />
+<MazBtn fab icon="/sun.svg" aria-label="Light mode" size="xl" />
 ```
 
 ## Block

package/docs/components/maz-input-number.md

@@ -61,7 +61,7 @@ You can remove the buttons with the props `hide-buttons`
 - `size` (`"xs" | "sm" | "md" | "lg" | "xl" | "mini"`, default: `'md'`): The size of the input number component.
 - `hide-buttons` (`boolean`, default: `false`): Whether to hide the increment and decrement buttons or not.
 - `text-center` (`boolean`, default: `true`): Whether to center the text inside the input or not.
-- `inputmode` (`"none" | "text" | "search" | "email" | "tel" | "url" | "numeric" | "decimal"`, default: `"numeric"`): The inputmode attribute for the input.
+- `inputmode` (`"none" | "text" | "search" | "url" | "email" | "tel" | "numeric" | "decimal"`, default: `"numeric"`): The inputmode attribute for the input.
 - `block` (`boolean`): The input will be displayed in full width.
 - `error` (`boolean`, default: `false`): Will display the input in error state.
 - `hint` (`string`): The hint text to display below the input.

package/docs/components/maz-input-phone-number.md

@@ -518,7 +518,7 @@ interface MazInputPhoneNumberData {
 - `block` (`boolean`, default: `false`): The input will be displayed in full width.
 - `orientation` (`"row" | "col" | "responsive"`, default: `"responsive"`): Orientation of the inputs in the component.
 - `country-select-attributes` (`Record<string, unknown>`, default: `{ name: "country", autocomplete: "off", style: { width: "14rem", }, }`): Meta attributes of the country input.
-- `phone-input-attributes` (`(Record<string, unknown> & { name: string; inputmode: "none" | "text" | "search" | "email" | "tel" | "url" | "numeric" | "decimal" | undefined; autocomplete: string; })`, default: `{ name: "phone", autocomplete: "tel", inputmode: "tel", }`): Meta attributes of the phone number input.
+- `phone-input-attributes` (`(Record<string, unknown> & { name: string; inputmode: "none" | "text" | "search" | "url" | "email" | "tel" | "numeric" | "decimal" | undefined; autocomplete: string; })`, default: `{ name: "phone", autocomplete: "tel", inputmode: "tel", }`): Meta attributes of the phone number input.
 - `assistive-text` (`string`): Helper text displayed below the input to provide additional context or validation feedback.
 - `hint` (`string`): Alternative text that replaces the label when provided. Useful for contextual hints.
 

package/docs/components/maz-input.md

@@ -305,7 +305,7 @@ Use the attribute `rounded-size` with a value in `'none' | 'sm' | 'md' | 'lg' |
 - `hint` (`string`): Alternative text that replaces the label when provided. Useful for contextual hints.
 - `input-classes` (`string`): Additional CSS classes to apply specifically to the input wrapper element.
 - `border` (`boolean`, default: `true`): Controls whether the input has a visible border. Set to false for borderless inputs.
-- `inputmode` (`"none" | "text" | "search" | "email" | "tel" | "url" | "numeric" | "decimal"`, default: `"text"`): HTML inputmode attribute that provides hints for virtual keyboards on mobile devices.
+- `inputmode` (`"none" | "text" | "search" | "url" | "email" | "tel" | "numeric" | "decimal"`, default: `"text"`): HTML inputmode attribute that provides hints for virtual keyboards on mobile devices.
 - `size` (`"xs" | "sm" | "md" | "lg" | "xl" | "mini"`): Controls the height and text size of the input component.
 - `debounce` (`number | boolean`, default: `false`): Enables input debouncing to limit the frequency of value updates. When true, uses 500ms delay. When a number, uses that value as delay in milliseconds.
 - `auto-focus` (`boolean`, default: `false`): Automatically focuses the input when the component mounts.

package/docs/ecosystem/nuxt.md

@@ -124,7 +124,7 @@ export default defineNuxtConfig({
 
     // Theming System
     theme: {
-      preset: 'maz-ui', // 'maz-ui' | 'pristine' | 'ocean' | 'obsidian' | 'nova' | custom object
+      preset: 'maz-ui', // 'maz-ui' | 'pristine' | 'ocean' | 'obsidian' | 'nova' | 'folio' | custom object
       strategy: 'runtime', // 'runtime' | 'buildtime'
       darkModeStrategy: 'class', // 'class' | 'media'
       darkClass: 'dark', // class on <html> when colorMode === 'dark' (default: 'dark')

package/docs/ecosystem/themes.md

@@ -21,7 +21,7 @@ Modern and performant theme system for Maz-UI built on native CSS features (`lig
 - **Native widget theming** - `color-scheme` makes scrollbars, native `<select>`, date pickers and autofill follow the active mode automatically
 - **Animated theme switch** - Optional full-page View Transitions via `setColorMode(..., { animate: true })`
 - **Anti-FART** - `<meta name="color-scheme">` injected at boot to prevent any Flash of inAccurate coloR Theme (no setup needed)
-- **Automatic color scales** - `--maz-X-50` through `--maz-X-950` derived via OKLCh relative color syntax - perceptually uniform and chroma-preserving
+- **Automatic color scales** - the `-50` to `-950` steps are derived via OKLCh relative color syntax, with an opt-in `perceptual` mode that keeps their order and hue with any base color
 - **Performance Strategies** - Runtime injection or build-time generation according to your needs
 - **Strict TypeScript** - Complete types for perfect DX
 - **Zero FOUC** - Pass the preset object up front; the full CSS is injected synchronously on first paint
@@ -47,7 +47,7 @@ const app = createApp(App)
 
 app.use(MazUi, {
   theme: {
-    preset: mazUi, // pristine | ocean | obsidian | nova
+    preset: mazUi, // pristine | ocean | obsidian | nova | folio
     strategy: 'runtime', // 'runtime' | 'buildtime'
     darkModeStrategy: 'class', // 'class' | 'media' (only if mode is `both`)
     mode: 'both', // 'light' | 'dark' | 'both' (supported color modes)
@@ -300,6 +300,18 @@ A modern startup / AI / creative preset - electric violet primary, hot coral sec
 import { nova } from '@maz-ui/themes/presets'
 ```
 
+### Folio
+
+An electric and modern preset made for long reading, and the one of this documentation: an electric blue primary, an electric magenta secondary and a cyan accent that blend into a plasma gradient, on faintly violet surfaces (almost white in light mode, violet-black in dark mode). Fraunces (serif) for the headings, Inter for the text, Geist Mono for the code, soft 0.625rem `md` radius. In dark mode the color roles turn into bright tones carrying dark text, so they stay readable as text on the surface too. Every text pair reaches WCAG AA.
+
+```typescript
+import { folio } from '@maz-ui/themes/presets'
+```
+
+**Tip: Fonts**
+
+Like the other presets, Folio only declares font stacks: load Fraunces, Inter and Geist Mono yourself (self-hosted or from a font service), the stacks fall back to system fonts otherwise.
+
 ## Rendering Strategies
 
 ### ⚡ Runtime (Recommended)
@@ -472,6 +484,32 @@ const codeTheme = definePreset({
 })
 ```
 
+### Color scales
+
+The steps `-50` to `-950` of the brand colors (`primary`, `secondary`, `accent`, `info`, `success`, `warning`, `destructive`) are derived from the base color, which is the `500` step. `scales.color` picks the derivation:
+
+- `relative` (default): a fixed lightness offset per step. With a very dark or very light base, the scale collapses: half of a navy scale is black, half of a gold scale is white.
+- `perceptual`: each step travels a share of the way between the base and a light or a dark bound, with a chroma capped near white and black. The steps keep their order and their hue whatever the base, and the classes do not change (`bg-accent-300`, `text-primary-700`...).
+
+```typescript
+const brandTheme = definePreset({
+  base: 'maz-ui',
+  overrides: {
+    colors: {
+      light: { secondary: '#0E1450', accent: '#FFC93C' },
+    },
+    scales: {
+      color: 'perceptual',
+    },
+  },
+})
+```
+
+- The scales stay dynamic: they follow `updateTheme()` and the light and dark values of the base. A step is relative to the base of each mode: `accent-300` gives two colors in light and dark when the two bases differ.
+- `surface`, `foreground`, `contrast` and `divider` keep the relative scale: the components use it as "one notch darker or lighter" (`bg-surface-600`).
+- The steps are redefined for the maz-ui components (`--maz-color-<role>-<step>`) and for the Tailwind classes of your project (`--color-<role>-<step>`). They take precedence over a step you redefine in your own `@theme`.
+- The browsers clip an out-of-gamut color channel by channel, which can shift its hue: the chroma cap keeps this shift under the visible threshold for almost every color, the most saturated blues and yellows excepted.
+
 ### Per-component overrides
 
 `components` is a small, validated set of per-component knobs. Every entry is per-mode where appropriate so light and dark can drift independently:
@@ -870,6 +908,7 @@ Multi-step scales under `scales.<key>`.
 | --- | --- | --- |
 | `rounded.xs..3xl` | `--maz-rounded-xs..3xl` | `rounded-{key}` (bridged to `--radius-{key}`) |
 | `shadow.{sm, md, lg, xl, elevation}` | `--maz-shadow-style-{key}` | `shadow-{key}` (bridged to `--shadow-{key}`) |
+| `color` (`'relative'` \| `'perceptual'`) | `--maz-color-<role>-50..950`, `--color-<role>-50..950` | `bg-primary-300`... (see Color scales) |
 
 > Same naming-collision avoidance as foundation: `rounded.*` (instead of `radius.*`) and `shadow-style-*` (instead of plain `shadow-*`) keep the bridge cycle-free under `prefix(maz)`.
 

package/docs/guide/maz-ui-provider.md

@@ -98,7 +98,7 @@ The entire Maz-UI setup is now code-split into the Dashboard chunk.
 
 ```typescript
 interface ThemeOptions {
-  preset: ThemePreset                            // Required - Theme preset (mazUi, ocean, pristine, obsidian, nova, or custom)
+  preset: ThemePreset                            // Required - Theme preset (mazUi, ocean, pristine, obsidian, nova, folio, or custom)
   overrides?: ThemePresetOverrides               // Partial overrides for colors, foundation, etc.
   strategy?: 'runtime' | 'buildtime'             // CSS generation strategy (default: 'runtime')
   darkModeStrategy?: 'class' | 'media'           // Dark mode handling (default: 'class')

package/docs/guide/vue.md

@@ -83,7 +83,7 @@ app.use(MazUi, {
    * @see https://maz-ui.com/ecosystem/themes
    */
   theme: {
-    preset: mazUi, // 'ocean' | 'pristine' | 'obsidian' | 'nova'
+    preset: mazUi, // 'ocean' | 'pristine' | 'obsidian' | 'nova' | 'folio'
     overrides: {
       foundation: {
         'space': '0.25rem',