吾码UI（Microi.UI / MCI-UI）

Microi Design System

让每一个吾码前端项目，都有统一、先进、可持续的视觉底座。

吾码UI（Microi.UI / MCI-UI）面向 Vue 3 PC 网站、响应式网站、移动端 H5、uni-app 项目， 提供品牌 token、主题运行时、跨端基础组件、骨架屏、安全区、动效和 AI 生成规范。

快速接入组件预览设计模式AI 开发规则

Microi.UI Runtime

light / darkrounded / flatskeleton / safe-area / motion

01

统一品牌

通过 --mci-* token 收束颜色、阴影、圆角、间距、骨架屏和动效。

02

AI 可复用

AI 不再临时写散装 CSS，而是默认使用 MCI-UI 组件与项目级 mci-* 封装。

03

跨端一致

同一套主题能力覆盖 PC 网站、企业站、产品站、移动端商城和 uni-app。

04

商业级扩展

第三方库继续负责复杂能力，最终视觉由吾码UI统一承载。

设计系统定位

Why Microi.UI

吾码UI不是重复造组件，而是统一产品气质、AI产出和商业交付标准。

Microi.UI 主要服务官网、企业站、产品站、文档站、移动端应用、会员中心、活动页、独立 Web 应用等非后台管理系统场景。 PC 后台管理系统仍然以 Element Plus 为主，但主题变量、骨架屏、动效密度和品牌识别也应该逐步向 --mci-* 对齐。

统一品牌颜色、阴影、圆角、动效、骨架屏全部收束到 token。

AI稳定生成页面、按钮、卡片、富文本、数据状态都有固定组件答案。

跨端一致Vue 3 Web、响应式网站、uni-app/H5 使用同一套设计语言。

主题能力

Theme Runtime

主题切换是内建能力，不是项目后期补丁。

所有移动端和 PC 网站项目默认支持明暗模式、九套主色、圆角/扁平形态和动效偏好。白色与黄色主色必须使用 --mci-text-on-primary，避免文字对比度不足。

light / dark明暗模式

black / white极简与高端企业感

red / orange / yellow品牌、活动、会员权益

green / cyan / blue健康、科技、企业服务

purpleAI、创意、数字产品

rounded / flat圆角与扁平都保留层次

工程结构

Microi.UI/src/theme/tokens.csssrc/theme/index.csssrc/theme/runtime.jssrc/web/componentssrc/uniapp/components

Source Layout

主题、Web、UniApp 三层分离，业务页面只消费稳定出口。

src/theme 是品牌 token 源头，src/web 服务 PC/响应式网站，src/uniapp 服务移动端项目。新增组件必须双端优先，颜色、圆角、阴影和安全区都走 --mci-* 变量。

快速接入

Vue 3 Web

import { createApp } from 'vue';
import MciUI, { initMciDesign } from '@microi/mci-ui/web';
import '@microi/mci-ui/theme';
initMciDesign({ theme: 'light', palette: 'red', shape: 'rounded', motion: 'full' });
createApp(App).use(MciUI).mount('#app');

uni-app

import { createSSRApp } from 'vue';
import App from './App.vue';
import MciUI, { initMciDesign } from '@/mci-ui/uniapp/index.js';
import '@/mci-ui/theme/index.css';
export function createApp() {
  const app = createSSRApp(App);
  initMciDesign({ theme: 'light', palette: 'red', shape: 'rounded' });
  app.use(MciUI);
  return { app };
}

主题运行时

Runtime API

一次初始化，统一控制主题、主色、形态和动效。

运行时会写入本地存储，并在支持 DOM 的环境中设置 data-theme、data-mci-palette、data-mci-shape、data-mci-motion。

import { initMciDesign, setMciTheme, setMciPalette, setMciShape, setMciMotion, toggleMciTheme } from '@microi/mci-ui/runtime';
initMciDesign({ theme: 'light', palette: 'red', shape: 'rounded', motion: 'full' });
setMciTheme('dark');
setMciPalette('blue');
setMciShape('flat');
setMciMotion('reduced');
toggleMciTheme();

样式隔离

Style Guard

