Skip to content

aldefy/compose-skill / skills/compose-expert

compose-expert

Unverified

Compose and Compose Multiplatform expert for UI development across Android, Desktop, iOS, and Web. Use whenever the user mentions Compose APIs (@Composable, remember, LaunchedEffect, NavHost, MaterialTheme, LazyColumn, Modifier, recomposition), Compose Multiplatform (commonMain, expect/actual, Res.*, ComposeUIViewController, UIKitView, ComposeViewport), Android TV (tv-material, D-pad, focus, Carousel), Material 3 motion, atomic design systems, design-to-code workflows, Paging 3, or navigation. Activates Review Mode on GitHub PR URLs and review phrases ("review this PR", "what's wrong with this"). Auto-detects Compose projects on session_start. Backed by actual androidx/androidx and JetBrains/compose-multiplatform-core source receipts. See "## When this skill applies" in SKILL.md for the full trigger surface.

FileKindSize
SKILL.mdskill md24.8 KB
agents/openai.yamlconfig278 B
references/accessibility.mdmarkdown11.2 KB
references/adaptive-layout-input.mdmarkdown5.2 KB
references/agentic-ui-a2ui.mdmarkdown4.7 KB
references/agsl-shaders.mdmarkdown11.5 KB
references/animation.mdmarkdown41.7 KB
references/appfunctions.mdmarkdown5.8 KB
references/appstate.mdmarkdown3.9 KB
references/atomic-design.mdmarkdown10.7 KB
references/auto-init.mdmarkdown1.6 KB
references/car-compose.mdmarkdown6.7 KB
references/composition-locals.mdmarkdown6.9 KB
references/deprecated-patterns.mdmarkdown8.3 KB
references/design-to-compose.mdmarkdown23.5 KB
references/graphics-modern.mdmarkdown2.6 KB
references/ink.mdmarkdown5.1 KB
references/lists-scrolling.mdmarkdown14.5 KB
references/material3-motion.mdmarkdown14.9 KB
references/media3-compose.mdmarkdown1.7 KB
references/ml-kit-agentic.mdmarkdown5.5 KB
references/modifiers.mdmarkdown13.6 KB
references/multiplatform.mdmarkdown21.1 KB
references/navigation-migration.mdmarkdown14.6 KB
references/navigation.mdmarkdown11.0 KB
references/official-android-skills.mdmarkdown2.7 KB
references/paging-mvi-testing.mdmarkdown6.4 KB
references/paging-offline.mdmarkdown6.4 KB
references/paging.mdmarkdown11.1 KB
references/performance.mdmarkdown22.7 KB
references/platform-specifics.mdmarkdown20.2 KB
references/pr-review.mdmarkdown14.1 KB
references/production-crash-playbook.mdmarkdown25.3 KB
references/remote-compose.mdmarkdown3.7 KB
references/side-effects.mdmarkdown13.0 KB
references/source-code/cmp-source.mdmarkdown17.8 KB
references/source-code/foundation-source.mdmarkdown560.9 KB
references/source-code/material3-source.mdmarkdown836.1 KB
references/source-code/navigation-source.mdmarkdown118.8 KB
references/source-code/runtime-source.mdmarkdown449.0 KB
references/source-code/ui-source.mdmarkdown313.1 KB
references/state-management.mdmarkdown17.6 KB
references/styles-experimental.mdmarkdown14.5 KB
references/text-editing.mdmarkdown3.8 KB
references/theming-material3.mdmarkdown13.0 KB
references/tv-compose.mdmarkdown30.2 KB
references/view-composition.mdmarkdown20.0 KB
references/wear-compose.mdmarkdown2.0 KB
references/xr-compose.mdmarkdown5.1 KB

references/pr-review.md

View on GitHub
# PR Review Mode

Activate when: input contains a GitHub PR URL (`github.com/.+/pull/\d+`) or explicit review
phrases: "review this PR", "review this diff", "check this code", "what's wrong with this".

When Review Mode activates:
1. Do **not** follow the generation workflow in `SKILL.md`
2. Follow this document for the workflow and report format
3. Also read the topic reference(s) for the dimensions under review (see Quick Routing in
   `SKILL.md`): this checklist does not cover draw cost, shaders, or state-read phases
4. Output a structured local report — do not post to GitHub

**Local file or directory (no PR URL):** skip Steps 1–2 (the `gh` steps). Read the named file(s)
in full, then continue from Step 3.

---

## Review Workflow

### Step 1 — Fetch the diff

```bash
gh pr diff <PR_URL>
```

