# 介绍

Miao Design 是一个基于 **Vue 3 + TypeScript** 的轻量级组件库，面向中后台系统、桌面应用与工具类产品。它不追求组件数量，而是把常用的那批组件做扎实：样式基于 MUI 的调色板、阴影、缓动曲线与尺寸令牌，交互细节对齐 Material Design。

## 设计原则

**令牌先行。** 所有视觉表现都落在 `--m-*` CSS 自定义属性上。换主题、调品牌色、改圆角，只需要覆写一层变量，不必碰组件源码，也不会有样式优先级战争。

**零运行时依赖。** `miao-design` 的 `dependencies` 是空的，`vue@^3.5` 只作为 peerDependency。产物直接由业务侧的打包器处理，不会平白多出一棵依赖树。

**组合优于配置。** 需要父子配合的组件（`MCheckboxGroup` / `MRadioGroup` / `MDropdown` / `MTabPanes`）用 `provide / inject` 传递上下文，父组件只负责状态与事件，子组件只管渲染，不引入额外的配置对象。

**类型即文档。** 每个组件的 props / events / slots 都由 TypeScript 描述并随包发布 `.d.ts`，IDE 里的自动补全就是最准确的文档。

## 组件一览

**26 个组件**与 `v-ripple` 指令，按用途分为五组：

| 分组 | 组件 |
| --- | --- |
| 通用 | `MButton`、`MButtonGroup`、`MIcon`、`MDivider`、`MFab` |
| 表单 | `MInput`、`MInputNumber`、`MSelect`、`MCheckbox` / `MCheckboxGroup`、`MRadio` / `MRadioGroup`、`MRadioButtonGroup`、`MSwitch`、`MSlider`、`MDatePicker`、`MDateRangePicker`、`MColorPicker` |
| 数据展示 | `MAvatar`、`MProgress`、`MTooltip`、`MAlert`、`MTabs` / `MVTabs` / `MTabPanes` / `MTabPane`、`MNav` |
| 反馈与弹层 | `MDialog`、`MDrawer`、`MDropdown` / `MDropdownItem`、`MToast` |
| 指令 | `v-ripple` |

::: tip 26 个「组件」和 32 个「标签」不是一回事
上表按**功能单元**计数：像 `MTabs` / `MVTabs` / `MTabPanes` / `MTabPane` 这类必须配套使用的，算作一个组件。
`app.use(MiaoDesign)` 实际注册的**全局标签是 32 个**（外加 `v-ripple` 指令），因为复选框组、单选框组、下拉项、标签内容区、纵向标签栏等子组件也各自占一个名字。
:::

另有编程式 API `toast`（`toast.success()` 等）与底层函数 `showToast`。

前往[组件总览](/components/)可以看到每个组件的实时预览。

## 兼容性

| 项目 | 版本要求 |
| --- | --- |
| Vue | `^3.5.0`（peerDependency） |
| 包格式 | ESM（`miao-design.js`）+ CJS（`miao-design.umd.cjs`） |
| 浏览器 | 支持原生 CSS 自定义属性与 ES2018 的现代浏览器（Chrome / Edge 79+、Safari 14+、Firefox 78+） |
| 无需构建工具 | 支持直接以 UMD 方式在浏览器中引入 |

## 下一步

- [快速开始](/guide/getting-started) —— 安装、引入与第一个组件。
- [主题定制](/guide/theme) —— 覆写设计令牌、接入深色模式。
- [AI 阅读](/guide/ai) —— 让 AI 助手直接读懂整份文档并生成正确代码。