# Miao Design

> Miao Design 是一个基于 Vue 3 + TypeScript 的轻量级组件库，提供 26 个高质量组件、完整类型定义与配套设计变量，开箱即用。

Miao Design 的文档站为 AI 智能体提供了三种读取方式：

- 本文件（`llms.txt`）：全站索引，先看这里定位页面，再按链接取单页 Markdown。
- 单页 Markdown：把下面任意链接直接 fetch 下来即可，内容是纯净 Markdown（演示代码块已展开为完整 Vue SFC）。
- `llms-full.txt`：全站合一的单文件版本，适合一次性投喂。

约定：组件名为 `M` 前缀（如 `MButton`），全局注册后可省略 import；样式需引入 `miao-design/style.css`；主题令牌统一为 `--m-<name>` 形式的 CSS 自定义属性。

## 概览

- [Miao Design](https://tongmingwang.github.io/miao-design/md/index.md): Miao Design 是面向 Vue 3 的轻量级组件库：26 个打磨过的组件、完整 TypeScript 类型、设计变量驱动的主题系统与内置深色模式，安装即用，无需额外配置。

## 指南

- [介绍](https://tongmingwang.github.io/miao-design/md/guide/index.md): Miao Design 是基于 Vue 3 + TypeScript 的轻量级组件库，提供 26 个组件、完整类型定义、设计变量驱动的主题系统与内置深色模式。
- [快速开始](https://tongmingwang.github.io/miao-design/md/guide/getting-started.md): 安装 miao-design 并在 Vue 3 项目中引入：完整注册、按需引入、v-ripple 指令、编程式 toast、UMD 引入方式与 TypeScript 配置。
- [主题定制](https://tongmingwang.github.io/miao-design/md/guide/theme.md): Miao Design 的主题令牌体系：语义色、中性色、背景、形状、阴影、缓动、zIndex 与控件尺寸，以及深色模式与组件级变量。
- [图标检索](https://tongmingwang.github.io/miao-design/md/guide/icons.md): MIcon 图标组件用法与全量图标检索工具，数据来自 @mdi/js 的 7000+ Material Design Icons，支持尺寸、颜色、翻转、旋转与自旋。
- [AI 阅读](https://tongmingwang.github.io/miao-design/md/guide/ai.md): 用 llms.txt、llms-full.txt 与每页 Markdown 原文，把 Miao Design 的完整文档以最省 token 的方式投喂给 AI 编程助手。
- [常见问题](https://tongmingwang.github.io/miao-design/md/guide/faq.md): Miao Design 高频踩坑点：样式不生效、弹层被裁剪、组内子组件必须传 value、Divider 默认纵向、Button 点击节流、DatePicker 的 format 语义等。

## 组件

- [组件总览](https://tongmingwang.github.io/miao-design/md/components/index.md): Miao Design 全部组件与 v-ripple 指令的实时预览与文档入口，按通用、表单、数据展示、反馈与弹层、指令五个分组排列。
- [Button 按钮](https://tongmingwang.github.io/miao-design/md/components/button.md): MButton 按钮组件，六种语义色、五种外观变体、四种尺寸，支持加载态、节流点击、圆角与块级布局，内置 Material 涟漪反馈。
- [ButtonGroup 按钮组](https://tongmingwang.github.io/miao-design/md/components/button-group.md): MButtonGroup 按钮组容器，把多个 MButton 拼成整体并统一下发 variant、color、size 与 disabled 上下文，子按钮的变体与尺寸由组接管，颜色子优先、禁用取并集。
- [Icon 图标](https://tongmingwang.github.io/miao-design/md/components/icon.md): MIcon 图标组件，接收 @mdi/js 的 24x24 SVG path 字符串，支持数字或 CSS 单位的尺寸、六种语义色、禁用态、水平/垂直翻转、任意角度旋转与自旋动画。
- [Divider 分割线](https://tongmingwang.github.io/miao-design/md/components/divider.md): MDivider 分割线组件，通过 vertical 在纵向与横向之间切换，颜色、粗细与间距分别由 color、size、gap 下发的 CSS 变量控制。
- [Fab 悬浮按钮](https://tongmingwang.github.io/miao-design/md/components/fab.md): MFab 悬浮操作按钮，六种语义色与 small/medium/large 三档尺寸，可在扩展模式下把图标与文字拼成胶囊，支持四个视口角落的 fixed 定位、禁用态与内置涟漪。
- [Input 输入框](https://tongmingwang.github.io/miao-design/md/components/input.md): MInput 文本输入框，对齐 MUI OutlinedInput 的描边风格，支持前后缀插槽、一键清除、原生 maxlength 字数限制、只读与禁用状态，尺寸与圆角均可覆盖。
- [InputNumber 数字输入框](https://tongmingwang.github.io/miao-design/md/components/input-number.md): MInputNumber 数字输入框，基于 MUI OutlinedInput 结构，支持步进按钮、min/max 收敛、精度归一化、键盘上下键调节与一键清空，空值统一以 null 抛出。
- [Select 选择器](https://tongmingwang.github.io/miao-design/md/components/select.md): MSelect 下拉选择器，由 options 数据驱动，支持单选与多选、图标、清空、键盘导航，面板可 Teleport 或内联，宽度随内容自适应并带视口夹紧与跟随滚动。
- [Checkbox 复选框](https://tongmingwang.github.io/miao-design/md/components/checkbox.md): MCheckbox 复选框与 MCheckboxGroup 复选框组。独立使用时用 boolean v-model，放进组内改用 value 与数组联动，支持半选态、禁用、六种颜色与三档尺寸。
- [Radio 单选框](https://tongmingwang.github.io/miao-design/md/components/radio.md): MRadio 单选框与 MRadioGroup 单选框组。独立使用时用 boolean v-model，组内改用 value 与组激活值比对实现互斥，支持禁用、name 继承、六种颜色与三档尺寸。
- [RadioButtonGroup 按钮单选](https://tongmingwang.github.io/miao-design/md/components/radio-button-group.md): MRadioButtonGroup 按钮单选组，由 options 数组驱动、不依赖 MRadio，把若干选项拼成等宽或自适应的分段控件，支持图标、纵向排列、语义色与尺寸，适用于视图切换等场景。
- [Switch 开关](https://tongmingwang.github.io/miao-design/md/components/switch.md): MSwitch 开关组件，基于原生 checkbox 保留表单与键盘可访问性，支持六种语义色、三种尺寸、禁用与加载态，可选右侧标签插槽。
- [Slider 滑块](https://tongmingwang.github.io/miao-design/md/components/slider.md): MSlider 滑块组件，横向 / 纵向拖动取值，支持步进、数值气泡、六种语义色与三档尺寸，轨道粗细与拇指直径可单独覆盖，拖动中经 rAF 合帧。
- [DatePicker 日期选择](https://tongmingwang.github.io/miao-design/md/components/date-picker.md): MDatePicker 日期 / 日期时间选择器，format 模板决定是否启用时间面板，支持年 / 月快捷面板、min/max 限制、清除、三档尺寸与触发区 / 面板圆角定制。
- [DateRangePicker 日期范围](https://tongmingwang.github.io/miao-design/md/components/date-range-picker.md): MDateRangePicker 日期范围选择器，双月并排展示并支持悬停预览，format 决定是否启用时间选择，支持 min/max 约束、清除、三档尺寸与触发区 / 面板圆角定制。
- [ColorPicker 颜色选择](https://tongmingwang.github.io/miao-design/md/components/color-picker.md): MColorPicker 颜色选择器，色板拖动 + 色相条 + 可选透明度，支持 HEX 与 RGB 输入、预设色、清除与三档尺寸，面板自动翻转定位。
- [Avatar 头像](https://tongmingwang.github.io/miao-design/md/components/avatar.md): MAvatar 头像组件，支持图片与自动回退：加载失败时依次回退到默认插槽、alt 首字符与内置人形占位。提供三种预设尺寸加任意像素尺寸、三种形状与六种语义色。
- [Progress 进度条](https://tongmingwang.github.io/miao-design/md/components/progress.md): MProgress 进度指示器，提供线性与环形两种形态，determinate / indeterminate / buffer 三种变体，六种语义色，可自定义环形直径与描边厚度。
- [Tooltip 文字提示](https://tongmingwang.github.io/miao-design/md/components/tooltip.md): MTooltip 浮层提示，支持 hover、click、focus 三种触发方式与 12 种方位，空间不足自动翻转并夹紧视口，可设置开合延迟、禁用与受控显示。
- [Alert 警告提示](https://tongmingwang.github.io/miao-design/md/components/alert.md): MAlert 语义化提示条，四种严重级别搭配浅底、实底、描边三种外观，支持标题、自定义图标插槽与可关闭，关闭时带离场动画。
- [Tabs 标签页](https://tongmingwang.github.io/miao-design/md/components/tabs.md): Miao Design 标签页由 MTabs 横向标签栏、MVTabs 纵向标签栏、MTabPanes 内容区与 MTabPane 面板组成。标签栏为纯 items 数据驱动，二者靠共享 v-model 联动，仅激活面板挂载 DOM 并带方向偏移动画。
- [Nav 导航](https://tongmingwang.github.io/miao-design/md/components/nav.md): MNav 导航栏，由 items 数组驱动，支持纵向侧栏与横向底栏、图标、数字徽标与红点、三档尺寸、六种语义色，激活块带滑动动画与键盘方向键导航。
- [Dialog 对话框](https://tongmingwang.github.io/miao-design/md/components/dialog.md): MDialog 模态对话框，从 #trigger 触发元素或 anchor 指定位置 Morph 展开，支持自定义宽度与圆角、遮罩与 Esc 关闭开关、全屏模式与背景滚动锁定，进入时按先形后字两段动画播放。
- [Drawer 抽屉](https://tongmingwang.github.io/miao-design/md/components/drawer.md): MDrawer 抽屉面板，支持左 / 右 / 上 / 下四个方向滑出，可配置尺寸、标题与底部插槽、遮罩与 Esc 关闭开关，打开时锁定页面滚动，内容超出在正文区内部滚动。
- [Dropdown 下拉菜单](https://tongmingwang.github.io/miao-design/md/components/dropdown.md): MDropdown 下拉菜单容器与 MDropdownItem 菜单项，支持点击 / 悬停触发、六种弹出位置、键盘导航与禁用项，子项点击后自动抛 command 并收起菜单，菜单超过 320px 时内部滚动。
- [Toast 轻提示](https://tongmingwang.github.io/miao-design/md/components/toast.md): Toast 轻提示提供声明式 MToast 组件与编程式 toast.success() 两套用法，五种语义类型、六个角位堆叠、自动关闭与可关闭按钮，正文支持任意插槽内容，容器按需懒挂载。
- [v-ripple 涟漪](https://tongmingwang.github.io/miao-design/md/components/ripple.md): v-ripple 是 Miao Design 提供的全局指令，给任意元素加上 Material 风格的水波纹按下反馈，可配置颜色、时长、起始缩放与是否从中心扩散，并支持触摸延迟与键盘涟漪。

## 可选

- [完整文档（单文件）](https://tongmingwang.github.io/miao-design/llms-full.txt): 全站所有页面合并为一个 Markdown 文件，建议只在需要通读时使用。
- [sitemap.xml](https://tongmingwang.github.io/miao-design/sitemap.xml): 全部页面 URL 列表。