compose-expert

安装说明： 此技能现在以插件形式分发。 如果你曾手动将文件复制到 ~/.claude/skills/，则使用的是不再维护的安装方式， 无法收到更新。请通过以下命令迁移：

/plugin marketplace add aldefy/compose-skill
/plugin install compose-expert

Codex 和 Copilot CLI 的说明请参阅 MIGRATION.md。 此横幅将保留至 v2.x，并在 v3.0 中升级提示级别。

此技能的适用场景

frontmatter 中的 description: 有意保持简短，以满足 Codex / Copilot CLI 对该字段 1024 个字符的限制（参见 issue #12）。完整的触发条件 列于此处，以便技能加载后 Claude 仍能访问。

Compose API 提及

@Composable、remember、mutableStateOf、derivedStateOf、rememberSaveable、 LaunchedEffect、DisposableEffect、SideEffect、rememberCoroutineScope、 Scaffold、NavHost、NavController、MaterialTheme、ColorScheme、 Typography、LazyColumn、LazyRow、LazyVerticalGrid、HorizontalPager、 Modifier、Modifier.Node、recomposition、CompositionLocal、Style、 styleable、MutableStyleState、Material 3 Expressive、M3 Expressive、 MaterialExpressiveTheme、ButtonGroup、SplitButton、 FloatingActionButtonMenu、LoadingIndicator、HorizontalFloatingToolbar、 NavDisplay、NavKey、rememberNavBackStack、NavigableListDetailPaneScaffold。

Compose Multiplatform / KMP

Compose Multiplatform、CMP、KMP、commonMain、expect、actual、 ComposeUIViewController、Window composable、UIKitView、ComposeViewport、 Res.drawable、Res.string、SkikoMain。

Android TV

tv-material、tv-foundation、Carousel、NavigationDrawer（TV）、 D-pad、焦点指示、TV 上的 FocusRequester、10-foot UI、 客厅、tv compose、Android TV、Google TV、leanback migration。

Paging 3

PagingSource、Pager、PagingConfig、PagingData、LazyPagingItems、 collectAsLazyPagingItems、RemoteMediator、LoadState、 asSnapshot、TestPager、cachedIn。

设计系统 / 设计转代码

atomic design、atoms、molecules、organisms、templates、 design tokens、design system、component library、reusable component、 Figma to Compose、design to compose、build this UI、implement this design、 spec to code、redline。

日常表达

“我的 Compose 屏幕运行很慢”、“我的重组出问题了”、 “如何在屏幕之间传递数据”、“如何构建 TV 应用”、 “Android UI”、“Kotlin UI”、“Compose 布局”、“Compose 导航”、 “Compose 动画”、“Compose 样式”、“桌面版 Compose”、“iOS Compose”、 “Compose Web”。

Review Mode 触发条件

任何匹配 github.com/.*/pull/\d+ 的 GitHub PR URL，或以下短语： “review this PR”、“review this diff”、“review this code”、 “check this code”、“check this diff”、“what's wrong with this”。 匹配时，仅遵循 references/pr-review.md。

会话开始

在 session_start 时自动检测 Compose 项目 — 参见 references/auto-init.md。

快速路由