Note all changed `.kt` files. Store the output.

### Step 2 — Fetch full file contents

For each changed `.kt` file, fetch the **complete file** — not just the diff lines.

```bash
# Get PR metadata
gh pr view <PR_URL> --json headRefName,headRepository \
  --jq '{branch: .headRefName, repo: .headRepository.nameWithOwner}'

# Fetch full file (replace {owner}, {repo}, {path}, {branch})
gh api "repos/{owner}/{repo}/contents/{path}?ref={branch}" \
  --jq '.content' | base64 -d
```

**Why full files matter:** The diff shows what changed. The full file shows what the composable
actually looks like — including whether a `modifier` parameter exists at all, and how modifier
chains are structured across multiple lines. Single-line modifier patterns like
`Row(modifier = Modifier.fillMaxWidth().padding(16.dp)) {` are invisible in a diff-only view
when that line itself was not modified.

### Step 3 — Scan project settings

Run in priority order. Always run step d regardless of what lint config is found.

**a. `.editorconfig`:**
```bash
cat .editorconfig 2>/dev/null || echo "not found"
```
Note: indent size, max line length, trailing comma rules under `[*.kt]`.

**b. ktlint config:**
```bash
grep -A 20 "\[\*\.kt\]" .editorconfig 2>/dev/null
cat .ktlint 2>/dev/null || echo "not found"
```

**c. detekt:**
```bash
find . -name "detekt.yml" -o -name "detekt-config.yml" 2>/dev/null | head -3
```
If found, read it and note complexity, naming, and style rules.

**d. Infer codebase conventions (always run):**
```bash
# Find 3–5 existing composable files NOT in the diff
find . -name "*.kt" -not -path "*/build/*" | xargs grep -l "@Composable" | \
  grep -v "Test" | head -5
```
For each file, note:
- Modifier chaining: one per line vs. inline on constructor line
- Modifier parameter name: `modifier` vs `Modifier` (both are valid — note which team uses)
- Trailing lambda vs. named `content =` on single-slot composables
- Named parameter usage on single-arg calls

Build a **project profile**. Use it to suppress false positives — flag deviations from the
team's own conventions, not deviations from an external style guide.

### Step 4 — Run the checklist

Evaluate every changed composable against all 6 categories below.
Use the **full file** from Step 2, not the diff from Step 1.

### Step 5 — Output the report

Use the format at the end of this document.

---

## Compose Review Checklist

### Category 1: Modifier Hygiene

Scan the full file for each changed `@Composable` function.

- [ ] **Modifier parameter present.** Every `@Composable` function that renders UI must have
  a `modifier: Modifier = Modifier` parameter. Flag if absent.
  Exception: private composables used only as internal implementation detail with no layout impact.

- [ ] **Modifier passed to root element.** The `modifier` parameter must be applied to the
  outermost layout composable in the function body — not ignored, not applied to an inner element,
  not used on a sibling.

- [ ] **Modifier not duplicated.** `modifier` must not be split across two sibling elements.
  One root element receives it.

- [ ] **Modifier ordering follows the paint model.** Work outward-in:
  `size / fillMaxWidth` → `padding` → `background / border` → `clickable / pointerInput`.
  Remember a later modifier can only *shrink* the constraints, never grow them: with this
  order `padding` insets the content *inside* the fixed size (footprint unchanged). To make
  the padding *add* to the footprint, put `padding` **before** `size`.
  Flag these specific reversals:
  - Wrong `background` / `padding` order for the intent
    (`Modifier.background(Color.Red).padding(16.dp)` = background paints the **outer** area,
    padding then insets the content = background *includes* the padded border;
    `Modifier.padding(16.dp).background(Color.Red)` = padding insets first, so the background
    paints only the **inner** content area and does NOT cover the padded border)
  - `padding()` before `clickable()` — excludes the padding from the touch target, shrinking it.
    `clickable()` before `padding()` makes the whole padded area tappable (usually what you want).
  - `size()` or `fillMaxWidth()` after `padding()` when the intent is padding-adds-to-footprint —
    the earlier `padding` gets absorbed into the fixed size instead of expanding it. (This order is
    fine when you *want* the padding to inset content inside a fixed size — flag only against intent.)

- [ ] **Single-line modifier check.** Read the full constructor line even when unchanged in the diff.
  Verify ordering is correct even when the entire modifier chain is written inline:
  `Row(modifier = Modifier.fillMaxWidth().padding(16.dp).clickable { })` — this has wrong ordering
  (`padding` before `clickable` excludes the 16.dp from the touch target, shrinking it).

