---
name: microi-ui
description: 用于构建或编写 Microi.UI / MCI-UI 文档，覆盖 Vue 3 网站、响应式站点、uni-app 移动端、主题色板、形态模式、高品质移动端界面、骨架屏、安全区、动效和 Microi 品牌前端组件。
---

# Microi.UI / MCI-UI

Microi.UI 是 Microi 产品共享前端设计系统。Vue 3 网站、响应式站点、H5 和 uni-app 移动端项目都应使用它。PC 后台页面仍可使用 Element Plus，但视觉变量、加载状态、空状态、动效和品牌色应与 `--mci-*` 变量保持一致。

当用户要求制作 Microi 移动端应用、H5、小程序、客户门户、员工端、会员中心、官网、产品站、活动页、仪表盘或报告页，且没有指定其它设计系统时，默认使用 Microi.UI。

这是自动规则。不要等用户明确说“遵循 `microi.skills/microi-ui/SKILL.md`”。只要仓库、需求、文件路径或项目上下文属于 Microi 生态，且工作涉及前端界面、网站界面、H5、uni-app、小程序、客户/员工/会员页面、报告、仪表盘或视觉打磨，就默认读取并应用本 skill。

## 核心承诺

Microi.UI 不只是组件集合，它是 AI 构建软件的视觉交付标准：

- 每个首屏都必须有明确视觉锚点。
- 每个页面都必须使用有品牌意识的色彩和组件层级。
- 每个重要操作都必须明显、美观且容易触达。
- 每个列表、详情、表单都应基于可复用场景模式构建，而不是复制一次性 CSS。
- 每个移动端页面都必须处理安全区、加载状态、按下反馈和底部操作。

## 内置设计模式

当需求只说“主流、高级、好看”时，先为页面确定一种主模式，再开始选组件和写样式：

| 主模式 | 首要目标 | 推荐组合 |
| --- | --- | --- |
| 品牌叙事 | 用单一观点和章节节奏建立记忆 | `MciPage + MciSection + MciButton` |
| 真实产品流程 | 让登录、创建、支付、权限、设置等任务完整可恢复 | `MciFormField + MciButton + MciDataState` |
| 趋势构图 | 用编辑式留白、字号和不对称栅格建立视觉张力 | `MciSection + MciCard + 项目级 mci-*` |
| 沉浸互动 | 用产品对象、Canvas/WebGL 或空间层次辅助理解 | `MciPage + MciHeroPanel + 静态降级资源` |
| 动态首屏 | 用 0—1200ms 时间线组织标题、说明和主操作 | `MciHeroPanel + MciButton + reduced-motion` |
| 数据工作台 | 优先异常、趋势、明细和筛选回显 | `MciMetricCard + MciFilterBar + MciDataState` |

- 一页只能有一个主模式，辅助能力最多两项；禁止把六种风格堆成拼盘。
- 先完成默认、加载、空、错误、禁用、权限、成功状态，再增加装饰和动效。
- 涉及完整产品设计时，读取 [设计模式库](../ui-design/references/design-pattern-library.md)；涉及登录、订阅、支付、权限、搜索和设置时读取 [产品流程配方](../ui-design/references/product-flow-recipes.md)；涉及动效、Canvas/WebGL、图片或视频时读取 [动效与媒体规范](../ui-design/references/motion-and-media.md)。
- 整站或长期维护项目必须在项目根目录维护 `MCI-DESIGN.md`，按 [设计契约规范](../ui-design/references/mci-design-contract.md) 描述 token、组件状态、动效、响应式和降级策略；可复制 [契约模板](../ui-design/assets/templates/MCI-DESIGN.md)。
- 设计契约必须同时包含“精确值”和“设计理由”：机器块保存语义 token、`{路径}` 引用与组件状态，说明章节保存用户任务、主情绪、具体视觉隐喻、选择理由和明确禁区。实现前先读理由，不能只读取色值。
- 契约固定核心章节顺序，检查重复/近似章节、错误类型、缺失/循环引用、主色与对比度、孤立 token、透明表面底色、状态覆盖和有意省略；契约差异与页面差异必须一起评审。
- [原创模式案例](../ui-design/assets/pattern-showcase/index.html) 只用于理解结构、状态和视觉差异，业务项目应替换为自己的信息架构和合法资产。

