mamba-layout

Shared Mamba Vue layout shell, styles, locale helpers, and a standalone browser layout build.

⚠️ Important: Required CDN Links and Styles

The following CDN links and styles are REQUIRED and cannot be omitted or modified:

Required Links (must be included in <head>):

<!-- Icon fonts - DO NOT modify or remove -->
<link type="text/css" rel="stylesheet" href="https://at.alicdn.com/t/c/font_4614982_ta3fsffdp7.css" />
<link type="text/css" rel="stylesheet" href="https://at.alicdn.com/t/c/font_4839395_zeh0j9u8an.css" />

<!-- Mamba Layout CSS - DO NOT modify or remove -->
<script src="https://cdn.jsdelivr.net/npm/@tailwindcss/browser@4"></script>
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/mamba-layout@latest/dist/layout.css" />

Required Styles (must be included in <head>):

<style>
  html, body, mamba-layout {
    width: 100%;
    height: 100%;
    margin: 0;
  }
  mamba-layout {
    display: block;
  }
</style>

Required Script (must be included before closing </body>):

<script src="https://cdn.jsdelivr.net/npm/mamba-layout@latest/dist/layout.global.js"></script>

⚠️ CRITICAL: All of the above links and styles are essential for the layout to function correctly. Do not skip, modify, or change any of these URLs.

Quick Start

<!doctype html>
<html lang="zh-CN">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>My App</title>
    <link type="text/css" rel="stylesheet" href="https://at.alicdn.com/t/c/font_4614982_ta3fsffdp7.css" />
    <link type="text/css" rel="stylesheet" href="https://at.alicdn.com/t/c/font_4839395_zeh0j9u8an.css" />
    <script src="https://cdn.jsdelivr.net/npm/@tailwindcss/browser@4"></script>
    <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/mamba-layout@latest/dist/layout.css" />
    <style>
      html, body, mamba-layout {
        width: 100%;
        height: 100%;
        margin: 0;
      }
      mamba-layout {
        display: block;
      }
    </style>
  </head>
  <body>
    <mamba-layout>
      <div class="demo-content">
        <h1>Hello World</h1>
        <p>Your content goes here</p>
      </div>
    </mamba-layout>
    <script src="https://cdn.jsdelivr.net/npm/mamba-layout@latest/dist/layout.global.js"></script>
  </body>
</html>

Locale Availability

The language selector exposes en-US and zh-CN by default. Additional locales must be enabled explicitly by the host after its messages, locale normalization, and backend language contract are ready:

const setting = {
  supportedLocales: ["en-US", "zh-CN", "es-419"],
  onLocaleChange: async (locale) => {
    // Return false when the host cannot complete the locale switch.
  },
};

LanguageSelect also accepts the same supportedLocales prop when it is used outside BaseLayout, such as on a login page.

Desktop Sidebar Collapse

Desktop sidebar collapsing is opt-in and supports controlled or uncontrolled state. The host application owns persistence when it uses v-model.

<BaseLayout
  v-model:sidebar-collapsed="sidebarCollapsed"
  :setting="setting"
  sidebar-collapse-mode="push-preview"
  :show-sidebar-toggle="true"
/>

Available sidebar-collapse-mode values:

• disabled: keep the desktop sidebar expanded and hide the toggle.
• hidden: collapse the sidebar completely without hover preview.
• push-preview: hover or focus the collapsed toggle to preview the sidebar while moving the main content back to its expanded position.
• overlay-preview: hover or focus the collapsed toggle to preview the sidebar above the main content.

Use default-sidebar-collapsed for uncontrolled initial state. When the sidebar toggle occupies the start of the content header, descendants receive --layout-sidebar-toggle-safe-inset (44px while collapsed, otherwise 0px) so host page-header components can reserve the correct title space without depending on layout internals.

Dark Mode CSS

The layout uses CSS variables that automatically adapt to dark mode. When dark mode is active, the following variables change:

/* Light mode (default) */
:root {
  --ui-bg-page: #ffffff;
  --ui-bg-card: #ffffff;
  --ui-text-primary: #303133;
  --ui-text-secondary: #606266;
  --ui-border-default: #dcdfe6;
}

/* Dark mode (automatically applied when theme="dark") */
html.dark {
  --ui-bg-page: #1a1a1a;
  --ui-bg-card: #2a2a2a;
  --ui-text-primary: #e5e5e5;
  --ui-text-secondary: #a0a0a0;
  --ui-border-default: #404040;
}