- [ ] **No `padding` + `offset` for the same adjustment.** `offset` does not affect layout;
  `padding` does. They are not interchangeable.

### Category 2: Recomposition

- [ ] **Unstable parameters are intentional and measured:**
  - Plain `List<T>` is unstable, but strong skipping can skip it when the same
    instance is passed. Use immutable collections/wrappers when value equality
    and the stability contract justify the change—not as a ritual annotation.
  - `HashMap`, `MutableMap`, any mutable collection — not stable
  - Non-`data` class without `@Stable` — compiler cannot infer stability

- [ ] **Lambda allocation matches the compiler mode.** With strong skipping
  (default on Kotlin 2.0.20+), lambdas inside composition are remembered automatically.
  ```kotlin
  // Fine under default strong skipping.
  MyComposable(onClick = { doSomething() })

  // OK — stable reference
  val onClick = remember { { doSomething() } }
  MyComposable(onClick = onClick)
  ```
  Only add manual `remember` when supporting an older compiler mode or when
  measurement shows a real allocation/identity issue.

- [ ] **`derivedStateOf {}` used where it pays off.** Flag a value computed from **State that
  changes much more often than the result**, read in a scope that is otherwise expensive, with
  no `derivedStateOf`. Do not flag cheap predicates on state the scope already needs:
  ```kotlin
  // Worth flagging: scroll offset changes every frame, the boolean rarely does
  val showButton = listState.firstVisibleItemIndex > 0   // read in a large scope

  // OK
  val showButton by remember { derivedStateOf { listState.firstVisibleItemIndex > 0 } }
  ```

- [ ] **`remember {}` keys are correct.**
  - Missing keys but referencing an input variable inside — stale value bug
  - Key that never changes (`remember(Unit)` or `remember(constant)`) — effectively `remember {}` with no recalculation

### Category 3: M3 Motion

Cross-reference with `references/material3-motion.md` for token values and easing names.

- [ ] **Durations and easings come from the theme or named constants.** Prefer
  `MaterialTheme.motionScheme` specs inside M3-styled components. Flag a bare `tween(N)` only when
  it is not user-configurable or intentionally custom. `MotionTokens` is `internal` to material3:
  never suggest app code reference it; suggest a named constant with the token's value instead.

- [ ] **Easing choice is deliberate.** `FastOutSlowInEasing` and friends are valid public
  easings; do not flag them as errors. Suggest `motionScheme` (or an emphasized `CubicBezierEasing`
  constant) only for M3-styled components that should follow the app's motion scheme.

- [ ] **`animateColorAsState` has an `animationSpec`.** No-spec `animateColorAsState(target)`
  uses the default spring which is inappropriate for color transitions.
  Suggest: `animationSpec = MaterialTheme.motionScheme.defaultEffectsSpec()`

- [ ] **`AnimatedVisibility` enter/exit easing is asymmetric.** Enter must use Decelerate easing;
  exit must use Accelerate easing. Same easing for both is incorrect.

- [ ] **No non-shared-element animation > 600ms.** Flag durations above `DurationLong4` (600ms)
  unless the animation is a shared element or full-screen transition.

- [ ] **New components use `MotionScheme` not raw `tween()`.** A new component accepting no
  `AnimationSpec` parameter should use `MaterialTheme.motionScheme.defaultSpatialSpec()` /
  `defaultEffectsSpec()` to be theme-motion-aware.

### Category 4: CMP Compatibility

Apply only to files whose path contains `commonMain` or has no platform-specific path segment.

- [ ] No `android.*` imports (`android.content.Context`, `android.util.Log`, etc.)
- [ ] No `androidx.*` imports that are Android-only. Check `references/multiplatform.md`
  API availability matrix for what is available in `commonMain`.
- [ ] No `LocalContext.current` — not available in CMP `commonMain`
- [ ] No `Activity`, `Context`, or `Application` references
- [ ] Resources via `Res.drawable.*` / `Res.string.*` — not `R.drawable.*` / `R.string.*`

### Category 5: Lists & Keys

- [ ] **Every `items()` call has a `key = {}`** in `LazyColumn`, `LazyRow`, `LazyVerticalGrid`,
  `LazyHorizontalGrid`. Missing keys cause incorrect animations and item reuse bugs.
  ```kotlin
  // BAD
  items(movies) { movie -> MovieCard(movie) }

  // OK
  items(movies, key = { it.id }) { movie -> MovieCard(movie) }
  ```

