一套 Kotlin 代码，一套设计语言，一套完整的跨平台 UI 开发体系。

2026 年 10 月 29 日，GearUI Kit 1.0.0 正式发布！

从 2026 年 3 月 2 日写下第一行代码，到今天正式发布，历经近 8 个月、440 多次代码提交、8 个公开测试版本，我们终于迎来了 GearUI Kit 的第一个正式版本。

这不仅仅是一次版本号升级。

我们希望为 Kotlin 开发者提供一种更统一、更高效、更完整的跨平台 UI 开发方式。

不必为不同平台重复编写整套界面，不必从零搭建主题、导航、弹层与组件体系，也不必为了统一设计语言而反复调整每个平台的实现。

GearUI Kit 1.0 带来了：

• 82 个 UI 组件，覆盖基础控件、表单、导航、数据展示、反馈与布局。

• 四端跨平台布局，面向 Android、iOS、Web 和 HarmonyOS。

• 统一的 GearUI Design Language，以精致、克制、现代的移动端视觉体验为核心。

• 完整的应用级基础设施，涵盖 Navigator、Overlay、Runtime、Theme、I18n。

• 矢量图标系统，支持 Phosphor 图标、Regular/Fill 切换与类型安全调用。

• AI Coding Ready，提供专门的 Agent Skill，让 AI 也能遵循 GearUI 的架构规范开发应用。

更重要的是：

GearUI Kit 已经发布到 Maven Central，可以直接集成到你的 Kotlin Multiplatform 项目。

implementation("com.gearui:gearui-kit:1.0.0")

开源、可扩展、面向真实应用开发。

欢迎来到 GearUI Kit 1.0。

一、为什么已经有 Flutter 和 Compose Multiplatform，我们还要做 GearUI Kit？

跨平台开发已经不是新鲜事。

Flutter 证明了一套代码构建多平台界面的可行性，Kotlin Multiplatform 让 Kotlin 开发者能够共享越来越多的业务逻辑，Compose 则让声明式 UI 成为现代 Kotlin 开发的重要方式。

但对于真正要交付复杂应用的开发团队来说，跨平台远远不只是让一个 Button 同时显示在 Android 和 iOS 上。

你还需要解决：

• 不同平台的安全区、状态栏与键盘适配；

• 页面导航、返回手势和状态恢复；

• 对话框、底部面板与浮层的统一管理；

• 亮色、暗色及品牌主题；

• 表单校验、输入法组字和焦点管理；

• 多语言与本地化；

• 图标资源与设计规范；

• 组件行为一致性；

• 平台运行时差异。

这些能力如果都由业务项目自己实现，跨平台带来的效率优势就会被大量基础设施工作抵消。

我们希望 GearUI Kit 解决的，正是这些问题。

GearUI Kit 基于 Kotlin Multiplatform 和腾讯开源的 KuiklyUI 构建。

KuiklyUI 提供跨平台 UI 运行与渲染基础，GearUI Kit 则在其上构建完整的设计语言、组件体系与应用基础设施。

我们的目标很明确：

让开发者把精力集中在产品和业务，而不是反复实现按钮、导航、弹窗、安全区和主题系统。

GearUI Kit 不只是一个组件库，而是一套 Kotlin 跨平台应用 UI Toolkit。

二、82 个组件：从一个按钮，到一整套复杂应用

GearUI Kit 1.0 正式提供 82 个 UI 组件，覆盖六大类别。

这不是只有 Button、Input、Card 的基础组件集合。

从复杂表单、数据表格、日历、树形选择，到导航、浮层、通知、下拉刷新与图片预览，GearUI Kit 已经具备构建多种业务界面的组件基础。

基础组件 · 9 个

Button、Icon、Link、CloseButton、PressableFeedback、Text、Tag、Badge、Divider。

表单组件 · 22 个

Input、Checkbox、AgreementCheckbox、Radio、InputOTP、ComboBox、NumberField、ToggleButton、InputGroup、Switch、Slider、Stepper、Textarea、Rate、Select、Picker、DatePicker、Upload、Form、Cascader、ListBox、ColorPicker。

导航组件 · 8 个

NavBar、BottomNavBar、Tabs、Drawer、Steps、IndexBar、Segmented、Toolbar。

数据展示 · 21 个

List、Card、Cell、CellGroup、Table、Image、ImageViewer、Avatar、ScrollShadow、Collapse、Progress、Empty、Skeleton、Timeline、Calendar、Format、Watermark、Meter、User、Code、Kbd。

反馈组件 · 15 个

SwipeCell、ActionSheet、Toast、Dialog、Tooltip、ContextMenu、Loading、Alert、NoticeBar、Notification、Snackbar、Popup、Popover、Result、Tour。

布局组件 · 7 个

Grid、Swiper、SearchBar、PullRefresh、LoadMore、BottomSheet、BackTop。

82 个组件，统一的 API 风格，统一的设计语言，统一的交互规范。

每个组件都提供对应的 Sample 演示页面。