## 源码结构

- `Microi.UI/src/theme/tokens.css`：设计变量、色板、圆角、阴影、动效、移动端场景变量。
- `Microi.UI/src/theme/index.css`：基础类、页面壳、移动端高品质基础能力、骨架屏、动效、底部导航、富内容卡片、面板、表单选项。
- `Microi.UI/src/theme/runtime.js`：`initMciDesign`、`applyMciDesign`、`getMciDesign`、`toggleMciTheme`、`setMciTheme`、`setMciPalette`、`setMciShape`、`setMciMotion`。
- `Microi.UI/src/web`：Vue 3 Web 组件。
- `Microi.UI/src/uniapp`：uni-app Vue 3 组件。

## 默认要求

- 应用启动时调用 `initMciDesign()`，或提供等效的项目级主题服务。
- 支持 `theme: light | dark`、`palette: black | white | red | orange | yellow | green | cyan | blue | purple`、`shape: rounded | flat`、`motion: full | reduced`。
- Microi.UI 页面或嵌入式界面区域使用 `.mci-page` 或 `[data-mci-ui-root]` 包裹。
- 使用 `MciPage` 作为页面壳。移动端客户/员工/会员页面通常应使用 `premium`。
- 业务页面不要硬编码颜色、阴影、圆角、渐变或安全区间距。使用 `--mci-*` 变量或 `mci-*` 类。
- 只允许使用 `mci-` 前缀的公开共享类。不要引入外部 UI 库名称、复制来的类名，或 `.card`、`.list`、`button {}` 这类泛化全局选择器。
- 如果某个界面模式出现在两个及以上页面中，要抽取成 Microi.UI 组件或项目级 `mci-*` 封装。
- 动态页面首次加载必须显示骨架屏，不能只有 spinner，也不能过早显示空状态。
- 醒目按钮必须使用图标加文字，flex 居中，固定高度，具备加载态和按下反馈。
- `open-type="getPhoneNumber"` 这类小程序原生按钮必须样式化为 Microi 主按钮，并移除默认边框。
- API 请求头必须把 `OsClient` 作为单一运行期值传递，例如 `demo`，不得出现 `demo, demo` 这类重复值。
- `MciPage` 必须统一注入运行时安全区变量。微信小程序不能只使用 CSS `env()`；自定义导航页还必须读取胶囊矩形并为 `.mci-topbar` 预留右侧空间。
- 页面安全区验收以 `pages.json` 全路由为清单，至少覆盖 iPhone、Android 和微信开发者工具；首页、详情、表单、底部弹层及 fixed 操作栏必须全部通过。

## 组件选择

- `MciPage`：页面壳、安全区、动效、高品质移动端背景。
- `MciHeroPanel`：带品牌感的首屏/状态面板。
- `MciBottomNav`：自定义底部导航，支持图标、角标、激活态和可选凸起中间项。
- `MciButton`：主按钮、朴素按钮、金色按钮、冷色按钮、幽灵按钮。
- `MciCard`：通用内容容器。
- `MciCell`：设置、菜单、列表行。
- `MciSection`：主要分区。
- `MciTabs`：分段导航和内容切换。
- `MciMetricCard` / `MciAssetCard`：数字、资产、汇总。
- `MciOrderCard`：订单、工单、任务、维修申请。
- `MciActionBar`：安全区底部操作。
- `MciAvatar`：会员、客户、员工身份。
- `MciProductCard`：商品/内容网格。
- `MciFormField`：表单和数据录入。
- `MciFilterBar`：列表搜索/筛选区域。
- `MciModal`：弹窗和确认。
- `MciUploader`：图片/文件上传。
- `MciTimeline`：服务记录、维修进度、审批记录。
- `MciSteps`：流程和状态阶段。
- `MciSkeleton`：加载占位。
- `MciDataState`：空、错、成功状态。
- `MciRichText`：报告、文章、说明。

