maooo-design

maooo-design 是面向微信小程序 Skyline 的 UI 组件库与 AI 设计系统工作区。当前根目录本身就是一个可运行的小程序预览工程，用于在真实 Skyline 环境中验证 packages/ui 下的组件、demo 页面和构建产物。

当前技术边界：

• 微信小程序 Skyline 渲染，componentFramework: "glass-easel"。
• 公共组件标签统一使用 mo- 前缀，例如 <mo-button />、<mo-popup-page />。
• 单组件公共 API 以各组件的 schema.json 为准。
• 跨组件复用、分层和组合关系以 packages/ui/component-registry.json 为准。
• 设计源数据、schema、prompt 和 AI 生成约束沉淀在 design-system。

组件能力概览

组件源码位于 packages/ui，每个组件目录通常包含 README.md、schema.json 和 src/ 小程序实现文件。

Base 组件

基础组件负责稳定、可复用的 UI 原子能力，不绑定具体业务流程：

• mo-button: 操作按钮，支持多类型、多尺寸、block、disabled、loading 和 icon slot。
• mo-card: 信息容器，支持标题、描述、默认 slot 和可点击状态。
• mo-icon: Iconfont.cn 图标渲染，支持 name、size、固定 color 和外层样式。
• mo-input: 受控单行输入，支持输入类型归一化、清除、确认、搜索、前后缀图标。
• mo-textarea: 受控多行输入，支持高度、字数展示、disabled、input 和 confirm 事件。
• mo-form: 表单区块容器，提供标题、描述、默认内容和 actions slot。
• mo-form-group: 字段标签容器，提供必填、帮助文案、错误文案和默认 slot。
• mo-popup: 基础弹层容器，负责遮罩、层级、显示隐藏、关闭请求和背景滚动锁定。
• mo-progress: 条状或环形进度展示，支持百分比、尺寸、文字和主题颜色。
• mo-rate: 星级评分，支持半星、普通/方块样式、只读、禁用和 change 事件。
• mo-countdown: 秒级倒计时，支持 DD、HH、mm、ss 分段和 change/finish 事件。
• mo-switch: 严格受控布尔开关，支持 checked、disabled、loading 和 change 事件。
• mo-stepper: 数值步进器，支持增减、输入、min/max 限制、disabled 和 input-disabled。
• mo-upload: 基础媒体选择与受控列表展示，支持预览、删除、数量限制和状态遮罩。
• mo-image-cropper: 图片裁剪组件，支持拖拽缩放、固定比例、缩略图状态和 canvas 导出。

Composed 组件

组合组件复用基础组件，提供更完整但仍然通用的界面结构：

• mo-calendar: 基于 mo-popup-page 的日历弹层，支持单选/多选日期、日期文案、价格、tag 和确认流程。
• mo-form-input: 组合 mo-form-group 与 mo-input 的带标签单行表单字段。
• mo-form-textarea: 组合 mo-form-group 与 mo-textarea 的带标签多行表单字段。
• mo-popup-page: 基于 mo-popup 与 mo-button 的页面式底部弹层，提供标题、滚动内容区和底部操作。
• mo-oss-upload: 组合 mo-upload 的阿里云 OSS 上传组件，负责签名请求、上传、进度、成功和错误事件。
• mo-navbar: Skyline 自定义导航栏，支持状态栏/胶囊安全区测量、占位、标题、返回和首页事件。

Business 组件

业务组件封装更完整的业务链路，但仍避免硬编码业务项目依赖：

• mo-media-upload: 组合 mo-upload、mo-image-cropper 和 OSS 上传机制，支持图片/视频上传、裁剪、可选审核、视频封面和主图设置。

目录结构与职责