你不需要从文档中猜测组件效果，可以直接运行 Sample，查看实际渲染与交互。

三、GearUI Design Language：我们不想再做任何设计系统的影子

GearUI Kit 的设计语言经历过多轮演进。

我们研究过 Apple UIKit、TDesign、shadcn/ui 等成熟设计体系，也参考了大量优秀移动应用的交互与视觉细节。

但最终，我们决定建立自己的设计语言：

GearUI Design Language

它不追求堆砌视觉效果，而是强调四个原则：

精致、统一、自然、高效。

默认视觉以现代 iOS 风格为主要方向，同时通过语义化 Token 和组件规范保持跨平台一致性。

统一的颜色语义

不再让组件随意使用硬编码颜色。

页面背景、卡片、浮层、文本、边框、输入框、强调色、危险操作和反馈状态，都有明确的语义 Token。

Theme.colors.background
Theme.colors.foreground
Theme.colors.surface
Theme.colors.primary
Theme.colors.destructive
Theme.colors.border

组件关心的是颜色的语义，而不是某个固定的十六进制值。

完整的亮色与暗色主题

GearUI Kit 支持运行时主题切换。

不仅仅是把白色变成黑色。

卡片层级、浮层背景、边框、文字、禁用状态、危险操作和反馈色，都需要在不同主题下保持正确的视觉关系。

我们还专门建立了反馈色前景 Token，解决成功、警告、危险等彩色背景上的文字对比度问题。

统一的尺寸、圆角与间距

GearUI Kit 使用统一的设计尺度：

• 圆角：none / sm / md / lg / xl / full

• 图标：sm / md / lg / xl

• 间距：统一 Spacing Tokens

• 动效：统一 Motion Tokens

业务可以调整设计风格，而不必逐个修改组件内部的尺寸。

设计一致性不应该依靠开发者记住规范，而应该由组件库本身保证。

四、不是 WebView 套壳：基于 KuiklyUI 的跨平台渲染架构

GearUI Kit 的技术基础是：

Kotlin Multiplatform + KuiklyUI + 声明式 Compose UI。

开发者使用熟悉的 Kotlin 声明式语法构建界面，KuiklyUI 负责连接不同平台的渲染运行时。

这不是把一个网页放进 WebView，然后分别包装成 Android 和 iOS App。

GearUI Kit 面向的平台包括：

在不同平台上，GearUI Kit 尽可能复用相同的组件定义、状态逻辑与设计语义。

平台差异由 Runtime 和 Host 适配层负责处理。

业务代码不应该承担本该由跨平台框架解决的平台适配工作。

这也是 GearUI Kit 从最初设计时就坚持的架构原则。

五、性能不是口号，我们拿数据说话

跨平台 UI 框架不仅要能运行，还必须足够快。

在小米 12 Pro 上，我们对 GearUI Kit 进行了性能测试。

以下是本次测试得到的部分结果：

其中，冷启动结果为多次测试的中位数。

主题切换测试覆盖约 200 个同时参与渲染的组件。

756KB 数据来自启用 R8 的独立最小工程，不代表包含全部业务功能的实际 App 安装包大小。

我们希望通过持续的性能基准测试，让 GearUI Kit 的性能表现可以被测量、复现和改进。

轻量不是删掉功能，性能也不应该靠牺牲交互体验来换取。

六、Navigator：真正为应用开发准备的导航系统

很多 UI 组件库只负责绘制组件。

但真正的 App 需要一套完整的导航系统。

GearUI Kit 提供 Navigator，统一管理页面栈、页面状态、返回行为和转场动画。

它支持：

• Push / Pop / Replace / Reset

• 页面级唯一 Key

• 页面状态保存与恢复

• 返回拦截

• 异步确认后的强制返回

• 页面移除回调

• Overlay / Modal Presentation

• 页面转场动画

更重要的是，Navigator 与 KuiklyUI 的运行时生命周期和 BackHandler 机制进行了专门适配。

iOS：跟手的侧滑返回

在支持的 Push 页面中，开发者不需要自己编写手势逻辑。

从屏幕左侧向右拖动时：

当前页面跟随手指移动，上一页逐渐显露，松手后根据手势进度决定回弹还是完成返回。

Android：尊重系统返回机制

Android 端采用系统返回手势与 Navigator 的返回处理机制。

我们没有通过强行抢占系统边缘手势来实现一套与系统竞争的返回逻辑。

好的跨平台体验，不是无视平台差异，而是在统一架构下正确处理差异。

七、完整的浮层运行时：不再让每个 Dialog 自己管理生命周期

Dialog、Popup、BottomSheet、ActionSheet、Toast……

这些组件看起来简单，实际涉及大量交互边界。

例如：

• 点击遮罩是否关闭？

• 系统返回键是否优先关闭弹层？

• 页面切换后弹层是否自动销毁？

• 动画期间能否重复关闭？

• 键盘弹出时如何调整位置？

• 多个浮层同时存在时谁处于最上层？

GearUI Kit 将这些行为统一纳入 Overlay Runtime 管理。

