Skip to content

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

compose-ui

Verified

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

FileKindSize
OWNERSHIPother20 B
SKILL.mdskill md637 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

audit/references/subcomposition/overview.md

View on GitHub
# Compose Subcomposition — Power vs Cost

**Core principle:** Avoid subcomposition unless measurement genuinely drives composition. If
the same layout can be expressed with standard modifiers or pre-calculated derived state, prefer
that.

> **Routing:** Use this workflow when profiling shows unexpected composition overhead during
> resize, scroll, or layout, or when reviewing whether `BoxWithConstraints` can be replaced.

## Workflow

### Phase 1 — Measure

- [ ] **1. Profile during resize.** Resize the window. If CPU spikes, capture a sample:

```bash
# JFR — pass JVM flags via JAVA_TOOL_OPTIONS, not --args
JAVA_TOOL_OPTIONS="-XX:+FlightRecorder -XX:StartFlightRecording=duration=30s,filename=resize.jfr" \
  ./gradlew run
```

Look for `SubcomposeLayoutSubcompositionState` or `BoxWithConstraints` in the flame graph.

- [ ] **2. Add logging inside `BoxWithConstraints` or `SubcomposeLayout`.**

```kotlin
BoxWithConstraints {
    SideEffect { println("[Subcompose] BoxWithConstraints recomposed, maxWidth=$maxWidth") }
    // ...
}
```

If it logs on every minor resize tick, subcomposition is running too often.

For Desktop-specific measurement, read
[desktop-subcomposition-measurement.md](desktop-subcomposition-measurement.md).

### Phase 2 — Diagnose

- [ ] **3. Determine if subcomposition is necessary.** Ask: does the composition tree structure
  depend on the measured size?

| Situation | Needs subcomposition? | Alternative |
|-----------|----------------------|-------------|
| Change padding based on width | No | Conditional logic in composition phase. |
| Switch layout based on width | Maybe | Read window size from `LocalWindowInfo`. |
| Show/hide elements based on min width | Maybe | Pre-calculate breakpoints with `derivedStateOf`. |
| Intrinsics-dependent layout | Yes | `SubcomposeLayout` is the correct tool. |
| Embed a Swing component | Yes | `SwingPanel` uses subcomposition internally. |

For the decision tree, read [subcomposition-decision-tree.md](subcomposition-decision-tree.md).

- [ ] **4. Check for `BoxWithConstraints` overuse.** Common cases that do not need it:

```kotlin
// WRONG — subcomposition for simple padding
BoxWithConstraints {
    val padding = if (maxWidth > 600.dp) 32.dp else 16.dp
    Box(modifier = Modifier.padding(padding)) { /* ... */ }
}

// RIGHT — no subcomposition; read container width from LocalWindowInfo
val containerWidth = with(LocalDensity.current) {
    LocalWindowInfo.current.containerSize.width.toDp()
}
val padding = if (containerWidth > 600.dp) 32.dp else 16.dp
Box(modifier = Modifier.padding(padding)) { /* ... */ }
```

- [ ] **5. Check `SwingPanel` resize behaviour.** `SwingPanel` subcomposes on every size change.
  If the Swing component does expensive layout on resize, the combination is costly.

For SwingPanel optimisations, read [swing-panel-subcomposition.md](swing-panel-subcomposition.md).

### Phase 3 — Fix

- [ ] **6. Replace `BoxWithConstraints` with derived state when possible.**

```kotlin
// BEFORE — subcomposes on every measure
@Composable
fun ResponsiveCard(content: @Composable () -> Unit) {
    BoxWithConstraints {
        if (maxWidth > 600.dp) WideCard(content) else NarrowCard(content)
    }
}

// AFTER — composes once, uses derived state or hoisted window width
@Composable
fun ResponsiveCard(windowWidth: Dp, content: @Composable () -> Unit) {
    if (windowWidth > 600.dp) WideCard(content) else NarrowCard(content)
}
```

- [ ] **7. Use `SubcomposeLayout` only for genuine intrinsics or two-pass needs.**