- [ ] **`contentType = {}` present for heterogeneous lists.** When a lazy list renders more than
  one type of composable (e.g., headers + items), `contentType` must be specified so Compose
  reuses composition nodes correctly.

- [ ] **No `LazyColumn` directly nested inside `LazyColumn`** without a fixed height on the inner
  one. Unbounded nested lazy lists throw `java.lang.IllegalStateException` at runtime.

- [ ] **`TvLazyRow` / `TvLazyColumn` / `TvLazyVerticalGrid` / `TvLazyHorizontalGrid` from
  `tv-foundation` flagged as deprecated.** Replace with standard Foundation equivalents.
  See migration table in `references/tv-compose.md` Section 5.

### Category 6: Atomic Design

Cross-reference with `references/atomic-design.md` for token patterns and naming rules.

- [ ] **No hardcoded `Color(0xFF...)` inside composable bodies.** Colors must come from
  `MaterialTheme.colorScheme.*` or an app-level brand token (`CompositionLocal`).
  Exception: `Color.Transparent`, `Color.Unspecified`, and `Color.White`/`Color.Black` as
  explicit design choices are acceptable.

- [ ] **No hardcoded `fontSize`, `fontWeight`, or `TextStyle(...)`.** Typography must come from
  `MaterialTheme.typography.*`. Flag any inline `TextStyle(fontSize = 14.sp)` or
  `fontWeight = FontWeight.Bold` outside of a theme definition file.

- [ ] **No magic number spacing (`16.dp`) without token.** If the project defines a spacing
  scale (check for `CompositionLocal` with spacing values), flag raw `dp` values that should
  use the scale. If no spacing scale exists, note it as a suggestion — not a critical issue.

- [ ] **Composable names describe function, not context.** Flag composables matching these
  patterns: `*For*` (e.g., `ButtonForSettings`), `*With*` (e.g., `CardWithRedBorder`),
  `*In*` (e.g., `HeaderInHome`). Exception: `*WithDefaults` pattern used for providing
  default parameters is acceptable.

- [ ] **Public composables have `modifier: Modifier = Modifier`.** (Overlaps Category 1 — in
  atomic context, additionally verify the modifier is passed to the root element and not
  consumed by an inner element.)

- [ ] **Composables rendering variable content have slot APIs.** Flag composables that hardcode
  `Text("Submit")`, `Icon(Icons.Default.Close, ...)`, or similar fixed content that should
  be a slot parameter. Exception: internal/private composables with fixed content by design.

- [ ] **Organisms do not directly reference ViewModel.** Any composable that combines multiple
  UI components (organism-level) must accept data and callbacks as parameters. Flag direct
  `viewModel()`, `hiltViewModel()`, or `koinViewModel()` calls inside organisms.
  The screen-level composable is the correct place for ViewModel access.

---

## Output Report Format

```
## PR Review: <PR title> (#NNN)
Branch: <head-branch> → <base-branch>

### Project Profile
- Code style: <inferred — e.g. "modifier chains one per line", "trailing lambdas preferred">
- Lint config: <ktlint / detekt / neither found>
- Conventions from: <files sampled>

---

### Issues

#### Critical
Issues that cause bugs, crashes, or correctness problems.

- `path/File.kt:42` — `MyCard` is missing `modifier: Modifier = Modifier` parameter. All UI
  composables must expose a modifier for caller layout control.
  Fix: add `modifier: Modifier = Modifier` to the signature; pass to the root element.

#### Suggestions
Style, M3 alignment, and performance improvements.

- `path/File.kt:87` — `tween(300)` → `MotionTokens.DurationMedium2.toInt()` (300ms = Medium2)
- `path/File.kt:103` — `FastOutSlowInEasing` → `MotionTokens.EasingEmphasizedCubicBezier`
- `path/File.kt:115` — `items(movies)` missing `key = { it.id }` — add key to prevent reorder bugs

#### Positive Patterns
Good Compose usage — always include at least one.

- `path/File.kt:55` — Correct `derivedStateOf {}` preventing redundant recompositions
- `path/File.kt:71` — `sharedBounds()` used correctly for container-to-page expansion

---

### Summary
<N> critical, <M> suggestions across <K> files reviewed.
```

**Sections policy:**
- Critical and Suggestions are always present (write "None found" if empty)
- Positive Patterns is always present — reviews must not read as a pure hit list
brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation).Stars: 322kUpdated Claude CodeCodexVerifiedInstall
brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK).Stars: 198kUpdated Claude CodeCodexVerifiedInstall