吾码UI必须在复杂项目里保持自己的视觉边界。

官网、文档站、企业站、移动端应用经常混用第三方 UI、Markdown、富文本和项目老 CSS。MCI-UI 通过命名空间、根容器、token 和主题层收口，尽量避免样式被其它组件覆盖。

根容器页面或局部 UI 使用 .mci-page 或 data-mci-ui-root 包裹。

命名空间共享类名统一 mci- 前缀，不写泛化 button、.card、img。

token 收口颜色、圆角、阴影、间距通过 --mci-* 控制，不直接改库内部样式。

主题层官网/文档站使用 VitePress theme 层统一美化，避免每篇文档散装 CSS。

组件预览

下面是按吾码UI设计 token 绘制的组件截图式预览。真实项目中组件会使用同一套 --mci-* 变量、主题 runtime、圆角/扁平模式、骨架屏和安全区规则，因此不同业务系统会保持统一的 Microi 品牌质感。

Microi App

MciPage

页面 shell、安全区、入场动效、结构化背景。

页面标题

MciNavbar

移动端顶部导航，兼容沉浸式状态栏和返回操作。

MciButton

品牌按钮，内置 hover、focus、pressed、sheen 等反馈。

Surface商业数据卡片

柔和阴影、清晰边界、扫光层次。

MciCard

通用内容卡片，适合信息承载、入口、统计和商品容器。

SECTION

核心能力

MciSection

统一区块标题、副标题、eyebrow 和操作区。

账户设置安全与偏好›

消息通知系统与业务提醒›

MciCell

列表、菜单、设置、服务入口的标准单元格。

全部待处理已完成

MciTabs

分段标签，适合分类、状态、筛选和资产切换。

累计收益¥ 9,489.70今日 +128.00

MciMetricCard

资产、收益、积分、数据看板的强视觉指标卡。

MciActionBar

底部固定操作栏，内置底部安全区和按钮布局。

吾码UIAI

MciAvatar

用户头像，图片失败时自动用昵称/首字兜底。

标准商品卡¥ 299.00

MciProductCard

商品、权益、内容、服务项目都可复用的商业卡片。

MciSkeleton

支持 list、grid、banner、detail、metric 的骨架屏。

暂无数据完成请求后再显示空态

MciDataState

loading、empty、error 的统一动态数据状态。

内容标题

文字内容保留舒适留白，图片保持满宽展示。

MciRichText

文章、协议、商品详情、公告详情的移动端富文本容器。

rounded / flat

MciThemePanel

主题、palette、圆角/扁平、动效偏好的统一设置面板。

联系人请输入姓名备注

多行输入内容...

MciFormField

表单项，统一 label、必填、帮助、错误和输入框状态。

筛选关键词状态时间

MciFilterBar

列表页筛选栏，适合搜索、状态过滤和批量动作。

账户资产128,800本月增长 +12.8%

MciAssetCard

余额、积分、资产、数据面板的通用资产卡。

订单 #20260607已完成

标准订单卡服务项目 / 交易记录 / 审批事项

¥299

MciOrderCard

订单、审批、工单、任务记录的业务列表卡片。

确认操作

弹窗内容展示区

MciModal

弹窗组件，支持遮罩、标题、内容区和底部操作。

上传文件点击选择或拖拽上传

MciUploader

上传容器，统一选择、提示、文件列表和交互反馈。

提交申请09:30

审核通过10:15

完成归档11:00

MciTimeline

时间轴，适合状态流转、操作日志和活动记录。

1提交

2审核

3完成

MciSteps

步骤条，适合流程、订单、审批和新手引导。

组件代码示例

MciPage

Layout Recipe

页面与区块

用 MciPage 做页面 shell，区块统一交给 MciSection，首屏、网格、入场动效和结构化背景一套成型。

<MciPage safe-area tech-grid shape="rounded"> <MciSection title="核心能力" description="统一品牌、主题、动效和组件体验" animated> <div class="mci-grid mci-grid--3"> <MciCard interactive animated sheen>...</MciCard> <MciCard interactive animated sheen>...</MciCard> <MciCard interactive animated sheen>...</MciCard> </div> </MciSection></MciPage>

