--- name: jetbrains-compose-ui-audit description: "Audit Compose Desktop UI state and effects." license: "NOASSERTION" metadata: decimalai-skill-id: "f8eef270-05e2-4f34-accd-409da500342a" decimalai-version-id: "69c0ff74-a7f3-40b9-b9d7-86e08710ad93" decimalai-version: "2" decimalai-body-sha256: "91133c16a4f01f5df2145a62b5e64f419d57c98615df91cb02f1a309161e87e0" decimalai-name: "jetbrains/compose-ui-audit" decimalai-format: "1" decimalai-invocation: "model" decimalai-category: "code-review" decimalai-source: "https://app.decimal.ai/s/jetbrains-compose-ui-audit@2/SKILL.md" --- # Compose UI Audit Audit Compose Desktop UI code for architectural correctness and Compose runtime hygiene. This workflow gathers read-only evidence rather than reviewing visual design. Use `compose-ui-architecture` for day-to-day authoring guardrails and `jewel-ui` for Jewel component and theming guidance. If the user asks for a general review, cleanup pass, or broad investigation rather than a Compose UI architecture audit, use the review subagents available in the current harness. If subagent delegation is unavailable, run those review passes sequentially yourself. Keep the audit proportional. A focused request on one file should get a focused file review; a broad request like "audit this tool window" should map the surface, sample representative files, and report systemic patterns. ## Relationship To Agent Review Capabilities - For a quick second opinion on current changes, use an available read-only review subagent. - For cleanup or consolidation after implementation, use an available cleanup or refactoring subagent, then review the diff. - For a slow investigative review, use available deeper review subagents or specialist reviewers. - For a Compose UI architecture and runtime review specifically, use this skill directly. ## Scope In scope: - composition-vs-presenter boundary violations - app/state/workflow logic inside composables - `remember`, `derivedStateOf`, and local state misuse - `LaunchedEffect`, `DisposableEffect`, `snapshotFlow`, and coroutine-scope misuse - lazy-list keys and `contentType` - The audit covers modifier forwarding and order, composable size, file organization, KDoc, and reusable composable API shape. - Review Detekt and Compose-rules signals that affect UI API contracts, state ownership, effects, or hot-path performance. - recomposition/performance smells in Compose Desktop code - The audit checks animation API choice, remembered animation state, target-driven effects, and phase-correct animated reads. - desktop flow collection and coherent screen projections - state-holder shape and testability - The audit covers desktop seams including focus, keyboard shortcuts, dialogs and file pickers, clipboard and open URI handling, popups, window-local state, and protocol or runtime-backed UI boundaries. Out of scope unless the user explicitly asks: - Defer Jewel component choice, theme wrappers, icon APIs, and typography details to `jewel-ui`. - low-level Swing/AWT interop mechanics; defer to `jewel-swing-interop` - Android-specific topics include Android lifecycle, `collectAsStateWithLifecycle`, Navigation, Material, Accompanist, baseline profiles, and R8. - numeric Android-style 0-100 scoring - broad Detekt cleanup unrelated to Compose UI architecture ## Output Shape ```markdown ## Summary [overall posture: healthy / targeted cleanup needed / risky] ## Top findings 1. [severity] [finding] — `path:line` 2. ... ## Category notes ### Boundary and state ownership ### Desktop lifecycle and flow collection ### Effects and coroutine usage ### Lazy lists, animation, and recomposition ### Modifier/API shape ### Desktop interop seams ## Top 3 fixes 1. ... ## Confidence and limits [what was sampled, what was not checked] ``` Do not assign numeric scores by default. If the user explicitly requests scoring, read [reporting-guidance.md](references/reporting-guidance.md), label scoring as a project-specific heuristic, and avoid importing Android release metrics. ## Audit Process ### 1. Confirm target If the user gives paths, audit those. Otherwise locate the UI source root from the project's architecture docs or by searching for `@Composable`. Skip generated/build directories and tests unless the user asks. ### 2. Map the surface Find representative files before judging: - screens and full layouts - reusable components - timeline / lazy-list surfaces - settings panels - permission/review workflow UI - state-holder classes - presenter projection classes consumed by UI For broad audits, name the sampled surface in the report. ### 3. Gather evidence Treat search hits as candidate locations and read the surrounding code before reporting a finding. For the full pattern list, read [audit-search-patterns.md](references/audit-search-patterns.md). ### 4. Judge by desktop Compose categories Use the category checklist below, but avoid re-reading every reference file. Open only the reference files needed for actual evidence you find. | Category | What to check | Read when deeper diagnosis is needed | |---------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | Boundary and state ownership | Business/app logic in composition, broad app-state reads, local state shadowing app state, presenter objects passed into leaf components, direct IJPL API/`Project` parameter leaks in `@Composable` (use abstract state or explicit provider boundaries, no lazy `CompositionLocal` minting like `LocalProject`) | [boundary-violations.md](references/boundary-violations.md) | | Desktop lifecycle and flow collection | Multiple raw flows that must be coherent, resource-producing flows started from leaves, composition-owned file watchers/subprocesses/loops | [effects/overview.md](references/effects/overview.md) | | Effects and coroutine usage | Work launched from bodies, bad effect keys, stale callbacks, missing cleanup, noisy `snapshotFlow`, business workflows in effects | [effects/overview.md](references/effects/overview.md) | | Lazy lists and recomposition | Missing stable keys/content types, per-row lookups, row/model churn, hot-path transforms, stale `remember` caches for theme/environment-derived UI values | [lazy-layouts/overview.md](references/lazy-layouts/overview.md), [stability/overview.md](references/stability/overview.md) | | Animation | Wrong animation API, unremembered `Animatable`, target-driven animation launched from composition, per-frame values read during composition, broad `AnimatedContent` targets, offscreen infinite transitions | [compose-ui-architecture animation](../compose-ui-architecture/references/animation.md), [modifiers/overview.md](references/modifiers/overview.md), [lazy-layouts/animate-item.md](references/lazy-layouts/animate-item.md) | | Modifier/API shape | Swallowed modifiers, missing/misordered `modifier`, `MutableState`/`State` component APIs, unstable or mutable parameters, event/content-slot parameter shape, action/presenter `CompositionLocal`s, unnecessary `Modifier.composed {}`, huge/deeply nested composables, poor file ordering, missing/stale KDoc on reusable composables | [api-hygiene.md](references/api-hygiene.md), [modifiers/overview.md](references/modifiers/overview.md) | | Desktop interop seams | AWT/Swing details in leaves, shortcut paths bypassing presenter checks, persisted window/session policy in `remember`, protocol/runtime work in UI | [subcomposition/overview.md](references/subcomposition/overview.md) | ### Composable Size, Nesting, And API Hygiene When the target includes reusable component APIs, public/cross-file composables, Detekt findings, or lint-like Compose smells, read [api-hygiene.md](references/api-hygiene.md). It distils Detekt's comments/naming/complexity/coroutines/ performance guidance and Nacho López' Compose Rules into Compose Desktop/Jewel audit heuristics. Review composables as production code, not as throwaway markup. Flag composables that are so large, deeply nested, or mixed-purpose that they obscure state ownership, make recomposition behavior hard to reason about, or prevent focused testing/reuse. Prefer findings that point to a specific extraction boundary: a toolbar, row, empty state, footer, popup, repeated section, or distinct branch. Do not ask for arbitrary fragmentation; extraction should make the UI easier to read, name, test, or reuse. Also check file organization and API polish: 1. public screen/entry-point composables should appear near the top of the file; 2. private sub-composables should generally follow in top-down usage order; 3. helpers/constants should stay close to the code that uses them unless project conventions say otherwise; 4. public or cross-file reusable composables should have KDoc explaining purpose, important parameters, slot expectations, and non-obvious behavior. For private helpers, KDoc often means the helper needs a clearer name or smaller scope instead. For reusable component API design, use the AndroidX Compose API guidelines as high-level reference material, adapted for Compose Desktop/Jewel and without importing Android-only assumptions: - [Compose API guidelines](https://android.googlesource.com/platform/frameworks/support/+/androidx-main/compose/docs/compose-api-guidelines.md) - [Compose component API guidelines](https://android.googlesource.com/platform/frameworks/support/+/androidx-main/compose/docs/compose-component-api-guidelines.md) ### Theme And Environment-Sensitive `remember` Keys Check `remember(...)` calls that cache UI values derived from theme, density, locale, font scale, window state, Swing LaF defaults, or similar environment-provided state. Coarse keys such as a theme name, LaF name, dark-mode boolean, or no key can leave stale UI. Underlying colours, typography, metrics, strings, shortcut text, or defaults can change without that coarse label changing. Report this only when stale output is plausible and user-visible. Good fixes are, in order: 1. remove `remember` if the calculation is cheap; 2. pass the concrete inputs used by the calculation as `remember` keys; 3. key by a framework-provided theme/environment change token when the dependency is broad or not practical to enumerate, such as `JewelTheme.instanceUuid` in Jewel code. Do not mechanically demand more keys for every `remember`; the finding needs a concrete stale-cache risk. ### 5. Optional: performance diagnosis If the task involves jank, slow UI, or recomposition issues, measure before diagnosing and again after any proposed fix. Use the relevant existing reference instead of duplicating the procedure here: - Measurement methodology: [measurement/overview.md](references/measurement/overview.md) - Compiler stability reports: [stability/overview.md](references/stability/overview.md) - Modifier phase violations: [modifiers/overview.md](references/modifiers/overview.md) - Lazy list scroll perf: [lazy-layouts/overview.md](references/lazy-layouts/overview.md) - Subcomposition overhead: [subcomposition/overview.md](references/subcomposition/overview.md) ### 6. Optional: Perfetto tracing Use these guides when investigating jank, recomposition, or rendering performance with trace evidence: - Setup: [tracing-setup.md](references/tracing-setup.md) - Usage: [tracing-usage.md](references/tracing-usage.md) ## Reporting Rules Read [reporting-guidance.md](references/reporting-guidance.md) before producing the final report. In short: - Cite concrete file paths and line numbers where possible. - Prefer 2-4 representative examples for systemic findings. - Do not infer runtime problems from a grep hit alone. - Do not double-count one root cause across categories. - Separate Compose runtime/architecture findings from Jewel component-choice findings. - When no serious issues are found, say so with confidence/limits and low-priority polish only.