Skip to content

JetBrains/intellij-community / .agents/skills/compose-ui

compose-ui

Verified

Write or audit Compose Desktop UI state, effects, and boundaries.

FileKindSize
OWNERSHIPother20 B
SKILL.mdskill md532 B
architecture/GUIDE.mdmarkdown5.7 KB
architecture/evals/evals.jsonconfig6.5 KB
architecture/references/animation.mdmarkdown11.3 KB
architecture/references/component-api-lists-performance.mdmarkdown4.1 KB
architecture/references/desktop-seams-review-output.mdmarkdown1.5 KB
architecture/references/effects.mdmarkdown1.7 KB
architecture/references/state-boundaries.mdmarkdown5.4 KB
architecture/skill-source.jsonconfig2.0 KB
audit/GUIDE.mdmarkdown14.1 KB
audit/evals/evals.jsonconfig18.1 KB
audit/references/api-hygiene.mdmarkdown8.8 KB
audit/references/audit-search-patterns.mdmarkdown3.9 KB
audit/references/boundary-violations.mdmarkdown3.3 KB
audit/references/effects/derived-state-of-guide.mdmarkdown2.2 KB
audit/references/effects/effect-selection-guide.mdmarkdown2.7 KB
audit/references/effects/infinite-loop-patterns.mdmarkdown2.6 KB
audit/references/effects/overview.mdmarkdown7.7 KB
audit/references/lazy-layouts/animate-item.mdmarkdown2.0 KB
audit/references/lazy-layouts/cache-window-and-prefetch.mdmarkdown3.2 KB
audit/references/lazy-layouts/desktop-scroll-measurement.mdmarkdown2.0 KB
audit/references/lazy-layouts/keys-and-content-type.mdmarkdown2.2 KB
audit/references/lazy-layouts/nested-lazy-layouts.mdmarkdown1.6 KB
audit/references/lazy-layouts/overview.mdmarkdown7.5 KB
audit/references/measurement/benchmarking-methodology.mdmarkdown1.9 KB
audit/references/measurement/overview.mdmarkdown5.5 KB
audit/references/measurement/profiler-setup.mdmarkdown2.5 KB
audit/references/modifiers/custom-modifier-node.mdmarkdown3.4 KB
audit/references/modifiers/modifier-order.mdmarkdown2.1 KB
audit/references/modifiers/overview.mdmarkdown7.4 KB
audit/references/modifiers/phase-deferral.mdmarkdown2.6 KB
audit/references/reporting-guidance.mdmarkdown2.3 KB
audit/references/stability/ci-stability-gate.mdmarkdown2.0 KB
audit/references/stability/desktop-measurement.mdmarkdown2.2 KB
audit/references/stability/overview.mdmarkdown7.6 KB
audit/references/stability/reading-classes-txt.mdmarkdown2.1 KB
audit/references/stability/reading-composables-txt.mdmarkdown1.9 KB
audit/references/stability/stabilising-types.mdmarkdown3.1 KB
audit/references/stability/stability-config-syntax.mdmarkdown1.6 KB
audit/references/stability/stability-inference-algorithm.mdmarkdown3.4 KB
audit/references/stability/strong-skipping-escape-hatches.mdmarkdown2.6 KB
audit/references/subcomposition/desktop-subcomposition-measurement.mdmarkdown1.7 KB
audit/references/subcomposition/overview.mdmarkdown7.2 KB
audit/references/subcomposition/subcomposition-decision-tree.mdmarkdown1.8 KB
audit/references/subcomposition/swing-panel-subcomposition.mdmarkdown1.8 KB
audit/references/tracing-setup.mdmarkdown5.3 KB
audit/references/tracing-usage.mdmarkdown6.3 KB
audit/skill-source.jsonconfig2.5 KB

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.
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: 472kUpdated Claude CodeCodexVerifiedInstall
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: 472kUpdated Claude CodeCodexVerifiedInstall
rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first.Stars: 194kUpdated Claude CodeCodexVerifiedInstall