To customize dark mode colors for your content:

/* Your custom dark mode styles */
html.dark {
  --ui-bg-page: #0f0f0f;        /* Custom dark background */
  --ui-bg-card: #1f1f1f;        /* Custom dark card */
  --ui-text-primary: #ffffff;   /* Custom text color */
  --ui-text-secondary: #b0b0b0; /* Custom secondary text */
}

Available CSS Variables

主题颜色

/* 基础颜色 */
--ui-color-primary         /* 主色 */
--ui-color-success         /* 成功色 */
--ui-color-warning         /* 警告色 */
--ui-color-destructive     /* 危险色 */
--ui-color-info            /* 信息色 */

背景和前景色

/* 页面背景 */
--ui-bg-page               /* 页面背景色 */
--ui-bg-card               /* 卡片背景色 */
--ui-bg-muted              /* 次要背景色 */
--ui-bg-disabled           /* 禁用背景色 */
--ui-bg-overlay            /* 遮罩层背景色 */
--ui-bg-inverse            /* 反色背景色 */

/* 颜色变量（底层） */
--ui-color-background      /* 背景色 */
--ui-color-foreground      /* 前景色 */
--ui-color-card            /* 卡片背景色 */
--ui-color-card-foreground /* 卡片前景色 */
--ui-color-muted           /* 柔和背景色 */
--ui-color-accent          /* 强调色 */
--ui-color-overlay         /* 遮罩色 */
--ui-color-inverse         /* 反色 */
--ui-color-on-brand        /* 品牌色上的文字颜色 */

文字颜色

/* 文字颜色 */
--ui-text-primary          /* 主要文字 */
--ui-text-secondary        /* 次要文字 */
--ui-text-muted            /* 柔和文字 */
--ui-text-placeholder      /* 占位符文字 */
--ui-text-disabled         /* 禁用文字 */
--ui-text-on-brand         /* 品牌色上的文字 */

边框颜色

/* 边框颜色 */
--ui-border-default        /* 默认边框 */
--ui-border-soft           /* 柔和边框 */
--ui-border-strong         /* 强边框 */
--ui-ring                  /* 焦点环颜色 */

/* 颜色变量（底层） */
--ui-color-border          /* 边框色 */
--ui-color-border-soft     /* 柔和边框色 */
--ui-color-border-strong   /* 强边框色 */
--ui-color-ring            /* 焦点环颜色 */

顶部导航栏颜色

/* 顶部导航栏 */
--ui-topnav-bg                    /* 导航栏背景色 */
--ui-topnav-accent                /* 导航栏强调色 */
--ui-topnav-foreground            /* 导航栏前景色 */
--ui-topnav-muted                 /* 导航栏柔和文字 */
--ui-topnav-border                /* 导航栏边框 */
--ui-topnav-hover                 /* 悬停背景色 */
--ui-topnav-surface               /* 表面背景色 */
--ui-topnav-shadow                /* 导航栏阴影 */
--ui-topnav-active-bg             /* 激活状态背景色 */
--ui-topnav-active-fg             /* 激活状态文字色 */
--ui-avatar-bg                    /* 头像背景色 */
--ui-avatar-fg                    /* 头像前景色 */
--ui-avatar-border                /* 头像边框色 */

侧边栏颜色

/* 侧边栏 */
--ui-sidebar-bg                   /* 侧边栏背景色 */
--ui-sidebar-accent               /* 侧边栏强调色 */
--ui-sidebar-foreground           /* 侧边栏前景色 */
--ui-sidebar-border               /* 侧边栏边框 */
--ui-sidebar-active-bg            /* 激活项背景色 */
--ui-sidebar-active-fg            /* 激活项文字色 */
--ui-sidebar-hover-bg             /* 悬停背景色 */
--ui-sidebar-hover-fg             /* 悬停文字色 */
--ui-sidebar-width                /* 桌面侧边栏宽度，默认 14rem / 224px */

侧栏 hover 与 selected 分别映射到通用交互状态 token：

--ui-interactive-hover-bg
--ui-interactive-hover-fg
--ui-interactive-selected-bg
--ui-interactive-selected-fg

徽章颜色

