<!-- Generated by community/.ai/render-guides.mjs; edit community/.agents/skills/jewel-ui-audit/SKILL.md -->

Jewel UI Design Review

Review Compose UI built with JetBrains Jewel for two intertwined concerns:

1. UX quality — is every visual value themeable, is each custom component or treatment justified, does interaction behavior match what IDE users expect, and are the expected states present?
2. Jewel/Compose API correctness — is the code using Jewel (and, in plugins, the Swing/LaF bridge) APIs correctly and in the right way for its runtime context?

This is a UX-and-API-usage review, not an architecture, runtime-performance, or pure-accessibility review (route those elsewhere; see "When to use").

Runtime context: standalone vs. IJPL bridge (establish this first)

Jewel runs in two contexts, and the correct answer to many findings depends on which one applies. Determine it before reviewing, because it changes the right fix, not just the wording:

• Standalone Jewel (a Compose Desktop app using Jewel): theming comes from the Int UI standalone styling and palette; there is no IJ Swing LaF to replicate.
• IJPL plugin/Swing-LaF bridge (Jewel UI embedded in an IntelliJ-based IDE): theming bridges the IDE's Swing Look-and-Feel. Colors should resolve through the bridge (e.g., retrieveColorOrUnspecified("SomeKey") / retrieveColorOrNull against IDE LaF keys), the bridge theme/styling providers are used, and the surface must track IDE theme switches and LaF changes.

Using standalone-only assumptions in a plugin (or vice versa) is itself a finding. When the context is not obvious from imports/dependencies, say which you assumed.

Within the IDE/bridge context there are three theme generations:

• Old UI (pre-Int UI, such as Darcula or IntelliJ): effectively deprecated, not a design target, and missing many keys.
• New UI = Int UI: the default target.
• Islands builds on Int UI as the default in recent IJPL versions and renders tool windows as rounded islands.

Detect New UI via NewUI.isEnabled or JewelTheme.newUiChecker.isNewUi(). Islands has no Jewel-native check yet; IntelliJ Platform offers IslandsState.isEnabled (only possible under New UI). Read references/standalone-vs-bridge.md for the full distinction, API-misuse checklist, LaF-fallback rules, and theming-container pattern.

Apply three hard rules when a plugin reads values from the LaF. Missing keys break untested themes and standalone UI runs (such as UI unit tests, where no IJPL LaF exists):

• Always supply a fallback for everything read from the LaF, including colors, dimensions, insets, corner sizes, and ints. Old 1p themes lack the Int UI palette, many 3p themes lack keys, and standalone runs have no IJ LaF. Missing reads return null or Unspecified. Prefer a layered fallback: primary key, palette/secondary key, then hardcoded default.
• Always supply both a light and a dark value — palette indices mean different things in each mode, so one value cannot serve both. Jewel surfaces always need to support both light and dark variants.
• Centralize reads in a theming-container object instead of scattering raw retrieve* calls through composables. Standalone code can hardcode the defaults in that container (see references/standalone-vs-bridge.md). Read references/portability-structuring.md to structure content composables and injected theming for both plugin and standalone preview/test runs.

This skill is read/evidence-based. Search hits are leads; read the surrounding code and confirm the concern is real and user-visible (or a real API misuse) before reporting.

Evidence-first review loop

Before reporting a finding:

1. Run a quick recon pass: determine runtime context (standalone vs. bridge), theme generation/keys involved, component families, and which reference files are relevant.
2. If the harness supports subagents, split independent review areas (theme/LaF, icons, interaction/a11y, layout/state) after recon; otherwise write a short recon plan and execute the relevant areas yourself.
3. Identify the exact component/API/pattern in the snippet.
4. Cite or name the line/pattern that proves the concern is present.
5. Apply only the relevant checklist/reference; do not run a full design-system audit on unrelated parsing, model, or business logic.
6. Do not infer that a fix exists elsewhere unless the prompt or visible code shows it.
7. Do not praise a fix unless the exact API/value is present in the snippet.

For the first-pass pattern cards, read references/quick-triggers.md. Use those triggers to decide which detailed reference to open next; they are not a substitute for reading the actual code.

Authoritative reference