全部内容商品

List Recipe

移动端商品/内容列表

列表页必须有骨架屏、状态切换和稳定网格。接口未返回前不显示空态，商品/内容卡片保持统一比例。

<MciTabs v-model="type" :options="typeOptions" /> <MciDataState :loading="loading" skeleton-type="grid" :empty="!items.length"> <div class="mci-grid mci-grid--2"> <MciProductCard v-for="item in items" :key="item.Id" :title="item.Name" :image="item.Cover" :price="item.Price" :tag="item.TagName" /> </div></MciDataState>

累计收益¥949.79今日 +128.00

Action Recipe

资产与底部操作栏

资产指标用强视觉卡承载，底部操作栏必须兼容安全区，主次按钮层级明确，移动端点击有按压反馈。

<MciMetricCard label="累计收益" value="949.79" suffix="元" trend="今日 +0.00" /> <MciActionBar> <MciButton variant="plain" block>加入购物车</MciButton> <MciButton variant="primary" block sheen>立即购买</MciButton></MciActionBar>

筛选关键词状态

Flow Recipe

表单、筛选与流程

筛选、订单卡、步骤条、时间轴应该作为一个业务组合出现，既能承载查询，也能表达状态流转。

<MciFilterBar title="高级筛选"> <MciFormField v-model="keyword" placeholder="请输入关键词" /> <MciTabs v-model="status" :options="statusOptions" /> <template #actions> <MciButton variant="primary">查询</MciButton> </template></MciFilterBar> <MciOrderCard title="服务工单" status="处理中" amount="¥299.00" /><MciSteps :steps="steps" :current="1" /><MciTimeline :items="timeline" />

通用业务场景适配

Business Patterns

面向通用系统建设，不绑定任何定制项目。

无论是企业官网、移动端会员中心、服务平台、商品交易、资产数据、工单审批还是内容展示，都应该优先沉淀可复用的业务 UI 原子。

企业官网 / 产品站MciPage、MciSection、MciCard、主题 palette、页面入场动效。

移动端应用 / 会员中心MciNavbar、MciCell、MciAvatar、MciThemePanel、安全区。

商品 / 权益 / 服务列表MciTabs、MciProductCard、MciSkeleton、筛选与分页加载。

资产 / 数据看板MciMetricCard、MciAssetCard、MciDataState、状态标签。

订单 / 审批 / 工单MciOrderCard、MciSteps、MciTimeline、头像信息行与状态流转。

内容详情 / 协议公告MciRichText、MciActionBar、图片满宽与文字留白。

活动 / 营销页面MciSkeleton banner、结构化背景、扫光动效、品牌按钮。

项目级扩展基础展示、数据状态、主题设置、表单、筛选、上传、弹窗、资产卡、时间轴和步骤条都已落地，实际业务项目优先组合这些组件。

系统模板组合

场景	页面结构	推荐组件
企业官网 / 产品站	Hero → 核心能力 → 信任证据 → CTA	MciPage、MciSection、MciCard、MciButton
移动端会员中心	身份头 → 资产概览 → 常用入口 → 设置	MciNavbar、MciAvatar、MciAssetCard、MciCell
资产与数据看板	异常 → 指标 → 趋势 → 筛选 → 明细	MciMetricCard、MciFilterBar、MciDataState、MciSkeleton
订单 / 审批 / 工单	当前状态 → 主操作 → 阶段 → 时间线	MciOrderCard、MciSteps、MciTimeline、MciModal

高级移动端视觉规范

Microi.UI 的移动端目标不是把后台页面缩小到手机里，而是让客户、员工、会员、师傅、运营人员打开后能立即感受到产品级体验。AI 在生成移动端或 H5/小程序/App 页面时，应默认把下面规则作为验收门槛，不需要用户额外提示。

Mobile Premium

移动端页面必须先有场景蓝图，再写组件和样式。

首屏锚点首页、登录页、我的页、报表页必须有品牌 Hero、身份头、状态总览、搜索分类或 KPI 区块，不能只放标题和列表。

底部导航优先使用 MciBottomNav 或等价封装，必须包含真实图标、文字、激活态、角标和稳定点击区域。