### 后台数据卡片

- 卡片模式按“身份 → 标题/状态 → 关键字段 → 时间/标签 → 操作”组织；无真实图片时使用 40—44px 紧凑标记，不使用大面积装饰字母占位。
- 无显式列数时桌面默认四列，显式业务列数优先；平板降为两至三列，移动单列。标题最多两行，数据卡不做营销海报式大图和多重炫光。
- 操作区只突出一个主动作，一至两个次动作，其余进入“更多”；危险动作降权，移动触控高度不小于 44px。
- 可点击整卡必须有 hover/focus/pressed、键盘 Enter/Space、可见焦点与内部控件事件隔离；骨架屏和最终卡片结构等高。

## 高品质移动端视觉标准

移动端应用必须像经过打磨的产品，而不是把后台表单硬塞进手机视口。

写页面局部 CSS 前，优先使用这些基础能力：

- `.mci-page--mobile-premium`
- `.mci-mobile-hero`
- `.mci-mobile-panel`
- `.mci-mobile-bubble-grid`
- `.mci-mobile-stat-grid`
- `.mci-mobile-titlebar`
- `.mci-mobile-chip-row`
- `.mci-mobile-bottom-nav`
- `.mci-mobile-rich-card`
- `.mci-mobile-meta-grid`
- `.mci-mobile-option-grid`
- `.mci-mobile-photo-grid`
- `.mci-mobile-sheet`
- `.mci-mobile-chart-card`
- `.mci-mobile-kpi-strip`
- `.mci-mobile-empty-result`

### 首屏规则

首屏必须展示以下任一视觉锚点：

- 带品牌感的首屏面板和 CTA
- 身份/会员头部
- 工作台状态卡
- 报告/状态总览
- 搜索加分类面板
- 图片主导的内容首屏
- KPI 仪表盘摘要

移动端页面不要只用平铺标题和普通列表开头。

### 层次规则

高品质移动端页面通常由以下层次组成：

1. 氛围背景或首屏
2. 悬浮快捷操作或统计面板
3. 带操作的标题栏
4. 富业务卡片
5. 底部导航或固定操作栏

避免单调堆叠相同白卡。

### 图标规则

底部导航、首页快捷操作、个人中心快捷项、九宫格操作、悬浮操作、空状态操作、设置/信息行、主题选项和主按钮必须使用可识别图标。`租`、`版`、`客`、`我` 这类单个汉字是占位，不是图标。

彩色圆形、胶囊或浮动快捷入口必须把“圆底色”和“图标色”作为一组主题 token 处理。红、绿、蓝、灰等深色底必须使用白色或高对比浅色图标；黄色、白色、浅灰底必须使用深色图标。主题覆盖不能只改背景不改 `color`，尤其要覆盖 `.mci-bubble:nth-child(n)`、`.entry:nth-child(n)` 这类更高优先级规则。

主题图标色覆盖必须有足够 CSS 优先级，并检查构建产物。若压缩器把同值 `color` 合并/移除，导致旧主题色胜出，可以对图标对比度兜底规则使用 `!important`，但不要把它扩散到普通布局样式。

### 动效规则

使用克制动效：页面入场、卡片错落出现、点击反馈、骨架屏流光、可选首屏闲置动效/高光。动效不能导致布局位移、文字裁切或操作干扰。尊重 `motion: reduced`。

## 移动端场景蓝图

### 登录/注册