• design-system: 设计源数据、tokens、schemas、patterns、prompts、skills、evaluations 和 references。
• packages/ui: 微信小程序组件源码、单组件 README、schema 和实现资产。
• packages/theme: 设计 token 构建后的运行时主题产物。
• packages/icons: 图标同步与 Iconfont 相关说明。
• packages/utils: 组件共享工具，构建时会复制到 miniprogram_dist/utils。
• packages/renderer: 面向 AI schema 到小程序 UI 的渲染层。
• pages: 当前根小程序的组件 demo 页面，统一放在 pages/<component>/<component>。
• scripts: 构建、schema、token、docs、icon 同步等脚本。
• docs: 架构、目录、组件规范、Skyline 注意事项、发包和贡献文档。
• miniprogram_dist: npm run build:dist 生成的小程序 npm 产物。

更完整的目录说明见 docs/directory-guide.zh-CN.md。

快速开始

安装依赖：

npm install

用微信开发者工具打开当前仓库根目录，即可作为 Skyline 小程序预览工程使用。根目录的 app.json 已开启 Skyline 和 glass-easel。

常用命令：

npm run build:dist
npm run pack:dry-run
npm run sync:icons
npm run build:schema
npm run build:token
npm run build:docs

命令说明：

• npm run build:dist: 构建 miniprogram_dist，并同步 pages/index/index 与 app.json 中的 demo 页面。
• npm run pack:dry-run: 构建后执行 npm pack --dry-run，检查实际发包内容。
• npm run sync:icons: 拉取并规范化 Iconfont 产物，更新 icon demo，再构建小程序产物。
• npm run build:schema: 构建或校验 schema 相关产物。
• npm run build:token: 从设计 token 源数据构建主题产物。
• npm run build:docs: 从组件和 schema 构建文档产物。

发包与业务接入说明见 docs/npm-publish.zh-CN.md。

组件开发约定

新增或修改组件时，优先遵守以下约定：

• 新增或重写的公共小程序组件使用 mo- 前缀，目录名不需要带前缀。
• 单组件 API 修改以组件目录内的 schema.json 为准。
• 新增、重命名、删除组件，或改变组件公共能力时，同步更新 packages/ui/component-registry.json。
• 组件 demo 页面放在 pages/<component>/<component>，不要放在 packages/ui/<component>/demo。
• 新增或删除 demo 页面后运行 npm run build:dist，同步预览入口和 app.json。
• 对外说明中的事件名使用 onXxx，运行时 triggerEvent 使用小程序小写事件名，demo WXML 使用 bind:click、bind:change 等小程序绑定语法。
• 内部 handler 使用 handleXxx 命名，公共 utility 使用 isXxx、hasXxx、getXxxClass、getXxxStyle、normalizeXxx、emitXxx 等命名。
• <mo-icon /> 的 color 必须传 Iconfont 可直接解析的固定色值，例如 #333333、rgb(51,51,51)、rgba(51,51,51,0.8)。
• Skyline 页面滚动优先使用 scroll-view，弹层、手势、动画和复杂滚动需要在真实 Skyline 环境中验证。
• 组件和 demo WXSS 不写 color: inherit;，选中、禁用、激活等状态色应直接作用到可见文本节点。

组件目录规范见 docs/component-spec.md，Skyline 注意事项见 docs/skyline-notes.md，贡献流程见 docs/contribution.md。

业务项目使用示例

业务小程序安装 npm 包并在微信开发者工具中构建 npm 后，可在页面或组件 .json 中注册：

{
  "usingComponents": {
    "mo-card": "maooo-skyline-ui-system/card/card",
    "mo-input": "maooo-skyline-ui-system/input/input",
    "mo-button": "maooo-skyline-ui-system/button/button"
  }
}

页面 .wxml 中使用：

<mo-card title="客户信息" desc="请确认资料">
  <mo-input placeholder="请输入客户姓名" bind:change="handleNameChange" />
  <mo-button label="保存" bind:click="handleSave" />
</mo-card>

主题变量可在业务小程序 app.wxss 中引入：

@import "maooo-skyline-ui-system/theme/theme.wxss";

组件 API 以各组件的 schema.json 和 README 为准，根 README 只维护项目入口信息。

相关文档

• 系统架构
• 目录说明
• 组件规范
• Skyline Notes
• npm 发包与业务接入
• 贡献说明
• UI Package