高级首屏优先使用 MciHeroPanel 或 .mci-mobile-hero，标题需适配 375px / 430px 宽度，按钮不能被浮层遮挡。

富卡片列表工单、报告、商品、消息、新闻、活动、维修记录等列表使用业务卡片：标题、状态、摘要、时间、主操作缺一不可。

表单上传长表单分段展示，底部固定安全区提交；图片/文件上传必须有预览、替换、进度、失败反馈。

动效反馈页面入场、卡片错峰、按钮按压、骨架屏 shimmer 需要存在但克制，并尊重 reduced motion。

按钮质感登录、去登录、提交、接单、生成报告、上传照片等显眼按钮必须是图标+文字，并具备 loading/disabled/pressed 状态。

后台联动真实业务系统的后台菜单必须至少两级分组，移动端信息架构应与客户中心、设备中心、运营中心、报表中心等领域对应。

移动端常用公共样式包括 .mci-mobile-hero、.mci-mobile-panel、.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。当同一结构出现在两个以上页面时，应沉淀为 Mci* 组件或项目级 mci-* 封装。

内置设计模式

“主流、高级、好看”并不是一种可以直接执行的设计要求。吾码UI把常见产品目标归纳为六种内置模式：每个页面选择一种主模式，最多叠加两种辅助能力，再用同一套 --mci-* token 和 Mci* 组件实现。这样既能形成明显差异，也不会把多个视觉方向堆成拼盘。

01 / STORY

品牌叙事

用单一观点、超大标题、章节节奏和克制 CTA 建立首屏记忆。

适合官网、产品发布、品牌介绍

02 / FLOW

真实产品流程

先完成登录、创建、支付、权限、设置和异常恢复，再进行视觉装饰。

适合 SaaS、商城、会员与业务系统

03 / LAYOUT

趋势构图

通过编辑式留白、字号对比、不对称栅格建立清晰阅读顺序。

适合内容、创意、活动与作品展示

04 / SPACE

沉浸互动

用产品对象、空间层次或 Canvas/WebGL 辅助理解，并提供静态降级。

适合 3D、硬件、空间和互动产品

05 / MOTION

动态首屏

用 0—1200ms 时间线依次呈现标题、说明和主操作，避免持续噪声。

适合发布页、活动页与重点功能入口

06 / DATA

数据工作台

先异常、再趋势、后明细；筛选回显、数值格式和状态必须一致。

适合运营、监控、经营和分析场景

原创可运行案例

下面的案例完全使用吾码自有内容、--mci-* token、mci-* 类名和本地资源实现，不依赖外部图片、字体、组件库或网络请求。它用于展示六种模式之间的结构差异、明暗主题、响应式重排、筛选、表单校验、加载和成功反馈；业务项目应替换成自己的信息架构和合法素材，而不是逐像素复制案例。

桌面端1440px：首屏锚点、两列模式卡片与稳定内容宽度。

移动端390px：单列重排、满宽主操作、安全间距与无横向滚动。

产品流程完整性

视觉案例不能只有“默认状态”。登录、注册、订阅、支付、搜索、设置、创建和编辑等流程，至少应覆盖下面状态，并在同一容器中稳定切换，不能因为骨架屏、错误提示或分页出现而导致页面跳动。

Default字段标签、说明、主次操作与返回路径完整。

Loading使用结构等高的骨架屏或局部 loading，保留布局尺寸。

Empty说明为什么为空，并提供可执行的下一步。

Error错误靠近问题来源，保留用户输入并允许重试。

Permission解释所需权限、用途、拒绝结果与重新授权入口。

Disabled禁用原因可见，不能只降低透明度。

Success确认结果、关键编号与下一步，不显示无意义成功页。

Offline网络中断时保留草稿，并明确同步或重试状态。

MCI-DESIGN 设计契约

整站、复杂应用或需要多人和 AI 持续维护的项目，应在项目根目录维护 MCI-DESIGN.md。它不是灵感说明，也不是另一份脱离源码的色板，而是人和 AI 都能执行、检查和持续演进的界面契约。

两层信息缺一不可

