Skip to main content

General Questions

Lumo UI is a Gradle plugin for generating Compose UI components through a CLI. It provides customizable and ready-to-use components that you can copy-paste into your projects. Unlike traditional UI libraries, Lumo generates source code directly into your project, giving you full control over customization.
Lumo UI generates source code directly into your project, rather than providing precompiled components. This means:
  • Full Control: You own the code and can customize it completely
  • No Dependencies: Components become part of your codebase
  • No Version Lock-in: Update components independently
  • Learning Tool: See how components are implemented
  • Copy-Paste Workflow: Similar to shadcn/ui for React
Yes! Lumo UI supports both:
  • Android-only projects: Standard Android Compose projects
  • Kotlin Multiplatform projects: Compose Multiplatform with support for Android, iOS, Desktop, Web (JS/Wasm), and macOS
Enable multiplatform support in lumo.properties:
KotlinMultiplatform=true
Yes! Lumo UI is open source and licensed under the Apache License 2.0. You can use it freely in personal and commercial projects.
Absolutely! Once components are generated into your project, they’re part of your source code. You can:
  • Modify them as needed
  • Fix bugs directly
  • Add features
  • Maintain them like any other code
The components are production-ready and used in real applications.

Installation & Setup

  1. Add the plugin to your root build.gradle.kts:
plugins {
    id("com.nomanr.plugin.lumo") version "1.2.5"
}
  1. Initialize the plugin:
./gradlew lumo --init
  1. Configure lumo.properties with your project details
  2. Add required dependencies (shown during init)
  3. Setup theme:
./gradlew lumo --setup
  • Gradle: 7.0 or higher
  • Kotlin: 1.9.0 or higher
  • Compose: 1.5.0 or higher (Android) or Compose Multiplatform 1.5.0+
  • Java: JDK 11 or higher
For Kotlin Multiplatform, you also need the appropriate platform-specific dependencies configured.
No. The plugin should be applied to the root project only. It generates code into the directory you specify in lumo.properties, which can be in any module.
Yes! Lumo UI can be added to existing projects. Just:
  1. Install the plugin
  2. Point ComponentsDir to your existing UI package
  3. Generate components
The plugin will not overwrite existing files, so your current code is safe.

Component Generation

# List available components
./gradlew lumo --available-components

# Add a specific component
./gradlew lumo --add Button

# Add all components
./gradlew lumo --add-all
Current available components:
  • Accordion
  • AlertDialog
  • Badge
  • Button
  • Card
  • Checkbox
  • Chip
  • Divider
  • Icon
  • IconButton
  • ModalBottomSheet
  • NavigationBar
  • OTPTextField
  • ProgressIndicators (Linear and Circular)
  • RadioButton
  • Scaffold
  • Slider
  • Surface
  • Snackbar
  • Switch
  • SystemBars
  • Text
  • TextField (Standard, Outlined, Underlined)
  • Theme
  • Tooltip
  • TopBar
Run ./gradlew lumo --available-components for the latest list.
The plugin will not overwrite existing files. To regenerate:
  1. Backup your changes (if any)
  2. Delete the component file(s)
  3. Run the generation command again
  4. Manually merge your changes if needed
This is intentional to prevent accidental loss of customizations.
Some components depend on others. When you generate a component, the plugin automatically:
  • Resolves all dependencies
  • Generates supporting files
  • Creates foundation classes (like Elevation, Ripple)
For example, generating Button automatically includes:
  • ButtonElevation.kt
  • Elevation.kt
  • Ripple.kt
You’ll see these listed as “Generated supporting files” in the output.
Depends on the component, but typically:Main files:
  • The component itself (e.g., Button.kt)
Supporting files:
  • Foundation classes (elevation, ripple, etc.)
  • Helper classes and utilities
  • Default configurations
Platform-specific files (Multiplatform only):
  • Tooltip.android.kt
  • Tooltip.ios.kt
  • Tooltip.desktop.kt
  • etc.
The exact files are shown in the generation output.

Configuration

The configuration is stored in lumo.properties in your project root directory. This file is created when you run ./gradlew lumo --init.
Three required properties:
# Name of your theme
ThemeName=AppTheme

# Path to components directory (relative to project root)
ComponentsDir=app/src/main/java/com/example/ui

# Package name for generated files
PackageName=com.example.ui
And one optional property:
# Enable for Kotlin Multiplatform projects
KotlinMultiplatform=true
Yes! Simply edit lumo.properties with your new values. Changes take effect immediately for the next command.If you change ComponentsDir or PackageName, you may want to:
  1. Create the new directory structure
  2. Move existing generated files
  3. Update imports in your code
This is a Kotlin/Java convention. The directory structure should mirror the package structure:
# Correct
ComponentsDir=app/src/main/java/com/example/ui
PackageName=com.example.ui

# The path ends with: com/example/ui
# The package is: com.example.ui
# These match! ✓
The plugin validates this to prevent package/directory mismatches that would cause compilation errors.

Customization

Yes! That’s the whole point. Once generated, components are regular Kotlin files in your project. You can:
  • Modify styling
  • Add new parameters
  • Change behavior
  • Remove features you don’t need
  • Combine with other components
The files are yours to customize however you like.
No. The plugin will not overwrite existing files. If you try to generate a component that already exists, you’ll see:
Failed to generate some files as they already exist:
file:///path/to/Button.kt
To regenerate, you must explicitly delete the file first.
Yes, but you’ll need to:
  1. Update ThemeName in lumo.properties
  2. Manually rename the theme function in existing generated files
  3. Update imports/usages throughout your codebase