/* 徽章背景色 */
--ui-badge-purple-bg              /* 紫色徽章背景 */
--ui-badge-purple-fg              /* 紫色徽章文字 */
--ui-badge-blue-bg                /* 蓝色徽章背景 */
--ui-badge-blue-fg                /* 蓝色徽章文字 */
--ui-badge-green-bg               /* 绿色徽章背景 */
--ui-badge-green-fg               /* 绿色徽章文字 */
--ui-badge-orange-bg              /* 橙色徽章背景 */
--ui-badge-orange-fg              /* 橙色徽章文字 */
--ui-badge-yellow-bg              /* 黄色徽章背景 */
--ui-badge-yellow-fg              /* 黄色徽章文字 */

表格颜色

/* 表格 */
--ui-table-header-bg              /* 表头背景色 */
--ui-table-row-bg                 /* 表格行背景色 */
--ui-table-row-alt-bg             /* 表格交替行背景色 */

登录页颜色

/* 登录页 */
--ui-login-page-bg                /* 登录页背景色 */
--ui-login-panel-bg               /* 登录面板背景色 */
--ui-login-panel-border           /* 登录面板边框 */
--ui-login-hero-overlay           /* 英雄区遮罩 */
--ui-login-feature-bg             /* 功能项背景色 */
--ui-login-feature-border         /* 功能项边框 */
--ui-login-feature-icon           /* 功能项图标颜色 */
--ui-login-action-bg              /* 操作按钮背景色 */
--ui-login-action-border          /* 操作按钮边框 */
--ui-login-action-text            /* 操作按钮文字 */
--ui-login-input-bg               /* 输入框背景色 */
--ui-login-input-border           /* 输入框边框 */
--ui-login-input-border-hover     /* 输入框悬停边框 */
--ui-login-input-placeholder      /* 输入框占位符 */
--ui-login-input-icon             /* 输入框图标颜色 */

字体

/* 字体 */
--ui-font-heading                 /* 标题字体 */
--ui-font-body                    /* 正文字体 */
--ui-font-mono                    /* 等宽字体 */

圆角

/* 圆角 */
--ui-radius-sm                    /* 小圆角 */
--ui-radius-control               /* 控件圆角 */
--ui-radius-card                  /* 卡片圆角 */
--ui-radius-modal                 /* 模态框圆角 */
--ui-radius-pill                  /* 胶囊圆角 */
--ui-body-radius                  /* 页面主体圆角 */

间距

/* 间距 */
--ui-space-inline                 /* 内联间距 */
--ui-space-control                /* 控件间距 */
--ui-space-card                   /* 卡片间距 */
--ui-space-section                /* 区块间距 */

阴影

/* 阴影 */
--ui-shadow-card                  /* 卡片阴影 */
--ui-shadow-pop                   /* 弹出层阴影 */

过渡动画

/* 过渡动画 */
--ui-transition-fast              /* 快速过渡 */
--ui-transition-base              /* 基础过渡 */

布局

/* 布局 */
--ui-layout-shell-bg              /* 布局壳背景渐变 */

AI Usage Guidelines

⚠️ Important for AI Code Generation:

When using Mamba Layout, DO NOT generate the following components as they are already provided by the <mamba-layout> element:

• ❌ Sidebar/Navigation Menu - The layout includes a built-in sidebar with navigation
• ❌ Top Header Bar - The layout includes a built-in header with logo and actions
• ❌ Layout Structure - Do not create flex/grid containers for overall page layout
• ❌ Theme Toggle Button - Dark mode is handled automatically by the layout

What to generate:

• ✅ Page Content Only - Place your actual page content inside <mamba-layout> tags
• ✅ Data Cards - Statistics cards, metric displays
• ✅ Charts & Visualizations - Data charts, graphs
• ✅ Tables - Data tables, lists
• ✅ Forms - Input forms, filters
• ✅ Custom Components - Any business-specific UI components

Example for AI Prompts:

Create a dashboard page with statistics cards and charts using Mamba Layout.
Only generate the page content that goes inside the <mamba-layout> element.
Do NOT create sidebar, header, or navigation as they are provided by the layout.

Correct Usage:

<mamba-layout>
  <!-- Only your page content here -->
  <div class="dashboard-content">
    <h1>Data Dashboard</h1>
    <div class="stats-grid">...</div>
    <div class="charts">...</div>
  </div>
</mamba-layout>

Incorrect Usage (what NOT to do):

<mamba-layout>
  <!-- ❌ Don't create your own sidebar -->
  <aside class="sidebar">...</aside>

  <!-- ❌ Don't create your own header -->
  <header class="top-bar">...</header>

  <!-- ❌ Don't create layout containers -->
  <div style="display: flex;">
    <main>...</main>
  </div>
</mamba-layout>