层次	保存什么	解决什么问题
机器可读层	颜色、字体、间距、圆角、层级、组件状态、token 引用和有意省略	准确复用、结构检查、差异审查、生成运行时变量
人类可读层	用户任务、情绪目标、具体视觉隐喻、信息层级、选择理由和明确禁区	在契约未覆盖的新场景中继续作出一致判断

精确值会因项目而变，设计理由决定取舍方向。只有 token 会让接手者不知道“为什么”，只有“高级、现代、极简”一类形容词又无法稳定实现。推荐先写“用户任务 → 主情绪 → 具体视觉隐喻 → 三条应当/禁止”，最后才选择颜色与组件。

例如，“安静的专业工作台”会自然导出中性色表面、细边框、紧凑卡片、宽松区块留白，也自然排除大面积炫光、彩虹渐变和所有操作同权；这比堆叠抽象形容词更可执行。

固定章节与扩展规则

核心章节按顺序维护：产品与用户、视觉性格、颜色、字体、布局与间距、层级与形状、组件与状态、页面模式、动效与媒体、响应式与安全区、可访问性/性能/降级、应当与禁止。

• 项目专属章节放在末尾；读取和改写时必须保留未知扩展内容。
• 核心章节不能重复，也不能用近似拼写另起一份同义规则。
• 不适用的能力写进“有意省略”，说明理由和替代方案；不能静默缺失。
• 契约格式锁定版本，升级时先看语义差异，再同步迁移契约和实现。

机器可读示例

contract:
  version: 1
  mode: data-workspace
  intent: 安静、清晰、可快速扫描的专业工作台

tokens:
  color:
    canvas: var(--mci-bg-base)
    surface: var(--mci-bg-card)
    textPrimary: var(--mci-text-primary)
    primary: var(--mci-color-primary)
    danger: var(--mci-color-danger)
  spacing:
    compact: 8px
    card: 16px
    section: 24px
  shape:
    card: var(--mci-shape-card)
  elevation:
    card: var(--mci-shadow-card)
    cardHover: var(--mci-shadow-card-hover)

components:
  dataCard:
    background: "{tokens.color.surface}"
    radius: "{tokens.shape.card}"
    states:
      default: { elevation: "{tokens.elevation.card}" }
      hover: { elevation: "{tokens.elevation.cardHover}", lift: -2px }
      focus: { outline: "{tokens.color.primary}" }
      selected: { border: "{tokens.color.primary}" }

token 要按用途命名，组件通过 {路径} 引用共享值；颜色透明度必须说明叠加底色。组件按适用场景定义 default、hover、focus、pressed、loading、empty、error、disabled、selected、success，不能只写默认态。

契约检查与差异门禁

每次变更依次检查：

1. 核心章节存在且顺序正确，无重复、近似拼写或无法识别的 token 组。
2. 颜色、长度、数字、布尔值和状态对象类型正确；所有 {路径} 引用存在且无循环。
3. 主色、页面底色、表面、主/次文字和危险色完整；正文、焦点和交互态对比度达标。
4. 孤立 token 必须删除或说明用途，透明表面必须有底色，省略项必须有理由。
5. 契约差异与页面差异一起评审；意外删除、重命名、大范围漂移或单边修改都应阻止合入。
6. 运行时变量和其它主题输出只从校验后的机器块派生，不能再维护第二份手工 token。

AI 或开发者接手页面时，先完整读取契约和三条禁区再实现；如果页面发生结构性调整，必须同步更新契约。颜色、间距、圆角、组件状态和设计理由都不能只存在于截图或聊天记录中。

可迁移的视觉气质

气质	颜色与材质	形状与节奏	不应出现
温暖友好	暖白或浅沙底、自然低饱和强调色、轻触感层次	圆润或轻有机形、外部留白宽松	冷硬霓虹、尖锐切角、密集高对比
深色发光	深色分层、少量青蓝紫状态光、高对比文字	边界精确、密度紧凑、短促状态动效	大面积炫光、彩虹状态、持续漂移
雾感通透	灰白低彩、细线、轻透明表面	大留白、轻圆角、慢速淡入	厚重投影、不透明色块堆叠、过度模糊

