Skip to main content
Proper directory structure is essential for Lumo UI to generate components correctly. This guide explains how to organize your project files and configure the ComponentsDir property.

​
Overview

Lumo UI requires a specific directory structure that aligns with your Kotlin package names. The ComponentsDir property in lumo.properties tells the plugin where to generate UI components.

​
Directory Structure Requirements

​
Package-Directory Alignment

The most important rule: Your directory structure must match your package name. 
project-root/
├── lumo.properties
├── app/
│   └── src/
│       └── main/
│           └── java/
│               └── com/
│                   └── example/
│                       └── myapp/
│                           └── ui/          ← ComponentsDir points here
│                               ├── Theme.kt
│                               ├── Color.kt
│                               ├── Typography.kt
│                               └── components/
└── build.gradle.kts

Configuration:
ComponentsDir=app/src/main/java/com/example/myapp/ui
PackageName=com.example.myapp.ui

​
ComponentsDir Configuration

​
What is ComponentsDir?

​
ComponentsDir
string
required
A relative path from the project root to the directory where Lumo UI will generate and manage UI components.Key Points:
  • Path is relative to project root
  • Must be an existing directory
  • Must align with the package structure
  • Uses forward slashes (/) as separators

​
Validation Process

When you run Lumo UI, it validates your configuration:
  1. Directory Existence Check
    • Verifies that the directory exists
    • Creates the directory if needed (in some cases)
  2. Package Alignment Check
    • Converts the directory path to package format
    • Compares it with the PackageName
    • Ensures they match
Example Validation:
ConfigurationValidator.kt
val normalizedDirPath = config.componentsDir
    .removeSuffix("/").removeSuffix("\\")  // Remove trailing slashes
    .replace("\\", ".")                      // Replace backslashes
    .replace("/", ".")                        // Replace forward slashes
    .replace("//", ".")                       // Handle double slashes

// Result: "app.src.main.java.com.example.myapp.ui"
// Must end with: "com.example.myapp.ui"

​
Sample Project Structures

​
Sample Android Project

Based on the reference sample project:
Android Sample
sample-android/
├── ui-components/
│   └── src/
│       └── main/
│           └── java/
│               └── com/
│                   └── nomanr/
│                       └── sample/
│                           └── ui/                          ← ComponentsDir
│                               ├── Theme.kt                 (Generated)
│                               ├── Color.kt                 (Generated)
│                               ├── Typography.kt            (Generated)
│                               ├── configs/
│                               │   └── FontScaleConfig.kt
│                               ├── components/
│                               │   ├── button/
│                               │   ├── textfield/
│                               │   └── ...
│                               └── foundation/
└── catalogue/                                               (Demo app)

lumo.properties:
ThemeName=AppTheme
ComponentsDir=sample-android/ui-components/src/main/java/com/nomanr/sample/ui
PackageName=com.nomanr.sample.ui

​
Sample Multiplatform Project

Multiplatform Sample
sample-multiplatform/
├── ui-components/
│   └── src/
│       ├── commonMain/
│       │   └── kotlin/
│       │       └── com/
│       │           └── nomanr/
│       │               └── lumo/
│       │                   └── multiplatform/
│       │                       └── ui/                      ← ComponentsDir
│       │                           ├── Theme.kt             (Generated)
│       │                           ├── Color.kt             (Generated)
│       │                           ├── Typography.kt        (Generated)
│       │                           ├── configs/
│       │                           │   └── FontScaleConfig.kt
│       │                           ├── components/
│       │                           │   ├── button/
│       │                           │   ├── textfield/
│       │                           │   └── ...
│       │                           └── foundation/
│       ├── androidMain/
│       ├── iosMain/
│       ├── desktopMain/
│       └── wasmJsMain/
└── catalogue/                                               (Demo app)

lumo.properties:
ThemeName=AppTheme
ComponentsDir=sample-multiplatform/ui-components/src/commonMain/kotlin/com/nomanr/lumo/multiplatform/ui
PackageName=com.nomanr.lumo.multiplatform.ui
KotlinMultiplatform=true

​
Generated Files

When properly configured, Lumo UI generates these core files in your ComponentsDir:

​
Core Theme Files

The main theme composable that wraps your application. Contains:
  • AppTheme composable function
  • Theme configuration and setup
  • CompositionLocal providers
  • Dark/light mode handling