Or:
  1. Update ThemeName in lumo.properties
  2. Delete existing components
  3. Regenerate all components
The second approach is simpler but requires backing up any customizations.
Components use your theme colors defined in Color.kt and Theme.kt. To customize:
  1. Global changes: Edit Color.kt to change your color scheme
  2. Theme changes: Edit Theme.kt to modify theme behavior
  3. Component-specific: Edit the component file directly
Example - Change button colors:
// In Button.kt
Button(
    colors = ButtonDefaults.buttonColors(
        containerColor = Color.Blue,  // Your custom color
        contentColor = Color.White
    )
) {
    // ...
}

Multiplatform

Set KotlinMultiplatform=true in lumo.properties:
ThemeName=AppTheme
ComponentsDir=shared/src/commonMain/kotlin/com/example/ui
PackageName=com.example.ui
KotlinMultiplatform=true
Make sure:
  • Your ComponentsDir points to a commonMain directory
  • You have the Compose Multiplatform plugin applied
  • Platform source sets are configured in build.gradle.kts
When KotlinMultiplatform=true, components are generated for:
  • commonMain: Shared code for all platforms
  • androidMain: Android-specific implementations
  • iosMain: iOS-specific implementations
  • desktopMain: Desktop (JVM) implementations
  • jsMain: JavaScript implementations
  • wasmJsMain: WebAssembly implementations
  • macosMain: macOS-specific implementations
Platform-specific files are only generated if the source set exists in your project.
No. Most components work with just the common implementation. Platform-specific files are only needed for components that require platform-specific behavior, like:
  • Tooltip (different behavior on mobile vs desktop)
  • FontScaleConfig (platform-specific font handling)
The plugin automatically generates platform-specific files only when needed.
Yes! Common setup:
project/
├── build.gradle.kts
├── lumo.properties
└── shared/
    ├── build.gradle.kts
    └── src/
        ├── commonMain/kotlin/
        ├── androidMain/kotlin/
        └── iosMain/kotlin/
In lumo.properties:
ComponentsDir=shared/src/commonMain/kotlin/com/example/ui
PackageName=com.example.ui
KotlinMultiplatform=true

Dependencies

Get the exact list for your project:
./gradlew lumo --required-deps
For Android:
  • Compose BOM
  • Compose Foundation
  • Compose UI
  • Material Ripple
For Multiplatform:
  • Compose Runtime
  • Compose Foundation
  • Compose Material3
  • Compose UI
No! Once components are generated, they’re just regular Kotlin/Compose code. You can:
  • Remove the plugin from your build.gradle.kts
  • Use components without the plugin
  • Distribute components to other projects
The only runtime dependencies are the Compose libraries that your project already uses.
Yes, but:
  • Android: Use the Compose BOM to manage versions. Components are compatible with recent Compose versions (1.5.0+)
  • Multiplatform: Ensure your Compose Multiplatform version is compatible
If you encounter compatibility issues, you can modify the generated code since you own it.

Troubleshooting

Ensure Maven Central is in your plugin repositories:
// settings.gradle.kts
pluginManagement {
    repositories {
        mavenCentral()
        gradlePluginPortal()
        google()
    }
}
Then sync Gradle files.
Try:
  1. Sync Gradle: File → Sync Project with Gradle Files
  2. Invalidate caches: File → Invalidate Caches → Invalidate and Restart
  3. Mark directory as source root: Right-click directory → Mark Directory as → Sources Root
  4. Rebuild: Build → Rebuild Project
The documentation may show the latest version. If you:
  • Generated components with an older plugin version
  • Customized components after generation
  • Use a different theme
To get the latest components, delete old files and regenerate with the latest plugin version.

Contributing

Yes! Contributions are welcome. See the Contributing Guide for details.Ways to contribute:
  • Report bugs
  • Suggest new components
  • Improve existing components
  • Fix issues
  • Improve documentation
Create an issue on GitHub:
  1. Go to https://github.com/nomanr/lumo-ui/issues
  2. Click “New Issue”
  3. Describe the component you’d like
  4. Include examples or mockups if possible
The maintainers will review and discuss implementation.
Yes! Fork the repository and:
  1. Create the component in lumo-ui/components-lab/
  2. Add it to SupportedComponents enum
  3. Create templates
  4. Add to the template registry
  5. Test thoroughly
  6. Submit a pull request
See Contributing Guide for detailed instructions.

Advanced Usage

The templates are embedded in the plugin JAR, so you can’t directly modify them. However, you can:
  1. Generate the component
  2. Modify the generated code
  3. Use it as your custom template
For permanent changes, consider:
  • Forking the plugin repository
  • Modifying templates in the source
  • Building your own version
  • Or contributing improvements upstream
Yes! Configure it as a Multiplatform project with only desktop targets:
kotlin {
    jvm("desktop")
    
    sourceSets {
        desktopMain.dependencies {
            implementation(compose.desktop.currentOs)
        }
    }
}
Set KotlinMultiplatform=true in lumo.properties.
  1. Create a dedicated module for UI components
  2. Configure Lumo to generate into that module
  3. Generate all needed components
  4. Customize as needed
  5. Publish the module as a library
// In your UI module
ComponentsDir=ui-library/src/main/java/com/company/uilib
PackageName=com.company.uilib
Yes, but be careful with imports. Lumo components use Material3 APIs. You can:
  • Use Lumo components alongside Material2
  • Explicitly import from the correct package
  • Gradually migrate from Material2 to Material3
import androidx.compose.material.Button // Material2
import com.example.ui.Button // Your Lumo button

See Also

Build docs developers (and LLMs) love