Jewel: a Compose for Desktop theme

Jewel aims at recreating the IntelliJ Platform's New UI Swing Look and Feel in Compose for Desktop, providing a desktop-optimized theme and set of components.

[!CAUTION] Jewel is moving to the IntelliJ Platform! All active development will move to https://github.com/JetBrains/intellij-community and this repository will just mirror that. More information to follow soon — but please consider the code on this repository as read-only.

---

[!WARNING]

This project is in active development, and caution is advised when considering it for production uses. You can use it, but you should expect APIs to change often, things to move around and/or break, and all that jazz. Binary compatibility is not guaranteed across releases, and APIs are still in flux and subject to change.

Writing 3rd party IntelliJ Plugins in Compose for Desktop is currently not officially supported by the IntelliJ Platform. It should work, but your mileage may vary, and if things break you're on your own.

Use at your own risk!

Jewel provides an implementation of the IntelliJ Platform themes that can be used in any Compose for Desktop application. Additionally, it has a Swing LaF Bridge that only works in the IntelliJ Platform (i.e., used to create IDE plugins), but automatically mirrors the current Swing LaF into Compose for a native-looking, consistent UI.

[!TIP]

If you want to learn more about Jewel and Compose for Desktop and why they're a great, modern solution for your desktop UI needs, check out this talk by Jewel contributors Sebastiano and Chris.

It covers why Compose is a viable choice, and an overview of the Jewel project, plus some real-life use cases.

Getting started

The first thing to add is the necessary Gradle plugins, including the Compose Multiplatform plugin. You need to add a custom repository for it in settings.gradle.kts:

pluginManagement {
    repositories {
        google()
        gradlePluginPortal()
        maven("https://maven.pkg.jetbrains.space/public/p/compose/dev")
        mavenCentral()
    }
}

Then, in your app's build.gradle.kts:

plugins {
    // MUST align with the Kotlin and Compose dependencies in Jewel
    kotlin("jvm") version "..."
    id("org.jetbrains.compose") version "..."
}

repositories {
    maven("https://packages.jetbrains.team/maven/p/kpm/public/")
    // Any other repositories you need (e.g., mavenCentral())
}

[!WARNING] If you use convention plugins to configure your project you might run into issues such as this. To solve it, make sure the plugins are only initialized once — for example, by declaring them in the root build.gradle.kts with apply false, and then applying them in all the submodules that need them.

To use Jewel in your app, you only need to add the relevant dependency. There are two scenarios: standalone Compose for Desktop app, and IntelliJ Platform plugin.

If you're writing a standalone app, then you should depend on the latest int-ui-standalone-* artifact:

dependencies {
    // See https://github.com/JetBrains/Jewel/releases for the release notes
    implementation("org.jetbrains.jewel:jewel-int-ui-standalone-[latest platform version]:[jewel version]")

    // Optional, for custom decorated windows:
    implementation("org.jetbrains.jewel:jewel-int-ui-decorated-window-[latest platform version]:[jewel version]")

    // Do not bring in Material (we use Jewel)
    implementation(compose.desktop.currentOs) {
        exclude(group = "org.jetbrains.compose.material")
    }
}

For an IntelliJ Platform plugin, then you should depend on the appropriate ide-laf-bridge-* artifact:

dependencies {
    // See https://github.com/JetBrains/Jewel/releases for the release notes
    // The platform version is a supported major IJP version (e.g., 232 or 233 for 2023.2 and 2023.3 respectively)
    implementation("org.jetbrains.jewel:jewel-ide-laf-bridge-[platform version]:[jewel version]")

    // Do not bring in Material (we use Jewel) and Coroutines (the IDE has its own)
    api(compose.desktop.currentOs) {
        exclude(group = "org.jetbrains.compose.material")
        exclude(group = "org.jetbrains.kotlinx")
    }
}

[!TIP] It's easier to use version catalogs — you can use the Jewel version catalog as reference.

Using ProGuard/obfuscation/minification

Jewel doesn't officially support using ProGuard to minimize and/or obfuscate your code, and there is currently no plan to. That said, people are reporting successes in using it. Please note that there is no guarantee that it will keep working, and you most definitely need to have some rules in place. We don't provide any official rule set, but these have been known to work for some: https://github.com/romainguy/kotlin-explorer/blob/main/compose-desktop.pro

[!IMPORTANT] We won't accept bug reports for issues caused by the use of ProGuard or similar tools.

Dependencies matrix

Jewel is in continuous development and we focus on supporting only the Compose version we use internally. You can see the latest supported version in libs.versions.toml.

Different versions of Compose are not guaranteed to work with different versions of Jewel.

The Compose Compiler version used is the latest compatible with the given Kotlin version. See here for the Compose Compiler release notes, which indicate the compatibility.

The minimum supported Kotlin version is dictated by the minimum supported IntelliJ IDEA platform.

Project structure

The project is split in modules:

1. buildSrc contains the build logic, including:
   • The jewel and jewel-publish configuration plugins
   • The jewel-check-public-api and jewel-linting configuration plugins
   • The Theme Palette generator plugin
   • The Studio Releases generator plugin
2. foundation contains the foundational Jewel functionality:
   • Basic components without strong styling (e.g., SelectableLazyColumn, BasicLazyTree)
   • The JewelTheme interface with a few basic composition locals
   • The state management primitives
   • The Jewel annotations
   • A few other primitives
3. ui contains all the styled components and custom painters logic
4. decorated-window contains basic, unstyled functionality to have custom window decoration on the JetBrains Runtime
5. int-ui contains two modules:
   • int-ui-standalone has a standalone version of the Int UI styling values that can be used in any Compose for Desktop app
   • int-ui-decorated-window has a standalone version of the Int UI styling values for the custom window decoration that can be used in any Compose for Desktop app
6. ide-laf-bridge contains the Swing LaF bridge to use in IntelliJ Platform plugins (see more below)
7. markdown contains a few modules:
   • core the core logic for parsing and rendering Markdown documents with Jewel, using GitHub-like styling
   • extension contains several extensions to the base CommonMark specs that can be used to add more features
   • ide-laf-bridge-styling contains the IntelliJ Platform bridge theming for the Markdown renderer
   • int-ui-standalone-styling contains the standalone Int UI theming for the Markdown renderer
8. samples contains the example apps, which showcase the available components:
   • standalone is a regular CfD app, using the standalone theme definitions and custom window decoration
   • ide-plugin is an IntelliJ plugin that showcases the use of the Swing Bridge

Branching strategy and IJ Platforms

Code on the main branch is developed and tested against the current latest IntelliJ Platform version.

When the EAP for a new major version starts, we cut a releases/xxx release branch, where xxx is the tracked major IJP version. At that point, the main branch starts tracking the latest available major IJP version, and changes are cherry-picked into each release branch as needed. All active release b