JetBrains/intellij-community / .agents/skills/compose-ui
compose-ui
VerifiedWrite or audit Compose Desktop UI state, effects, and boundaries.
architecture/GUIDE.md
View on GitHub# Compose UI Architecture
Use this skill to keep Compose Desktop UI code architecturally correct while editing IntelliJ-style desktop surfaces.
This skill provides authoring and review guardrails for individual changes. When the user asks for a systemic Compose UI
architecture assessment across a codebase, use the [audit](../audit/GUIDE.md) guide instead.
For general post-change review or cleanup, use the review subagents available in the current harness instead of
stretching this skill beyond UI architecture. If subagent delegation is unavailable, run those review passes
sequentially yourself.
Do not use this skill to replace project docs. If the project has architecture docs, treat them as authoritative when
details conflict.
## Pair With / Defer To
Pair it with:
- Pair this skill with the `jewel` skill ([ui](../../jewel/ui/GUIDE.md) guide) when selecting Jewel components, theme wrappers, icons, typography, and
IntelliJ-style controls.
- Pair this skill with the `jewel` skill ([swing-interop](../../jewel/swing-interop/GUIDE.md) guide) when configuring Swing/AWT hosting, `ComposePanel`, `LocalComponent`,
popups, and bridge theme mechanics.
Defer these adjacent tasks instead of stretching this skill:
- Use the `jewel` skill ([ui](../../jewel/ui/GUIDE.md) guide) for component choice, label rules, icons, theme wrappers, typography, and Jewel visual style.
- Use the `jewel` skill ([swing-interop](../../jewel/swing-interop/GUIDE.md) guide) for `ComposePanel`, AWT popup forwarding, `LocalComponent`, and host Swing component access.
- Use configured review or refactoring subagents for general post-change code review or cleanup, or run those passes
sequentially yourself if delegation is unavailable.
- Use the [audit](../audit/GUIDE.md) guide for a whole-surface systemic Compose UI architecture assessment.
## Desktop Compose Terminology
Be precise with names:
- In Android docs, `ViewModel` roughly maps to a desktop UI **presenter/coordinator** layer.
- In desktop Compose code, a **view model** may also mean a view-layer data model / screen projection, such as
`ScreenState`, `RowModel`, or `SurfaceModel`. Avoid ambiguity by naming whether you mean lifecycle owner or render
model.
- Do not introduce Android `ViewModel`, Hilt/Koin, Android lifecycle, or Navigation guidance into desktop Compose UI
unless the project already uses those concepts.
## Core Rule
**Compositions render. Presenters decide.**
Composables may own ephemeral visual state: hover, focus, animation progress, expansion toggles, tooltip visibility,
and layout wiring. They must not own app state, persistence, RPC, file/process/network work, JSON parsing, model
selection, permission policy, review workflow decisions, or workspace/config lookup.
Route those through presenters/coordinators or equivalent state-owning layers and expose ready-to-render view models to
UI.
## Fast Guardrail Pass
Before returning Compose UI code, silently check these questions:
1. **Boundary:** does the composable render inputs, or does it decide business/app behavior?
2. **State:** is local state truly ephemeral? If state mirrors app/session/project settings, move it up.
3. **Projection:** should several values be combined into one presenter-owned screen state before UI sees them?
4. **Effects:** does every effect stay minimal and key on the values that should restart it?
5. **Modifier:** do reusable composables accept and forward `modifier: Modifier = Modifier` to the outermost layout?
6. **Lists:** do movable and heterogeneous lazy-list items pass a stable `key =` parameter and a matching
`contentType =` parameter?
7. **Performance:** does composition avoid expensive transforms, object churn, and broad state reads?
8. **Animation:** does the animation code use declarative APIs where possible, wrap stateful animation objects in
`remember`, and read per-frame values in the layout or draw phase?
9. **API shape:** do reusable components accept immutable data and event callbacks instead of presenter instances or
mutable state objects?
If an answer is no, fix the shape before writing more code rather than documenting the violation.
Also check for false positives. Local hover state, focus requesters, text-field state, expansion toggles, scroll
commands, and one-shot UI labels are usually fine in composition when they do not shadow app/session state.
## Progressive Reference Files
Read only the reference files needed for the current task:
- Read `references/state-boundaries.md` for rules on presenter/coordinator vs. state-holder vs. composition boundaries,
desktop lifecycle, flow collection, `CompositionLocal` guardrails, and testing ownership.
- Read `references/effects.md` for rules on `remember`, `LaunchedEffect`, `DisposableEffect`, `snapshotFlow`, coroutine
scopes, and effect keys.
- Read `references/animation.md` when choosing animation APIs, remembering `Animatable` state, launching target-driven
effects, deferring animated reads, or using `AnimatedContent`, infinite transitions, and gesture-driven motion.
- Read `references/component-api-lists-performance.md` for rules on reusable composable API shape, modifier contracts,
lazy-list keys and content types, recomposition and performance smells, and healthy patterns to preserve.
- Read `references/desktop-seams-review-output.md` for guidance on desktop dialogs, popups, shortcuts, clipboard and URI
opening, window state, protocol and runtime seams, and the file-grounded review output format.
## Review Output
When reviewing code with this skill, keep output short and file-grounded:
```markdown
### path/to/File.kt
- Issue: [rule name]
- Why it matters: [one sentence]
- Fix: [specific direction or tiny before/after]
```
End with the top three fixes, highest impact first. Do not list clean files.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |