常见问题
下面是使用时最容易踩到的点，也建议把这一页一并投喂给 AI 助手。
组件没有任何样式
组件库的样式是独立文件，必须显式引入一次：
import 'miao-design/style.css'只写 import MiaoDesign from 'miao-design' 不会带出样式。样式文件里同时包含全部 --m-* 设计令牌，漏引会导致颜色、圆角、阴影全部失效。
换了主题色但组件没变
先确认覆写的是组件库的令牌名（--m-*），而不是你自己项目的变量：
:root {
--m-primary: #0f766e; /* ✅ 组件库认这个 */
--primary-color: #0f766e; /* ❌ 没有组件会读它 */
}另外要注意 CSS 的加载顺序：覆写规则要在 miao-design/style.css 之后生效，否则会被原值覆盖。
弹层被父容器裁剪 / 层级不对
下拉菜单、日期面板、Tooltip 这类浮层都有明确的层级令牌，遇到被 overflow: hidden 裁剪时，检查父链路里有没有设置 transform / filter / contain，它们会创建新的层叠上下文：
| 令牌 | 值 | 用途 |
|---|---|---|
--m-z-modal | 1300 | Dialog / Drawer |
--m-z-menu | 1301 | 下拉面板 |
--m-z-tooltip | 1500 | Tooltip |
--m-z-toast | 1600 | Toast |
MDivider 默认是纵向的
vertical 的默认值是 true，所以 <MDivider /> 渲染出来是一条纵线（高度 100%）。要水平分割线必须显式关闭：
<MDivider :vertical="false" gap="12px" />另外 width / height 两个 prop 虽然在类型里存在，但实现中没有被引用，改宽度请用外层容器或样式覆盖。
组件放进 Group 之后就不生效了
MCheckbox、MRadio 在组内会改由父组件管理状态：
- 必须传
value，否则会以undefined参与比对，选中判断出错； - 组内子组件自身不再抛出
update:modelValue/change，这些事件由父组件（MCheckboxGroup/MRadioGroup）统一抛出； - 组内子组件的
modelValue会被忽略。
<MCheckboxGroup v-model="picked">
<MCheckbox value="a">选项 A</MCheckbox>
<MCheckbox value="b">选项 B</MCheckbox>
</MCheckboxGroup>MTabs 里放不下 MTabPane
MTabs / MVTabs 是纯标签栏，由 items 数组驱动，不收集子组件。标签栏与内容区是两个平级组件，靠绑定同一个 v-model 联动：
<script setup>
const active = ref('a')
</script>
<template>
<MTabs v-model="active" :items="[{ name: 'a', label: 'A' }, { name: 'b', label: 'B' }]" />
<MTabPanes v-model="active">
<MTabPane name="a">内容 A</MTabPane>
<MTabPane name="b">内容 B</MTabPane>
</MTabPanes>
</template>MTabPanes ↔ MTabPane 之间才是父子关系（通过 provide / inject 注册面板）。
按钮点击偶尔不响应
MButton 的点击默认有 200ms 节流，连点会被丢弃。需要每次都响应时显式关闭：
<MButton :throttle="0" @click="onClick">立即响应</MButton>MButton.loading 或 disabled 时按钮处于原生 disabled 状态，click 不会触发，这是预期行为。
MButtonGroup 里的按钮外观不受自己控制
放进 MButtonGroup 后：
variant与size会被组的设置覆盖（组没传 size 时也会写成default）；color是「子优先」——子组件自己设了就用子的，没设才取组值；disabled取父子并集。
DatePicker 什么时候会变成「日期时间」选择器
取决于 format 字符串里是否包含时间片段（大小写敏感）：
format | 结果 |
|---|---|
YYYY-MM-DD | 纯日期，点选即关闭面板 |
YYYY-MM-DD HH:mm | 日期 + 时间，点选日期不关闭，需点「确定」 |
YYYY-MM-DD HH:mm:ss | 日期 + 时 / 分 / 秒 |
Toast 只弹出一次 / 被宿主容器影响
toast 是模块级单例，容器在首次调用时才懒挂载到 document.body。因此在 SSR 场景下不要在模块顶层调用它，放到用户交互里：
// ❌ SSR 环境会在服务端执行
toast.success('欢迎回来')
// ✅
function onMountedClick() {
toast.success('欢迎回来')
}移到暗色模式后颜色很怪
组件库的暗色不是把浅色简单压暗：语义色会换成 MUI dark palette 的取值（--m-primary 由 #1976d2 变为 #90caf9），-contrast 变成深色文字，阴影 alpha 加重。业务样式里不要硬编码浅色态的具体色值，始终引用 --m-* 变量。