请先使用此表。根据用户的信号匹配一个参考文件，并在回答前阅读该文件。source-code/ 文件仅作为辅助证据 — 先加载一个 references/*.md 文件，然后在需要佐证时引用 source-code/ 来证明实现情况。

状态、重组、副作用

• remember、rememberSaveable、mutableStateOf 与 mutableIntStateOf 的对比、状态提升 → references/state-management.md
• derivedStateOf、snapshotFlow、UI 中的 StateFlow、重组作用域边界 → references/state-management.md（次要参考：references/performance.md）
• LaunchedEffect、SideEffect、DisposableEffect、rememberUpdatedState、rememberCoroutineScope → references/side-effects.md
• 重组频率、“我的屏幕重组过于频繁”、稳定性、@Stable/@Immutable、Compose 编译器指标、基线配置文件、强跳过 → references/performance.md
• CompositionLocal、环境值、主题传播、误用 LocalContext、自定义 local → references/composition-locals.md

动画与动效

• animate*AsState、AnimatedVisibility、Crossfade、updateTransition、Animatable、rememberInfiniteTransition → references/animation.md
• 共享元素过渡、手势驱动动画、Modifier.graphicsLayer、Canvas 绘制、自定义动效规范 → references/animation.md（次要参考：graphicsLayer 见 references/modifiers.md）
• M3 动效令牌、MotionTokens、MotionScheme、动画时长令牌、M3 缓动曲线 → references/material3-motion.md

布局、列表、修饰符

• LazyColumn、LazyRow、LazyVerticalGrid、LazyHorizontalGrid、key/itemKey、contentType、LazyListState、滚动状态、粘性标题 → references/lists-scrolling.md
• HorizontalPager、VerticalPager、PagerState → references/lists-scrolling.md
• Modifier 链顺序、自定义布局、Layout、SubcomposeLayout、布局修饰符、绘制修饰符、Painter、Modifier.Node → references/modifiers.md

导航

• NavHost、NavController、返回栈、深层链接、类型安全的 @Serializable 路由、导航图、嵌套导航图 → references/navigation.md
• 从 Nav 2 迁移到 Nav 3、NavDisplay、NavKey、rememberNavBackStack、NavBackStackEntry 的变更 → references/navigation-migration.md
• 在 Nav 2 与 Nav 3 之间进行选择、类型安全导航的选择、KMP 导航 → references/navigation-migration.md（次要参考：references/navigation.md）
• 高级 Nav 3：在目标页面之间返回结果、受身份验证限制的导航/条件导航、NavDisplay 中的动画/共享元素过渡、自适应列表-详情（NavigableListDetailPaneScaffold）、多个/每个标签页各自的返回栈 → references/navigation-migration.md

分页加载

• PagingSource、PagingData、Pager 设置、PagingConfig、pagingDataFlow、失效 → references/paging.md
• LazyPagingItems、collectAsLazyPagingItems、itemKey、itemContentType、UI 中的 LoadState、重试/刷新 → references/paging.md
• RemoteMediator、离线优先分页加载、网络 + 缓存分页加载、loadState.source.refresh → references/paging-offline.md
• MVI 中的分页加载、双流模式、分页测试（asSnapshot、TestPager）、CombinedLoadStates、分页反模式 → references/paging-mvi-testing.md

主题与设计系统

• MaterialTheme、ColorScheme、Typography、Shapes、动态颜色、M3 令牌、颜色角色 → references/theming-material3.md
• Material 3 Expressive、MaterialExpressiveTheme、ButtonGroup、SplitButton、FloatingActionButtonMenu、LoadingIndicator（波浪形）、HorizontalFloatingToolbar、@ExperimentalMaterial3ExpressiveApi → references/theming-material3.md（动效：references/material3-motion.md）
• 原子、分子、有机体、模板、组件层级、设计系统结构、可复用组件、设计令牌 → references/atomic-design.md
• Figma → Compose、截图 → 可组合项、设计令牌转换、从规范到代码、红线标注解读 → references/design-to-compose.md
• Style {}、MutableStyleState、Modifier.styleable()（实验性 Foundation Styles API） → references/styles-experimental.md

多平台与特定平台

• iOS/Desktop/Web CMP 目标、expect/actual、commonMain、Res.drawable、Res.string、平台特定的可组合项 → references/multiplatform.md
• ComposeUIViewController（iOS）、Window/Tray/MenuBar（Desktop）、UIKitView、ComposeViewport（Web）、平台互操作 → references/platform-specifics.md
• TV Compose、androidx.tv、D-pad 焦点、TV 上的 FocusRequester、Carousel、NavigationDrawer（TV）、10 英尺 UI、leanback 迁移 → references/tv-compose.md

互操作与无障碍

• XML 中嵌入 Compose、AndroidView、ComposeView、AbstractComposeView、混合迁移、View → Compose 互操作 → references/view-composition.md
• 无障碍、Modifier.semantics、TalkBack、触摸目标尺寸、contentDescription、WCAG、遍历顺序 → references/accessibility.md

生产、审查与迁移

• 生产环境崩溃、ANR、Compose 堆栈跟踪、remember 泄漏、零尺寸 DrawScope、重复键、过时的 derivedStateOf → references/production-crash-playbook.md
• PR 审查、代码审查、“审查此差异”、可组合项反模式、代码异味检测、GitHub PR URL → references/pr-review.md
• 已弃用的 Compose API、“在版本 X 中移除”、从旧 API 迁移、被替换的符号 → references/deprecated-patterns.md
• 实验性 API opt-in、@OptIn、@ExperimentalFoundationStyleApi、不稳定 API 的使用 → references/styles-experimental.md（适用于 Styles）；一般指导请参阅相关主题文件
• 会话开始、项目检测、自动初始化 → references/auto-init.md

源代码凭据（引用，不要路由到）

• “给我看看实际实现”、“在 androidx 的哪里”、Compose 内部机制 → 先加载主题参考文件，然后引用匹配的 references/source-code/*.md 文件：
  • Runtime/状态内部机制（Composer、Snapshot、Effects、Remember）→ references/source-code/runtime-source.md
  • UI/布局/测量/绘制内部机制 → references/source-code/ui-source.md
  • Foundation（LazyList、Pager、Clickable、Scrollable、BasicTextField）→ references/source-code/foundation-source.md
  • Material3 组件 → references/source-code/material3-source.md
  • Navigation Compose 内部机制 → references/source-code/navigation-source.md
  • CMP 入口点（Window、ComposeUIViewController、UIKitView、ComposeViewport）→ references/source-code/cmp-source.md

Compose 专家技能

为编写正确、高性能的 Compose 代码提供务实、中立的指导， 涵盖 Android、Desktop、iOS 和 Web。内容涉及 Jetpack Compose 和 Compose Multiplatform。 基于对 androidx/androidx 和 JetBrains/compose-multiplatform-core 实际源代码的分析。

Review Mode

在以下情况下激活：输入包含 GitHub PR URL（github.com/.+/pull/\d+），或明确的评审短语：“review this PR”“review this diff”“check this code”“what's wrong with this”。

激活 Review Mode 时：

1. 不要遵循下方的生成工作流
2. 阅读 references/pr-review.md，并仅遵循其中的工作流
3. 输出结构化的本地评审报告——不要向 GitHub 发布内容

Workflow

帮助处理 Compose 代码时，请遵循此检查清单：

1. 了解请求

• 涉及哪个 Compose 层？（Runtime、UI、Foundation、Material3、Navigation）
• 这是状态问题、布局问题、性能问题，还是架构问题？
• 这是仅适用于 Android，还是 Compose Multiplatform（CMP）？

2. 分析设计（如果提供了视觉参考）

• 如果用户分享了 Figma 画板、截图或设计规范，请参阅 references/design-to-compose.md
• 使用 5 步方法将设计分解为可组合项树
• 将设计令牌映射到 MaterialTheme，将间距映射到 CompositionLocals
• 确定动画需求，并参阅 references/animation.md 查找实现方案

3. 查阅合适的参考资料

回答前，请先阅读 references/ 中相关的参考文件：

主题	参考文件
@State、remember、mutableStateOf、状态提升、derivedStateOf、snapshotFlow	references/state-management.md
可组合项结构、插槽、提取、预览	references/view-composition.md — 关于设计系统结构，也请参阅 references/atomic-design.md
Modifier 顺序、自定义 Modifier、Modifier.Node	references/modifiers.md
LaunchedEffect、DisposableEffect、SideEffect、rememberCoroutineScope	references/side-effects.md
CompositionLocal、LocalContext、LocalDensity、自定义 local	references/composition-locals.md
LazyColumn、LazyRow、LazyGrid、Pager、键、内容类型	references/lists-scrolling.md
NavHost、类型安全路由、深层链接、共享元素转场	references/navigation.md
animate*AsState、AnimatedVisibility、Crossfade、转场	references/animation.md — 关于 M3 令牌选择，也请参阅 references/material3-motion.md
MaterialTheme、ColorScheme、动态颜色、Typography、形状	references/theming-material3.md — 关于动效，请参阅 references/material3-motion.md；关于设计令牌，请参阅 references/atomic-design.md
重组跳过、稳定性、基准配置、基准测试	references/performance.md
语义、内容描述、遍历顺序、测试	references/accessibility.md
已移除或替换的 API、旧版 Compose 的迁移路径	references/deprecated-patterns.md
Styles API（实验性）：Style {}、MutableStyleState、Modifier.styleable()	references/styles-experimental.md
Figma/截图分解、设计令牌、间距、Modifier 顺序	references/design-to-compose.md
生产环境崩溃模式、防御性编码、状态/性能规则	references/production-crash-playbook.md
Compose Multiplatform、expect/actual、资源（Res.*）、迁移	references/multiplatform.md
桌面端（Window、Tray、MenuBar）、iOS（UIKitView）、Web（ComposeViewport）	references/platform-specifics.md
TV Compose：Surface、Carousel、NavigationDrawer、Cards、焦点、D-pad	references/tv-compose.md
M3 动效令牌、MotionTokens、MotionScheme、动画时长、缓动	references/material3-motion.md
PR URL、代码评审、“review this PR”、“what's wrong with this”	references/pr-review.md
会话开始、项目检测	references/auto-init.md
原子设计、设计系统、可复用组件、组件库、设计令牌	references/atomic-design.md

4. 实施并验证

• 编写符合参考模式的代码
• 标出你在用户现有代码中发现的反模式
• 建议最简且正确的解决方案——不要过度设计

4a. 组件构建模式

当请求涉及构建组件（用于渲染 UI 的组合函数）时：

• 查阅 references/atomic-design.md
• 对组件级别进行分类（原子、分子、有机体、模板）
• 在搭建代码前，应用第 5 节中的“Ask”提示词
• 确保组件满足原子契约（修饰符、插槽、令牌、默认值）

5. 注明来源

引用 Compose 内部实现时，指出确切的源文件：

// See: compose/runtime/runtime/src/commonMain/kotlin/androidx/compose/runtime/Composer.kt

核心原则

1. Compose 以三个阶段思考：组合 → 布局 → 绘制。每个阶段中的状态读取只会触发该阶段及后续阶段的工作。

2. 重组频繁且成本低——但前提是你帮助编译器跳过未更改的作用域。使用稳定类型，避免在组合函数体中分配对象。

3. 修饰符顺序很重要。Modifier.padding(16.dp).background(Color.Red) 与 Modifier.background(Color.Red).padding(16.dp) 在视觉效果上不同。

4. 状态应尽可能靠近底层，并且只在必要时才向上提升。不要因为能把所有状态放进 ViewModel，就真的这么做。

5. 副作用用于连接 Compose 的声明式世界与命令式 API。根据用途选择合适的副作用——误用会导致难以追查的 bug。

6. Compose Multiplatform 共享运行时，但不共享平台。commonMain 中的 UI 代码具有可移植性。平台专属 API（LocalContext、BackHandler、Window）需要使用 expect/actual 或条件源码集。

源代码凭据

除了指导文档，此技能还包含来自 androidx/androidx（分支：androidx-main）和 JetBrains/compose-multiplatform-core （分支：jb-main）的实际源代码。需要验证某项功能的内部工作方式，或用户要求“展示实际实现”时，请阅读 references/source-code/ 中的原始源代码：

模块	源代码参考	包含的关键文件
运行时	references/source-code/runtime-source.md	Composer.kt、Recomposer.kt、State.kt、Effects.kt、CompositionLocal.kt、Remember.kt、SlotTable.kt、Snapshot.kt
UI	references/source-code/ui-source.md	AndroidCompositionLocals.android.kt、Modifier.kt、Layout.kt、LayoutNode.kt、ModifierNodeElement.kt、DrawModifier.kt
Foundation	references/source-code/foundation-source.md	LazyList.kt、LazyGrid.kt、BasicTextField.kt、Clickable.kt、Scrollable.kt、Pager.kt
Material3	references/source-code/material3-source.md	MaterialTheme.kt、ColorScheme.kt、Button.kt、Scaffold.kt、TextField.kt、NavigationBar.kt
Navigation	references/source-code/navigation-source.md	NavHost.kt、ComposeNavigator.kt、NavGraphBuilder.kt、DialogNavigator.kt
CMP	references/source-code/cmp-source.md	Window.kt、ComposeUIViewController.kt、UIKitView.kt、ComposeViewport.kt、ResourceReader.kt

两层方法

1. 从指导开始——阅读特定主题的参考文档（例如 references/state-management.md）
2. 深入查看源代码——用户需要凭据或你需要验证时，阅读 references/source-code/ 中的源代码

源代码树映射

androidx/androidx (branch: androidx-main)
├── compose/runtime/runtime/src/commonMain/kotlin/androidx/compose/runtime/
├── compose/ui/ui/src/androidMain/kotlin/androidx/compose/ui/platform/
├── compose/ui/ui/src/commonMain/kotlin/androidx/compose/ui/
├── compose/foundation/foundation/src/commonMain/kotlin/androidx/compose/foundation/
├── compose/material3/material3/src/commonMain/kotlin/androidx/compose/material3/
├── compose/navigation/navigation-compose/src/commonMain/kotlin/androidx/navigation/compose/
├── tv/tv-material/src/main/java/androidx/tv/material3/
└── tv/tv-foundation/src/main/java/androidx/tv/foundation/

compose-multiplatform-core (branch: jb-main)
├── compose/ui/ui/src/desktopMain/kotlin/androidx/compose/ui/window/
├── compose/ui/ui/src/iosMain/kotlin/androidx/compose/ui/window/
├── compose/ui/ui/src/webMain/kotlin/androidx/compose/ui/window/
├── compose/ui/ui/src/skikoMain/kotlin/androidx/compose/ui/
└── compose/foundation/foundation/src/skikoMain/kotlin/androidx/compose/foundation/

compose-multiplatform (resources library)
└── components/resources/library/src/commonMain/