📐 Blueprint

Visualize the dimensions of your composables on a blueprint

Introductory Medium Article

The Problem

Have you ever desired to see, what exactly is that padding's value while looking at the composable preview window? Especially when you are developing a button with 5 color styles, 3 sizes, and 2 optional icons; and each combination of these parameters has different paddings?

Combinatorial explosion of UI components in design systems requires having a lot of context about paddings, dp's, sizes, corner radiuses, and other dimensional information in your head at the same time.

In addition, code to produce those combinations can get tricky to analyze. So, verification also becomes hard: you make screenshots, move them to Figma, overlay them on top, and try to see the difference. Tedious 😩!

The Solution

The Blueprint library provides a way to visualize dimensional information in your UI using a simple DSL-based definition:

1. Just wrap your target UI in a Blueprint composable
2. Mark children with Modifier.blueprintId(id: String) modifier
3. Write the blueprint definition

Blueprint(
    blueprintBuilder = {
        widths {
            group {
                "item0".right lineTo "item1".left
                "item0" lineTo "item0"
                "item2" lineTo "item3"
            }
        }
        heights {
            group { "item0Icon" lineTo "item0Text" }
            group { "item0" lineTo "item0" }
            group(End) { "item3Icon".bottom lineTo "item3Text".top }
        }
    }
) {
    val items = remember { listOf("Songs", "Artists", "Playlists", "Settings") }
    NavigationBar {
        items.forEachIndexed { index, item ->
            NavigationBarItem(
                modifier = Modifier.blueprintId("item$index"),
                icon = { Icon(Modifier.blueprintId("item${index}Icon"), TODO()) },
                label = { Text(Modifier.blueprintId("item${index}Text"), TODO()) },
                selected = index == 0,
                onClick = { TODO() }
            )
        }
    }
}

Preview

And another example:

Correct arrow padding rendering animation

https://github.com/popovanton0/Blueprint/assets/15000556/7a90b534-3c7e-437a-8e08-1fdd4329c752

https://github.com/popovanton0/Blueprint/assets/15000556/535a016f-0ca9-41d2-8e52-2ed7b36fbdc0

Features

You can customize

1. Line and border strokes (width and color)
2. Font size and color
3. Arrow style (length, angle, round or square cap)
4. Decimal precision of the dimensional values

Of course, Blueprint works in Android Studio's Preview✨!

Also, you can disable all the overhead of this library in your release builds by either:

1. Disabling blueprint rendering using blueprintEnabled property.
2. Using the no-op version of the library:

   dependencies {
       debugImplementation("com.github.popovanton0.blueprint:blueprint:1.0.0-alpha05")
       releaseImplementation("com.github.popovanton0.blueprint:blueprint-no-op:1.0.0-alpha05")
   }
   

Getting Started

Add the following code to your project's root build.gradle file:

repositories {
    maven { url "https://jitpack.io" }
}

Next, add the dependency below to your module's build.gradle file:

dependencies {
    implementation "com.github.popovanton0.blueprint:blueprint:1.0.0-alpha05"
}

Add the following code to your project's root settings.gradle.kts file:

dependencyResolutionManagement {
    // ...
    repositories {
        // ...
        maven { url = uri("https://jitpack.io") }
    }
}

Next, add the dependency below to your module's build.gradle.kts file:

dependencies {
    implementation("com.github.popovanton0.blueprint:blueprint:1.0.0-alpha05")
}

Or using Gradle Version Catalog:

[versions]
blueprint = "1.0.0-alpha05"

[libraries]
blueprint = { module = "com.github.popovanton0.blueprint:blueprint", version.ref = "blueprint" }

[!WARNING] Do not use this dependency notation: com.github.popovanton0:blueprint:1.0.0-alpha05. It doesn't work!

Licence

Copyright 2023 Anton Popov

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.