docs/overview

zenit 开发手册

用 Zig 构建真正原生的 macOS 桌面界面。zenit 把窗口、GPU 渲染、文本、输入法与无障碍收进一个清晰的 UI 模型;这份手册带你从第一扇窗口走到可维护的生产应用。

5 分钟开始
$zig build run
0.15.2Zig 版本
Metal当前 GPU 后端
2 tiers公开 API:ui.X 与 ui.<group>.X
src/main.zig
const std = @import("std");
const ui = @import("ui");
const App = @import("zenit_app").App;

fn mountUi(cx: *ui.Cx, _: *ui.Scope) anyerror!*ui.Node {
    return ui.text(cx, "Hello, zenit!", .{
        .font_size = cx.tokens.font_size.xxxl,
        .color = cx.tokens.color.fg_primary,
    });
}

pub fn main() !void {
    var gpa = std.heap.GeneralPurposeAllocator(.{}){};
    defer _ = gpa.deinit();

    const app = try App.init(gpa.allocator(), .{
        .window = .{ .title = "Hello" },
    });
    defer app.deinit();
    try app.runWith(mountUi);
}
用 Claude Code 或其他 Agent 开发?先装上 zenit UI dev Skill。

它把这份手册、组件选型表和真实项目踩过的坑打包成 Agent 能按需加载的说明,写出的代码直接符合 zenit 的约定。

推荐学习路径

按顺序完成一次,约 45 分钟,你就拥有独立开发 zenit 应用所需的完整心智模型。

你将使用的架构

应用只依赖稳定的公开层,平台与渲染细节由 zenit 接管。

LAYERS
zenit.attach(dep, exe) 只给你的可执行文件加上 ui 与 zenit_app 两个模块导入,并编译原生桥接、链接系统框架。内部模块不在应用的构建图里,不是「约定不要用」,而是根本导入不到。

不只是一组 API

这三项能力贯穿运行时、文本与工程工具;每一项都有可运行的演示和真实窗口证据。

三条开发原则

遵守它们,代码能在 zenit 快速演进的阶段保持清晰。

01
只从公开层导入

应用代码使用 ui.*、ui.<group>.* 与 zenit_app.App,不要深入内部目录。

02
让数据决定 UI

持久状态放进 Signal 或绑定状态;派生值用 Memo,副作用用 Effect。

03
Token 优先

颜色、字号、间距与圆角来自主题;确需脱离刻度时,用 ui.arb 明确表达。

zenit · 双授权开源项目可按 GPL-3.0-only 免费使用;闭源或商业产品需要商业授权。可联系作者:zongyi.xzy#gmail.com(# 换成 @)zenit 5f9add5+wip 2026-09-30