# chunui

Adopt this skill: https://proskills.md/skills/other/liseami-chunui-skills-chunui

Page: https://proskills.md/skills/other/liseami-chunui-skills-chunui
This document is the public skill bundle for that page. It contains SKILL.md and every helper file the catalog carries. No login is required.

## File: skills/chunui/SKILL.md
size: 3599
upstream: https://github.com/liseami/chunui/blob/main/skills/chunui/SKILL.md

````text
---
name: chunui
description: Build iOS apps with the ChunUI design system (Monochrome texture extracted from the production app Zinner/Chat0IM). Use when integrating ChunUI via SPM, theming with CCColors, using CC components (buttons/forms/cards/sheet/toast/alert/skeleton), Metal effects (aurora/fractal/generating/sweep), motion primitives (ccReveal/zoom transitions), or the UIKit×SwiftUI hybrid presentation architecture. Includes real production page sources as LEGO blueprints.
---

# ChunUI 开发技能

ChunUI 是从生产级 iOS 应用 Zinner（阿奇/Chat0IM）提取的 SwiftUI 设计系统。
**使命：让你用它搭积木，搭出 Chat0IM 同级别 UI 质感的产品。**

## 目录（按需深入）

| 文档 | 内容 |
|---|---|
| `usage/setup.md` | SPM 接入、一行换肤、宿主接线座、组件文案本地化、可选资产 |
| `usage/presentation.md` | UIKit×SwiftUI 混合架构：窗口分层、sheet 标准（脏态/zoom 转场）、toast/alert、相册相机 |
| `usage/effects-motion.md` | 入场动画范式、AI 工作态特效、氛围底纹、骨架屏、打字机/流式、粒子消散、性能纪律 |
| `components/reference.md` | 全组件逐类参考（令牌/按钮/表单/卡片/chrome/反馈/媒体/文本/图标） |
| `examples/` | **五个真实生产页面源码**——组件组合的积木图纸（README 有阅读法） |

## 架构一图流

```
UIWindow 层级:  主窗口(UINav+Hosting) → CCToastWindow(+1) → CCAlertWindow(+2) → Sweep 覆盖窗
呈现命令式:     AppHelper.presentSheet / showBottomAlert / CCToastCenter.show（禁 SwiftUI .sheet/.alert）
主题单向流:     ChunUI.configure(colors:strings:) → CCColors.current → Color.cc.* → 全组件
```

## 质感五铁律（违反即失真）

1. **唯一彩色**：页面上只有 `Color.cc.primary` 一个彩色，其余全灰阶语义色；功能色也从品牌色同轴选冷调
2. **三梯度字号**：只用 `Font.cc.sm(13)/base(17)/lg(24)`（+Bold）；文字统一 `.ccText(font:color:)`
3. **呈现走命令式**：sheet/alert/toast 全走 AppHelper/CCToastCenter，禁系统原生弹窗 API
4. **动效走令牌**：入场一律 `ccReveal/ccWaveReveal`，循环动画禁 `repeatForever`
5. **图标统一 PikaIcon**：1225 枚随包，禁散用 SF Symbols 当业务图标

## 快速上手（30 秒）

```swift
// 1. App 启动
var colors = CCColors.default
colors.primary = .hex("你的品牌色")
ChunUI.configure(colors: colors)

// 2. SceneDelegate
CCToastWindow.shared.attach(to: windowScene)
CCAlertWindow.shared.attach(to: windowScene)

// 3. 开搭
CCNeoButton("开始", variant: .primary, fullWidth: true) { await start() }
CCToastCenter.shared.show(.success, "已保存")
AppHelper.shared.presentSheet(.form) { EditView() }
```

## 常见坑