- 除非业务明确有独立登录系统，否则不要强制用户切换角色。
- H5/App 登录通常应是一个账号或手机号 + 密码表单，不要把账号登录块和手机号登录块并列展示。
- 微信小程序登录默认使用 `<button open-type="getPhoneNumber">` 手机号授权；需要员工登录时，账号/密码兜底可以作为折叠或次级选项存在。
- Microi 账号登录要正确使用平台登录流程，不要调用不存在的方法。
- Microi 账号登录成功必须同时拿到成功码、有效 token 和有效用户 `Id`。token 可能在响应头，用户信息可能在响应体 `Data`；任一缺失都要清理本地会话并展示失败，不能留下“显示用户名但仍未登录”的半登录状态。
- 登录状态、头像姓名、角色文本、未登录提示和页面权限必须来自统一 session store。不要让单个页面直接读取旧 storage 显示用户名称。
- 微信小程序客户登录要支持手机号授权和注册/绑定。
- 登录页/个人中心不要向终端用户展示当前租户、OsClient、API host、移动端版本或调试元数据块。
- 使用顶部氛围加悬浮表单面板。
- 输入框要厚实、圆润、清晰，并成组呈现。
- 主登录、去登录、手机号登录按钮必须图标加文字，高对比，并在合适场景下满宽。
- 只有真实可用时才显示社交/快捷登录入口。

### 首页/工作台

- 首屏展示下一步操作：待处理订单、到期计划、报告、报修、审批或快捷操作。
- 使用 `MciHeroPanel` 或 `.mci-mobile-hero`。
- 使用带图标的悬浮快捷操作。
- 使用指标卡展示数量和状态。
- 使用富卡片展示近期任务或报告。
- 首屏文字必须适配 375px 和 430px 宽度。出现难看换行前，先减小标题字号。
- 悬浮面板不得覆盖首屏按钮。

### 个人中心/我的

- 使用身份头部，包含头像、姓名、角色/客户、状态和至少一个视觉徽章。
- 未登录时不得展示旧缓存用户名；头像、姓名和状态必须同时回到未登录态。
- 使用两个以上高亮快捷卡或服务宫格。
- 设置项和业务入口要分组成面板。
- 主题切换可以放在这里；如果未登录也能访问个人中心，则登录前也必须可用。
- 设置/信息行必须使用真实图标。租户、版本、主题或账号入口不要用单字徽章当图标。
- 公司简介、关于我们、资质介绍等内容如果不是页面主内容，在个人中心只放一个紧凑图标 + 标题 + 简短说明的导航项，点击进入详情。不要在“我的”首页直接铺大标题、摘要和预览图，避免和身份卡、主题、快捷入口抢视觉层级。
- 除非产品明确是极简工具型，否则不要把个人中心渲染成纯列表。

### 主题选项

- 如果客户在已接受旧设计后要求新视觉风格，除非用户明确要求移除，否则要把旧设计保留为一个命名主题。
- 主题名称应描述视觉意图，例如 `清新绿红`、`品牌经典`、`专业深色`。
- 如果产品定义默认主题，主题运行时的默认值必须与之匹配；用户切换过后优先读取本地持久化主题，不能启动后强行覆盖用户选择。
- 持久化已选主题，并应用到页面根、固定底部导航、按钮、卡片、空状态、骨架屏、加载过渡、表单、报告详情和 H5 桌面手机壳。
- uni-app 和微信小程序不能只依赖 `document.documentElement`；小程序端要通过项目级主题服务在每个页面根绑定主题类或变量。H5 端优先把主题写到 `html/body` 的属性、class 和 CSS 变量，再让页面、`uni-page-body` 与 fixed 组件继承变量。
- H5 uni-app 不要用 `querySelectorAll('.mci-page')`、`MutationObserver` 或延迟扫描去修改 `.mci-page`、`uni-page-body`、`uni-page`、`RouterView` 下的 class；这些节点由 Vue/uni 管理，运行中改 class 可能导致 `Cannot assign to read only property '_'`、`Cannot read properties of null (reading 'type')`、`parentNode` 或 `scheduler flush` 错误。
- 固定底部导航、固定提交栏、悬浮操作条等 fixed 组件在 H5 中优先使用 `--mci-*` 变量，不要为了换主题让组件自己订阅 store 并动态切换根 class；小程序端可以绑定稳定主题 class，但要避免主题切换时改变路由根节点结构。
- 个人中心/设置页上的主题切换应是紧凑操作，打开底部面板或弹窗。除非页面明确是完整设置页，否则不要把所有主题选项直接渲染在个人中心首页。
- H5 uni-app 主题切换不能破坏路由补丁。如果切主题后导航出现 `parentNode`、`scheduler flush`、`updateSlots`、`read only property '_'` 或 `null (reading 'type')` 错误，先停止改写 Vue/uni 托管节点，保持页面 class 稳定，并改为 `html/body` 变量驱动。
- 切换主题后，底部导航仍必须正常路由。要拦截当前路由点击、对重复点击防抖，并在必要时短暂延迟导航。
- 每个命名主题都要对 `pages.json` 中每个路由截图。快捷卡片、报告卡片、报告详情、骨架屏、加载过渡、空状态、弹窗和底部导航中的文字必须保持高对比。