The upstream source for IntelliJ UI conventions is the JetBrains UI Guidelines: https://plugins.jetbrains.com/docs/intellij/ui-guidelines-welcome.html (colors, layout/spacing, controls, text, and component behavior). Although written for Swing UI, its design principles apply equally to Jewel/Compose surfaces, which must match the same IDE. These principles include flat Int UI visuals, theme-driven colors, consistent spacing, standard controls, and restrained motion.

Treat the guidelines as the design intent and this skill as how to check Jewel/Compose code against it. Cite the guidelines when a finding rests on an IDE convention (separator weight, control sizing, spacing rhythm, or color roles). Prefer existing patterns to novel ones unless there is a strong reason to diverge.

When to use

Use when authoring or reviewing Jewel/Compose Desktop UI that ships inside an IntelliJ-based IDE (platform, product, or plugin), and the question is whether the visuals and interactions are themeable and idiomatic.

Defer, or hand off, when the primary concern is:

• Use the ui-accessibility skill to audit screen readers, keyboard operability, focus order, and accessible names or roles (this skill references ui-accessibility without replacing it).
• Use the compose-ui-audit skill to review Compose composition, state, and effect architecture, recomposition, lazy-list keys, and runtime performance.
• which Jewel component or theme API to use when authoring from scratch → use the jewel-ui skill for the catalog; use this skill to judge whether an existing choice is idiomatic.

These overlap. It is fine to raise a finding that also belongs to another skill; say so and keep the design-system reasoning here.

The core questions

Apply these to every styled element, custom component, and interaction. They are the core of the skill.

1. Is this themeable, or is it hardcoded? Every color, dimension, and shape must resolve to a context-appropriate theme source or derive from one:
   • Standalone surfaces use Jewel global colors or Int UI palette entries; bridge surfaces use IDE LaF keys via retrieveColor*.
   • Theme resolution lets UI respond to theme switches, custom themes, high contrast, and IDE zoom. Treat literal Color(...)/Color.X calls or bare dp magic numbers as leads.
2. Is the semantic role correct? A token's role noun must match how it is used. A border color must not fill a background; a foreground/text color must not paint a container; a disabled color must not style enabled content.
3. Is the Jewel/bridge API used correctly for this context? Standalone and bridge modes use different styling providers, theme entry points, and color sources (see references/standalone-vs-bridge.md). Reaching around Jewel to raw Swing/UIManager/JBColor from Compose, or using standalone palette entries in a plugin that must read LaF keys, is an API-usage finding.
4. No IJPL API interactions in composition (IJPL leaks): Direct interactions with IJPL platform objects or singletons in composition (EditorColorsManager.getInstance(), Project) violate Compose architecture:
   • Passing Project (com.intellij.openapi.project.Project) into @Composable functions leaks platform coupling and breaks stability tracking (Project lacks stable equals/hashCode), causing recomposition churn.
   • Do not mint ad-hoc CompositionLocals like LocalProject to pass platform instances implicitly. Use abstract state and explicit provider boundaries instead.
5. Is this custom treatment justified, and is there a built-in instead? Prefer Jewel built-ins (Divider, SimpleListItem, SingleSelectionLazyColumn/MultiSelectionLazyColumn, group headers, standard scrollbars) over bespoke components. A custom treatment needs a concrete requirement the built-in cannot meet. Flag structural component reinvention (such as hand-rolling menus or lists) before reviewing micro-styling or custom hover states.
6. Does the treatment match Int UI conventions and user expectations? IntelliJ's language is flat and restrained. Material concepts (elevation/drop shadows, ripples, FABs) are foreign. Interaction affordances (hover lift, zoom, pointer changes) must be justifiable and signal real behavior, not decoration.

Review areas

Theming and color fidelity

Start with references/quick-triggers.md for palette-index, custom-key, and bridge-read trigger cards. Read references/theming-and-color.md when you find color or dimension literals, or suspect a wrong color role. In the bridge/plugin context, read references/bridge-laf-read-api.md for the LaF read-helper catalog and safe-vs.-raw fallback forms.

Read references/ijpl-theming-and-editor-scheme.md when a surface touches editor/syntax content, reads EditorColorsManager/EditorColorsScheme, captures JBColor into Compose colors, or caches theme values across switches. The UI LaF and editor color scheme are independent systems with separate change events.