Location: {ComponentsDir}/Theme.kt
Color definitions and color schemes. Contains:
  • Predefined color palettes (Gray, Red, Blue, Green)
  • Colors data class
  • LightColors and DarkColors schemes
  • AppColors configuration
  • Color utility functions
Location: {ComponentsDir}/Color.kt
Typography system and text styles. Contains:
  • Typography data class
  • Default text styles (h1-h4, body1-3, label1-3, button, input)
  • Font family configuration
  • Font scaling utilities
Location: {ComponentsDir}/Typography.kt

​
Component Subdirectories

Components are typically organized in subdirectories: 
ComponentsDir/
├── Theme.kt
├── Color.kt
├── Typography.kt
├── components/
│   ├── button/
│   │   ├── Button.kt
│   │   ├── ButtonColors.kt
│   │   └── ButtonDefaults.kt
│   ├── textfield/
│   │   ├── TextField.kt
│   │   ├── TextFieldColors.kt
│   │   └── TextFieldDefaults.kt
│   └── ...
├── configs/
│   └── FontScaleConfig.kt
└── foundation/
    ├── ripple/
    └── ...

​
Creating the Directory Structure

​
Manual Setup

  1. Determine your package name: 
    com.example.myapp.ui
  2. Create the directory structure: 
    mkdir -p app/src/main/java/com/example/myapp/ui
  3. Update lumo.properties: 
    ComponentsDir=app/src/main/java/com/example/myapp/ui
PackageName=com.example.myapp.ui

​
Using the Plugin Initialization

Run the initialization command and then create the directory: 
# Initialize the plugin
./gradlew lumoUi --init

# Edit lumo.properties with your desired paths
# Then create the directory
mkdir -p path/to/your/components/dir

​
Multi-Module Projects

For multi-module projects, choose one module for UI components:
Multi-Module Structure
project-root/
├── lumo.properties
├── app/
│   └── src/
├── core/
│   └── src/
├── design-system/              ← Dedicated UI module
│   └── src/
│       └── main/
│           └── java/
│               └── com/
│                   └── example/
│                       └── design/
│                           └── ui/     ← ComponentsDir points here
└── build.gradle.kts

Configuration:
ComponentsDir=design-system/src/main/java/com/example/design/ui
PackageName=com.example.design.ui

​
Path Separators

​
Cross-Platform Compatibility

Lumo UI handles different path separators:
  • Forward slashes (/): Recommended for all platforms
  • Backslashes (\): Windows-style, automatically converted
Best Practice: Always use forward slashes in lumo.properties:
Good
ComponentsDir=app/src/main/java/com/example/ui
Also Works
ComponentsDir=app\\src\\main\\java\\com\\example\\ui

​
Common Issues and Solutions

Problem: The directory specified in ComponentsDir doesn’t exist.Solution:
mkdir -p path/to/your/components/dir
Problem: The directory structure doesn’t align with the package name.Example:
  • ComponentsDir: app/src/main/java/com/example/ui
  • PackageName: com.myapp.design.ui
Solution: Make them match:
ComponentsDir=app/src/main/java/com/myapp/design/ui
PackageName=com.myapp.design.ui
Problem: Generated files have wrong package declarations.Solution: Verify that:
  1. ComponentsDir points to the correct directory
  2. PackageName matches the directory structure
  3. The directory exists before running the plugin

​
Best Practices

Use Descriptive Paths

Make your component directory path clear and descriptive:
  • ui-components/src/.../ui ✓
  • shared/design-system/... ✓
  • src/... ✗ (too generic)

Dedicated UI Module

Consider creating a dedicated module for UI components in larger projects to keep them separate from business logic.

Consistent Naming

Use consistent naming conventions:
  • Package: com.company.app.ui
  • Module: ui-components or design-system

Source Control

Commit both lumo.properties and generated files to version control to ensure team consistency.

​
Verification

After setting up your directory structure, verify it works: 
# Run the plugin
./gradlew lumoUi --generate

# Check that files are generated correctly
ls -la path/to/ComponentsDir/
You should see:
  • Theme.kt
  • Color.kt
  • Typography.kt
  • Component subdirectories

​
Next Steps

lumo.properties

Complete configuration reference

Theme Customization

Customize your theme

Build docs developers (and LLMs) love

Get started for freeTalk to us