### 列表

- 移动端列表应使用业务卡片，而不是表格式行。
- 每张卡片需要标题、状态胶囊、关键元数据、时间和主操作。
- 数据类型不同的列表上方要增加筛选/搜索/标签。
- 加载时使用骨架卡片，空数据时使用有意义的空状态。
- 长标题和元数据要有意截断或换行，不能撑坏卡片高度。

### 详情/报告

- 从概览首屏/状态块开始。
- 然后展示事实信息、时间线/步骤、媒体、富报告内容和操作区。
- 重要状态必须无需滚动即可看到。
- 报告应使用 `MciRichText`、可读行高、图片最大宽度，以及分享/阅读/确认操作。
- 报告详情的封面、英文标识（如 `INSPECTION REPORT`）、状态胶囊、印章/水印、摘要卡和正文容器必须全部使用主题变量，不能把浅色文字固定在浅色背景上。
- 如果页面预期有操作，使用 `MciActionBar` 或固定安全区提交栏。
- 从列表到详情要保留查看者身份：员工报告卡打开员工鉴权详情数据，客户卡片打开 CustomerToken 详情数据，分享链接打开 ShareToken 详情数据。不要让已登录用户点击本来可见的卡片后被重定向到登录。

### 表单/上传

- 使用带小图标标记的分区标题。
- 使用大而清爽的输入区域和足够垂直间距。
- 重要选项使用彩色选项胶囊或选项卡片。
- 上传区域必须支持重新选择/替换、预览、关闭预览、进度、重试和失败提示。
- 长表单需要固定安全区提交栏。

### 底部导航

- 当原生 tabbar 限制视觉质量或造成运行时问题时，优先使用 `MciBottomNav`。
- 必须包含图标、文字、激活态和稳定点击区域。
- 创建、扫码、报修、报告等操作允许使用凸起中间按钮。
- 不要使用纯文字导航。

### 弹窗/底部面板/对话框

- 使用暗色遮罩、明确的面板圆角、底部面板拖拽线和紧凑操作层级。
- 底部面板不应在没有确认的情况下遮住不可逆操作。
- 确认对话框应显示清晰图标/状态和一个主操作。

### 图表/仪表盘

- 数字优先于图表。
- 首屏使用 2-4 个高信号指标。
- 使用少量配色，不要把每张图都做成彩虹。
- 密集仪表盘应选择清爽浅色分析风格或深色指挥中心风格，不要随意混搭。

### 消息/社交/资讯

- 消息需要头像/图标、类型、标题、摘要、时间、未读标记，以及必要操作。
- 社交/内容流需要稳定媒体比例、作者身份、标签和互动操作。
- 资讯/内容页需要分类标签、首屏或精选故事，以及可读卡片。

### 商城/活动

- 使用图片主导卡片、价格/状态锚点、促销标签和底部购买/操作区。
- 购物车/订单页需要可见选择状态、数量控件、合计和固定结算栏。
- 活动页需要活动首屏、进度/状态、奖励/操作面板和规则面板。

## 网站/PC 站标准