Read references/theme-key-resolution.md when reviewing *.theme.json files (missing keys, parent inheritance, * wildcards, per-OS values, nested-key flattening, or named-color aliases) to see how the loader populates UIDefaults.

Flag:

• Literal colors in UI: Color(0x...), Color.Red, Color.DarkGray, etc. Resolve to a Jewel global color, an Int UI palette entry, or a Swing LaF key instead. Replacing a previously themed value with a literal is a strong red flag, especially when the original themed value sits commented out beside it.
• Semantic role mismatches. The worst common case is a borders.* token used as a .background(...) fill: border tokens are tuned for 1 px separators and diverge from panel/background tokens under custom themes. Use a content/panel background role.
• Components must not repeat magic-number dimensions and shapes such as RoundedCornerShape(8.dp), paddings, and sizes across files without a shared token. Reviewers must also verify how those dimensions respond to IDE zoom and density, including the .compact density variants that Int UI and Islands expose.
• Raw palette assumptions: referencing a palette entry directly instead of a semantic role, or assuming a palette index maps consistently across themes. Old, Int UI, and Islands themes number differently and even reverse direction. The palette is not semantic; components must use role tokens.
• Flag any LaF read (color, dp, insets, or arc) that lacks a fallback or uses a single color for both light and dark modes, violating the hard rules above.

Do not flag a value derived from the theme just because it contains a literal. A size computed as an offset or scale of JewelTheme.defaultTextStyle.fontSize scales with IDE font settings and is the model to follow. The rule is "themeable by derivation," not "no numbers anywhere."

Mechanism note: Jewel typography and platform JBFont derive sizes additively via biggerOn/lessOn, not by a fixed multiplier. Do not assert a specific ratio as the type scale; require derivation from the theme base.

Idiomatic components and Int UI conventions

Read references/idiomatic-components.md for the built-in vs custom decision and the Int UI concept boundaries.

Flag:

• Int UI surfaces must not use Material concepts such as shadowElevation or drop shadows via graphicsLayer, Material ripples, or FAB-like floating buttons. Components must express grouping and state with borders, background-fill deltas, and selection instead.
• Custom components that duplicate a Jewel built-in (hand-rolled dividers, list items, selectable lists, scrollbars). Heavy non-standard treatments (e.g., a 4.dp divider where IDE separators are 1.dp) need explicit justification.
• Decorative-only complexity: a bespoke component or effect that adds no capability a built-in lacks.
• Editor/window registration policy treated as plumbing. For a FileEditor/tool-window surface, check getPolicy() and similar: FileEditorPolicy.HIDE_OTHER_EDITORS (or anything that seizes the frame or forces focus) is a UX takeover that is wrong for a non-modal informational screen. This lives in a provider/factory file, not the composable, so look for it deliberately.
• Icons loaded by hand-built path or Image(painterResource(...)) instead of an IconKey + the Icon composable/painter provider. Hand-built loading loses New-UI path mapping, dark variants, and theme recoloring.
  • For hardcoded filename variants, name the exact path divergence: Swing IconLoader may look for @2x.svg, while Jewel's HiDpi hint does not apply @2x to SVGs. A Jewel load failure renders magenta, whereas classic Swing often fails blank or silent.
  • For stateful Jewel icons, state that specialized variants (Selected, Disabled, _dark) are optional fallbacks. The bare base icon must exist because Jewel falls through to it at the end of the hint branch.
• Icon over-tinting & fill alpha clobbering: Tinting applies only to monochrome or stroke-based icons:
  • Use Jewel's PainterHint.Stroke(color) (or IconActionButton/SelectableIconActionButton, which pass Stroke) at load time for stroke-based SVGs.
  • Do not apply Compose layer-level ColorFilter.tint() to filled, multi-color, or gradient icons; it clobbers fill alpha and interior details to solid colors. Never mix PainterHint.Stroke(color) with ColorFilter.tint(). See references/icon-loading.md.
• Cross-plugin/cross-module icon references that resolve against the wrong classloader: Icons bind to a ClassLoader. Referencing another plugin's icon class or resource often works from sources but breaks silently in packaged builds due to isolated per-plugin classloaders.
  • Read references/icon-loading.md for IconKey/PainterHint, AllIcons/IconLoader, and classloader traps.
  • For the experimental com.intellij.platform.icons framework, read references/icon-loading-experimental.md (do not call it unbundled; the concern is @Internal/@Experimental API stability).