组件负责展示，Runtime 负责生命周期与关闭策略。

这意味着业务项目不需要为每一种弹层重复编写一套状态管理逻辑。

八、Phosphor 矢量图标：告别 PNG 和图标字体

GearUI Kit 1.0 内置 Phosphor 图标体系，支持 Regular 与 Fill 两种风格。

使用方式非常简单：

Icon(Icons.heart)

需要填充风格？

Icon(
    Icons.heart,
    fill = true,
)

选中态也可以直接绑定：

Icon(
    Icons.home,
    fill = selected,
)

图标基于矢量路径，不依赖固定分辨率的 PNG。

这意味着在不同屏幕密度和图标尺寸下，都能保持清晰的边缘。

同时，图标使用类型化 Kotlin 属性，避免业务代码到处拼接资源字符串。

对于应用开发者来说：

图标应该像 Button 一样，是一个可以直接使用的 UI Primitive，而不是一堆需要手动管理的图片文件。

九、主题、多语言、表单：让复杂业务开发变简单

主题：一套 Token 控制整个应用

GearUI Kit 提供完整的主题体系。

开发者可以使用默认亮色、暗色主题，也可以定义自己的品牌主题。

统一的语义 Token 让品牌色、文字、卡片、浮层和交互状态保持一致。

多语言：上层库可以独立扩展

GearUI Kit 内置：

• 简体中文

• 繁体中文

• 英文

支持运行时动态切换。

更重要的是，GearUI Kit 不要求所有业务文案都写进组件库。

上层业务库可以维护自己的强类型语言包，并共享统一的语言环境。

例如一个即时通信应用可以拥有独立的聊天文案，而不需要修改 GearUI Kit 源码。

面向真实业务的表单

GearUI Kit 不只提供普通输入框。

还包括：

• 手机号、银行卡号、身份证号格式化输入；

• 验证码输入；

• 表单验证与异步校验；

• 级联选择；

• 日期选择；

• 颜色选择；

• 协议勾选；

• 中文输入法组字与文本选区处理。

这些能力尤其适合需要大量表单交互的中国市场应用。

十、AI Coding Ready：让 AI 也能按照 GearUI 标准开发

AI 编程正在改变软件开发方式。

但 AI 生成 UI 代码时，经常出现一个问题：

功能能跑，代码却不符合项目架构。

例如：

• 绕开组件库直接手写控件；

• 在页面里硬编码颜色和尺寸；

• 重复实现导航或弹层；

• 忽略 SafeArea；

• 使用错误的主题或语言包 API。

GearUI Kit 提供专门的 Agent Skill：

skills/gearui-kit

它帮助 AI 编程助手理解 GearUI Kit 的组件、设计 Token、Runtime 边界和应用开发规范。

让 AI 不只是知道“如何写一个 Button”，还知道“如何按照 GearUI 的架构构建完整页面”。

配合项目的 CI Guardrails，可以进一步检查生成代码是否违反设计规范。

我们希望 GearUI Kit 不仅适合人类开发者，也适合 AI 辅助开发。

十一、从第一行代码到 1.0：我们为什么敢发布正式版？

1.0 不应该只是把版本号从 beta 改成 stable。

它意味着我们愿意对公开 API、组件行为和工程质量承担长期维护责任。

GearUI Kit 为此建立了多层质量保障。

API 兼容性检查

使用 Binary Compatibility Validator 检查 JVM 与 Kotlin/Native 的公开 API。

Design Token 兼容检查

Token 字段与主题定义纳入版本基线，避免未经审查的视觉语义变更。

架构 Guardrails

通过 CI 检查组件硬编码、Runtime 边界、SafeArea 使用、单根入口和其他架构约束。

跨平台验证

Android 真机、iOS 模拟器、Web 浏览器与 HarmonyOS 构建链路分别进行验证。

其中：

• Android 已完成 41 项真机交互验收。

• iOS 模拟器完成了 180 个页面状态的无障碍审计。

• Web 完成亮色、暗色及不同屏幕尺寸下的页面检查。

• HarmonyOS 已打通 HAP 构建链路，真机运行验证仍在继续。

我们不会把尚未完成的验证包装成已经完成。

但也不会因为跨平台工程存在持续改进空间，就否定已经取得的成果。

GearUI Kit 1.0 是一个正式的工程起点，而不是开发工作的终点。

十二、30 秒开始使用 GearUI Kit

GearUI Kit 1.0.0 已发布到 Maven Central。

在项目中配置依赖仓库：

dependencyResolutionManagement {
    repositories {
        mavenCentral()
        maven(
            "https://mirrors.tencent.com/nexus/repository/maven-tencent/"
        )
    }
}

然后添加依赖：

commonMain.dependencies {
    implementation("com.gearui:gearui-kit:1.0.0")
}

你就可以开始使用 GearUI Kit 提供的组件、主题、图标和应用基础设施。

对于第一次接触 GearUI Kit 的开发者，我们建议先打开在线 Demo。

82 个组件，直接在浏览器