| 症状 | 解法 |
|---|---|
| shader 特效黑块 | 宿主自绘调了 `ShaderLibrary.xxx`（主 bundle 无 metallib，函数查找失败即渲染黑块）。一律改 `CCShaders.xxx`（包内库，public）。真实案例：Zinner 订阅卡分形纹理直调 `ShaderLibrary.fractalJulia` 迁包后全黑，改 `CCShaders.fractalJulia` 即愈 |
| 换肤不生效 | configure 必须先于首个视图创建；运行时换主题需触发根视图重建 |
| sheet 无脏态确认 | 内容视图缺 `@EnvironmentObject var ctx: CCEditSheetContext` 或未挂 `.ccEditSheetDirty` |
| toast 不显示 | 未 attach 窗口，或场景未 foregroundActive |
| 组件文案是英文 | 未覆写 CCStrings（usage/setup.md） |
| 图标空白 | 图标名不在 pika 集，用 `PikaIcon.Name.*` 常量防拼写 |
````

## File: README.md
upstream: https://github.com/liseami/chunui/blob/main/README.md

````text
# ChunUI

**Define your palette. Ship the same texture.**

ChunUI 是从生产级 iOS 应用 [Zinner（阿奇）](https://zinnerapp.com) 中提取的 SwiftUI 设计系统——黑白灰阶 + 唯一品牌色的 Monochrome 质感、微拟物按钮、原生 sheet 标准、Metal shader 特效与点阵动画，全家桶开箱即用。

**你只需要定义自己的配色，就能做出同质感的应用。**

<p>
  <img src="docs/screenshots/gallery-home.jpg" alt="Gallery" width="135"><img src="docs/screenshots/buttons.jpg" alt="Buttons" width="135"><img src="docs/screenshots/cards-tags.jpg" alt="Cards & Tags" width="135"><img src="docs/screenshots/ai-effects.jpg" alt="AI Effects" width="135"><img src="docs/screenshots/ambient.jpg" alt="Ambient" width="135"><img src="docs/screenshots/shader-zoo.jpg" alt="Shader Zoo" width="135">
</p>

```swift
import ChunUI

// App 启动时，一行换肤
var colors = CCColors.default          // Zinner 同款极致黑白粉
colors.primary = .hex("007aff")        // 换成你的品牌色
ChunUI.configure(colors: colors)

// 之后全组件族自动着装
CCNeoButton("开始", variant: .primary) { await start() }
Text("标题").ccText(font: .cc.lgBold, color: .cc.foreground)
```

## AI Agent Skill

仓库自带 `skills/chunui/` —— 分门别类教 AI 编程助手搭出同级质感：
- `SKILL.md` 入口：架构一图流 + 质感五铁律 + 常见坑
- `usage/` 用法三册：接入换肤 / 呈现层（sheet·toast·alert·zoom）/ 特效动效
- `components/reference.md` 全组件逐类参考
- `examples/` **五个真实生产页面源码**（个人中心/时间线/收银台/AI 分析卡/tabbar）——积木图纸

**Claude Code**：

```bash
# 项目级（推荐，随仓库走）
mkdir -p .claude/skills && cp -R /path/to/ChunUI/skills/chunui .claude/skills/
# 或全局
cp -R /path/to/ChunUI/skills/chunui ~/.claude/skills/
# 或经 skills CLI
npx skills add liseami/ChunUI
```

**Codex / 其他 Agent**：把 `skills/chunui/SKILL.md` 内容追加进项目 `AGENTS.md`（或在其中写一行指引：`ChunUI 用法见 skills/chunui/SKILL.md`）。

**Cursor**：拷入 `.cursor/rules/chunui.mdc`。

安装后，Agent 会在涉及 ChunUI 的任务里自动遵循组件规范与架构铁律。

## 安装

Swift Package Manager，iOS 18.6+（iOS 26 自动启用 Liquid Glass，18.6–25 同形微拟物降级）：

```swift
.package(url: "https://github.com/liseami/ChunUI", branch: "main")
```

## 里面有什么

| 域 | 内容 |
|---|---|
| **Theme** | `CCColors` 语义调色板（shadcn 同构：background/card/panel/muted/accent/destructive…）、`Font.cc` 三梯度字号铁律、`CGFloat.cc` 间距/圆角令牌、`CCMotion` 全局动画曲线（reveal 零过冲 / wave 微过冲错峰） |
| **按钮** | `CCNeoButton` 微拟物五变体×三尺寸（async loading + glow/shake 按压）、`GlassButton`/`MetalGlassButton`/`GlassIconButton` 玻璃族（iOS 26 Liquid Glass / 以下微拟物同形降级） |
| **Sheet 标准** | `AppHelper.presentSheet(.form/.half/.compact/.picker)` 原生 UISheetPresentationController 深度调参：detents/脏态下拉确认/zoom 锚点转场/贴底吞安全区 |
| **Toast / Alert** | `CCToastCenter` 单槽玻璃胶囊 toast（loading 常驻顶换）＋ 沉底双胶囊 Alert（Twitter 风，禁 UIAlert） |
| **特效** | `CCAuroraLayer` AI 工作态极光（Metal）、`CCGeneratingCover` 呼吸点阵生成中质感、`CCFractalFloor` 九分形点阵地板、`CCSweepLight` 转场扫光、`ParticleDissolve` 粒子消散、Holographic/MetaBalls/Silk/Beams/Noise 全套 shader |
| **氛围** | `FluidGradient` 流体渐变、`Orb` 拟物 AI 球（发光/粒子/波浪）、`CCRainbowBar` 彩虹进度、`CCSkeleton` 扫光骨架屏、`StreamingText` 流式打字 |
| **表单/卡片** | `CCInput`/`CCTextArea`/`CCToggle`/`CCCheckbox`/`CCDatePicker`、`CCAppleCard` 连续圆角三级软阴影、`CCCuteTag`/`CCKeycapTag` |
| **图标** | `PikaIcon` —— 1225 枚 24×24 stroke 模板矢量随包分发，可染色可缩放 |
| **基建** | `VariableBlurView` 渐进模糊、`ccFloatingPageHeader` 页面 chrome 范式、相机/相册选择器、`InAppBrowser`、Markdown 渲染 |

## 设计哲学

1. **唯一彩色**：灰阶承载一切层级，品牌色是页面上唯一的彩色——这是同质感的根。
2. **三梯度字号铁律**：全应用只有 sm 13 / base 17 / lg 24 三个字号。
3. **组件级触觉与埋点**：按钮自带按压反馈；`CCTrack.onTap` 接线座让宿主埋点系统零侵入接入。
4. **配置即代码**：`ChunUI.configure(colors:strings:)` 是唯一初始化入口；文案表 `CCStrings` 可整体覆写做本地化。

## 宿主可注入的接线座

```swift
ChunUI.hapticsEnabled = userPrefs.haptics          // 触觉总开关
ChunUI.sheetPresentHook = { _, name in Analytics.page(name) }  // sheet 呈现埋点
CCTrack.onTap = { Analytics.tap($0) }              // 组件级点击埋点
CCImageLoader.custom = { url, _ in                 // 用 Kingfisher 接管网络图
    AnyView(KFImage(url).resizable())
}
AppHelper.toastRouteResolver = { ... }             // toast 气泡路由策略
```

## 依赖

- [Pow](https://github.com/EmergeTools/Pow)（MIT）——按钮 glow/shake 按压质感，唯一第三方依赖。

## 示例 App

`Example/ChunUIGallery.xcodeproj` 是可直接运行的组件画廊（xcodegen 生成，引用本地包）——按 Foundation / Controls / Feedback / Text / Effects / Ambient / Icons 分区展示全部组件与特效。画廊源码在 `Sources/ChunUIDemo/`，同时充当公开 API 面的编译级测试。

```bash
open Example/ChunUIGallery.xcodeproj   # 选模拟器直接 Run
```

## License

MIT.

---

*Extracted with care from Zinner. Texture is a feature.*
````