Interaction semantics

Start with references/quick-triggers.md for validation, text-selection, focus, and list trigger cards. Then read references/interaction-and-affordances.md for hover/focus/keyboard, tooltip, and context-menu patterns, references/accessibility-semantics.md for contentDescription and focus/keyboard semantics handoff, and references/selection-and-lists.md for selectable lists, text-selection scope, and scroll-derived selection.

Flag:

• Hover/elevation/zoom on non-interactive elements. Lift, scale, and z-raise read as "clickable/activatable"; applying them to a non-clickable card or image communicates a false affordance. Stacking two "z-axis up" effects (e.g., elevation increase and zoom on the same hover) is doubly wrong.
• Flag hand-rolled hover states on an IJPL bridge row, plain label, or container:
  • In bridge mode, swingCompatMode suppresses hover/pressed for many controls and plain rows stay flat, so custom hoverable/collectIsHoveredAsState highlights stand out.
  • Basic list items do not need custom hover handling, and backgroundActive is for active/pressed states, not hover. Always name the exceptions that do hover in the bridge: tabs, scrollbars, and icon buttons (not plain rows).
• Selectable lists built as a Column/LazyColumn with manual selected = ... + .clickable { } instead of SingleSelectionLazyColumn/MultiSelectionLazyColumn (which replaced deprecated SelectableLazyColumn, usually with SimpleListItem rows):
  • SimpleListItem is the right row component; the defect is hand-rolling the selection container, which owns selection state, keyboard navigation (arrows, home/end), and focus. Check speed search separately for non-trivial lists.
  • If a justified fork reuses SimpleListItem for the row body, preserve that reuse in Justified as-is instead of recommending raw Text/custom rows.
• Non-standard list scrolling or claiming scrollToItem is "laggy": IDE lists use instant step jumps (scrollToItem) during keyboard navigation to match platform desktop conventions, not smooth animated scrolling (animateScrollToItem). Instant step jumps are intentional; do not claim they are laggy.
• Non-trivial or searchable lists, trees, and combo boxes with no speed search (type-to-filter). Speed search is the default IDE affordance unless a visible search/filter field exists. Selection columns do not include speed search automatically; wrap with SpeedSearchableLazyColumn/SpeedSearchArea (or SpeedSearchableTree/ SpeedSearchableComboBox). See references/selection-and-lists.md.
• Selection or "active item" derived from scroll position (such as items[lazyListState.firstVisibleItemIndex]). At the end of scroll, the last item sits at the bottom of the viewport while an earlier item owns the top. As a result, trailing items never become "first visible." A working active-section model special-cases end-of-scroll and keys off a threshold crossing.
• Over-broad text selection on a read-only surface (whole-region SelectionContainer or selectable = true over a composite layout). This shows the text I-beam cursor over non-text layouts, images, and padding, and lets selection bleed across sections.
  • Scope selection to text runs where copying is needed, or leave read-only surfaces non-selectable with an arrow pointer. Even selectable UI labels outside text fields (such as error messages) must avoid the I-beam cursor.
  • Contrast protected and unprotected controls nested inside selectable content (for example, "the Install button uses DisableSelection, but the More IconButton does not"). Every nested action control needs DisableSelection and arrow-pointer handling.
• Missing tooltips where an IDE user expects them: icon-only controls (toolbar/icon buttons with no visible label) and truncated/ellipsized text (rows, tabs, breadcrumbs). Use Jewel's Tooltip component; keep content factual (action name, shortcut, full value). Overlaps ui-accessibility for icon buttons. See references/interaction-and-affordances.md.
• Missing or hand-rolled context menus: right-click unhandled on selectable text or on actionable rows/items where right-click is the expected path to actions/copy. Use Jewel's TextContextMenu for text and the built-in menu/popup components for item menus, not a bespoke dropdown (Jewel's internal ContextMenu is not a public entry point). See references/interaction-and-affordances.md.

Spacing and layout

Start with references/quick-triggers.md for resizable-pane, prose-width, and raw-scroll trigger cards. Then read references/spacing-and-layout.md for the additive-stacking analysis pattern.

Flag:

• Spacing owned at multiple nesting layers at once, so values stack additively. A gap between siblings should come from one source (the parent's Arrangement.spacedBy), not parent arrangement plus each child's outer padding plus a grandparent arrangement. Compute the effective gap by hand to expose the stack.
• Per-axis asymmetry produced by different mechanisms. Uniform padding(8.dp) works horizontally, but vertical spacings can stack on top of it, yielding smaller horizontal margins inside oversized vertical margins. Compare horizontal and vertical spacing at each seam (inner padding, inter-item, inter-row), and check whether asymmetric margins match similar codebase layouts.
• Mixed text style baseline alignment: Alignment.CenterVertically does not align baselines when multiple text styles (such as UI font + editor code font, or mixed font sizes) share a line. Use AnnotatedString in a single Text composable when possible, or explicit baseline alignment (Row(verticalAlignment = Alignment.Bottom) or Modifier.alignByBaseline()). Always visually verify baseline alignment when fixing mixed-style text lines.
• Reusing a content-rhythm token (e.g., a Markdown blockVerticalSpacing) as a layout margin, so changing content density silently changes layout gutters. Keep content spacing and layout spacing as separate tokens.
• Flag missing shared spacing scales where files pick 8, 12, and 32 dp values independently and create accidental inner-to-gutter ratios.

State completeness, async media, and expected-but-absent behavior

Read references/async-and-states.md for the required-states checklist and the absence checklist.

This area covers expected capabilities that are absent from the code. Examples include a feed without "new since last seen" tracking, a network dependency without loading/offline states, or an emptyable view without an empty state.

Because there is no code line to grep, run the absence checklist in references/async-and-states.md against the feature's purpose and report missing capabilities with their user-facing consequence.

Flag:

• A composable gated behind async work that early-returns into blankness instead of rendering a Loading state. Any async-backed screen must define what renders during Loading and Error, not just the happy path.
• Async images that render nothing (or null into flow content) while loading: no reserved space causes layout shift as each image arrives; reserve a fixed-ratio placeholder. Provide a loading indicator/shimmer and an error affordance (alt text or broken-image state), not a silent permanent gap or vanishing into nothing.
• Flag network-fetched media on a screen whose other content is bundled offline when it lacks an offline fallback and only logs failures. Route remote media through the standard image-loading path rather than ad-hoc fetching.
• Accessibility-semantics triage overlaps with the ui-accessibility skill when checking for contentDescription = "", noisy duplicate image descriptions, or icon-only controls and toggles that lack concise action or state descriptions. Reviewers must apply references/accessibility-semantics.md for triage while routing full semantics verification to ui-accessibility.
• Hardcoded UI strings in an IntelliJ plugin, instead of using bundles/messages (V2Bundle.message(...)). Prioritize i18n bundle string usage and proper trailing ellipsis rules over subjective or pedantic nitpicks about search placeholder verb wording.
• Progress feedback missing or the wrong kind: a perceptibly long operation with no indicator, or an indeterminate spinner where the total is known and a determinate percentage/step count is possible.
• Input surfaces (settings, dialogs, forms) with no inline validation — only a disabled or post-submit failure, no field-level message. The message should localize the failing field and use the themed error role/outline, not a hardcoded red.

Output format

## Summary

[overall: idiomatic and themeable/targeted fixes/significant rework]

## Findings

1. [severity] [finding] — `path:line`
    - Why it matters (theming/role/idiom/interaction/spacing/state)
    - Suggested fix (name the built-in, token, or pattern to use)
2. ...

## Justified as-is

[custom treatments that are appropriate, with the reason — so reviewers don't churn them]

## Confidence and limits

[what was checked; what needs runtime/zoom/theme-switch/human verification]

Always include a "Justified as-is" section when the code has custom components or non-default values that are appropriate. The skill's value is as much in not flagging justified choices (and the themeable-by-derivation pattern) as in catching the violations.

Validation before finishing

• Each finding cites a concrete file/line and names the idiomatic replacement (built-in, token, or pattern), not just the problem.
• Themeable-by-derivation values are not flagged as hardcoded.
• The review acknowledges genuinely justified custom components and avoids flagging custom code automatically.
• Findings that are really accessibility, architecture, or runtime concerns are routed to the matching skill rather than re-litigated here.
• State explicitly which checks need manual verification (theme switch, high contrast, IDE zoom, screen reader).