这些不是可以整套复制的皮肤，而是“设计理由如何推导 token、组件与禁区”的示范。一个页面只选一个主气质，辅助气质最多两项。

后台数据卡片模式

吾码后台的卡片模式服务于高频浏览和操作，不是营销海报墙。统一信息顺序如下：

区域	内容	规则
身份	真实图片、头像或首字标记	有图才显示媒体；无图使用 40—44px 紧凑标记，不生成大面积装饰占位图
标题	主标题、状态、必要副标题	标题最多两行，状态标签只表达状态或分类
数据	2—4 个关键字段、金额或负责人	主次文字和数字层级固定，不把每个字段都做成胶囊
辅助	更新时间、创建时间、少量标签	与正文用细分隔线或留白区分
操作	主动作、次动作、“更多”	一个主动作、一至两个次动作；危险动作降权并收进菜单

• 没有显式列数时，桌面默认四列；业务显式配置优先。中等宽度自动降为三列或两列，移动端单列，卡片最小可读宽度优先于同屏数量。
• 卡片使用稳定表面、细边框、轻阴影与 1—2px 悬浮反馈；不使用顶部霓虹线、径向光斑、旋转方块、彩虹渐变和重投影堆装饰。
• 整卡可打开详情时必须提供可见焦点、Enter/Space 触发；内部按钮和选择控件阻止冒泡。移动端触控目标不小于 44px。
• 骨架屏复刻最终图片（如有）、标题、字段与操作区的结构，不能先显示大图骨架再塌缩。空态说明原因并给出下一步。
• 截图验收覆盖有图/无图、长标题、多个按钮、选中、加载、空态、明亮/暗黑，以及 1366/1440/1920 桌面和 390 移动宽度。

AI 开发规则

AI Usage

用户没有主动指定 UI 风格时，AI 必须默认采用 Microi.UI / MCI-UI。

这条规则让 AI 生成的页面从第一版开始就具备统一主题、骨架屏、安全区、动效和品牌 token，而不是每个项目临时拼装样式。

默认识别规则

使用 Microi.UI / MCI-UI 开发此 Vue 3/uni-app 页面。
遵循 microi.skills/ui-design/SKILL.md 和 microi.skills/microi-ui/SKILL.md。
页面必须支持 light/dark、黑白红橙黄绿青蓝紫 palette、rounded/flat、骨架屏、安全区、页面入场和点击反馈。
业务页面不要硬编码颜色/阴影/圆角，必须使用 --mci-* token 或 MciPage/MciButton/MciCard 等组件。

Delivery Checklist

AI 完成后必须检查这些交付项。

页面骨架是否使用 MciPage 或等价页面 shell，内容区是否优先用 MciSection。

入口与设置设置、菜单、服务入口是否优先用 MciCell，主题设置是否可用 MciThemePanel。

业务卡片分类、资产、商城、会员页是否复用 MciTabs、MciMetricCard、MciAssetCard、MciProductCard。

表单流程表单、筛选、上传、弹窗、订单/工单、时间轴、步骤条是否优先使用对应 MCI 组件。

数据状态是否有骨架屏，而不是接口未返回时直接显示空态。

移动兼容是否支持 iPhone、Android 不同机型的顶部/底部安全区。

主题运行时是否通过 initMciDesign() 或项目主题服务设置主题。

构建验收是否没有硬编码主色、圆角、阴影，并跑过基础构建或至少 node --check / npm pack --dry-run。

与第三方 UI 的关系

Ecosystem

Microi.UI 不排斥第三方库，它负责最终呈现的统一质感。

复杂表格、日期选择、上传、弹窗、表单校验等成熟能力，可以继续使用 Element Plus、uni-ui、TDesign、uView、FirstUI 等。但项目最终呈现出来的视觉，应该由 --mci-* token 和 mci-* 组件封装统一承载。

01能力解耦第三方组件只解决复杂交互能力。

02外层封装外层使用 mci-* wrapper 或项目级组件封装。

03token 统一颜色、圆角、阴影、间距、字体、骨架屏都走 --mci-*。

04体验收口对用户可见的页面风格由 Microi.UI 统一控制。