- 构建真实产品/站点体验，不要做通用落地页外壳。
- 首屏必须让品牌、产品、地点或对象足够明确。
- 落地页首屏在合适时使用真实/生成位图或沉浸式互动场景，不要只依赖装饰渐变。
- 首屏文字不要放在卡片里。
- SaaS/CRM/运营站点应安静、密集、易扫读、聚焦工作。
- 产品/场馆/作品集站点可以更视觉化，但主要对象必须可检查。
- 写页面局部 CSS 前优先使用 `MciHeroPanel`、`MciSection`、`MciCard`、`MciMetricCard` 和 `MciButton`。

## 后台菜单配套

创建 Microi 低代码系统时，后台菜单不应全部是一层菜单。真实系统至少使用两级：

- 客户中心：客户、联系人、绑定。
- 资产/设备中心：设备、资产。
- 运营中心：计划、订单、记录、报修。
- 报告中心：报告、阅读日志。
- 系统/配置中心：字典、设置、模板。

移动端信息架构在可行时应与这些业务域匹配。

## AI 实施清单

- Microi 前端、网站、H5、uni-app、小程序、客户门户、员工端、会员中心、仪表盘、报告、活动和视觉重设计任务要自动识别本 skill。
- 设计界面前读取本 skill 和 `microi.skills/ui-design/SKILL.md`。
- 写页面前检查 logo/品牌色，并推导色板。
- 先选场景蓝图，再选组件，最后写 CSS。
- 优先使用 Microi.UI 组件或项目级 `mci-*` 封装，而不是直接套第三方视觉样式。
- 当可复用模式跨项目出现时，更新 `Microi.UI`。
- 当 Microi.UI 行为或标准变化时，更新 `microi.doc/docs/doc/system-engine/microi-ui.md`。
- 可行时用 `npm run check`、`npm run pack:check` 和文档构建验证。
- 对 UI/前端工作，只要有浏览器/H5/devtools 目标，就使用截图视觉验证。
- 对命名主题，在每个主题下截图验证所有 `pages.json` 路由，并在切换主题再导航后检查控制台日志。
- 使用真实账号登录后截图验证“我的”页姓名、角色和状态一致；不得出现缓存用户名和“未登录”同时存在。
- 截图必须包含底部导航和首页快捷入口，确认容器背景、选中态、未选中态、圆形图标底色和内部图标色都随主题变化且高对比。
- 移动端页面检查 375px 和 430px 宽度。
- 检查首屏标题换行、操作可见性、悬浮面板重叠、底部导航图标、空状态、表单提交栏和按钮居中。
- 检查未登录/未授权提示卡片是否在 header 与 tabBar/底栏之间的可用内容区上下左右居中，不能贴在顶部。

## 禁止输出

- Microi.UI 文件或文档内不得出现外部 UI 库身份或复制来的类名前缀。
- 不得使用纯文字底部导航。
- 设置/个人中心/主题/信息入口不得使用单字假图标。
- 不得使用泛化全局 CSS 选择器。
- 不得出现重复 `OsClient` 请求头值。
- 不得让未登录/授权提示只贴在 header 下方；它必须在剩余可用区域居中。
- 不得调用未定义的登录接口。
- 不得把缺 token 或缺用户 `Id` 的返回当作登录成功，也不得留下半登录缓存。
- 除非明确要求，一个登录页不得同时展示重复登录系统。
- 不得向用户展示当前租户、API host 或移动端版本调试块。
- 不得做只影响单页、导航或重启后消失的主题切换。
- 当“切换按钮 + 面板/弹窗”更清爽时，不得在个人中心页内联堆出所有主题选项。
- 不得在个人中心把公司简介/关于我们做成大资讯卡，除非该页面明确是资讯流或品牌介绍页。
- 主题切换不得在底部导航后造成 uni-app 路由/scheduler 错误。
- 报告/列表详情路由不得丢失员工/客户/分享鉴权上下文，并把可见项目重定向到登录。
- 业务系统后台菜单不得全部规划为一级菜单。
- 面向客户/员工的产品页面不得只有普通列表、普通按钮且没有视觉锚点。