```kotlin
// GENUINE NEED — text wraps around an image whose size depends on available width
SubcomposeLayout { constraints ->
    val imagePlaceable = subcompose("image") { Image(...) }.first().measure(constraints)
    val textPlaceable = subcompose("text") { Text(...) }.first().measure(
        constraints.copy(maxWidth = constraints.maxWidth - imagePlaceable.width)
    )
    layout(constraints.maxWidth, max(imagePlaceable.height, textPlaceable.height)) {
        imagePlaceable.placeRelative(0, 0)
        textPlaceable.placeRelative(imagePlaceable.width, 0)
    }
}
```

- [ ] **8. Cache `SwingPanel` factory when possible.**

```kotlin
// WRONG — new factory on every recomposition
SwingPanel(factory = { JLabel(labelText) }, modifier = Modifier.size(200.dp, 100.dp))

// RIGHT — stable factory, update via property
val factory = remember { { JLabel() } }
SwingPanel(factory = factory, modifier = Modifier.size(200.dp, 100.dp),
    update = { it.text = labelText })
```

### Phase 4 — Verify

- [ ] **9. Re-run the profiler.** `SubcomposeLayout` / `BoxWithConstraints` should no longer
  dominate the flame graph.
- [ ] **10. Verify visual correctness.** The layout must behave identically.
- [ ] **11. Check `SwingPanel` does not allocate on every recomposition.**

## Patterns

### Avoid BoxWithConstraints for breakpoints

```kotlin
// WRONG — subcomposition on every measure
BoxWithConstraints {
    when {
        maxWidth < 600.dp -> CompactLayout()
        maxWidth < 840.dp -> MediumLayout()
        else -> ExpandedLayout()
    }
}

// RIGHT — observe window container size via LocalWindowInfo (standard Compose API)
// LocalWindowInfo.containerSize is IntSize in pixels; convert to Dp with LocalDensity.
val containerWidth = with(LocalDensity.current) {
    LocalWindowInfo.current.containerSize.width.toDp()
}
when {
    containerWidth < 600.dp -> CompactLayout()
    containerWidth < 840.dp -> MediumLayout()
    else -> ExpandedLayout()
}
```

### SubcomposeLayout for intrinsics

```kotlin
// RIGHT — genuine two-pass measurement need
SubcomposeLayout { constraints ->
    val header = subcompose("header") { Header() }.first().measure(constraints)
    val body = subcompose("body") { Body() }.first().measure(
        constraints.copy(maxHeight = constraints.maxHeight - header.height)
    )
    layout(constraints.maxWidth, header.height + body.height) {
        header.placeRelative(0, 0)
        body.placeRelative(0, header.height)
    }
}
```

## Mandatory rules

- **MUST** measure subcomposition cost before deciding to keep `BoxWithConstraints`.
- **MUST NOT** use `BoxWithConstraints` for simple conditional padding or margin that can be
  computed from hoisted state.
- **MUST** prefer derived state or direct conditional composition over subcomposition when the
  layout structure does not depend on measured size.
- **MUST** use `SubcomposeLayout` only for intrinsics-dependent layout or two-pass measurement.
- **MUST** provide a stable `factory` to `SwingPanel` and use `update` for dynamic properties.
- **MUST NOT** allocate new Swing components in the `SwingPanel` factory on every recomposition.

## Verification checklist

- [ ] Profiling confirms reduced `SubcomposeLayout`/`BoxWithConstraints` overhead after the fix.
- [ ] No `BoxWithConstraints` remains in a hot path without justification.
- [ ] `SwingPanel` uses a remembered factory and `update` for property changes.
- [ ] Visual layout is identical before and after replacement.
- [ ] Resize and scroll interactions are smooth.

## References

- [subcomposition-decision-tree.md](subcomposition-decision-tree.md) — when subcomposition is necessary
- [swing-panel-subcomposition.md](swing-panel-subcomposition.md) — factory stability, update pattern
- [desktop-subcomposition-measurement.md](desktop-subcomposition-measurement.md) — profiling on Desktop
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